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 2022 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

Proxies (Commands)

A proxy driver is an interface to the Control4 system for a set of devices that share common functionality. For instance, most DVD disc changers have common controls such as PLAY, STOP, PAUSE and FAST FORWARD.  The disc changer proxy allows for a common user interface to control all disc changers.  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 3.3.0

Light Proxy Color Enhancements

This release of the 3.3.0 beta Proxy and Protocol Guide has been delivered to support the Light Proxy’s new color management functionality. This includes:

Light V2 Proxy Capabilities

color_correlated_temperature_max

color_correlated_temperature_min

color_rate_behavior

color_rate_max

color_rate_min

color_trace_tolerance

supports_color

supports_color_correlated_temperature

Light V2 Proxy Commands

ADD_DRIVER_COLOR_PRESET

DELETE_DRIVER_COLOR_PRESET

MODIFY_DRIVER_COLOR_PRESET

SET_COLOR_TARGET

Light V2 Proxy Conversion Commands

This section lists the Commands used for converting to/from hue, saturation and lightness (HSV) and red, blue and green (RGB).

Light V2 Proxy Conditionals

IS_COLOR

Light v2 Protocol Notifications

LIGHT_COLOR_CHANGED

LIGHT_COLOR_CHANGING

Light V2 Proxy Events

light_color_changed

light_color_changing

Light V2 Proxy Variables

color_active_agents

color_presets

Light V2 Proxy Extras

New supporting documentation.

Advanced Lighting Scene Agent 

New supporting documentation.

Light Driver Development Best Practices

A new section has been added to the Light V2 proxy content including best practice recommendations for light driver developers.

Audio Video Switch Display Adjustable Bindings

O.S. releases 3.3.0 provides the ability to hide AV Switch Bindings that are not being used. This feature has been provided to better manage the UI display within ComposerPro.

What’s New in 3.2.3

Audio Equalization available on Navigators

The Amplifier and AV Switch Proxies have been enhanced to support the ability to display audio EQ functions on devices running Navigator. The enhancement includes a set of new Proxy Commands, Notifications and Capabilities to support this functionality.

Dynamic Transport Controls on Navigators

Audio Video drivers now have the ability to define which transport controls are displayed on Navigators. This includes which buttons appear on the Button Bar as well as the Media Dashboard. This enhancement allows for the appropriate transport controls being displayed for each AV device.

What’s New in 3.2.2

There were no changes to this content for Operating System 3.2.2.

What’s New in 3.2.1

There were no changes to this content for Operating System 3.2.1.

What’s New in 3.2.0

Proxies that were Modified** 

Security Proxy The REQUEST_DEFAULT_USER_CODE partition notification was added as a mechanism for the protocol driver to initiate the communication to get that default user code upon driver update.

The following Security Protocol Notifications were deprecated from the SDK: ALARM, ALARM_CLEAR, AWAY, DISARM, HOME, TROUBLE. Please see the Security Panel Notification and Security Partition Notification areas for the latest list of Notifies.

What was New in 3.1.2

Proxies that were Deprecated** 

The following Proxies were deprecated from the Proxy and Protocol Guide:

• iPod
• Load Controller

What was New in 3.1.0

Proxies that were Modified** 

Light V2 Proxy light sample.c4i - A sample driver has been included to assist with better understanding the basic flow of commands from the Light Proxy as well as receiving protocol notifications. The driver can be found in the Samples directory under the root level of the DriverWorks SDK.zip file

Media Service Proxy Detail Screen Type - Information regarding the implementation of the Detail Type Screen has been added to the documentation.

What was New in O.S.3

Proxies that were Modified** 

KeyPad Proxy

New Button Linking functionality has been added to the Proxy. Button Linking supports the ability of a driver interacting with a second driver using Button State and Button LED State.

Light (V2) Proxy LightV2 Proxy has been significantly enhanced in this release. It is recommended that Light Driver writers thoroughly review the Proxy content in this release. The changes included not only impact drivers written against OS 3. Previously delivered Light Proxy elements have been modified or in some cases deprecated.

In OS 3, the proxy has been conceptually split into two components. The first being a Wall Control/Keypad portion and the second is a redesigned Light portion.The Light portion has been developed as a Bulb Library. The ultimate goal of the Bulb Library is to support ,more versatility for drivers to interrogate, group, control and manage individual drivers and bulbs. Bulb color, target level, minimum and maximum levels, cold start timing and other features are implemented in the Bulb Library. Dynamic Capabilities have also been added to the Light Portion. Note that all changes maintain backwards compatibility for driver side interaction. However, Navigators will have functionality deprecated due to performance reasons or improved ways of communicating with the driver.

Media Service Proxy Favoriting: In conjunction with the ability to "Favorite" Navigator UI screens in OS 3, drivers written using the Media Service Proxy can now provide the ability for end users to designate favorite media delivered through an Media Service Proxy driver such as Playlists, Albums, Tracks, Stations, Movies, TV Shows, etc.

DashboardChanged Event: The DashboardChanged event now includes content on the use of custom icons and actions.

Driver Notification Context Example: New code examples on have been added to the Media Service Proxy Driver Notification Prototype section in the Appendix.

 Best Practices A new section called Best Practices has been added to the Proxy and Protocol Guide. This section contains information regarding the use cases that fall outside of the typical Proxy/Protocol driver implementation. This release contains Best Practice content on the following:

Using the new Proxy-less command UPDATE PROPERTY. This is a non proxy-specific function that can be called from any device to change a property of any other device.

OS 3 Navigator UI and Volume Control - Managing Volume Commands in conjunction with the use of OS 3's new volume control slider on the Control4 UI.

Amplifier Protocol Notifications

AUDIO PARAMETER CHANGED

Audio parameter has changed

Signature

AUDIO_PARAMETER_CHANGED ()

Returns

None

