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 Keypad 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 Keypads have common controls such as KEYPAD BUTTON ACTION and KEYPAD BITTON INFO.  The Keypad proxy allows for a common user interface to control all keypads. 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 Keypad Proxy in conjunction with O.S. Release 3.4.2.

What’s New in 3.4.1

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

What’s New in 3.4.0

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

What’s New in 3.3.2

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

What’s New in 3.3.1

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

What’s New in 3.3.0

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

What’s New in 3.2.3

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

What’s New in 3.2.2

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

What’s New in 3.2.1

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

What’s New in 3.2.0

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

What was New in 3.1.2

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

What was New in 3.1.0

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

What was New in O.S.3

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.

Keypad Proxy Commands

Overview

This section describes describe the basic functionality of the Keypad Proxy. This proxy was introduced into the system in version 2.5.0, along with the gen3 lighting drivers. It is designed to be fairly generic, but there are a few capabilities that only Control4 keypads use such as track_previous_button. It should also work for fixed multi-row keypads. Configurable multi-row keypads are not supported with this proxy.

DELETE_KEYPAD_BUTTON

Used to delete a specific button from the keypad

Name

DELETE_KEYPAD_BUTTON ()

Returns

None

KEYPAD_ALL_BUTTON_COLOR

Used to set the color for all buttons on a keypad.

Name

KEYPAD_ALL_BUTTON_COLOR ()

Returns

None

KEYPAD_ALL_BUTTON_COLOR_CLEAR

Used to clear the color for all buttons on a keypad.

Signature

KEYPAD_ALL_BUTTON_COLOR_CLEAR ()

Returns

None

KEYPAD_BUTTON_COLOR_CLEAR

Used to clear the color for a button on a keypad.

Signature

KEYPAD_BUTTON_COLOR_CLEAR ()

Returns

None

KEYPAD_BUTTON_ACTION

Used to send remote commands to the keypad to have it act as if a button on the keypad was actually used.

Name

KEYPAD_BUTTON_ACTION ()

Returns

None

KEYPAD_BUTTON_COLOR

Used to set the color for a specific button on a keypad.

Name

KEYPAD_BUTTON_COLOR ()

Returns

None

KEYPAD_BUTTON_INFO

Used to change the settings on a particular button.

Name

KEYPAD_BUTTON_INFO ()

Returns

None

FINISH

Used to send a finish value to the proxy. Only used if the custom_finishes capability is set to true in the protocol driver Valid values are:

• 0 = White
• 1 = Light Almond
• 2 = Ivory
• 3 = Brown
• 4 = Black
• 5 = Aluminum
• 6 = Snow White
• 7 = Biscuit
• 8 = Midnight Black

Signature

FINISH ()

Returns

None

NEW_KEYPAD_BUTTON

Used to create a new button on the keypad. This is sent to the protocol by the proxy when the proxy is loaded. Thus the protocol doesn't have to store all its buttons settings, the proxy will do it.

Name

NEW_KEYPAD_BUTTON ()

Returns

None

SET_TRACK_PREV_BUTTON

Indicates whether the keypad should track the previous button being used. This mainly for Control4 Configurable keypad devices (zigbee, wired, combo, etc)

Name

SET_TRACK_PREV_BUTTON N ()

Returns

None

Keypad Capabilities

clear_led_current_color_support

Enabling this capability allows the Keypad Proxy to clear keypad button(s) color. Previously, this had to be done at the protocol level. Specifically, this is applicable to button colors that have been set programmatically in Composer Pro. Enabling this capability in your driver will expose two new Keypad Proxy Programming Action in Composer Pro: Clear LED Current and Clear All LED Current.

Available from 3.4.2.

Signature

<clear_led_current_color_support></clear_led_current_color_support>

Type

Boolean. Defaults to false

Dynamic Capability

No

Usage Note

In conjunction with this capabilities’ use, Drivers need to implement the following Proxy Commands:

KEYPAD_BUTTON_COLOR_CLEAR - A Notify must be sent when this command is received containing the new button color for the indicated button using the KEYPAD_BUTTON_COLOR notification.

KEYPAD_ALL_BUTTON_COLOR_CLEAR - A Notify must be sent when this command is received containing the new button colors for each button using the KEYPAD_BUTTON_COLOR notification.

Example

<capabilities>
    <clear_led_current_color_support>true</clear_led_current_color_support>
</capabilities>

Keypad Protocol Notifications

BEHAVIOR_NAME

