v3.2.0

What's Changed

• This module now requires Companion ≥3.4.0.
• The TCP connection this module creates to interact with a camera is more resiliently managed.
  • If the attempt to connect fails, or if the connection fails or is closed by the camera, the module will automatically try to reconnect until a connection is established. Any VISCA commands sent to the camera that are currently being processed will not be reattempted, because performing a command twice might not have the same effect as performing it once. (For example, a command instructing the camera to rotate by 25° would rotate 50° if performed twice.)
  • Camera responses that violate VISCA requirements will cause the connection to fail. No attempt is made to reconnect in this case. Whatever conditions triggered the violation might be present on reconnection (triggering an infinite error loop), so cleaning up and manually restarting the instance is left to the user (e.g. using a trigger that watches the instance status).
  • Instance status is consistently synced with the state of the TCP connection.

Manual install instructions

In Companion 3.4 or later:

1. Create an empty folder somewhere and give it a name like companion-dev-modules.
2. In that folder, extract the companion-module-ptzoptics-visca.tgz — such that companion-dev-modules/pkg/companion/manifest.json will exist.
   • You can rename the extracted pkg folder to another name if needed.
3. In Companion's launch window, click the little gear icon in top right, and set the "Developer modules path" at bottom to the companion-modules-dev folder.

You can verify that the module installed correctly using the "Help" icon on any connection's configuration page.

Full Changelog: v3.1.0...v3.2.0

v3.1.0

What's Changed