BALANCE LEVEL CHANGED

Selected balance level has changed.

Signature

BALANCE_LEVEL_CHANGED ()

Returns

None

BASS LEVEL CHANGED

Selected bass level has changed

Signature

BASS_LEVEL_CHANGED ()

Returns

None

INPUT OUTPUT CHANGED

Selected inputs & outputs have changed.

Signature

INPUT_OUTPUT_CHANGED ()

Returns

None

LOUDNESS CHANGED

Loudness state (On/Off) has changed.

Signature

LOUDNESS_CHANGED ()

Returns

None

MUTE CHANGED

MUTE state (On/Off) has changed.

Signature

MUTE_CHANGED ()

Returns

None

OFF

Device has turned off.

Signature

OFF ()

Parameter

None

Returns

None

ON

Device has turned on.

Signature

ON ()

Parameter

None

Returns

None

TREBLE LEVEL CHANGED

Selected treble level has changed.

Signature

TREBLE_LEVEL_CHANGED ()

Returns

None

VOLUME LEVEL CHANGED

Selected volume level has changed.

Signature

VOLUME_LEVEL_CHANGED ()

Returns

None

Amplifier Proxy Capabilities

audio consumer count

Count of number of audio consumers (inputs) of the device. This value must match the number of connections in the driver.

Signature

<audio_consumer_count></audio_consumer_count>

Example

<capabilities>
   <audio_consumer_count>8</audio_consumer_count>
</capabilities>

audio provider count

Count of number of audio providers (outputs) of the device. This value must match the number of connections in the driver.

Signature

<audio_provider_count></audio_provider_count>

Example

<capabilities>
   <audio_provider_count>8</audio_provider_count>
</capabilities>

can downclass

Specifies if the device switch can down convert. For example: S-Video -> Composite

Signature

<can_downclass></can_downclass>

Example

<capabilities>
   <can_downclass>true</can_downclass>
</capabilities>

can switch separately

Device specific capability that must be set to True to in order for a device’s Composer Pro interface reflecting independent audio and video signal switching.

Signature

<can_switch_separately></can_switch_separately>

Usage Note

This capability is not related with the requires separate switching capability.  A setting of True or False will have no impact on requires separate switching.

Example

<capabilities>
   <can_switch_separately>true</can_switch_separately>
</capabilities>

can upclass

Specifies if the device switch can up convert. For example: Composite -> S-Video

Signature

<can_upclass></can_upclass>

Example

<capabilities>
   <can_upclass>true</can_upclass>
</capabilities>

has audio signal sense

Specifies device switching is capable of sensing audio on an input. This is useful in triggering programming in ComposerPro based on the this setting.

Signature

<has_audio_signal_sense></has_audio_signal_sense>

Example

<capabilities>
   <has_audio_signal_sense>true</has_audio_signal_sense>
</capabilities>

has discrete balance control

Capable of directly specifying a balance setting.

Signature

<has_discrete_balance_control></has_discrete_balance_control>

Example

<capabilities>
   <has_discrete_balance_control>true</has_discrete_balance_control>
</capabilities>

has discrete bass control

Capable of directly specifying a bass setting.

Signature

<has_discrete_bass_control></has_discrete_bass_control>

Example

<capabilities>
   <has_discrete_bass_control>true</has_discrete_bass_control>
</capabilities>

has discrete loudness control

Capable of directly specifying a loudness setting.

Signature

<has_discrete_loudness_control></has_discrete_loudness_control>

Example

<capabilities>
   <has_discrete_loudness_control>true</has_discrete_loudness_control>
</capabilities>

has discrete mute control

Capable of directly specifying mute ON or OFF setting.

Signature

<has_discrete_ mute_control></has_discrete_ mute_control>

Example

<capabilities>
   <has_discrete_mute_control>true</has_discrete_mute_control>
</capabilities>

has discrete treble control

Capable of directly specifying a treble setting.

Signature

<has_discrete_treble_control></has_discrete_treble_control>

Example

<capabilities>
   <has_discrete_treble_control>true</has_discrete_treble_control>
</capabilities>

has discrete volume control

Capable of directly specifying a volume setting.

Signature

<has_discrete_volume_control></has_discrete_volume_control>

Example

<capabilities>
   <has_discrete_volume_control>true</has_discrete_volume_control>
</capabilities>

has discrete loudness control

Capable of handling ON/OFF loudness control.

Signature

<has_discrete_loudness_control></has_discrete_loudness_control>

Example

<capabilities>
   <has_discrete_loudness_control>true</has_discrete_loudness_control>
</capabilities>

has toggle mute control

Capable of handling ON/OFF mute control.

Signature

<has_toggle_mute_control></has_toggle_mute_control>

Example

<capabilities>
   <has_toggle_mute_control>true</has_toggle_mute_control>
</capabilities>

has up down balance control

Capable of directly specifying a balance setting.

Signature

<has_up_down_balance_control></has_up_down_balance_control>

Example

<capabilities>
   <has_up_down_balance_control>true</has_up_down_balance_control>
</capabilities>

has up down bass control

Capable of directly specifying a bass setting.

Signature

<has_up_down_bass_control></has_up_down_bass_control>

Example

<capabilities>
   <has_up_down_bass_control>true</has_up_down_bass_control>
</capabilities>

has up down treble control

Capable of directly specifying a treble setting.

Signature

<has_up_down_treble_control></has_up_down_treble_control>

Example

<capabilities>
   <has_up_down_treble_control>true</has_up_down_treble_control>
</capabilities>

has up down volume control

Has capability of handling volume UP and DOWN adjustments.

Signature

<has_up_down_volume_control></has_up_down_volume_control>

Example

<capabilities>
   <has_up_down_volume_control>true</has_up_down_volume_control>
</capabilities>

has video signal sense

Specifies if the device switching is capable of sensing video on an input. This is useful in triggering programming in ComposerPro based on the this setting.

