License, Copyright, and Trademark

The content contained in this repository is the intellectual property of Snap One, LLC, (formerly known as Wirepath Home Systems, LLC), and use without a valid license from Snap One is strictly prohibited. The user of this repository shall keep all content contained herein confidential and shall protect this content in whole or in part from disclosure to any and all third parties except as specifically authorized in writing by Snap One.

License and Intellectual Property Disclaimer

The content in this repository is provided in connection with Snap One products. No license, express or implied, by estoppal or otherwise, to any intellectual property rights is granted by this document or in this repository. Except as provided in Snap Oneʼs terms and conditions for the license of such products, Snap One and its affiliates assume no liability whatsoever and disclaim any express or implied warranty, relating to the sale and/or use of Snap One products including liability or warranties relating to fitness for a particular purpose, merchantability, or infringement of any patent, copyright or other intellectual property right. Snap One products are not intended for use in medical, lifesaving, or life sustaining applications.

Information regarding third-party products is provided solely for educational purposes. Snap One is not responsible for the performance or support of third-party products and does not make any representations or warranties whatsoever regarding the quality, reliability, functionality or compatibility of these products. The reader is advised that third parties can have intellectual property rights that can be relevant to this repository and the technologies discussed herein, and is advised to seek the advice of competent legal counsel regarding the intellectual property rights of third parties, without obligation of Snap One.

Snap One retains the right make changes to this repository or related product specifications and descriptions in this repository, at any time, without notice. Snap One makes no warranty for the use of this repository and assumes no responsibility for any errors that can appear in the repository nor does it make a commitment to update the content contained herein.

Copyright

Copyright 2024 Snap One, LLC. All rights reserved.

The above copyright notice applies to all content in this repository unless otherwise stated explicitly herein that a third-party’s copyright applies.

No part of this publication may be reproduced, photocopied, stored on a retrieval system, or transmitted without the express written consent of the publisher.

Trademarks

Snap One and Snap One Logo, Control4 and the Control4 logo, and DriverWorks are trademarks or registered trademarks of Snap One, LLC. Other product and company names mentioned in this repository may be the trademarks or registered trademarks of their respective owners.

 Derivative Works

To the extent that you create any “Derivative Work” (meaning any work that is based upon one or more preexisting versions of the work provided to you in this repository, such as an enhancement or modification, revision, translation, abridgement, condensation, expansion, collection, compilation or any other form in which such preexisting works may be recast, modified, transformed or adapted, explicitly including without limitation, any updates or changes to Snap One, LLC’s software code or intellectual property) such Derivative Work shall be owned by Snap One, LLC and all right, title and interest in and to each such Derivative Work shall automatically vest in Snap One, LLC. To the extent any Derivative Work does not automatically vest in Snap One, LLC by operation of law, you hereby assign such Derivative Work to Snap One, LLC with full title guarantee. Snap One, LLC shall have no obligation to grant you any right in any such Derivative Work.

Contact Us

Snap One, LLC 11734 S. Election Road Salt Lake City, UT 84020 USA

http://www.control4.com

Introduction

This documentation includes content that details the functions that make up the Camera Proxy which is supported in the DriverWorks Software Development Kit.

Additional driver development documentation supporting camera driver development can be found in the DriverWorks Fundamentals Guide. This includes:

Camera Proxy Audio Distribution

Camera Proxy and Dynamic Streams

Proxies (Commands)

A proxy driver is an interface to the Control4 system for a set of devices that share common functionality. For instance, most Cameras have common controls such as NIGHT MODE, PAN RIGHT and PAN LEFT.  The camera proxy allows for a common user interface to control all cameras.  The Control4 system (Director) sends information to and receives information from the proxy drivers.  The proxy drivers send information to and receives information from the protocol drivers. Remember, your DriverWorks driver interacts with the proxy driver which then interacts with the system.  As a driver developer you will be relying on this proxy to provide status (notification) to the Control4 system for the device you are controlling.  You will also receive commands from the system that you will act on to control the device.  These commands and notifications are at the heart of what you will be implementing in your driver.  Essentially your driver is becoming the go-between from the Control4 system and your device with the proxy driver giving structure to the commands and notifications which you will be implementing. Your driver can facilitate communications with multiple types of proxies for a single device. As an example, a Security System driver will utilize both the Security proxy and the Contacts proxy. These additional proxies are configured in the <connections> section of the .c4z.

Protocol (Notifications)

Two similar devices may have the same functionality but utilize a very different command set.  A protocol driver provides the device-specific information needed to communicate with the Control4 system.  In the case of DriverWorks, the DriverWorks driver is the protocol driver.  When combined with the device-specific.c4Z file it provides the custom code necessary to implement the 2-way device driver. In the case of DriverWorks, the DriverWorks driver is the protocol driver. When combined with the device-specific.c4Z file it provides the custom code necessary to implement the 2-way device driver.

What’s New

What’s New in 4.0.0

Beta Documentation: The content included in this documentation associated with the release of Operating System 4.0.0 is in a beta state. This content may be incomplete, modified or removed prior to the production release of O.S. 4.0.0.

Updated Content

The Preset and Select_Preset commands content has been updated to reflect the manner in which they are handled in Composer Pro.

The Presets_Changed notification content has been updated to reflect the need for all Preset data to be included when the notification is sent.

The has_dynamic_presets and the number_presets capability content has been updated to reflect the manner in which they are handled in Composer Pro.

What’s New in 3.4.2

There were no modifications to the Camera Proxy in conjunction with O.S. Release 3.4.2.

What’s New in 3.4.1

There were no modifications to the Camera Proxy in conjunction with O.S. Release 3.4.1.

What’s New in 3.4.0

Camera Proxy

Beginning with O.S. 3.4.0, camera drivers have the ability to distribute audio to devices running Navigator. If a camera supports the proper CODEC and the camera microphone has been enabled in the appropriate interface a new audio button will appear at the bottom of the single-camera view. This will allow the user to hear live audio with the live video.

What’s New in 3.3.2

Camera Proxy

Support for Dynamic Camera Streams

Camera drivers can now implement a new dynamic streams API to provide a list of streams that the Navigators can pick from.