• From @ploveman: Add an action to recall a preset using a text input that accepts variables. (#53)
• From @ploveman: Add an action to save a preset using a text input that accepts variables. (#60)

New Contributors

• @ploveman made their first contribution in e139845 (#53)

Manual install instructions

In Companion 3.2 or later:

1. Create an empty folder somewhere and give it a name like companion-dev-modules.
2. In that folder, extract the companion-module-ptzoptics-visca.tgz — such that companion-dev-modules/pkg/companion/manifest.json will exist.
   • You can rename the extracted pkg folder to another name if needed.
3. In Companion's launch window, click the little gear icon in top right, and set the "Developer modules path" at bottom to the companion-modules-dev folder.

You can verify that the module installed correctly using the "Help" icon on any connection's configuration page.

Full Changelog: v3.0.3...v3.1.0

v3.1.0-rc1

What's Changed

• From @ploveman: Add an action to recall a preset using a text input that accepts variables. (#53)

New Contributors

• @ploveman made their first contribution in e139845 (#53)

Manual install instructions

In Companion 3.2 or later:

1. Create an empty folder somewhere and give it a name like companion-dev-modules.
2. In that folder, extract the companion-module-ptzoptics-visca.tgz — such that companion-dev-modules/pkg/companion/manifest.json will exist.
   • You can rename the extracted pkg folder to another name if needed.
3. In Companion's launch window, click the little gear icon in top right, and set the "Developer modules path" at bottom to the companion-modules-dev folder.

You can verify that the module installed correctly using the "Help" icon on any connection's configuration page.

Full Changelog: v3.0.3...v3.1.0-rc1

v3.0.3

What's Changed

Bugfixes:

• Make parameters specified in the "Custom command" action work correctly, rather than each interpolating as if it had the value zero. (#55 )

Manual install instructions

In Companion 3.2 or later:

1. Create an empty folder somewhere and give it a name like companion-dev-modules.
2. In that folder, extract the companion-module-ptzoptics-visca.tgz — such that companion-dev-modules/pkg/companion/manifest.json will exist.
   • You can rename the extracted pkg folder to another name if needed.
3. In Companion's launch window, click the little gear icon in top right, and set the "Developer modules path" at bottom to the companion-modules-dev folder.

You can verify that the module installed correctly using the "Help" icon on any connection's configuration page.

Full Changelog: v3.0.2...v3.0.3

v3.0.2

What's Changed

Bugfixes:

• Skip network change replies (z0 38 FF, where z is 8 to F encoding a device address 0 to 7 for serial access) wherever they appear in non-PTZOptics camera replies. (PTZOptics users shouldn't need this fix and won't be affected by it.) (#54)

Manual install instructions

In Companion 3.2 or later:

1. Create an empty folder somewhere and give it a name like companion-dev-modules.
2. In that folder, extract the companion-module-ptzoptics-visca.tgz — such that companion-dev-modules/pkg/companion/manifest.json will exist.
   • You can rename the extracted pkg folder to another name if needed.
3. In Companion's launch window, click the little gear icon in top right, and set the "Developer modules path" at bottom to the companion-modules-dev folder.

You can verify that the module installed correctly using the "Help" icon on any connection's configuration page.

Full Changelog: v3.0.1...v3.0.2

v3.0.1

What's Changed

Bugfixes:

• Don't delay the module init process waiting for the connection to the camera to be established, just in case that takes long enough that Companion times out the call and reloads the module (likely causing the cycle to endlessly repeat) (#50)

Manual install instructions

In Companion 3.2 or later:

1. Create an empty folder somewhere and give it a name like companion-dev-modules.
2. In that folder, extract the companion-module-ptzoptics-visca.tgz — such that companion-dev-modules/pkg/companion/manifest.json will exist.
   • You can rename the extracted pkg folder to another name if needed.
3. In Companion's launch window, click the little gear icon in top right, and set the "Developer modules path" at bottom to the companion-modules-dev folder.

You can verify that the module installed correctly using the "Help" icon on any connection's configuration page.

Full Changelog: v3.0.0...v3.0.1

v3.0.0

What's Changed

New user features:

• The "Exposure Mode" and "Focus Mode" actions can "Learn" the actual mode active on the camera. (#33)
• Actions and presets to access the on-screen display (OSD) menu have been added. (#35)
• The "Custom command" action now supports user-filled numeric parameters. (#33, #42)
• A "Debug logging" config option has been added to enable extra logging of module operations (default: off)

Bugfixes:

• The "EXP MODE" Exposure Mode preset now works. (#40)
  • (The action itself has always worked, but instances created by dragging the preset on to a button page previously would not work.)

Internal changes:

• The VISCA message sending/receiving pipeline has been completely rewritten. (#33, #42)
  • Responses to VISCA messages sent to the camera are now processed, rather than being totally ignored.
  • This allows command errors to be detected, and it enables sending VISCA inquiries to the camera and reacting to the response information -- for example, to add the "Learn" support mentioned above.
• VISCA messages are now represented in a structured format. (#33, #42)
  • Commands are messages that may contain parameters. Their expected response is ACK followed by Completion.
  • Inquiries are fixed-byte-sequence messages. An inquiry's expected response must match an inquiry-specific format and can contain parameters. (Inquiries are not yet directly exposed to module users. But they are used inside module code itself, and more internal uses will be added in the future.)
• The module has been converted to TypeScript and may be compiled using the standard yarn install && yarn build. (#37)
• Support for testing using Jest (run them with yarn test) has been added.
  • Brief tests have been added for command representation and for the current set of upgrade scripts.
  • Extensive tests have been added for VISCA command/inquiry sending and response processing.
• A Github workflow that automatically builds and tests the module on push/PR has been added.

This release is a major-version bump:

• The command/processing rewrite is more than complicated enough to warrant it.
• The "Custom command" changes presume that all user custom commands will receive an ACK followed by Completion (or an error) in response.
  • If your custom command expects a different response, you likely won't be able to use it. (File an issue and perhaps this shortcoming can be fixed.)

Camera assumptions

This release makes certain assumptions about cameras:

• The camera must adhere to the PTZOptics VISCA over IP return message interface:
  • ACK (90 4y FF) and later Completion (90 5y FF) for a successful command (y remaining consistent in the two return messages)
  • Syntax Error (90 60 02 FF) for unrecognized or invalidly specified commands/inquiries
  • Command Buffer Full (90 60 03 FF) when the camera is too backed-up to process the command/inquiry
  • Command Not Executable (90 6y 41 FF) when a command isn't currently executable (because, for example, the proper camera mode isn't active)
    • This must be the only return message for a command in error: it cannot be preceded by an ACK assigning it to socket y.
  • All camera inquiries must be responded to by 90 50 <one or more non-FF bytes> FF.
    • The camera must specifically support the PTZOptics "Exposure Mode" and "Focus Mode" inquiries to "Learn" the modes' current values for the appropriate action.
    • The camera must support the PTZOptics "Menu Open / Close" inquiry for the "OSD Open/Close" action (with "open" selected) to work.

Your mileage will vary if you use this module with a camera incompatible with these assumptions.

Manual install instructions

In Companion 3.2 or later:

1. Create an empty folder somewhere and give it a name like companion-dev-modules.
2. In that folder, extract the companion-module-ptzoptics-visca.tgz — such that companion-dev-modules/pkg/companion/manifest.json will exist.
   • You can rename the extracted pkg folder to another name if needed.
3. In Companion's launch window, click the little gear icon in top right, and set the "Developer modules path" at bottom to the companion-modules-dev folder.

You can verify that the module installed correctly using the "Help" icon on any connection's configuration page.

Full Changelog: v2.1.0...v3.0.0

v3.0.0-rc4

What's Changed

New user features:

• The "Exposure Mode" and "Focus Mode" actions can "Learn" the actual mode active on the camera. (#33)
• Actions and presets to access the on-screen display (OSD) menu have been added. (#35)
• The "Custom command" action now supports user-filled numeric parameters. (#33, #42)
• A "Debug logging" config option has been added to enable extra logging of module operations (default: off)

Bugfixes:

• The "EXP MODE" Exposure Mode preset now works. (#40)
  • (The action itself has always worked, but instances created by dragging the preset on to a button page previously would not work.)

Internal changes:

• The VISCA message sending/receiving pipeline has been completely rewritten. (#33, #42)
  • Responses to VISCA messages sent to the camera are now processed, rather than being totally ignored.
  • This allows command errors to be detected, and it enables sending VISCA inquiries to the camera and reacting to the response information -- for example, to add the "Learn" support mentioned above.
• VISCA messages are now represented in a structured format. (#33, #42)
  • Commands are messages that may contain parameters. Their expected response is ACK followed by Completion.
  • Inquiries are fixed-byte-sequence messages. An inquiry's expected response must match an inquiry-specific format and can contain parameters. (Inquiries are not yet directly exposed to module users. But they are used inside module code itself, and more internal uses will be added in the future.)
• The module has been converted to TypeScript and may be compiled using the standard yarn install && yarn build. (#37)
• Support for testing using Jest (run them with yarn test) has been added.
  • Brief tests have been added for command representation and for the current set of upgrade scripts.
  • Extensive tests have been added for VISCA command/inquiry sending and response processing.
• A Github workflow that automatically builds and tests the module on push/PR has been added.

This release is a major-version bump:

• The command/processing rewrite is more than complicated enough to warrant it.
• The "Custom command" changes presume that all user custom commands will receive an ACK followed by Completion (or an error) in response.
  • If your custom command expects a different response, you likely won't be able to use it. (File an issue and perhaps this shortcoming can be fixed.)

Camera assumptions

This release makes certain assumptions about cameras:

• The camera must adhere to the PTZOptics VISCA over IP return message interface:
  • ACK (90 4y FF) and later Completion (90 5y FF) for a successful command (y remaining consistent in the two return messages)
  • Syntax Error (90 60 02 FF) for unrecognized or invalidly specified commands/inquiries
  • Command Buffer Full (90 60 03 FF) when the camera is too backed-up to process the command/inquiry
  • Command Not Executable (90 6y 41 FF) when a command isn't currently executable (because, for example, the proper camera mode isn't active)
    • This must be the only return message for a command in error: it cannot be preceded by an ACK assigning it to socket y.
  • All camera inquiries must be responded to by 90 50 <one or more non-FF bytes> FF.
    • The camera must specifically support the PTZOptics "Exposure Mode" and "Focus Mode" inquiries to "Learn" the modes' current values for the appropriate action.
    • The camera must support the PTZOptics "Menu Open / Close" inquiry for the "OSD Open/Close" action (with "open" selected) to work.

Your mileage will vary if you use this module with a camera incompatible with these assumptions.

Full Changelog: v2.1.0...v3.0.0-rc4

v3.0.0-rc3

What's Changed

New user features:

• The "Exposure Mode" and "Focus Mode" actions can "Learn" the actual mode active on the camera. (#33)
• Actions and presets to access the on-screen display (OSD) menu have been added. (#35)
• The "Custom command" action now supports user-filled numeric parameters. (#33, #42)

Bugfixes:

• The "EXP MODE" Exposure Mode preset now works. (#40)
  • (The action itself has always worked, but instances created by dragging the preset on to a button page previously would not work.)

Internal changes:

• The VISCA message sending/receiving pipeline has been completely rewritten. (#33, #42)
  • Responses to VISCA messages sent to the camera are now processed, rather than being totally ignored.
  • This allows command errors to be detected, and it enables sending VISCA inquiries to the camera and reacting to the response information -- for example, to add the "Learn" support mentioned above.
• VISCA messages are now represented in a structured format. (#33, #42)
  • Commands are messages that may contain parameters. Their expected response is ACK followed by Completion.
  • Inquiries are fixed-byte-sequence messages. An inquiry's expected response must match an inquiry-specific format and can contain parameters. (Inquiries are not yet directly exposed to module users. But they are used inside module code itself, and more internal uses will be added in the future.)
• The module has been converted to TypeScript and may be compiled using the standard yarn install && yarn build. (#37)
• Support for testing using Jest (run them with yarn test) has been added.
  • Brief tests have been added for command representation and for the "Custom command" action upgrade script.
  • Extensive tests have been added for VISCA command/inquiry sending and response processing.
• A Github workflow that automatically builds and tests the module on push/PR has been added.

This release is a major-version bump:

• The command/processing rewrite is more than complicated enough to warrant it.
• The "Custom command" changes presume that all user custom commands will receive an ACK followed by Completion (or an error) in response.
  • If your custom command expects a different response, you likely won't be able to use it. (File an issue and perhaps this shortcoming can be fixed.)

Camera assumptions

This release makes certain assumptions about cameras:

• The camera must adhere to the PTZOptics VISCA over IP return message interface:
  • ACK (90 4y FF) and later Completion (90 5y FF) for a successful command (y remaining consistent in the two return messages)
  • Syntax Error (90 60 02 FF) for unrecognized or invalidly specified commands/inquiries
  • Command Buffer Full (90 60 03 FF) when the camera is too backed-up to process the command/inquiry
  • Command Not Executable (90 6y 41 FF) when a command isn't currently executable (because, for example, the proper camera mode isn't active)
    • This must be the only return message for a command in error: it cannot be preceded by an ACK assigning it to socket y.
  • All camera inquiries must be responded to by 90 50 <one or more non-FF bytes> FF.
    • The camera must specifically support the PTZOptics "Exposure Mode" and "Focus Mode" inquiries to "Learn" the modes' current values for the appropriate action.
    • The camera must support the PTZOptics "Menu Open / Close" inquiry for the "OSD Open/Close" action (with "open" selected) to work.

Your mileage will vary if you use this module with a camera incompatible with these assumptions.

Full Changelog: v2.1.0...v3.0.0-rc3

v3.0.0-rc2

What's Changed

New user features:

• The "Exposure Mode" and "Focus Mode" actions can "Learn" from the active camera mode. (#33)
• Actions and presets to access the on-screen display (OSD) menu have been added. (#35)
• The "Custom command" action now supports user-filled numeric parameters. (#33, #42)

Bugfixes:

• The "EXP MODE" Exposure Mode preset now works. (#40)
  • (The action itself has always worked, but instances created by dragging the preset on to a button page previously would not work.)

Internal changes:

• The VISCA message sending/receiving pipeline has been completely rewritten. (#33, #42)
  • Responses to VISCA messages sent to the camera are now processed, rather than being totally ignored.
  • This allows command errors to be detected, and it enables sending VISCA inquiries to the camera and reacting to the response information -- for example, to add the "Learn" support mentioned above.
• VISCA messages are now represented in a structured format. (#33, #42)
  • Commands are messages that may contain parameters. Their expected response is ACK followed by Completion.
  • Inquiries are fixed-byte-sequence messages. An inquiry's expected response must match an inquiry-specific format and can contain parameters. (Inquiries are not yet directly exposed to module users. But they are used inside module code itself, and more internal uses will be added in the future.)
• The module has been incrementally (but completely) converted to TypeScript and may be compiled using the standard yarn install && yarn build. (#37)
• Support for testing using Jest (run them with yarn test) has been added.
  • Brief tests have been added for command representation and for the "Custom command" action upgrade script.
  • Extensive tests have been added for VISCA command/inquiry sending and response processing.
• A Github workflow that automatically builds and tests the module on push/PR has been added.

This release is a major-version bump:

• The command/processing rewrite is more than complicated enough to warrant it.
• The "Custom command" changes presume that all user custom commands will receive an ACK followed by Completion (or an error) in response.
  • If your custom command expects a different response, you likely won't be able to use it. (File an issue and perhaps this shortcoming can be fixed.)

Camera assumptions

This release makes certain assumptions about cameras:

• The camera must adhere to the PTZOptics VISCA over IP return message interface:
  • ACK (90 4y FF) and later Completion (90 5y FF) for a successful command (y remaining consistent in the two return messages)
  • Syntax Error (90 60 02 FF) for unrecognized or invalidly specified commands/inquiries
  • Command Buffer Full (90 60 03 FF) when the camera is too backed-up to process the command/inquiry
  • Command Not Executable (90 6y 41 FF) when a command isn't currently executable (because, for example, the proper camera mode isn't active)
    • This must be the only return message for a command in error: it cannot be preceded by an ACK assigning it to socket y.
  • All camera inquiries must be responded to by 90 50 <one or more non-FF bytes> FF.
    • The camera must specifically support the PTZOptics "Exposure Mode" and "Focus Mode" inquiries to "Learn" the modes' current values for the appropriate action.
    • The camera must support the PTZOptics "Menu Open / Close" inquiry for the "OSD Open/Close" action (with "open" selected) to work.

Your mileage will vary if you use this module with a camera incompatible with these assumptions.

Full Changelog: v2.1.0...v3.0.0-rc2