Signature

<has_video_signal_sense></has_video_signal_sense>

Example

<capabilities>
   <has_video_signal_sense>true</has_video_signal_sense>
</capabilities>

requires separate switching

Device specific capability that when set to True notifies Director of the existence of individual audio and video paths. This capability has no impact on Composer Pro user interface. For that reason, when set to True it is recommended that the capability can switch separately be set to True as well.

Signature

<requires_separate_switching></requires_separate_switching>

Example

<capabilities>
   <requires_separate_switching>true</requires_separate_switching>
</capabilities>

video consumer count

Count of number of video consumers (inputs) of the device. This value must match the number of connections in the driver.

Signature

<video_consumer_count></video_consumer_count>

Example

<capabilities>
   <video_consumer_count>8</video_consumer_count>
</capabilities>

video provider count

Count of number of video providers (outputs) of the device. This value must match the number of connections in the driver.

Signature

<video_provider_count></video_provider_count>

Example

<capabilities>
   <video_provider_count>8</video_provider_count>
</capabilities>

Amplifier Navigator EQ

Introduction

The ability to display audio equalization controls on devices running Navigator was added in conjunction with Operating System 3.2.3. Currently, the only Proxies that support Navigator EQ controls are the Amplifier and AV Switch Proxies.

The majority of the of the commands, notifications and capabilities defined here must be implemented in your driver to display EQ controls. Several commands are optional including SET_AUDIOMODE_BYPASS, SET_AUDIOMODE_EQ and SET_AUDIOMODE_TONECONTROL as these have been included to suspect legacy Audio Matrix Switches.

Note that this functionality is disabled by default. The HIDE EQ FROM NAVS CHANGED notification must be sent with a value of False to enable the EQ functionality in Navigator.

Navigator EQ Proxy Commands

LOUDNESS OFF

Navigator EQ command called to set the loudness off for indicated output. The driver should notify proxy with the LOUDNESS_CHANGED notification of the new value.

Signature

LOUDNESS_OFF

Returns

None

LOUDNESS ON

Navigator EQ command called to set the loudness on for indicated output. The driver should notify proxy with the LOUDNESS_CHANGED notification of the new value.

Signature

LOUDNESS_ON

Returns

None

SET AUDIOMODE BYPASS

Navigator EQ command called to change the output's mode to BYPASS. This is an optional command and should be used only if your device needs to switch modes.

Signature

SET_AUDIOMODE_BYPASS

Returns

None

SET AUDIOMODE EQ

Navigator EQ command called to change the output's mode to EQUALIZER. This is an optional command and should be used only if your device needs to switch modes.

Signature

SET_AUDIOMODE_EQ

Returns

None

SET AUDIOMODE TONECONTROL

Navigator EQ command called to change the output's mode to TONE_CONTROL. This is an optional command and should be used only if your device needs to switch modes.

Signature

SET_AUDIOMODE_TONECONTROL

Returns

None

SAVE EQ TO CUSTOM PRESET

Navigator EQ command called to save the current EQ values to a custom preset with a name. The driver should notify proxy with the EQ_NAMES_CHANGED notification with the updated name.

Signature

SAVE_EQ_TO_CUSTOM_PRESET

Returns

None

SET BASS LEVEL

Navigator EQ command called to set the bass level for tone control. The driver should notify proxy with the BASS_LEVEL_CHANGED notification of the new value.

Signature

SET_BASS_LEVEL

Returns

None

SET EQPRESET

Navigator EQ command called to change the selected preset for an output.

Signature

SET_EQPRESET

Returns

None

SET EQ GAIN VALUES

Navigator EQ command called to set the current equalizer’s gain values.

Signature

SET_EQ_GAIN_VALUES

Returns

None

SET TREBLE LEVEL

Navigator EQ command called to set the treble level for tone control. The driver should notify the proxy with TREBLE_LEVEL_CHANGED notification of the new value.

Signature

SET_TREBLE_LEVEL

Returns

None

Navigator EQ Protocol Notifications

AUDIOMODE CHANGED

Navigator EQ notification that the output's audio mode has changed to either Tone Control or Equalizer for the output. This is an optional notification and should be used only if your device has audio modes.

Signature

AUDIOMODE_CHANGED

Returns

None

BALANCE LEVEL CHANGED

Navigator EQ notification that the balance has changed.

Signature

BALANCE_LEVEL_CHANGED

Returns

None

Example

-- Notify Balance level is set to 'Full Left' for Output 3 (Binding ID 4002)
C4:SendToProxy(5001, "BALANCE_LEVEL_CHANGED", { OUTPUT = "4002", LEVEL = 0 }, "NOTIFY")



-- Notify Balance level is set to 'Center' for Output 3 (Binding ID 4002)
C4:SendToProxy(5001, "BALANCE_LEVEL_CHANGED", { OUTPUT = "4002", LEVEL = 50 }, "NOTIFY")



-- Notify Balance level is set to 'Full Right' for Output 3 (Binding ID 4002)
C4:SendToProxy(5001, "BALANCE_LEVEL_CHANGED", { OUTPUT = "4002", LEVEL = 100 }, "NOTIFY")

BASS LEVEL CHANGED

Navigator EQ notification that the bass has changed.

Signature

BASS_LEVEL_CHANGED

Returns

None

Example

-- Notify Bass Level is at -6 for Output 3 (Binding ID 4002)
C4:SendToProxy(5001, "BASS_LEVEL_CHANGED", { OUTPUT = "4002", LEVEL = -6 }, "NOTIFY") 

-- Notify Bass Level is at +6 for Output 3 (Binding ID 4002)
C4:SendToProxy(5001, "BASS_LEVEL_CHANGED", { OUTPUT = "4002", LEVEL = 6 }, "NOTIFY")

EQ DISPLAY ORDER CHANGED