What’s New in 3.3.1

There were no modifications to the Camera Proxy in conjunction with O.S. Release 3.3.1.

What’s New in 3.3.0

There were no modifications to the Camera Proxy in conjunction with O.S. Release 3.4.2.

What’s New in 3.2.3

There were no modifications to the Camera Proxy in conjunction with O.S. Release 3.2.3.

What’s New in 3.2.2

There were no modifications to the Camera Proxy in conjunction with O.S. Release 3.2.2.

What’s New in 3.2.1

There were no modifications to the Camera Proxy in conjunction with O.S. Release 3.2.1.

What’s New in 3.2.0

There were no modifications to the Camera Proxy in conjunction with O.S. Release 3.2.0.

What was New in 3.1.2

There were no modifications to the Camera Proxy in conjunction with O.S. Release 3.1.2.

What was New in 3.1.0

There were no modifications to the Camera Proxy in conjunction with O.S. Release 3.1.0.

What was New in O.S.3

There were no modifications to the Camera Proxy in conjunction with O.S. Release 3.0.0.

Camera Proxy Commands

CAMERA_OFF

Command to turn camera image capturing off.

Name

CAMERA_OFF ()

Parameters

None

Returns

None

CAMERA_ON

Command to turn camera image capturing on.

Name

CAMERA_ON ()

Parameters

None

Returns

None

CHANGE_PRESET_NAME

Change theme of a Preset.

Name

CHANGE_PRESET_NAME ()

Returns

None

CHANGE_PRESET_ORDER

Change the order of the Presets

Name

CHANGE_PRESET_ORDER ()

Returns

None

CHECK_ADDRESS_PORT

Composer Pro command used in the Camera Test/Validation area. Verifies the camera Address and Port ID.

Name

CHECK_ADDRESS_PORT ()

Returns

None

CHECK_URL

Composer Pro command used in the Camera Test/Validation area. Verifies the camera 's URL components.

Name

CHECK_URL ()

Returns

None

CREATE_PRESET

Creates a new preset.

Name

CREATE_PRESET ()

Returns

None

DELETE_PRESET

Deletes a Preset.

Name

DELETE_PRESET ()

Returns

None

GET_MJPEG_QUERY

Command that is initiated in Composer Pro and immediately returns a block of XML information. It returns the query string needed to create the URL for MJPEG server push request.

Name

GET_MJPEG_QUERY ()

Returns

XML: <mjpeg_query_string> url-query-string</mjpeg_query_string>

GET_PROPERTIES

Command called once by a UI entity to learn how to access a camera. It returns a block of XML reporting the properties of the camera.

Name

GET_PROPERTIES ()

Returns

 <camera_properties>
  <address >hostname or internet address</address>
  <http_port>port</http_port>
  <rtsp_port>port</rtsp_port>
  <authentication_required>true or false</authentication_required>
  <authentication_type>BASIC</authentication_type>
  <username>~username~</username>
  <password>password</password>
  <publicly_accessible>true or false</publicly_accessible>
</camera_properties>

GET_ RTSP_H264_QUERY_ STRING

Command that is initiated in Composer Pro and immediately returns a block of XML information. It returns the query string needed to create the URL for RTSP H264 stream request.

Name

GET_RTSP_H264_QUERY ()

Returns

XML: <rtsp_h264_query_string> url-query-string</rtsp_h264_query_string>

GET_SNAPSHOT_QUERY_STRING

Command that is initiated in Composer Pro and immediately returns a block of XML information. It returns the query string needed to create the URL for HTTP snapshot request.

Name

GET_SNAPSHOT_QUERY_STRING ()

Returns

XML: <snapshot_query_string>url-query-string</snapshot_query_string>

GET_STREAM_URLS

This command is used to obtain URLs for a camera that does not have a constant URL like a Cloud based camera or for cameras that have a wider range of features and configurable options that can produce better customer experiences using various clients.

A Client will make this request to a driver and provide information about how the client will be using the stream. The driver optionally can adjust the URL(s) returned based on this information. Driver developers are encouraged to test their driver on various devices to ensure good customer experiences when viewing collages, high resolution or high frame rate streams.

Examples

An example of the simplest XML returned by a driver is shown to the right:

<streams>
   <stream>url="http://192.168.1.150/view_camera.cgi"></stream>
</streams>

or

<streams>
   <stream> url="https://192.168.1.150:443/view_camera.cgi" codec="h264"</stream>
   <stream>url="http://192.168.1.150:80/view_camera_h265.cgi" codec="h265"</stream>
</streams>

This is followed by an example from a camera with more features and can provide more options to allow clients to pick a better stream:

<streams>
<stream url="rtsps://server.company.com:554/rtsp.cgi" codec="h265" resolution="1920x1080" fps="60">
<stream url="rtsps://server.company.com:554/cloudapi.cgi?fh2f5hw2" codec="h265" resolution="640x480" fps="5">
<stream url="rtsp://server.company.com:554/cloudapi.cgi?fh2f4hw1" codec="h264" resolution="1920x1080" fps="60">
<stream url="rtsp://server.company.com:554/cloudapi.cgi?fh2f4hw2" codec="h264" resolution="640x480" fps="5">
<stream url="https://server.company.com:443/cloudapi.cgi?fh2fhsw3" codec="mjpeg" resolution="1920x1080" fps="20">
<stream url="https://server.company.com:443/cloudapi.cgi?fh2fhsw5" codec="mjpeg">
<stream url="http://server.company.com:80/cloudapi.cgi?fh2fhw3" codec="mjpeg" resolution="1920x1080" fps="20">
<stream url="http://server.company.com:80/cloudapi.cgi?fh2fhw5" codec="mjpeg">
</streams>

HOME

Move the camera to its home position.

Name

HOME ()

Parameters

None

Returns

None

MODIFY_PRESET

Modify an existing Preset.

Name

MODIFY_PRESET ()

Returns

None

MOVE_TO

Have the camera move to location x and y within the specified window.

Name

MOVE_TO ()

Returns

None

NIGHT_MODE

Enable/disable night mode.

