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 Fan 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 fans have common controls such as ON, OFF and TOGGLE  The fan proxy allows for a common user interface to control all fans.  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 Fan Proxy in conjunction with O.S. Release 3.4.2.

What’s New in 3.4.1

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

What’s New in 3.4.0

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

What’s New in 3.3.2

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

What’s New in 3.3.1

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

What’s New in 3.3.0

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

What’s New in 3.2.3

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

What’s New in 3.2.2

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

What’s New in 3.2.1

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

What’s New in 3.2.0

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

What was New in 3.1.2

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

What was New in 3.1.0

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

What was New in O.S.3

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

Fan Proxy Commands

ON

Turn the fan on to the designated preset level. Another possible behavior would be to turn it back on to the most recent on speed.

Name

ON ()

Parameters

None

Returns

None

OFF

Turn the fan OFF.

Name

OFF ()

Parameters

None

Returns

None

TOGGLE

If the fan is on, turn it off. If the fan is off, do the same behavior as the ON command.

Name

TOGGLE ()

Parameters

None

Returns

None

DESIGNATE_PRESET

Specifies which fan preset value should be the default one to go to when an ON or TOGGLE command is sent.

Name

DESIGNATE_PRESET ()

Returns

None

SET_SPEED

Set the current speed of the fan to the designated level. Setting to 0 will turn the fan off.

Name

SET_SPEED ()

Returns

None

CYCLE_SPEED_UP

Bump the fan up to the next higher speed from its current setting. It would be up to the protocol driver to decide if it wraps or stops when we’re already at the highest speed.

Name

CYCLE_SPEED_UP ()

Parameters

None

Returns

None

CYCLE_SPEED_DOWN

Bump the fan down to the next lower speed from its current setting. It would be up to the protocol driver to decide if it wraps or stops when the fan is currently off.

Name

CYCLE_SPEED_DOWN ()

Parameters

None

Returns

None

SET_DIRECTION

Tell the fan which direction to spin. This command would only be valid if the can_reverse capability is set to true in the driver file.

Name

SET_DIRECTION ()

Returns

None

TOGGLE_DIRECTION

Reverse the direction which the fan is currently spinning. This command would only be valid if the can_reverse capability is set to true in the driver file.

Name

TOGGLE_DIRECTION ()

Parameters

None

Returns

None

GET_CURRENT_STATE

Tell the protocol to report its current values. This wouldn’t be available through programming, but generated by the proxy to get its initial settings.

Name

GET_CURRENT_STATE ()

Parameters

None

Returns

None

GET_STATE

Command handled by the proxy driver. Immediately returns a block of XML information to the caller. Reports the current state of the device.

Name

GET_STATE ()

Parameters

None

Returns

None

Example

<fan_state>
  <current_speed>3</current_speed>
  <is_reversed>false</is_reversed>
</fan_state>

GET_SETUP

Command handled by the proxy driver. Immediately returns a block of XML information to the caller. Usually called just once by a UI entity to know how to setup the UI. This would report such things as how many settings the device has and what the name of those settings are.

Name

GET_SETUP ()

Parameters

None

Returns

None

Example

<fan_setup>
   <speeds_count>4</speeds_count>
   <speed_names>Low,Low Medium,Medium High,High</speed_names>
   <can_reverse>false</can_reverse>
   <can_set_preset>true</can_set_preset>
   <preset_speed>3</preset_speed>
</fan_setup>

Fan Protocol Notifications

CURRENT_SPEED

Received from the protocol driver when the fan speed changes. This would also happen when the fan turned off because it would be set to speed 0.

Name

CURRENT_SPEED ()

Returns

None

DIRECTION

Received from the protocol driver when the fan direction changes.

Name

DIRECTION ()

Returns

None

PRESET_SPEED

Received from the proxy when the preset speed changes.

Name

PRESET_SPEED ()

Returns

None

ON

Received from the protocol when the power goes from off to on. The proxy would assume that the fan just went to its preset speed. Would not be required, but could be used if the fan only has one speed.

Signature

ON ()

Parameters

None

Returns

None

OFF

Received from the protocol when the power goes from on to off. Would not be required, but could be used if the fan only has one speed.

Signature

OFF ()

Parameters

None

Returns

None

Fan Capabilities

can_reverse

Signature

<can_reverse></can_reverse>

Example

<capabilities>
   <can_reverse>true</can_reverse>
</capabilities>

can_set_preset

Signature

<can_set_preset></can_set_preset>

Example

<capabilities>
   <can_set_preset>true</an_set_preset>
</capabilities>

discrete_levels

Signature

<discrete_levels></discrete_levels>

Example

<capabilities>
   <discrete_levels>1</discrete_levels>
</capabilities>

preset_speed

Signature

<preset_speed></preset_speed>

Example

<capabilities>
   <preset_speed>1</preset_speed>
</capabilities>

proxy_fan_speed_connections

This capability is applicable to newer fan drivers which create BUTTON_LINK connections dynamically in association with fan speeds in the fan proxy. Setting this capability to true simply enables this ability. It relies on two other capabilities to successfully implement the dynamic connection functionality. They include: discreet_levels and speed_name.

Available from 3.4.2.

Signature

<proxy_fan_speed_connections></proxy_fan_speed_connections>

Example

<capabilities>
   <proxy_fan_speed_connections>true</proxy_fan_speed_connections>
</capabilities>

speed_names

Signature

<speed_names></speed_names>

Example

<capabilities>
   <speed_names>3</speed_names>
</capabilities>

Fan Conditionals

Is On

Parameters

None

Returns

Returns true if the fan is on at any speed.

Is Off

Parameters

None

Returns

Returns true if the fan is off.

Current Speed Equal/NotEqual

Returns

True if the current speed is equal to (or not equal) to the reference number

Is Reversed

Parameters

None

Returns

Return true if the fan is spinning in reverse. This would only be available if the can_reverse capability is set to true in the driver file.

Fan Events

Fan Events

The following Events are supported by the Fan Proxy. The events fired by the proxy have to deal with changes in the fan itself. They include:

turned_on - Fired when the power goes from off to on.

turned_off - Fired when the power goes from on to off.

speed_changed - Fired when the speed number changes. Since turning on or off also involves a change of speed this would also fire when the fan turns on or off.

direction_changed - Fired when the fan spin direction changes. This would only be available if the can_reverse capability is set to true in the driver file.

Fan Variables

Fan Variables

The following Variables are supported by the Fan Proxy. They include:

Is On - Boolean: Read/Write

Current Selected Speed - Unsigned Long: Read/Write

Is Reversed - Boolean: Read/Write

Current Preset- Unsigned Long: Read/Write