Navigator EQ notification of the order that the names from EQ_NAMES_CHANGED should be presented to the user.

Signature

EQ_DISPLAY_ORDER_CHANGED

Returns

None

Example

C4:SendToProxy(5001, "EQ_DISPLAY_ORDER_CHANGED", {​​​​​​​ [1] = 1, [2] = 2, [3] = 3, [4] = 4, [5] = 5, OUTPUT = "4002" }​​​​​​​, "NOTIFY")

C4:SendToProxy(5001, "EQ_DISPLAY_ORDER_CHANGED", {​​​​​​​ 1, 2, 3, 4, 5, OUTPUT = "4002" }​​​​​​​, "NOTIFY")

EQ NAMES CHANGED

Navigator EQ notification of the current names for the equalizer presets.

Signature

EQ_NAMES_CHANGED

Returns

None

Example

C4:SendToProxy(5001, "EQ_NAMES_CHANGED", { [1] = "FLAT", [2] = "CLASSICAL", [3] = "JAZZ", [4] = "POP", [5] = "ROCK", OUTPUT = "4002" }, "NOTIFY")

C4:SendToProxy(5001, "EQ_NAMES_CHANGED", {"FLAT", "CLASSICAL", "JAZZ", "POP", "ROCK", OUTPUT = 4002}, "NOTIFY")

EQ FREQS CHANGED

Navigator EQ notification that the frequencies of a equalizer have been modified.

Signature

EQFREQS_CHANGED

Returns

None

Example

-- Notify Gains and Frequencies for EQ Bands for Output 3 (Binding ID 4002)
C4:SendToProxy(5001, "EQGAINS_CHANGED", { OUTPUT = "4002", VALUES = "7.5,3.8,5.4,4.59,7.8,7.4" }, "NOTIFY")_

C4:SendToProxy(5001, "EQFREQS_CHANGED", { OUTPUT = "4002", VALUES = "33,125,750,3000,8000,16000" }, "NOTIFY")

EQ GAINS CHANGED

Navigator EQ notification that the gains of an equalizer have been modified.

Signature

EQGAINS_CHANGED

Returns

None

Example

-- Notify Gains and Frequencies for EQ Bands for Output 3 (Binding ID 4002)
C4:SendToProxy(5001, "EQGAINS_CHANGED", { OUTPUT = "4002", VALUES = "7.5,3.8,5.4,4.59,7.8,7.4" }, "NOTIFY")_

C4:SendToProxy(5001, "EQFREQS_CHANGED", { OUTPUT = "4002", VALUES = "33,125,750,3000,8000,16000" }, "NOTIFY")

EQ PRESET CHANGED

Navigator EQ notification used when a different preset is selected for an output. Should be called after SET_EQPRESET is sent or if the preset is changed from a different event.

Signature

EQPRESET_CHANGED

Returns

None

Example

-- Notify change of current EQ Preset for Output 3 (Binding ID 4002)
C4:SendToProxy(5001, "EQPRESET_CHANGED", { OUTPUT = "4002", EQPRESET = 2 }, "NOTIFY")

HIDE EQ FROM NAVS CHANGED

Navigator EQ notification that the equalizer should be shown or hidden from Navigator. This must be sent with a value of False to enable the EQ functionality in Navigator.

Signature

HIDEEQFROMNAVS_CHANGED

Returns

None

Example

-- Notify Hide (or show) Navigator EQ for Output 3 (Binding ID 4002)
C4:SendToProxy(5001, "HIDEEQFROMNAVS_CHANGED", { OUTPUT = "4002", ENABLED = false }, "NOTIFY")

LOUDNESS CHANGED

Navigator EQ notification that the loudness has changed.

Signature

LOUDNESS_CHANGED

Returns

None

TREBLE LEVEL CHANGED

Navigator EQ notification that the treble level has changed.

Signature

TREBLE_LEVEL_CHANGED

Returns

None

Example

-- Notify Treble Level is at -6 for Output 3 (Binding ID 4002)
C4:SendToProxy(5001, "TREBLE_LEVEL_CHANGED", { OUTPUT = "4002", LEVEL = -6 }, "NOTIFY")


-- Notify Treble Level is at +6 for Output 3 (Binding ID 4002)
C4:SendToProxy(5001, "TREBLE_LEVEL_CHANGED", { OUTPUT = "4002", LEVEL = 6 }, "NOTIFY")

Navigator EQ Capabilities

<has_eq_preset_control></has_eq_preset_control>: Boolean capability where True indicates this device supports the navigator equalizer interface and should allow navigators to interact with equalizers.

<eq_preset_nav_count></eq_preset_nav_count>: Capability that requires a count (integer) of the number of presets to be presented to the Navigators.

<eq_band_nav_count></<eq_band_nav_count>: Capability that requires a count (integer) of the number of adjustable bands for equalizer control.

<use_tone_max_value></use_tone_max_value>: Capability that requires the max value (integer) for tone controls.

<use_tone_min_value></use_tone_min_value>: Capability that requires the minimum value (integer) for tone controls.

Audio Output Bindings and Proxy Events

Note: Audio Output binding ID values defined in drivers written in conjunction with this Proxy must start with a binding value of 4000. The acceptable range for Audio Outputs is 4000 - 4999. However, if the first output binding ID value is not 4000, issues with Proxy Events firing correctly can be encountered.

For a list of valid Binding ID values please see the Connections section of the DriverWorks Fundamentals Guide.

Amplifier Proxy Commands

BACK

Pulse Back button

Signature

BACK ()

Parameters

None

Returns

None

BINDING CHANGE ACTION

Command sent when a bound binding changes. Performs any actions needed to the protocol.

Signature

BINDING_CHANGE_ACTION ()

Returns

None

CANCEL

Pulse Cancel button

Signature

CANCEL ()

Parameters