Name

NIGHT_MODE ()

Returns

None

PAN_LEFT

Pan to the left.

Name

PAN_LEFT ()

Parameters

None

Returns

None

PAN_RIGHT

Pan to the right.

Name

PAN_RIGHT ()

Parameters

None

Returns

None

PAN_SCAN

Have the camera execute a complete scan from left to right.

Name

PAN_SCAN ()

Parameters

None

Returns

None

PRESET

Set the camera to preset location. This command is used with the original camera proxy Composer Pro UI (pre-O.S. 4.0.0) in conjunction with the number_presets capability.

Name

NIGHT_MODE ()

Returns

None

SELECT_PRESET

Set the camera to preset location. This command is used with the updated camera proxy Composer Pro UI style (post-O.S. 4.0.0) in conjunction with the has_dynamic_presets capability.

Name

SELECT_PRESET ()

Returns

None

SET_ADDRESS

Set the camera address.

Name

SET_ADDRESS ()

Returns

None

SET_AUTHENTICATION_REQUIRED

Composer Pro command to set whether or not authentication is required

Name

SET_AUTHENTICATION_REQUIRED ()

Returns

None

Usage Note

See the DriverWorks API documentation for URL Interface API: POST for Authentication information.

SET_AUTHENTICATION_TYPE

Composer Pro command to set whether or not authentication is required

Name

SET_AUTHENTICATION_TYPE ()

Returns

None

Usage Note

Note that as of 2.5.3 only Basic Authentication is supported. See the DriverWorks API documentation for URL Interface API: POST for Authentication information.

SET_USERNAME

Composer Pro command to set the Authentication username.

Name

SET_USERNAME ()

Returns

None

Usage Note

See the DriverWorks API documentation for URL Interface API: POST for Authentication information.

SET_HTTP_PORT

Composer Pro command to set the HTTP Port

Name

SET_HTTP_PORT ()

Returns

None

SET_RSTP_PORT

Composer Pro Command to set the Rapid Spanning Tree Protocol port.

Name

SET_RSTP_PORT ()

Returns

None

SET_PASSWORD

ComposerPro command to set the Authentication password.

Name

SET_PASSWORD ()

Returns

None

SET_PUBLICLY_ACCESSIBLE

Composer Pro command to set whether or not the camera can be accessed from public Internet.

Name

SET_PUBLICLY_ACCESSIBLE ()

Returns

None

SET_SNAPSHOT_REFRESH_RATE

Sets image refresh rate in seconds.

Name

SET_SNAPSHOT_REFRESH_RATE ()

Returns

None

TILT_DOWN

Tilt camera down.

Name

TILT_DOWN ()

Parameters

None

Returns

None

TILT_SCAN

Have the camera execute a complete scan from top to bottom.

Name

TILT_SCAN ()

Parameters

None

Returns

None

TILT_UP

Tilt camera down.

Name

TILT_UP ()

Parameters

None

Returns

None

USE_DEFAULTS

Command to use the camera's factory defaults as defined by the driver capabilities.

Name

USE_DEFAULTS ()

Parameters

None

Returns

None

ZOOM_IN

Zoom canera in.

Name

ZOOM_IN ()

Parameters

None

Returns

None

ZOOM_OUT

Zoom camera out.

Name

ZOOM_OUT ()

Parameters

None

Returns

None

Camera Protocol Notifications

ADDRESS_CHANGED

Notification that the camera's address has a changed. Sent from the API OnNetworkBindingChanged.

Name

ADDRESS_CHANGED ()

Returns

None

DYNAMIC_URLS_CHANGED

Notify used when the configured camera URLS have been changed. The Camera proxy will then force Navigators to refresh any cached URLs.

Name

DYNAMIC_URLS_CHANGED ()

Parameters

None

Returns

None

Example

C4:SendToProxy(PROXY_BINDING, 'DYNAMIC_URLS_CHANGED', { }, 'NOTIFY')

HTTP_PORT_CHANGED

Notification that the HTTP port has changed. Used rarely but applicable in instances where the protocol driver sets the HTTP port.

Name

HTTP_PORT_CHANGED ()

Parameters

None

Returns

None

HTTPS_PORT_CHANGED

Used to update the HTTPS port that will be used when constructing HTTPS URLs.

Name

HTTPS_PORT_CHANGED ()

Returns

None

DYNAMIC_CAPABILITY_CHANGED

Used to Notify the Proxy that the driver would like to change a capabilities value. This is only applicable to capabilities denoted as "Yes" in the Dynamic Capabilities section of this Proxy’s Capabilities section.

Name

DYNAMIC_CAPABILITY_CHANGED ()

Returns

None

Example

NOTIFY.DYNAMIC_CAPABILITIES_CHANGED({supports_color=true}, 5001)

PRESETS_CHANGED

The camera driver should send this notification to the Proxy on startup with the complete presets list. The driver must notify again whenever presets are changed: created, renamed, updated, deleted, or re-ordered. This must include all of the preset data, regardless if a subset of that data has not changed.

Name

PRESETS_CHANGED ()

Parameters

None

Returns

None

Example

