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 Amplifier Control Proxy which is supported in the DriverWorks Software Development Kit.

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 SET VOLUME, SET INPUT and SET OUTPUT.  The amplifier proxy allows for a common user interface to control all amps.  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.4.2

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

What’s New in 3.4.1

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

What’s New in 3.4.0

There were no modifications to the Amplifier Proxy conjunction with O.S. Release 3.4.0.

What’s New in 3.3.2

There were no modifications to the Amplifier Proxy conjunction with O.S. Release 3.3.2.

What’s New in 3.3.1

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

What’s New in 3.3.0

There were no modifications to the Amplifier Proxy conjunction with O.S. Release 3.3.0.

What’s New in 3.2.3

Audio Equalization available on Navigators

The Amplifier 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.

What’s New in 3.2.2

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

What’s New in 3.2.1

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

What’s New in 3.2.0

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

What was New in 3.1.2

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

What was New in 3.1.0

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

What was New in O.S.3

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

Amplifier Proxy Commands

BACK

Pulse Back button

Name

BACK ()

Parameters

None

Returns

None

BINDING_CHANGE_ACTION

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

Name

BINDING_CHANGE_ACTION ()

Returns

None

CANCEL

Pulse Cancel button

Name

CANCEL ()

Parameters

None

Returns

None

DASH

Pulses the ‘-’ button.

Name

DASH ()

Parameter

None

Returns

None

DISCONNECT_ OUTPUT

Disconnect (turn off) selected output on device

Name

DISCONNECT_OUTPUT ()

Returns

None

EMIT_CODE

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

Name

EMIT_CODE ()

Returns

None

EMIT_MACRO

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

Name

EMIT_MACRO ()

Returns

None

GET_AUDIO_INPUTS

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

Name

GET_AUDIO_INPUTS ()

Parameters

None

Returns

None

HYPHEN

Pulse ‘-’ button

Name

HYPHEN ()

Parameters

None

Returns

None

INFO

Pulse Info button

Name

INFO ()

Parameters

None

Returns

None

LOUDNESS_OFF

Turn loudness off.

Name

LOUDNESS_OFF ()

Returns

None

LOUDNESS_ON

Turn loudness on.

Name

LOUDNESS_ON ()

Returns

None

LOUDNESS_TOGGLE

Toggle loudness on/off.

Name

LOUDNESS_TOGGLE ()

Returns

None

MUTE_OFF

Turning muting off.

Name

MUTE_OFF ()

Returns

None

MUTE_ON

Turn muting on.

Name

MUTE_ON ()

Returns

None

MUTE_TOGGLE

Toggle muting on/off.

Name

MUTE_TOGGLE ()

Returns

None

NUMBER_0

Pulse ‘0’ button

Name

Number_0 ()

Parameters

None

Returns

None

NUMBER_1

Pulse ‘1’ button

Name

Number_1 ()

Parameters

None

Returns

None

NUMBER_2

Pulse ‘2’ button

Name

Number_2 ()

Parameters

None

Returns

None

NUMBER_3

Pulse ‘3’ button

Name

Number_3 ()

Parameters

None

Returns

None

NUMBER_4

Pulse ‘4’ button

Name

Number_4 ()

Parameters

None

Returns

None

NUMBER_5

Pulse ‘5’ button

Name

Number_5 ()

Parameters

None

Returns

None

NUMBER_6

Pulse ‘6’ button

Name

Number_6 ()

Parameters

None

Returns

None

NUMBER_7

Pulse ‘7’ button

Name

Number_7 ()

Parameters

None

Returns

None

NUMBER_8

Pulse ‘8’ button

Name

Number_8 ()

Parameters

None

Returns

None

NUMBER_9

Pulse ‘9’ button

Name

Number_9 ()

Parameters

None

Returns

None

OFF

Turn device Off.

Name

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.

Name

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

Name

POUND ()

Parameters

None

Returns

None

PULSE_BALANCE_DOWN

Pulse balance down (Left)

Name

PULSE_BALNCE_DOWN ()

Returns

None

PULSE_BALANCE_UP

Pulse balance up (Right)

Name

PULSE_BALNCE_UP ()

Returns

None

PULSE_BASS_DOWN

Pulse bass down (Left)

Name

PULSE_BASS_DOWN ()

Returns

None

PULSE_BASS_UP

Pulse bass up (Right)

Name

PULSE_BASS_UP ()

Returns

None

PULSE_INPUT

Toggle (cycle through) input selection on device.

Name

PULSE_INPUT

Parameters

None

Returns

None

PULSE_SUR_UP

Toggle (cycle through) surround mode presets on device.

Name

PULSE_SUR_UP

Returns

None

PULSE_VOL_DOWN

Pulse volume level down.

Name

PULSE_VOL_DOWN

Returns

None

PULSE_VOL_ UP

Pulse volume level up.

Name

PULSE_VOL_UP

Returns

None

PULSE_TREBLE_ DOWN

Pulse treble down.

Name

PULSE_TREBLE_DOWN ()

Returns

None