None

Returns

None

DASH

Pulses the ‘-’ button.

Signature

DASH ()

Parameter

None

Returns

None

DISCONNECT OUTPUT

Disconnect (turn off) selected output on device

Signature

DISCONNECT_OUTPUT ()

Returns

None

EMIT CODE

Emit IR/Serial code. This is used by the AVGen IR/Serial Proxy.

Signature

EMIT_CODE ()

Returns

None

EMIT MACRO

Emit IR/Serial code macro (used by AVGen IR/Serial Proxy)

Signature

EMIT_MACRO ()

Returns

None

GET AUDIO INPUTS

Command sent to the protocol during the proxy initialization. Returns available audio inputs from the protocol device.

Signature

GET_AUDIO_INPUTS ()

Parameters

None

Returns

None

HYPHEN

Pulse ‘-’ button

Signature

HYPHEN ()

Parameters

None

Returns

None

INFO

Pulse Info button

Signature

INFO ()

Parameters

None

Returns

None

LOUDNESS OFF

Turn loudness off.

Signature

LOUDNESS_OFF ()

Returns

None

LOUDNESS ON

Turn loudness on.

Signature

LOUDNESS_ON ()

Returns

None

LOUDNESS TOGGLE

Toggle loudness on/off.

Signature

LOUDNESS_TOGGLE ()

Returns

None

MUTE OFF

Turning muting off.

Signature

MUTE_OFF ()

Returns

None

MUTE ON

Turn muting on.

Signature

MUTE_ON ()

Returns

None

MUTE TOGGLE

Toggle muting on/off.

Signature

MUTE_TOGGLE ()

Returns

None

NUMBER 0

Pulse ‘0’ button

Signature

Number_0 ()

Parameters

None

Returns

None

NUMBER 1

Pulse ‘1’ button

Signature

Number_1 ()

Parameters

None

Returns

None

NUMBER 2

Pulse ‘2’ button

Signature

Number_2 ()

Parameters

None

Returns

None

NUMBER 3

Pulse ‘3’ button

Signature

Number_3 ()

Parameters

None

Returns

None

NUMBER 4

Pulse ‘4’ button

Signature

Number_4 ()

Parameters

None

Returns

None

NUMBER 5

Pulse ‘5’ button

Signature

Number_5 ()

Parameters

None

Returns

None

NUMBER 6

Pulse ‘6’ button

Signature

Number_6 ()

Parameters

None

Returns

None

NUMBER 7

Pulse ‘7’ button

Signature

Number_7 ()

Parameters

None

Returns

None

NUMBER 8

Pulse ‘8’ button

Signature

Number_8 ()

Parameters

None

Returns

None

NUMBER 9

Pulse ‘9’ button

Signature

Number_9 ()

Parameters

None

Returns

None

OFF

Turn device Off.

Signature

OFF ()

Parameters

None

Returns

None

Usage Note

The ON and OFF proxy commands have the ability to send proxy notifications to display a device power state in Composer and Navigator Devices only. Any desired commands or notifications based off the device ON/OFF state must be handled by your DriverWorks driver.

ON

Turn device On.

Signature

ON ()

Parameters

None

Returns

None

Usage Note

The ON and OFF proxy commands have the ability to send proxy notifications to display a device power state in Composer and Navigator Devices only. Any desired commands or notifications based off the device ON/OFF state must be handled by your DriverWorks driver.

POUND

Pulse ‘#’ button

Signature

POUND ()

Parameters

None

Returns

None

PULSE BALANCE DOWN

Pulse balance down (Left)

Signature

PULSE_BALNCE_DOWN ()

Parameters

None

PULSE BALANCE UP

Pulse balance up (Right)

Signature

PULSE_BALNCE_UP ()

Returns

None

PULSE BASS DOWN

Pulse bass down (Left)

Signature

PULSE_BASS_DOWN ()

Returns

None

PULSE BASS UP

Pulse bass up (Right)

Signature

PULSE_BASS_UP ()

Parameters

None

Returns

None

PULSE INPUT

Toggle (cycle through) input selection on device.

Signature

PULSE_INPUT

Parameters

None

Returns

None

PULSE SUR UP

Toggle (cycle through) surround mode presets on device.

Signature

PULSE_SUR_UP

PULSE VOL DOWN

Pulse volume level down.

Signature

PULSE_VOL_DOWN

Returns

None

PULSE VOL UP

Pulse volume level up.

Signature

PULSE_VOL_UP

Returns

None

PULSE TREBLE DOWN

Pulse treble down.

Signature

PULSE_TREBLE_DOWN ()

Returns

None

PULSE TREBLE UP

Pulse treble up.

Signature

PULSE_TREBLE_UP ()

Returns

None

RECALL

Pulse Recall button

Signature

RECALL ()

Parameters

None

Returns

None

STAR

Pulse * button

Signature

STAR ()

Parameters

None

Returns

None

START BALANCE DOWN

Start ramping balance down (left).

Signature

START_BALANCE_DOWN ()

Returns

None

START BASS DOWN

Start ramping bass down.

Signature

START_BASS_DOWN ()

Returns

None

START BASS UP

Start ramping bass up.

Signature

START_BASS_UP ()

Returns

None

START TREBLE DOWN

Start ramping treble down.

Signature

START_TREBLE_DOWN ()

Returns

None

START TREBLE UP

Start ramping treble up.

Signature

START_TREBLE_UP ()

Returns

None

START VOL DOWN

Start ramping volume down.

Signature

START_VOL_DOWN ()

Returns

None

START VOL UP

Start ramping volume up.

Signature

START_VOL_UP ()

Returns

None

SET ALL EQ SETTINGS

Set balance to a specified position.

Signature

SET_ALL_EQ_SETTINGS ()

Returns

None

SET BALANCE

Set balance to a specified position.

Signature

SET_BALANCE ()