C4:SendToProxy(PROXY_BINDING, 'PRESETS_CHANGED', { XML = "<dynamic_presets><max_presets>100</max_presets><preset...</dynamic_presets>" }, 'NOTIFY') `

— Note that formed XML for dynamic_presets should resemble the following:

<dynamic_presets>
    <max_presets> Int of max allowed presets </max_presets>
    <presets>
        <preset>
            <id> preset id </id>
            <name> Base64 encoded name </name>
        </preset>
    …
    </presets>
</dynamic_presets>

PROPERTY_DEFAULTS

Notification sent from the protocol driver through ON DRIVER LATE INIT containing the camera's default properties

Name

PROPERTY_DEFAULTS ()

Returns

None

STREAM_URLS_READY

Notify used for following up to a GET_STREAM_URLS Synchronous call. This Notify will let a UI know that the URL information they requested is ready. The driver must use the same key parameter value that was returned to the UI as the key parameter in this notify.

Examples

An example of the simplest XML used by a driver is shown to the right:

<streams key="1234">
   <stream url="http://192.168.1.150/view_camera.cgi">
</streams>

or

<streams key="1234" camera_address="192.168.1.150">
   <stream url="https://192.168.1.150:443/view_camera.cgi" codec="h264">
   <stream url="http://192.168.1.150:80/view_camera_h265.cgi" codec="h265">
</streams>

This is followed by an example from a camera with more features and can provide more options to allow clients to pick a better stream:

<streams key="1234" camera_address="server.company.com">
<stream url="rtsps://192.168.1.150:554/rtsp.cgi" codec="h265" resolution"1920x1080" fps="60">
<stream url="rtsps://192.168.1.150:554/cloudapi.cgi?fh2f5hw2" codec="h265" resolution"640x480" fps="5">
<stream url="rtsp://192.168.1.150:554/cloudapi.cgi?fh2f4hw1" codec="h264" resolution"1920x1080" fps="60">
<stream url="rtsp://192.168.1.150:554/cloudapi.cgi?fh2f4hw2" codec="h264" resolution"640x480" fps="5">
<stream url="https://192.168.1.150:443/cloudapi.cgi?fh2fhsw3" codec="mjpeg" resolution"1920x1080" fps="20">
<stream url="https://192.168.1.150:443/cloudapi.cgi?fh2fhsw5" codec="mjpeg">
<stream url="http://192.168.1.150:80/cloudapi.cgi?fh2fhw3" codec="mjpeg" resolution"1920x1080" fps="20">
<stream url="http://192.168.1.150:80/cloudapi.cgi?fh2fhw5" codec="mjpeg">
</streams>

USE_HTTPS_CHANGED

Used to update the proxy to tell it to generate HTTPS URLs instead of HTTP URLs.

Name

USE_HTTPS_CHANGED ()

Returns

None

Camera Properties

ADDRESS

The camera Hostname or Internet address. Displayed on the Camera Driver's Properties page in Composer Pro.

AUDIO

Established whether or not audio distribution is supported from the camera. If present, this property is displayed on the Camera Driver's Properties page in Composer Pro.

ASPECT RATIO

Allows for the setting of the desired aspect ratio for camera queries. Navigators use this value when sending a request to a camera. Displayed on the Camera Driver's Properties page in Composer Pro.

Populated by the defined:1 aspect_ratio capability.

ASPECT RATIO LIST

Comma-delimited list of possible aspect ratios that the camera supports. The values here are displayed on the Camera Driver's Properties page in Composer Pro.

AUTHENTICATION REQUIRED

Established whether or not authentication is required. Displayed on the Camera Driver's Properties page in Composer Pro.

AUTHENTICATION TYPE

The type of authentication: "BASIC" or "DIGEST" Displayed on the Camera Driver's Properties page in Composer Pro. Note that prior to O.S Release 2.5.3 only Basic Authentication was supported.

HTTP PORT

The camera’s HTTP port. Displayed on the Camera Driver's Properties page in Composer Pro.

PASSWORD

The password value displayed on the Camera Driver's Properties page in Composer Pro.

PUBLICLY ACCESSIBLE

Can the camera be accessed on public Internet. Displayed on the Camera Driver's Properties page in Composer Pro.

RTSP PORT

The camera’s RTSP port to setup H.264 stream. Displayed on the Camera Driver's Properties page in Composer Pro.

SNAPSHOT REFRESH RATE

The amount of time in seconds for the camera to refresh its image signal. Displayed on the Camera Driver's Properties page in Composer Pro.

USERNAME

The username value. This is displayed on the Camera Driver's Properties page in Composer Pro.

Camera Proxy Extras Interface Library

Extras are configured from the Setting option from the main menu in ComposerPro. The settings option only shows if the has_extras capability is set to true.

Extras Class

Overview

This class provides an interface between instances of the ExtrasObjectBasedClass. This class can cover following use cases:

• Add/Remove/Change Extras Section of an Extras Object
• Add/Remove Extras Object
• Get instance of an existing Extras Object
• Make Extras State/Setup XML strings based on objects provided
• Update Extras Object state

ObjectParameters

Structure that contains all fields needed to initialize ExtrasObject instance

Extras:addObjects

Adds extras object to the container in the section named sectionLabel

New object will be added at the end of the section and will be displayed as the last section element in the CI. In case of object array, Object order in the CI will be in the same order objects were sorted in the input array.

Function Signature:

Extras:addObjects(objects, sectionLabel)

Function Parameters:

Returns:

Extras:getObject

Returns extras object with id no matter the section

Function Signature:

Extras:getObject(id)

Function Parameters:

Returns:

Extras:updateObject

Updates value and hide parameter for the object with objId and sends notification to proxy bound to proxyId

If value or hide is not provided, field value will not change. This methods updates fields and sends Proxy Notification that state has been changed.

Function Signature:

Extras:updateObject(proxyId, objId, newValue, hide)

Function Parameters:

Extras:removeObject

Removes extras object with id no matter the section.

Function Signature:

Extras:removeObject(id)

Function Parameters:

Returns:

Extras:makeSetupXml

This method makes complete XML string to be send as response to GET_EXTRAS_SETUP proxy command.

Function Signature:

Extras:makeSetupXml()

Returns:

Extras:makeStateXml

This method makes complete XML string to be send as response to GET_EXTRAS_STATE proxy command or to be sent after extras object update.

Function Signature:

Extras:makeStateXml()

Returns:

Extras:sendSetup

Builds xml and sends proxy notification EXTRAS_SETUP_CHANGED

Function Signature:

Extras:sendSetup(proxyId)

Extras:sendState

Builds xml and sends proxy notification EXTRAS_STATE_CHANGED

Function Signature:

Extras:sendState(proxyId)

Section

Structure that represent a section. Holds section name and ExtrasObject based classes array.

ExtrasObjectBasedClass

This alias is for all classes that inherits the ExtrasObject class.

Type

string_bool

Alias for values can be provided as hide argument

Type

Extras

Container class for the ExtrasObject based instances (Button, Checkbox ...) This class is used to hold ExtrasObject based instances and to handle XML assembling and sending. This class handles sections as well as = inheritsFrom(nil)

Function Parameters:

Extras:addSection

Adds section to the instance

A Section table will be initialized and added in the self.sections field. The object field of the table type Section will bi initialized as empty table. Section order in the CI will be in the same order section were added in the container class instance.

Function Signature:

Extras:addSection(label)

Function Parameters:

Returns:

Extras:removeSection

Removes the section with the label sectionLabel from the list

This method will remove the section with label sectionLabel and all objects in the section. Section indexes will be changed to fill the empty space but the order will not change.

Function Signature:

Extras:removeSection(sectionLabel)

Function Parameters:

Returns:

Extras:getSection

Returns section table with the label sectionLabel

Function Signature:

Extras:getSection(sectionLabel)

Function Parameters:

Returns:

Extras:changeSection

Moves extras object with id in section named newSection

Function Signature:

Extras:changeSection(id, newSection)

Function Parameters:

Extras:cleanCapability

This method cleans the has_extras capability.

Function Signature:

Extras:cleanCapability()

Extras:setCapability

This method sets the has_extras capability.

Function Signature:

Extras:setCapability()

ExtrasButton

Overview

This class represents an abstraction of the Extras Button object. The class interface provides following cations:

• Initialization of an Extras Button object
• Setting Extras Button object parameters (label, button text, etc)

ExtrasButton : ExtrasObject

Class that represent extras button functionality. This class is derived from ExtrasObject. Instance of the class can be created independently but will not be displayed alone, it should be added to the instance of the Extras class.rasButton = inheritsFrom(ExtrasObject)

ExtrasButton:construct

ExtrasButton constructor

Function Signature:

ExtrasButton:construct(objParams, text)

Function Parameters:

ExtrasButton:makeSetupXml

Returns XML string that represents the button setup with all extra parameters

Makes XML that should be integrated in the response to GET_EXTRAS_SETUP Proxy message.

Function Signature:

ExtrasButton:makeSetupXml()

Returns:

ExtrasButton:getStateXml

Returns XML string that represents extras object state

This method overrides the method from the base class. This string should be incorporated in response to GET_EXTRAS_STATE command. id and value fields will be escaped and integrated in the string.

The string will be return in the following command: - \<object id= "\[self.id]" value="\[self.value]" /\>

Function Signature:

ExtrasButton:getStateXml()

Returns:

ExtrasCheckbox

Overview

This class represents an abstraction of the Extras Checkbox object. The class interface provides following cations:

• Initialization of an Extras Checkbox object
• Setting Extras Checkbox object parameters and value

ExtrasCheckbox : ExtrasObject

Class that represent extras checkbox functionality. This class is derived from ExtrasObject. Instance of the class can be created independently but will not be displayed alone, it should be added to the instance of the Extras class.rasCheckbox = inheritsFrom(ExtrasObject)

ExtrasCheckbox:construct

ExtrasCheckbox constructor

Function Signature:

ExtrasCheckbox:construct(objParams, value)

Function Parameters:

ExtrasCheckbox:makeSetupXml

Returns XML string that represents the button setup with all extra parameters

Makes XML that should be integrated in the response to GET_EXTRAS_SETUP Proxy message.

Function Signature:

ExtrasCheckbox:makeSetupXml()

Returns:

ExtrasIcon

Overview

This class represents an abstraction of the Extras Icon object. The class interface provides following cations:

• Initialization of an Extras Icon object
• Setting Extras Icon object parameters and value

ExtrasIcon : ExtrasObject

Class that represent extras icon functionality. This class is derived from ExtrasObject. Instance of the class can be created independently but will not be displayed alone, it should be added to the instance of the Extras class.rasIcon = inheritsFrom(ExtrasObject)

ExtrasIcon:construct

ExtrasIcon constructor

Function Signature:

ExtrasIcon:construct(objParams, value)

Function Parameters:

ExtrasIcon:makeSetupXml

Returns XML string that represents the button setup with all extra parameters

Makes XML that should be integrated in the response to GET_EXTRAS_SETUP Proxy message.

Function Signature:

ExtrasIcon:makeSetupXml()

Returns:

ExtrasList

Overview

This class represents an abstraction of the Extras List object. The class interface provides following cations:

• Initialization of an Extras List object
• Setting Extras Checkbox object parameters and list parameters
• Setting the currently selected item

ExtrasListParameters

ExtrasList : ExtrasObject

Class that represent extras list functionality. This class is derived from ExtrasObject. Instance of the class can be created independently but will not be displayed alone, it should be added to the instance of the Extras class.rasList = inheritsFrom(ExtrasObject)

ExtrasList:construct

ExtrasList constructor

Function Signature:

ExtrasList:construct(objParams, listParams)

Function Parameters:

ExtrasList:makeListXml

Returns the xml string needed to for response to the GET_EXTRAS_SETUP proxy message.

Returns complete list tag. This tag should be a child tag of the object tag.

Function Signature:

ExtrasList:makeListXml()

Returns:

ExtrasList:makeSetupXml

Returns XML string that represents the list setup with all extra parameters

Makes XML that should be integrated in the response to GET_EXTRAS_SETUP Proxy message.

Function Signature:

ExtrasList:makeSetupXml()

Returns:

ExtrasNumber

Overview

This class represents an abstraction of the Extras Number object. The class interface provides following cations:

• Initialization of an Extras Number object
• Setting Extras Number object parameters, number parameters

ExtrasNumber : ExtrasObject

Class that represent extras number functionality. This class is derived from ExtrasObject. Instance of the class can be created independently but will not be displayed alone, it should be added to the instance of the Extras class.rasNumber = inheritsFrom(ExtrasObject)

ExtrasNumber:construct

ExtrasNumber constructor

Function Signature:

ExtrasNumber:construct(objParams, numberParams)

Function Parameters:

ExtrasNumber:makeSetupXml

Returns XML string that represents the button setup with all extra parameters

Makes XML that should be integrated in the response to GET_EXTRAS_SETUP Proxy message.

Function Signature:

ExtrasNumber:makeSetupXml()

Returns:

ExtrasObject

ExtrasObject

Base class for classes that represent extras objects (button, checkbox ...) Should not create independent instance from this class This class only purpose is to be base class for extras object classesrasObject = inheritsFrom(nil)

ExtrasObject:construct

ExtrasObject constructor

Function Signature:

ExtrasObject:construct(objParams)

Function Parameters:

ExtrasObject:addExtraparam

Adding extra parameter to the Object instance

If extra parameter is added, tParams argument of the Proxy command will contain value of the extras object with id.

Function Signature:

ExtrasObject:addExtraparam(id, name)

Function Parameters:

ExtrasObject:removeExtraparam

Removing extra parameter from the list

This method will remove extra parameter with id and value of that extras object will not be received in proxy command.

Function Signature:

ExtrasObject:removeExtraparam(id)

Function Parameters:

ExtrasObject:getStateXml

Returns XML string that represents extras object state

This string should be incorporated in response to GET_EXTRAS_STATE command. id and value fields will be escaped and integrated in the string. The string will be return in the following command: `- \<object id= "\[self.id]" value="\self.value" /> ``