Used to inform (or update) the proxy of a button behavior name

Name

BEHAVIOR_NAME ()

Returns

None

CLICK_COUNT

Used to inform the proxy that a button has been clicked multiple times. This is used by the proxy to fire the proper event (single, double, triple click, etc).

Name

CLICK_COUNT ()

Returns

None

DELETE_KEYPAD_BUTTON

Used to inform the proxy that a button is being deleted

Name

DELETE_KEYPAD_BUTTON ()

Returns

None

KEYPAD_BUTTON_ACTION

Used by the protocol to inform the proxy that some type of action occurred on a button. The proxy will then update colors, send the proper command to the bound device, etc.

Name

KEYPAD_BUTTON_ACTION ()

Returns

None

KEYPAD_ALL_BUTTON_COLOR

Used by the protocol to inform the proxy of a change in color for every button on the keypad.

Name

KEYPAD_ALL_BUTTON_COLOR ()

Returns

None

KEYPAD_BUTTON_COLOR

This is used by the protocol to inform the proxy that it has been instructed to change the color of a button.

Name

KEYPAD_BUTTON_COLOR ()

Returns

None

KEYPAD_BUTTON_INFO

Used by the protocol to inform the proxy of a changed setting for a particular button. It can have multiple parameters, but the only required one is BUTTON_ID.

Name

KEYPAD_BUTTON_INFO ()

Returns

None

LED_BEHAVIOR_NAME

Used to inform (or update) the proxy of a LED's behavior name

Name

LED_BEHAVIOR_NAME ()

Returns

None

NEW_KEYPAD_BUTTON

Used to inform the proxy about the existence of a new button on the keypad. If the specified button already exists, this notification will do nothing.

Name

NEW_KEYPAD_BUTTON ()

Returns

None

ONLINE_CHANGED

Used by the protocol to notify the proxy if the device is online or offline. The payload of the notify message is a boolean indicating true/false

Name

ONLINE_CHANGED ()

Parameter

None

Returns

None

Keypad Button Link Bindings

KEYPAD BUTTON LINK BINDINGS

BUTTON_LINK bindings are a way for drivers to interact with other drivers that either expose a physical or virtual Keypad Button or for drivers that want to integrate with drivers that have a physical or virtual button. Button State and LED State information are the information that can be passed between the drivers. For example, a Control4 Keypad exposes a BUTTON_LINK binding that the Tune-In driver integrates with so a user can select a playlist or change songs via a Control4 Physical Keypad.

BUTTON_LINK was designed and assumes button and led functionality is the same between all keypad button hardware existing in the Control4 project, which causes some drivers to have to sometimes have incomplete or even fake functionality, ie: Button Release or Button Color functionality because some Non-Control4 physical keypads do not have LEDs. Also hardware/drivers do not have an API that allows drivers to interrogate hardware for what is supported. Some new devices also have specific double and triple click support which is newer. Note that older drivers were not updated to support those multi-press calls that go over BUTTON_LINK bindings. There is also no limit to what can be sent over a BUTTON_LINK as it's purely just a passage.

A driver making use of another drivers physical keypad buttons will typically support the following Commands and Notifies and will check the binding ID of the messages of the bound call command to know which button (BUTTON_LINK) the message applies to.

Commands

DO_PUSH Button was Pushed. Driver can expect to get a CLICK or RELEASE sometime in the future.  If a driver does not care if the button is held or clicked, Control4 recommends executing native driver's functionality on Press rather than waiting for the upcoming CLICK or RELEASE.

DO_CLICK Button was Clicked, not held. Driver can expect to get a CLICK or RELEASE sometime in the future.  If a driver does not care if the button is held or clicked, Control4 recommends executing native driver's functionality on Press rather than waiting for the upcoming CLICK or RELEASE

DO_RELEASE Button was finally released. Note that drivers might tie up Director between a users physical PUSH and RELEASE. For example, a half second push may appear to the driver as many seconds of being held. This could result in causing unwanted results such as "runaway" volume or light ramping. There is no way to detect or work around this at the current time.

REQUEST_BUTTON_COLORS Causes the driver to respond back with BUTTON_COLORS and MATCH_LED_STATE calls to let the other end of the binding know what the colors and state of them are._ 

SET_BUTTON_COLOR Used to set the color of a button, this command name can be unique or non-existent for some drivers but this should be followed to make mass setting LED's possible from driver to driver.

Notifications

BUTTON_COLORS

MATCH_LED_STATE