Returns

None

SET BALANCE UP

Set balance to a specified position.

Signature

SET_BALANCE_UP ()

Returns

None

SET BASS LEVEL

Set bass to a specified level.

Signature

SET_BASS_LEVEL

Returns

None

SET DIGI OFF

Used with the v.3 amp to turn digital inputs off.

Signature

SET_DIGI_OFF ()

Parameters

None

Returns

None

SET DIGI ON

Used with the v.3 amp to turn digital inputs on.

Signature

SET_DIGI_ON ()

Parameters

None

Returns

None

SET INPUT

Specify input selection of device.

Signature

SET_INPUT ()

Returns

None

Usage Note

• Control Bindings = 1 -> 999
• Video Inputs = 1000 -> 1099
• Video Outputs = 2000 -> 2999
• Audio Inputs = 3000 -> 3099
• Audio Outputs = 4000 -> 4999
• Proxy Bindings = 5000 -> 5999
• Network Bindings = 6000 -> 6999
• Room Bindings = 7000 -> 7999
• Power Manager = 8000 -> 8999

SET LOUDNESS

Turn loudness on.

Signature

SET_LOUDNESS ()

Returns

None

SET MAX VOLUME

Set maximum allowable volume level

Signature

SET_MAX_VOLUME ()

Returns

None

SET OUTPUT INPUT

Specify input and output selection of device.

Signature

SET_OUTPUT_INPUT ()

Returns

None

SET SURROUND MODE

Select specified surround mode preset on device.

Signature

SET_SURROUND_MODE ()

Returns

None

SET TREBLE LEVEL

Set treble to a specified level.

Signature

SET_TREBLE_LEVEL ()

Returns

None

SET UP DOWN SWAP

Swap page UP/DOWN buttons (used by AVGen)

Signature

SET_UP_DOWN_SWAP ()

Returns

None

STOP VOL DOWN

Stop ramping volume down.

Signature

SET_VOL_DOWN ()

Returns

None

SET VOLUME LEVEL

Set volume to a specified level.

Signature

SET_VOLUME_LEVEL () 

Returns

None

STOP BALANCE DOWN

Start ramping balance.

Signature

STOP_BALANCE_DOWN ()

Returns

None

STOP BASS DOWN

Stop ramping bass

Signature

STOP_BALANCE_UP ()

Returns

None

STOP BASS DOWN

Stop ramping bass down.

Signature

STOP_BASS_DOWN ()

Returns

None

STOP BASS UP

Stop ramping bass up

Signature

STOP_BASS_UP ()

Returns

None

STOP TREBLE DOWN

Stop ramping the treble down

Signature

STOP_TREBLE_DOWN ()

Returns

None

STOP TREBLE UP

Stop ramping the treble up.

Signature

STOP_TREBLE_UP ()

Returns

None

STOP VOL DOWN

Stop ramping the volume down.

Signature

STOP_VOL_DOWN ()

Returns

None

STOP VOL UP

Stop ramping the volume up.

Signature

STOP_VOL_UP ()

Returns

None

Audio Switch Proxy Commands

BACK

Pulse Back button

Signature

BACK ()

Parameters

None

Returns

None

CANCEL

Pulse Cancel button

Signature

CANCEL ()

Parameters

None

Returns

None

DASH

Pulses the ‘-’ button.

Signature

DASH ()

Parameter

None

Returns

None

DISCONNECT OUTPUT

Disconnect (turn off) selected output on device

Signature

DISCONNECT_OUTPUT ()

Returns

None

SET LOUDNESS

Turn loudness on.

Signature

SET_LOUDNESS ()

Returns

None

Audio Video Switch Capabilities

audio consumer count

Count of number of audio consumers (inputs) of the device. This value must match the number of connections in the driver.

Signature

<audio_consumer_count></audio_consumer_count>

Example

<capabilities>
   <audio_consumer_count>8</audio_consumer_count>
</capabilities>

audio provider count

Count of number of audio providers (outputs) of the device. This value must match the number of connections in the driver.

Signature

<audio_provider_count></audio_provider_count>

Example

<capabilities>
   <audio_provider_count>8</audio_provider_count>
</capabilities>

can downclass

Specifies if the A/V switch can down convert. For example: S-Video -> Composite

Signature

<can_downclass></can_downclass>

Example

<capabilities>
   <can_downclass>true</can_downclass>
</capabilities>

can switch separately

Device specific capability that must be set to True to in order for an AV Switch’s Composer Pro interface reflecting independent audio and video signal switching.

Signature

<can_switch_separately></can_switch_separately>

Usage Note

This capability is not related with the requires separate switching capability.  A setting of True or False will have no impact on requires separate switching.

Example

<capabilities>
   <can_switch_separately>true</can_switch_separately>
</capabilities>

can upclass

Specifies if the A/V switch can up convert. For example: Composite -> S-Video

Signature

<can_upclass></can_upclass>

Example

<capabilities>
   <can_upclass>true</can_upclass>
</capabilities>

has audio signal sense

Specifies AV switching is capable of sensing audio on an input. This is useful in triggering programming in ComposerPro based on the this setting.

Signature

<has_audio_signal_sense></has_audio_signal_sense>

Example

<capabilities>
   <has_audio_signal_sense>true</has_audio_signal_sense>
</capabilities>

has discrete balance control

Capable of directly specifying a balance setting.

Signature

<has_discrete_balance_control></has_discrete_balance_control>

Example

<capabilities>
   <has_discrete_balance_control>true</has_discrete_balance_control>
</capabilities>

has discrete bass control

Capable of directly specifying a bass setting.

Signature

<has_discrete_bass_control></has_discrete_bass_control>

Example

<capabilities>
   <has_discrete_bass_control>true</has_discrete_bass_control>
</capabilities>

has discrete loudness control

Capable of directly specifying a loudness setting.