Function Signature:

ExtrasObject:getStateXml()

Returns:

ExtrasObject:getExtraparamsXml

Returns XML string that represents list of extraparameters

This string should be incorporated in response to GET_EXTRAS_SETUP Key and value of the extraparams field will be escaped end integrated in the message.

Function Signature:

ExtrasObject:getExtraparamsXml()

Returns:

ExtrasObject:update

Update extras object individually.

This method should be called when the user wants to udate an object individually. The method from the Extras class will update all objects, this method will update just this on object. Also, this method is inherited by all ExtrasObjectBasedClass instances.

Function Signature:

ExtrasObject:update(value, hidden)

Function Parameters:

ExtrasSlider : ExtrasObject

Class that represent extras slider functionality. This class is derived from ExtrasObject. Instance of the class can be created independently but will not be displayed alone, it should be added to the instance of the Extras class.rasSlider = inheritsFrom(ExtrasObject)

ExtrasSlider:construct

ExtrasSlider constructor

Function Signature:

ExtrasSlider:construct(objParams, sliderParams)

Function Parameters:

ExtrasSlider:makeSetupXml

Returns XML string that represents the button setup with all extra parameters

Makes XML that should be integrated in the response to GET_EXTRAS_SETUP Proxy message.

Function Signature:

ExtrasSlider:makeSetupXml()

