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

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 AV Tuner 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 AV Tuners have common controls such as ON, SET CHANNEL and RECALL. The disc AV Tuner proxy allows for a common user interface to control all tuners. 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 AV Tuner Proxy in conjunction with O.S. Release 3.4.2.

What’s New in 3.4.1

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

What’s New in 3.4.0

There were no modifications to the AV Tuner Proxy in conjunction with O.S. Release 3.4.0.

What’s New in 3.3.2

There were no modifications to the AV Tuner Proxy in conjunction with O.S. Release 3.3.2.

What’s New in 3.3.1

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

What’s New in 3.3.0

There were no modifications to the AV Tuner Proxy in conjunction with O.S. Release 3.3.0.

What’s New in 3.2.3

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

What’s New in 3.2.2

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

What’s New in 3.2.1

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

What’s New in 3.2.0

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

What was New in 3.1.2

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

What was New in 3.1.0

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

What was New in O.S.3

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

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

Parameter	Description
int	Number of audio consumers.

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>

Parameter	Description
int	Number of audio providers.

Example

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

has_channel_up_down

Tuner can cycling up or down for valid channels

Signature

<has_channel_up_down></has_channel_up_down>

Parameter	Description
bool	True/False

Example

<capabilities>
   <has_channel_up_down>true</has_channel_up_down>
</capabilities>

has_discrete_channel_select

Capability of directly selecting specified channel.

Signature

<has_discrete_channel_select></has_ discrete_channel_select>

Parameter	Description
bool	True/False

Example

<capabilities>
   <has_discrete_channel_select>true</has_discrete_channel_select>
</capabilities>

has_discrete_input_select

Capability of directly selecting specified input.

Signature

<has_discrete_input_select></has_ discrete_input_select>

Parameter	Description
bool	True/False

Example

<capabilities>
   <has_discrete_input_select>true</has_discrete_input_select>
</capabilities>

has_discrete_preset

Capable of directly selecting from a preset list.

Signature

<has_discrete_preset></has_discrete_preset>

Parameter	Description
bool	True/False

Example

<capabilities>
   <has_discrete_preset>true</has_discrete_preset>
</capabilities>

has_feedback

Device has the ability to report back the tuner channel. Required so the Tuner channel can be displayed through navigator.

Signature

<has_feedback></has_feedback>

Parameter	Description
bool	True/False

Example

<capabilities>
   <has_feedback>true</has_feedback>
</capabilities>

has_provider_count

Count of number of video providers (outputs) of the device.

Signature

<has_provider_count></has_provider_count>

Parameter	Description
int	Number of video providers.

Example

<capabilities>
   <has_provider_count>8</has_provider_count>
</capabilities>

has_preset_up_down

Tuner can cycle up or down through a preset list.

Signature

<has_preset_up_down></has_preset_up_down>

Parameter	Description
bool	True/False

Example

<capabilities>
   <has_preset_up_down>true</has_preset_up_down>
</capabilities>

has_toad_input_select

Capability of toggling through inputs

Signature

<has_toad_input_select></has_toad_input_select>

Parameter	Description
bool	True/False

Example

<capabilities>
   <has_toad_input_select>true</has_toad_input_select>
</capabilities>

has_tune_ up_down

Tuner can cycle up or down through tuning frequencies or channels

Signature

<has_tune_up_down></has_tune_up_down>

Parameter	Description
bool	True/False

Example

<capabilities>
   <has_tune_up_down>true</has_tune_up_down>
</capabilities>

preset_count

Number of Tuner presets available.

Signature

<preset_count></preset_count>

Parameter	Description
int	Number of Presets

Example

<capabilities>
   <preset_count>6</preset_count>
</capabilities>

selection_delay

Delay time in milliseconds before new tuner selection is online.

Signature

<selection_delay></selection_delay>

Parameter	Description
bool	True/False

Example

<capabilities>
   <selection_delay>true</selection_delay>
</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>

Parameter	Description
int	Number of video consumers.

Example

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

preface_band_with_tuner_ capability

Specifies if the device can switch to the Tuner input (AM, FM..) and then send the SET_CHANNEL command.

Signature

<preface_bandwith_tuner_capability></preface_bandwith_tuner_capability>

Parameter	Description
bool	True/False

Example

<capabilities>
   <preface_bandwith_tuner_capability>true</preface_bandwith_tuner_capability>
</capabilities>

Tuner Protocol Notifications

CHANNEL_CHANGED

Selected disc has changed.

Name

CHANNEL_CHANGED ()

Parameter	Type	Description
ChannelNumber	INT	Channel Number

Returns

None

Usage Note