PULSE_TREBLE_UP

Pulse treble up.

Name

PULSE_TREBLE_UP ()

Returns

None

RECALL

Pulse Recall button

Name

RECALL ()

Parameters

None

Returns

None

STAR

Pulse * button

Name

STAR ()

Parameters

None

Returns

None

START_BALANCE_DOWN

Start ramping balance down (left).

Name

START_BALANCE_DOWN ()

Returns

None

START_BASS_DOWN

Start ramping bass down.

Name

START_BASS_DOWN ()

Returns

None

START_BASS_UP

Start ramping bass up.

Name

START_BASS_UP ()

Returns

None

START_TREBLE_DOWN

Start ramping treble down.

Name

START_TREBLE_DOWN ()

Returns

None

START_TREBLE_UP

Start ramping treble up.

Name

START_TREBLE_UP ()

Returns

None

START_VOL_DOWN

Start ramping volume down.

Name

START_VOL_DOWN ()

Returns

None

START_VOL_UP

Start ramping volume up.

Name

START_VOL_UP ()

Returns

None

SET_ALL_EQ_SETTINGS

Set balance to a specified position.

Name

SET_ALL_EQ_SETTINGS ()

Returns

None

SET_BALANCE

Set balance to a specified position.

Name

SET_BALANCE ()

Returns

None

SET_BALANCE_UP

Set balance to a specified position.

Name

SET_BALANCE_UP ()

Returns

None

SET_BASS_LEVEL

Set bass to a specified level.

Name

SET_BASS_LEVEL

Returns

None

SET_DIGI_OFF

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

Name

SET_DIGI_OFF ()

Parameters

None

Returns

None

SET_DIGI_ON

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

Name

SET_DIGI_ON ()

Parameters

None

Returns

None

SET_INPUT

Specify input selection of device.

Name

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.

Name

SET_LOUDNESS ()

Returns

None

SET_MAX_VOLUME

Set maximum allowable volume level

Name

SET_MAX_VOLUME ()

Returns

None

SET_OUTPUT_INPUT

Specify input and output selection of device.

Name

SET_OUTPUT_INPUT ()

Returns

None

SET_SURROUND_MODE

Select specified surround mode preset on device.

Name

SET_SURROUND_MODE ()

Returns

None

SET_TREBLE_LEVEL

Set treble to a specified level.

Name

SET_TREBLE_LEVEL ()

Returns

None

SET_ UP_DOWN_SWAP

Swap page UP/DOWN buttons (used by AVGen)

Name

SET_UP_DOWN_SWAP ()

Returns

None

STOP_VOL_DOWN

Stop ramping volume down.

Name

SET_VOL_DOWN ()

Returns

None

SET_VOLUME_LEVEL

Set volume to a specified level.

Name

SET_VOLUME_LEVEL () 

Returns

None

STOP_BALANCE_DOWN

Start ramping balance.

Name

STOP_BALANCE_DOWN ()

Returns

None

STOP_BASS_DOWN

Stop ramping bass

Name

STOP_BALANCE_UP ()

Returns

None

STOP_BASS_DOWN

Stop ramping bass down.

Name

STOP_BASS_DOWN ()

Returns

None

STOP_BASS_UP

Stop ramping bass up

Name

STOP_BASS_UP ()

Returns

None

STOP_TREBLE_DOWN

Stop ramping the treble down

Name

STOP_TREBLE_DOWN ()

Returns

None

STOP_TREBLE_UP

Stop ramping the treble up.

Name

STOP_TREBLE_UP ()

Returns

None

STOP_VOL_DOWN

Stop ramping the volume down.

Name

STOP_VOL_DOWN ()

Returns

None

STOP_VOL_UP

Stop ramping the volume up.

Name

STOP_VOL_UP ()

Returns

None

Amplifier Protocol Notifications

AUDIO_PARAMETER _CHANGED

Audio parameter has changed

Name

AUDIO_PARAMETER_CHANGED ()

Returns

None

BALANCE_LEVEL_CHANGED

Selected balance level has changed.

Name

BALANCE_LEVEL_CHANGED ()

Returns

None

BASS_LEVEL_CHANGED

Selected bass level has changed

Name

BASS_LEVEL_CHANGED ()

Returns

None

INPUT_OUTPUT_CHANGED

Selected inputs & outputs have changed.

Name

INPUT_OUTPUT_CHANGED ()

Returns

None

LOUDNESS_CHANGED

Loudness state (On/Off) has changed.

Name

LOUDNESS_CHANGED ()

Returns

None

MUTE_CHANGED

MUTE state (On/Off) has changed.

Name

MUTE_CHANGED ()

Returns

None

OFF

Device has turned off.

Name

OFF ()

Parameter

None

Returns

None

ON

Device has turned on.

Name

ON ()

Parameter

None

Returns

None

TREBLE_LEVEL_CHANGED

Selected treble level has changed.

Name

TREBLE_LEVEL_CHANGED ()

Returns

None

VOLUME_LEVEL_CHANGED

Selected volume level has changed.

Name

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>

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.