Returns:

ExtrasObject

Base class for classes that represent extras objects (button, checkbox ...) Should not create independent instance from this class This class only purpose is to be base class for extras object classesrasObject = inheritsFrom(nil)

ExtrasObject:construct

ExtrasObject constructor

Function Signature:

ExtrasObject:construct(objParams)

Function Parameters:

ExtrasObject:addExtraparam

Adding extra parameter to the Object instance

If extra parameter is added, tParams argument of the Proxy command will contain value of the extras object with id.

Function Signature:

ExtrasObject:addExtraparam(id, name)

Function Parameters:

ExtrasObject:removeExtraparam

Removing extra parameter from the list

This method will remove extra parameter with id and value of that extras object will not be received in proxy command.

Function Signature:

ExtrasObject:removeExtraparam(id)

Function Parameters:

ExtrasObject:getStateXml

Returns XML string that represents extras object state

This string should be incorporated in response to GET_EXTRAS_STATE command. id and value fields will be escaped and integrated in the string.The string will be return in the following command: - \<object id= "\[self.id]" value="\[self.value]" /\>

Function Signature:

ExtrasObject:getStateXml()

Returns:

ExtrasObject:getExtraparamsXml

Returns XML string that represents list of extraparameters

This string should be incorporated in response to GET_EXTRAS_SETUP Key and value of the extraparams field will be escaped end integrated in the message.

Function Signature:

ExtrasObject:getExtraparamsXml()

Returns:

ExtrasObject:update

Update extras object individually.

This method should be called when the user wants to update an object individually. The method from the Extras class will update all objects, this method will update just this on object. Also, this method is inherited by all ExtrasObjectBasedClass instances.

Function Signature:

ExtrasObject:update(value, hidden)

Function Parameters:

ExtrasSlider

Overview

This class represents an abstraction of the Extras Slider object. The class interface provides following cations:

• Initialization of an Extras Slider object
• Setting Extras Slider object parameters and slider parameters

ExtrasSlider : ExtrasObject

Class that represent extras slider functionality. This class is derived from ExtrasObject. Instance of the class can be created independently but will not be displayed alone, it should be added to the instance of the Extras class.rasSlider = inheritsFrom(ExtrasObject)

ExtrasSlider:construct

ExtrasSlider constructor

Function Signature:

ExtrasSlider:construct(objParams, sliderParams)

Function Parameters:

ExtrasSlider:makeSetupXml

Returns XML string that represents the button setup with all extraparameters

Makes XML that should be integrated in the response to GET_EXTRAS_SETUP Proxy message.

Function Signature:

ExtrasSlider:makeSetupXml()

Returns:

ExtrasSwitch

Overview

This class represents apstraction of the Extras Switch object. The class interface provides following cations:

• Initialization of an Extras Switch object
• Setting Extras Switch object parameters and value

ExtrasSwitch : ExtrasObject

Class that represent extras switch functionality. This class is derived from ExtrasObject. Instance of the class can be created independently but will not be displayed alone, it should be added to the instance of the Extras class.rasSwitch = inheritsFrom(ExtrasObject)

ExtrasSwitch:construct

ExtrasSwitch constructor

Function Signature:

ExtrasSwitch:construct(objParams, value)

Function Parameters:

ExtrasSwitch:makeSetupXml

Returns XML string that represents the button setup with all extraparameters

Makes XML that should be integrated in the response to GET_EXTRAS_SETUP Proxy message.

Function Signature:

ExtrasSwitch:makeSetupXml()

Returns:

ExtrasText

Overview

This class represents an abstraction of the Extras Text object. The class interface provides following cations:

• Initialization of an Extras Text object
• Setting Extras Text object parameters and value

ExtrasText : ExtrasObject