Usage Note:If the BANDTYPE is not supplied, as in older drivers, the INPUT binding # will be used to determine which band the tuner is on. All DriverWorks drivers need to use the BANDTYPE parameter if they want the band to propagate up to Navigator to display the channel properly. If the DriverWorks driver does not know the current channel and the “has feedback” capability is not set to “True”, none of this matters and everything will keep working as it previously has.

A CHANNEL CHANGED must be issued immediately after the INPUT CHANGED in order for the UI to update.

Example

C4:SendToProxy(5002, "INPUT_CHANGED", {INPUT=3014,BANDTYPE='FMBand',MINCHANNEL=8750,MAXCHANNEL=10450,CHANNELSPACING=10})

C4:SendToProxy(5002, "CHANNEL_CHANGED", {CHANNEL=8780})

Note that in the example to the right, 5002 is the ProxyBindingID for the Tuner. INPUT 3014 is the ID for the FM Antenna on the 5002 Tuner.

Navigator determines AM/FM/XM with the following rule:

ID 3000 and 3001 are AM
ID 3002 and 3003 are FM

INPUT_CHANGED

Selected input has changed.

Name

INPUT_CHANGED ()

Parameter	Type	Description
	INT	Binding ID of RF cloud
	STR	One of the following case sensitive values: “AMBand” “FMBand”
	INT	Lowest tune-able channel e.g. 8750 for FM, 530 for AM
	INT	Highest tunable channel e.g. 10790 for FM, 1760 for AM
	INT	Channel increment e.g. 20 for FM in U.S., 10 for AM in U.S.

Returns

None

Usage Note

If the BANDTYPE is not supplied, as in older drivers, the INPUT binding # will be used to determine which band the tuner is on. All DriverWorks drivers need to use the BANDTYPE parameter if they want the band to propagate up to Navigator to display the channel properly. If the DriverWorks driver does not know the current channel and the “hasfeedback” capability is not set to “True”, none of this matters and everything will keep working as it previously has.

A CHANNEL_CHANGED must be issued immediately after the INPUT_CHANGED in order for the UI to update.

Example

C4:SendToproxy(5002,'INPUTCHANGED',{INPUT=3009,BANDTYPE='FMBand',MINCHANNEL=8750,
  MAXCHANNEL=10790,CHANNELSPACING=20})

C4:SendToProxy(5002,'CHANNELCHANGED',CHANNEL=10290)

Note that in the example to the right, 5002 is the ProxyBindingID for the Tuner. INPUT 3009 is the ID for the FM Antenna on the 5002 Tuner.

Navigator determines AM/FM/XM with the following rule:

ID 3000 and 3001 are AM
ID 3002 and 3003 are FM

Name

RADIO_TEXT_CHANGED ()

Parameter	Type	Description
RADIO TEXT	STR	Two free-form text strings. Radio information/text from RDS and currently playing title.

Usage Note

MaxImum 64 characters in two free form text strings.

Returns

None

PSN_CHANGED

Text from PSN has changed.

Name

PSN_CHANGED ()

Parameter	Type	Description
PSN	STR	Two free-form text strings. Radio information and text from the station ID. Periodically updated from the station.

Usage Note

MaxImum 64 characters in two free form text strings.

Returns

None

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.

Tuner Proxy Commands

Returns

None

Example

The example to the right detail the table of information that is received from the proxy when a channel is selected:

FM:
ReceivedFromProxy:      SET_CHANNEL
BindingID               5002
CHANNEL                 96.3
INPUT                   3028
OUTPUT                  0

AM:
ReceivedFromProxy:      SET_CHANNEL
INPUT                   3027
BindingID               5002
CHANNEL                 1100
INPUT                   3027
OUTPUT                  0

In the FM example, channel 96.3 has been selected in the tuner protocol. The 96.3 value is passed into the data table as a string. It is important to note that if the bandwidth type (AM, FM) is not provided (and the proxy in question is not TV) a manner in which to identify the bandwidth type will need to be developed. An example of this code follows:

  if tParams['BANDTYPE'] == nil then
   if (string.find(tParams['CHANNEL'],"%p") ~= nil) then
    tParams['BANDTYPE'] = 'FM'
    local ChannelLen = string.len(tParams['CHANNEL'] )
    local ChannelFix = string.sub(tParams['CHANNEL'],1,ChannelLen-2) ..
    string.sub(tParams['CHANNEL'],ChannelLen-1,ChannelLen-1)
    tParams ['CHANNEL'] = ChannelFix
   else
    tParams['BANDTYPE'] = 'AM'
end end
end

SET_PRESET

Select specified tuning preset.

Name

SET_PRESET ()

Parameter	Type	Description
PresetNum	INT	Preset Number

Returns

None