Signature

<has_discrete_loudness_control></has_discrete_loudness_control>

Example

<capabilities>
   <has_discrete_loudness_control>true</has_discrete_loudness_control>
</capabilities>

has discrete mute control

Capable of directly specifying mute ON or OFF setting.

Signature

<has_discrete_ mute_control></has_discrete_ mute_control>

Example

<capabilities>
   <has_discrete_mute_control>true</has_discrete_mute_control>
</capabilities>

has discrete treble control

Capable of directly specifying a treble setting.

Signature

<has_discrete_treble_control></has_discrete_treble_control>

Example

<capabilities>
   <has_discrete_treble_control>true</has_discrete_treble_control>
</capabilities>

has discrete volume control

Capable of directly specifying a volume setting.

Signature

<has_discrete_volume_control></has_discrete_volume_control>

Example

<capabilities>
   <has_discrete_volume_control>true</has_discrete_volume_control>
</capabilities>

has discrete loudness control

Capable of handling ON/OFF loudness control.

Signature

<has_discrete_loudness_control></has_discrete_loudness_control>

Example

<capabilities>
   <has_discrete_loudness_control>true</has_discrete_loudness_control>
</capabilities>

has toggle mute control

Capable of handling ON/OFF mute control.

Signature

<has_toggle_mute_control></has_toggle_mute_control>

Example

<capabilities>
   <has_toggle_mute_control>true</has_toggle_mute_control>
</capabilities>

has up down balance control

Capable of directly specifying a balance setting.

Signature

<has_up_down_balance_control></has_up_down_balance_control>

Example

<capabilities>
   <has_up_down_balance_control>true</has_up_down_balance_control>
</capabilities>

has up down bass control

Capable of directly specifying a bass setting.

Signature

<has_up_down_bass_control></has_up_down_bass_control>

Example

<capabilities>
   <has_up_down_bass_control>true</has_up_down_bass_control>
</capabilities>

has up down treble control

Capable of directly specifying a treble setting.

Signature

<has_up_down_treble_control></has_up_down_treble_control>

Example

<capabilities>
   <has_up_down_treble_control>true</has_up_down_treble_control>
</capabilities>

has up down volume control

Has capability of handling volume UP and DOWN adjustments.

Signature

<has_up_down_volume_control></has_up_down_volume_control>

Example

<capabilities>
   <has_up_down_volume_control>true</has_up_down_volume_control>
</capabilities>

has video signal sense

Specifies AV switching is capable of sensing video on an input. This is useful in triggering programming in ComposerPro based on the this setting.

Signature

<has_video_signal_sense></has_video_signal_sense>

Example

<capabilities>
   <has_video_signal_sense>true</has_video_signal_sense>
</capabilities>

requires separate switching

Device specific capability that when set to True notifies Director of the existence of individual audio and video paths. This capability has no impact on Composer Pro user interface. For that reason, when set to True it is recommended that the capability can switch separately be set to True as well.

Signature

<requires_separate_switching></requires_separate_switching>

Example

<capabilities>
   <requires_separate_switching>true</requires_separate_switching>
</capabilities>

video consumer count

Count of number of video consumers (inputs) of the device. This value must match the number of connections in the driver.

Signature

<video_consumer_count></video_consumer_count>

Example

<capabilities>
   <video_consumer_count>8</video_consumer_count>
</capabilities>

video provider count

Count of number of video providers (outputs) of the device. This value must match the number of connections in the driver.

Signature

<video_provider_count></video_provider_count>

Example

<capabilities>
   <video_provider_count>8</video_provider_count>
</capabilities>

Audio Video Switch Protocol Notifications

AUDIO PARAMETER CHANGED

Audio parameter has changed

Signature

AUDIO_PARAMETER_CHANGED ()

Returns

None

BALANCE LEVEL CHANGED

Selected balance level has changed.

Signature

BALANCE_LEVEL_CHANGED ()

Returns

None

BASS LEVEL CHANGED

Selected bass level has changed

Signature

BASS_LEVEL_CHANGED ()

Returns

None

INPUT OUTPUT CHANGED

Selected inputs & outputs have changed.

Signature

INPUT_OUTPUT_CHANGED ()

Returns

None

LOUDNESS CHANGED

Loudness state (On/Off) has changed.

Signature

LOUDNESS_CHANGED ()

Returns

None

MUTE CHANGED

MUTE state (On/Off) has changed.

Signature

MUTE_CHANGED ()

Returns

None

OFF

Device has turned off.

Signature

OFF ()

Parameter

None

Returns

None

ON

Device has turned on.

Signature

ON ()

Parameter

None

Returns

None

TREBLE LEVEL CHANGED

Selected treble level has changed.

Signature

TREBLE_LEVEL_CHANGED ()

Returns

None

VOLUME LEVEL CHANGED

Selected volume level has changed.

Signature

VOLUME_LEVEL_CHANGED ()

Returns

None

Audio Video Switch Navigator EQ

Introduction

The ability to display audio equalization controls on devices running Navigator was added in conjunction with Operating System 3.2.3. Currently, the only Proxies that support Navigator EQ controls are the Amplifier and AV Switch Proxies.

The majority of the of the commands, notifications and capabilities defined here must be implemented in your driver to display EQ controls. Several commands are optional including SET_AUDIOMODE_BYPASS, SET_AUDIOMODE_EQ and SET_AUDIOMODE_TONECONTROL as these have been included to suspect legacy Audio Matrix Switches.

Note that this functionality is disabled by default. The HIDE EQ FROM NAVS CHANGED notification must be sent with a value of False to enable the EQ functionality in Navigator.

Navigator EQ Proxy Commands

LOUDNESS OFF

Navigator EQ command called to set the loudness off for indicated output. The driver should notify proxy with the LOUDNESS_CHANGED notification of the new value.

Signature