Class that represent extras text functionality. This class is derived from ExtrasObject. Instance of the class can be created independently but will not be displayed alone, it should be added to the instance of the Extras class.rasText = inheritsFrom(ExtrasObject)

ExtrasText:construct

ExtrasText constructor

Function Signature:

ExtrasText:construct(objParams, value)

Function Parameters:

ExtrasText:makeSetupXml

Returns XML string that represents the button setup with all extraparameters

Makes XML that should be integrated in the response to GET_EXTRAS_SETUP Proxy message.

Function Signature:

ExtrasText:makeSetupXml()

Returns:

ExtrasTextField

Overview

This class represents abstraction of the Extras Text Field object. The class interface provides following cations:

• Initialization of an Extras Text Field object
• Setting Extras Text Field object parameters, text field mode and value

TextFieldMode

Type

ExtrasTextField : ExtrasObject

Class that represent extras checkbox functionality. This class is derived from ExtrasObject. Instance of the class can be created independently but will not be displayed alone, it should be added to the instance of the Extras class.rasTextField = inheritsFrom(ExtrasObject)

ExtrasTextField:construct

ExtrasTextField constructor

Function Signature:

ExtrasTextField:construct(objParams, value, mode)

Function Parameters:

ExtrasTextField:makeSetupXml

Returns XML string that represents the button setup with all extraparameters

Makes XML that should be integrated in the response to GET_EXTRAS_SETUP Proxy message.

Function Signature:

ExtrasTextField:makeSetupXml()

Returns:

Extras Library Use Case Examples

Importing the library

To use this library, please move all *.lua files to the source directory of your driver, then import Extras.lua file in your driver.lua file. The Extras.lua file includes all other library files needed.

This library depends on a driver template. Please, make sure that the driver template files are included in the path. NOTE Make sure paths are setup correctly

How to use the library

Set Up

The code to the right is an example how to setup the extras library:

require "Extas"


function ON_DRIVER_INIT.SetupExtras()
    extras = Extras:new(DEFAULT_PROXY_BINDINGID)
    extras:addSection("ButtonLabel")
    extras:addSection("CheckboxLabel")
    local bt1Table = {
        id = "Button1ID",
        label = "Button 1 Label",
        command = "Button1Command",
        extraparams = {
            Checkbox4ID = "Extr1",
            Checkbox3ID = "Extr2",
            Button2ID = "Extr3"
            }
        }
    extras:addObjects({ExtrasButton:new(bt1Table, "ButtonText1"),
           ExtrasButton:new({id = "Button3ID", label = "Button 3 Label", command = "Button1Command"}, "ButtonText3"),
           ExtrasButton:new({id = "Button2ID", label = "Button 2 Label", command = "Button1Command"}, "ButtonText2"),
           ExtrasButton:new({id = "Button4ID", label = "Button 4 Label", command = "Button1Command"}, "ButtonText4")},
           "ButtonLabel")
    extras:addObjects({ExtrasCheckbox:new({id = "Checkbox1ID", label = "Checkbox 1 Label", command = "Checkbox1Command"}, "true"),
           ExtrasCheckbox:new({id = "Checkbox2ID", label = "Checkbox 2 Label", command = "Checkbox1Command"}, "true"),
           ExtrasCheckbox:new({id = "Checkbox3ID", label = "Checkbox 3 Label", command = "Checkbox1Command"}, "true"),
           ExtrasCheckbox:new({id = "Checkbox4ID", label = "Checkbox 4 Label", command = "Checkbox1Command"}, "true")},
           "CheckboxLabel")
    extras:sendSetup(DEFAULT_PROXY_BINDINGID)
end

• Section order in the CI will be in the same order section were added in the container class instance.
• Object order in the CI will be in the same order objects were added in the section.
• Remember that object could be added as separated elements or as an array of objects.
• This setup can be called in DriverLateInit(). Setting extras in the DriverInit() callback is possible but not recommended.

Handling Proxy Commands

The next code example shows how to write handlers for proxy commands received when extras change:

-- Proxy Command Handlers


PRX_CMD.Button1Command(proxyId, tParams)
    C4:SetVariable("Extras_Button1", os.date())
    LogDebug(os.date() .. " " .. extras:getObject(tParams.id).label .. " - Extras Button pressed")
end

function PRX_CMD.Checkbox1Command(proxyId, tParams)
    C4:SetVariable("Extras_Checkbox1", tParams.value)
    LogDebug(os.date() .. " " .. extras:getObject(tParams.id).label .. " - Extras Checkbox switched")
    extras:updateObject(proxyId, tParams.id, tParams.value)
end

To handle changes in extras parameters coming from the device side, the updateObject method can be used. This method updates extras object instance and sends proxy notification that extras status has been changed. Also, each ExtrasObjectBasedClass class supports the ExtrasObjectBasedClass:update(value, hidden) method that enables extras update from the class instance directly.

It is nice to create a variable for each extras object, to give the partner opportunity to monitor and take action based on extras states. Sample variable definitions are to the right.

--Variable Examples

C4:AddVariable("Extras_Button1", "", "STRING")
C4:AddVariable("Extras_Checkbox1", "", "BOOL")

Sqishy

If the Lua Squish is used, the Module code snippet below should be included in the squishy file:

-- Lua Squish Sample

Module "Extras" "extras/Extras.lua"
Module "ExtrasObject" "extras/ExtrasObject.lua"
Module "ExtrasButton" "extras/ExtrasButton.lua"
Module "ExtrasCheckbox" "extras/ExtrasCheckbox.lua"
Module "ExtrasIcon" "extras/ExtrasIcon.lua"
Module "ExtrasList" "extras/ExtrasList.lua"
Module "ExtrasSwitch" "extras/ExtrasSwitch.lua"
Module "ExtrasNumber" "extras/ExtrasNumber.lua"
Module "ExtrasSlider" "extras/ExtrasSlider.lua"
Module "ExtrasText" "extras/ExtrasText.lua"
Module "ExtrasTextField" "extras/ExtrasTextField.lua"

In this case, the library can be used as git submodule.

Removing

To remove the object or the section please use following methods:

• Extras:removeObject(id)
• Extras:removeSection(sectionLabel)

This way, you will avoid lost objects (objects that are in section array but will not be displayed because empty index before). It is strongly recommended to hide rather than remove objects that will be temporary removed form the CI.

Before destroying an Extras class instance, please use the Extras:cleanCapability() method. Also, please pay attention to the Capability section of the documentation.

Camera Capabilities

address_readonly

Defaults to false.

Signature

<address_readonly></address_readonly>

Example

<capabilities>
    <address_readonly>false</address_readonly>
</capabilities>

aspect_ratio

Comma-delimited list of possible aspect ratios that the camera supports. If this capabilities is not defined in the c4i/c4z file, it will default to ‘16x9,4x3’ for aspect_ratio.

Signature

<aspect_ratio></aspect_ratio>

Example

<capabilities>
    <aspect_ratio>false</aspect_ratio>
</capabilities>

default_aspect_ratio

The expected ratio that the camera will use at start up. The value in the default_aspect_ratio capability should be one of the entries in the aspect_ratios list. If this capabilities is not defined in the c4i/c4z file, it will default to 16x9.

Signature

<deafult_aspect_ratio></default_aspect_ratio>

Example

<capabilities>
    <default_aspect_ratio>false</default_aspect_ratio>
</capabilities>

default_authentication_required

Defaults to false.

Signature

<default_authentication_required></default_authentication_required

Example

<capabilities>
    <default_authentication_required>false</default_authentication_required>
</capabilities>

default_authentication_type

Defaults to BASIC.

Signature

<default_authentication_type></default_authentication_type>

Example

<capabilities>
    <default_authentication_type>BASIC</default_authentication_type>
</capabilities>

default_http_port

Defaults to 80.

Signature

<default_http_port></default_http_port>

Example

<capabilities>
    <default_http_port>80</default_http_port>
</capabilities>

default_password

Defaults to “password”.

Signature

<default_password></default_password>

Example

<capabilities>
    <default_password>password</default_password>
</capabilities>

default_rtsp_port

Defaults to 554.

Signature

<default_rtsp_port></default_rtsp_port>

Example

<capabilities>
    <default_rtsp_port>554</default_rtsp_port>
</capabilities>

default_username

Defaults to “username”.

Signature

<default_username></default_username>

Example

<capabilities>
    <default_username>username</default_username>
</capabilities>

dynamic_urls_use_type

Support the following use types:

MULTIPLE - Default if the capability is not specified. URLs can be used repeatedly. If URLs change, the driver should send DYNAMIC_URLS_CHANGED notification to the proxy.

SINGLE - URLs can only be used once. Driver must be asked each time for a new set of URLs.

Signature

<dynamic_urls_use_type></dynamic_urls_use_type>

Dynamic Capability

Yes

Example

<capabilities>
    <dynamic_urls_use_type>SINGLE</dynamic_urls_use_type>
</capabilities>

has_dynamic_presets

Returns true if the cameras support for dynamic presets. Defaults to false. See the Camera Proxy and Presets documentation for more information.

Signature

<has_dynamic_presets></has_dynamic_presets>

Example

C4:SendToProxy(PROXY_BINDING, 'DYNAMIC_CAPABILITIES_CHANGED', { has_dynamic_presets = true }, 'NOTIFY')

has_extras

Boolean indicating if the device has extras commands support. This capability can be changed through a DYNAMIC_CAPABILITIES_CHANGED  notification.

Signature

<has_extras></has_extras>

Dynamic Capability

Yes

Example

<capabilities>
    <has_extras>TRUE</has_extras>
</capabilities>

has_ pan

True/False. Default is False. This is a Dynamic Capability.

Signature

<has_pan></has_pan>

Example

<capabilities>
    <has_pan>false</has_pan>
</capabilities>

has_pan_scan

True/False. Default is False.

Signature

<has_pan_scan></has_pan_scan>

Example

<capabilities>
    <has_pan_scan>false</has_pan_scan>
</capabilities>

has_tilt

True/False. Default is False. This is a Dynamic Capability.

Signature

<has_tilt></has_tilt>

Example

<capabilities>
    <has_tilt>false</has_tilt>
</capabilities>

has_tilt_scan

True/False. Default is False.

Signature

<has_tilt_scan></has_tilt_scan>

Example

<capabilities>
    <has_tilt_scan>false</has_tilt_scan>
</capabilities>

has_zoom

True/False. Default is False. This is a Dynamic Capability.

Signature

<has_zoom></has_zoom>

Example

<capabilities>
    <has_zoom>false</has_zoom>
</capabilities>

has_home

True/False. Default is False. This is a Dynamic Capability.

Signature

<has_home></has_home>

Example

<capabilities>
    <has_home>false</has_home>
</capabilities>

has_night_mode

True/False. Default is False.

Signature

<has_night_mode></has_night_mode>

Example

<capabilities>
    <has_night_mode>false</has_night_mode>
</capabilities>

modes

Signature

<modes></modes>

Example

<capabilities>
    <modes>MJPEG</modes>
</capabilities>

number_presets

Defines the number of presets displayed on the UI. See the Camera Proxy and Presets documentation for more information.

Signature

<number_presets></number_preets>

Usage Note

Default is 0. Note that Navigator devices will truncate this value to a supported number.

Example

<capabilities>
    <number_presets>6</number_presets>
</capabilities>

requires_dynamic_stream_urls

Whether the camera should be asked for stream URLs through the more advanced API call.

Signature

<requires_dynamic_stream_urls></requires_dynamic_stream_urls>

Type

Boolean: Defaults to false.

Dynamic Capability

Yes

Example

<capabilities>
    <requires_dynamic_stream_urls>true</requires_dynamic_stream_urls>
</capabilities>

show_test_url

Signature

<show_test_url></show_test_url>

Usage Note

Default is True.

Example

<capabilities>
    <show_test_url>true</show_test_url>
</capabilities>

use_http_for_h264

Signature

<use_http_for_h264> </use_http_for_h264> 

Usage Note

Default is False.

Example

<capabilities>
    <use_http_for_h264>true</use_http_for_h264>
</capabilities>