LOUDNESS_OFF

Returns

None

LOUDNESS ON

Navigator EQ command called to set the loudness on for indicated output. The driver should notify proxy with the LOUDNESS_CHANGED notification of the new value.

Signature

LOUDNESS_ON

Returns

None

SET AUDIOMODE BYPASS

Navigator EQ command called to change the output's mode to BYPASS. This is an optional command and should be used only if your device needs to switch modes.

Signature

SET_AUDIOMODE_BYPASS

Returns

None

SET AUDIOMODE EQ

Navigator EQ command called to change the output's mode to EQUALIZER. This is an optional command and should be used only if your device needs to switch modes.

Signature

SET_AUDIOMODE_EQ

Returns

None

SET AUDIOMODE TONECONTROL

Navigator EQ command called to change the output's mode to TONE_CONTROL. This is an optional command and should be used only if your device needs to switch modes.

Signature

SET_AUDIOMODE_TONECONTROL

Returns

None

SAVE EQ TO CUSTOM PRESET

Navigator EQ command called to save the current EQ values to a custom preset with a name. The driver should notify proxy with the EQ_NAMES_CHANGED notification with the updated name.

Signature

SAVE_EQ_TO_CUSTOM_PRESET

Returns

None

SET BASS LEVEL

Navigator EQ command called to set the bass level for tone control. The driver should notify proxy with the BASS_LEVEL_CHANGED notification of the new value.

Signature

SET_BASS_LEVEL

Returns

None

SET EQPRESET

Navigator EQ command called to change the selected preset for an output.

Signature

SET_EQPRESET

Returns

None

SET EQ GAIN VALUES

Navigator EQ command called to set the current equalizer’s gain values.

Signature

SET_EQ_GAIN_VALUES

Returns

None

SET TREBLE LEVEL

Navigator EQ command called to set the treble level for tone control. The driver should notify the proxy with TREBLE_LEVEL_CHANGED notification of the new value.

Signature

SET_TREBLE_LEVEL

Returns

None

Navigator EQ Protocol Notifications

AUDIOMODE CHANGED

Navigator EQ notification that the output's audio mode has changed to either Tone Control or Equalizer for the output. This is an optional notification and should be used only if your device has audio modes.

Signature

AUDIOMODE_CHANGED

Returns

None

BALANCE LEVEL CHANGED

Navigator EQ notification that the balance has changed.

Signature

BALANCE_LEVEL_CHANGED

Returns

None

Example

-- Notify Balance level is set to 'Full Left' for Output 3 (Binding ID 4002)
C4:SendToProxy(5001, "BALANCE_LEVEL_CHANGED", { OUTPUT = "4002", LEVEL = 0 }, "NOTIFY")



-- Notify Balance level is set to 'Center' for Output 3 (Binding ID 4002)
C4:SendToProxy(5001, "BALANCE_LEVEL_CHANGED", { OUTPUT = "4002", LEVEL = 50 }, "NOTIFY")



-- Notify Balance level is set to 'Full Right' for Output 3 (Binding ID 4002)
C4:SendToProxy(5001, "BALANCE_LEVEL_CHANGED", { OUTPUT = "4002", LEVEL = 100 }, "NOTIFY")

BASS LEVEL CHANGED

Navigator EQ notification that the bass has changed.

Signature

BASS_LEVEL_CHANGED

Returns

None

Example

-- Notify Bass Level is at -6 for Output 3 (Binding ID 4002)
C4:SendToProxy(5001, "BASS_LEVEL_CHANGED", { OUTPUT = "4002", LEVEL = -6 }, "NOTIFY") 

-- Notify Bass Level is at +6 for Output 3 (Binding ID 4002)
C4:SendToProxy(5001, "BASS_LEVEL_CHANGED", { OUTPUT = "4002", LEVEL = 6 }, "NOTIFY")

EQ DISPLAY ORDER CHANGED

Navigator EQ notification of the order that the names from EQ_NAMES_CHANGED should be presented to the user.

Signature

EQ_DISPLAY_ORDER_CHANGED

Returns

None

Example

C4:SendToProxy(5001, "EQ_DISPLAY_ORDER_CHANGED", {​​​​​​​ [1] = 1, [2] = 2, [3] = 3, [4] = 4, [5] = 5, OUTPUT = "4002" }​​​​​​​, "NOTIFY")

C4:SendToProxy(5001, "EQ_DISPLAY_ORDER_CHANGED", {​​​​​​​ 1, 2, 3, 4, 5, OUTPUT = "4002" }​​​​​​​, "NOTIFY")

EQ NAMES CHANGED

Navigator EQ notification of the current names for the equalizer presets.

Signature

EQ_NAMES_CHANGED

Returns

None

Example

C4:SendToProxy(5001, "EQ_NAMES_CHANGED", { [1] = "FLAT", [2] = "CLASSICAL", [3] = "JAZZ", [4] = "POP",   [5] = "ROCK", OUTPUT = "4002" }, "NOTIFY")

C4:SendToProxy(5001, "EQ_NAMES_CHANGED", {"FLAT", "CLASSICAL", "JAZZ", "POP", "ROCK", OUTPUT = 4002}, "NOTIFY")

EQ FREQS CHANGED

Navigator EQ notification that the frequencies of a equalizer have been modified.

Signature

EQFREQS_CHANGED

Returns

None

Example

-- Notify Gains and Frequencies for EQ Bands for Output 3 (Binding ID 4002)
C4:SendToProxy(5001, "EQGAINS_CHANGED", { OUTPUT = "4002", VALUES = "7.5,3.8,5.4,4.59,7.8,7.4" }, "NOTIFY")_

C4:SendToProxy(5001, "EQFREQS_CHANGED", { OUTPUT = "4002", VALUES = "33,125,750,3000,8000,16000" }, "NOTIFY")

EQ GAINS CHANGED