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 Lock 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 locks have common controls such as OPEN, CLOSE and LOCK.  The lock proxy allows for a common user interface to control all locks.  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 Lock Proxy in conjunction with O.S. Release 3.4.2.

What’s New in 3.4.1

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

What’s New in 3.4.0

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

What’s New in 3.3.2

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

What’s New in 3.3.1

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

What’s New in 3.3.0

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

What’s New in 3.2.3

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

What’s New in 3.2.2

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

What’s New in 3.2.1

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

What’s New in 3.2.0

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

What was New in 3.1.2

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

What was New in 3.1.0

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

What was New in O.S.3

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

Lock Proxy Commands

ADD_USER

Adds a user.

Signature

ADD_USER ()

Returns

None

CLOSE

Lock if status is unlocked. Called by bound relay.

Name

CLOSE ()

Parameters

None

Returns

None

DELETE_USER

Deletes a user.

Name

DELETE_USER ()

Parameters

None

Returns

None

EDIT_USER

Edits the user's schedule and status.

Name

ADD_USER ()

Returns

None

LOCK

Lock if status is unlocked.

Name

LOCK ()

Parameters

None

Returns

None

OPEN

Unlock if status is unlocked. Called by bound relay.

Name

OPEN ()

Parameters

None

Returns

None

REQUEST_CAPABILITIES

This command results in the Protocol Notification CAPABILITY_CHANGEDbeing sent from the Protocol to the Proxy.

Name

REQUEST_CAPABILITIES ()

Parameters

None

Returns

None

REQUEST_CUSTOM_SETTINGS

This command results in the Protocol Notification CUSTOM_SETTINGS being sent from the Protocol to the Proxy.

Name

REQUEST_CUSTOM_SETTINGS ()

Parameters

None

Returns

None

REQUEST_CUSTOM_SETTINGS

This command results in the Protocol Notification HISTORY being sent from the Protocol to the Proxy.

Name

REQUEST_HISTORY ()

Parameters

None

Returns

None

REQUEST_SETTINGS

This command results in the Protocol Notification SETTINGS being sent from the Protocol to the Proxy.

Name

REQUEST_SETTINGS ()

Parameters

None

Returns

None

REQUEST_USERS

This command results in the Protocol Notification USERS being sent from the Protocol to the Proxy.

Name

REQUEST_USERS ()

Parameters

None

Returns

None

SET_ADMN_CODE

Set the lock's administrator code.

Name

PSET_ADMIN_CODE ()

Returns

None

SET_AUTO_LOCK_SECONDS

Set the number of seconds to wait before locking automatically after unlocked. A value of 0 means do not auto lock. Range determined by capabilities.

Name

SET_AUTO_LOCK_SECONDS ()

Returns

None

SET_CUSTOM_SETTINGS

This command results in the Protocol Notification CUSTOM_SETTINGS being sent from the Protocol to the Proxy.

Name

SET_CUSTOM_SETTINGS ()

Returns

None

SET_LANGUAGE

Set the lock's language. Values determined by capabilities.

Name

SET_ LANGUAGE ()

Returns

None

SET_LOCK_MODE

Set the lock’s mode. The supported modes are determined by capabilities.

Name

SET_ LOCK_MODE ()

Returns

None

SET_LOG_FAILED_ATTEMPTS

For lock’s that have internal log storage, sets whether or not to log failed attempts.

Name

SET_LOG_FAILED_ATTEMPTS ()

Returns

None

SET_NUMBER_LOG_ITEMS

For locks that have internal log storage, set the maximum number of log items to store. Range determined by capabilities.

Name

SET_NUMBER_LOG_ITEMS ()

Returns

None

SET_ONE_TOUCH_LOCKING

Set whether or not keypad activation will extend bolt if unlocked.

Name

SET_ONE_TOUCH_LOCKING ()

Returns

None

SET_SCHEDULED_LOCKOUT_ENABLED

Disable or enable all user passcode access.

Name

SET_SCHEDULED_LOCKOUT_ENABLED ()

Returns

None

SET_SHUT_OUT_TIMER

Set the number of seconds to wait after wrong code attempts has been reached. Range determined by capabilities.

Name

SET_SHUT_OUT_TIMER ()

Returns

None

SET_WRONG_CODE_ATTEMPTS

Set the number of failed passcode attempts before users are temporarily shut out. Range determined by capabilities.

Name

SET_WRONG_CODE_ATTEMPTS ()

Returns

None

SET_VOLUME

Sets the lock’s volume.

Name

SET_VOLUME ()

Returns

None

TOGGLE

Toggle the state of the lock. If the lock status is unknown or default, the resulting status is indeterminable

Name

TOGGLE ()

Parameter

None

Returns

None

UNLOCK

Unlock if status is locked.

Signature

UNLOCK ()

Parameter

None

Returns

None

Lock Protocol Notifications

BATTERY_STATUS_CHANGED

Sent when battery status changed.

Name

BATTERY_STATUS_CHANGED ()

CAPABILITY_CHANGED

Sent when a capability changes; or when requested by the protocol driver command REQUEST_CAPABILITES, and a capability has changed from what is defined in the driver capabilities XML

Name

CAPABILITY_CHANGED ()

HISTORY

Sent in response to the command REQUEST_HISTORY.

Name

HISTORY ()

Parameter

None

Returns

None

Example

<lock_history>
    <history_item>
        <history_id>history-ID INT</history_id>
        <date>date STRING</date>
        <time>time STRING</time>
        <message>message STRING</message>
        <source>source STRING</source>
    </history_item>
</lock_history>

CUSTOM_SETTINGS

Sent in response to the command REQUEST_CUSTOM_SETTINGS.

Name

CUSTOM_SETTINGS ()

Parameter

None

Returns

None

Example

<lock_custom_settings>
    <custom_setting>
        <name>name STRING</name>
        <type>STRING,LIST,RANGED_INTEGER,RANGED_FLOAT,BOOLEAN</type>
        <mode> alpha|alpha-numeric|password</mode>
        <items>
            <item>item</item>
            <item>item</item>
        </items>
        <minimum>min</minimum>
        <maximum>max</maximum>
        <value>value</value>
</custom_setting>
</lock_custom_settings>

CUSTOM_SETTINGS_CHANGED

Sent in when a custom setting changes

Name

CUSTOM_SETTINGS_CHANGED ()

Parameter

None

Returns

None

LOCK_STATUS_CHANGED

Sent in when a lock status changes for any reason.

Name

LOCK_STAUS_CHANGED ()

Returns

None

SETTINGS

Sent in response to the command REQUEST_SETTINGS.

Name

SETTINGS ()

Parameters

None

Returns

None

Example

<lock_settings>
    <admin_code>admin-code STRING</admin_code>
    <auto_lock_time>nINT</auto_lock_time>
    <log_item_count>nINT </log_item_count>
    <schedule_lockout_enabled>true|false</schedule_lockout_enabled>
    <lock_mode> normal|vacation|privacy</lock_mode>
    <log_failed_attempts>true|false</log_failed_attempts>
    <wrong_code_attempts>nINT</wrong_code_attempts>
    <shutout_timer>nINT</shutout_timer>
    <language>English|French|Spanish|etc</language>
    <volume>silent|low|high</volume>
    <one_touch_locking>true|false</one_touch_locking>
</lock_settings>

SETTINGS_CHANGED

Sent when a setting changes.

Name

SETTINGS_CHANGED ()

Returns

None

USERS

Sent in response to the command REQUEST_HISTORY.

Name

USERS ()

Parameter

None

Returns

None

USER_ADDED

Sent when a user is added.

Name

USER_ADDED ()

Returns

None

USER_CHANGED

Sent when a user setting is changed.

Name

USER_CHANGED ()

Returns

None

USER_DELETED

Sent when a user setting is deleted.

Name

USER_DELETED ()

Returns

None

Lock Capabilities

LOCK CAPABILITIES

The following Capabilities are supported with the Lock Proxy. Note that these capabilities will persist their values. This can result in inaccurate capability values being displayed on Navigators.

The correct way to update these capabilities when a driver is updated is with the DYNAMIC_CAPABILITY_CHANGED notification. For example see the lua code to the right which uses name/value pairs:

C4:SendToProxy(5001, 'CAPABILITY_CHANGED', { NAME = 'shutout_timer_values', VALUE = '10, 30' } , 'NOTIFY')


C4:SendToProxy(5001, 'CAPABILITY_CHANGED', { NAME = 'shutout_timer_display_values', VALUE = '10s, 30s' }, 'NOTIFY') 

Capabilities

<auto_lock_time_display_values></auto_lock_time_display_values>

Comma delimited list of correlating display values: str

<auto_lock_time_values></auto_lock_time_values>

Comma delimited list of increasing values: int

<has_admin_code></has_admin_code>

Defines whether the lock has an admin code that must be entered to access lock management. true|false

<has_auto_lock_time></has_auto_lock_time>

Defines whether a lock has an auto lock setting. A lock can auto lock after a set amount of time or not auto lock if time set to 0 – OFF: true|false

<has_custom_settings></has_custom_settings>

Defines whether the lock supports any custom settings that should be added to the list of standard proxy defined settings. See lock_custom_settings data-to-ui: true|false

<has_date_range_schedule></has_date_range_schedule>

Defines whether the lock supports a date range schedule for users: true|false

<has_daily_schedule></has_daily_schedule>

Defines whether the lock supports a daily schedule for users: true|false

<has_internal_history></has_internal_history>

Defines whether the lock maintains its own list of log / history items: true|false

<has_language></has_language>

Defines whether the lock has a setting for different languages: true|false

<has_log_item_count></has_log_item_count>

Defines whether a lock has a setting for the number of log items to store for internal logging/history: true|false

<has_log_failed_attempts></has_log_failed_attempts>

Defines whether a lock has a setting for logging failed keypad unlock attempts: true|false

<has_lock_modes></has_lock_modes>

Defines whether the lock has a setting for different modes. Vacation mode prevents users from opening a lock using the keypad. Privacy mode prevents users from opening a lock using the keypad. However, if a key is used during privacy mode the lock resets to normal mode. Not all modes have to be supported. true|false

<has_one_touch_locking></has_one_touch_locking>

Defines whether the lock has a setting to allow one touch locking at the keypad without entering full key code: true|false

<has_schedule_lockout></has_schedule_lockout>

Defines whether a lock has a schedule lockout setting. The schedule lockout can be used to prevent all users from manually unlocking a lock using the lock's keypad. This is similar to privacy mode: true|false

<has_settings></has_settings>

Defines whether the lock supports any settings: true|false

<has_shutout_timer></has_shutout_timer>

Defines whether the lock has a setting for how long to disable lock keypad after failed attempts: true|false

<has_volume></has_volume>

Defines whether the lock has a setting for volume: true|false

<has_wrong_code_attempts</has_wrong_code_attempts>

Defines whether the lock has a setting for the number of failed unlock attempts to allow before temporarily disabling the lock: true|false

<is_management_only></is_management_only>

Defines whether the lock is only used for managing users A lock that is management only does not support the LOCK, UNLOCK, and TOGGLE commands: true|false

<language_values></language_values>

English, French, Spanish …: str

<lock_modes_values></lock_modes_values>

normal, vacation, privacy: str

<log_item_count_values></log_item_count_values>

Comma delimited list of increasing values: int

<max_users></max_users>

The maximum number of user that can be added to a lock: int

<shutout_timer_display_values></shutout_timer_display_values>

Comma delimited list of correlating display values: str

<shutout_timer_values></shutout_timer_values>

Comma delimited list of increasing values: int

<wrong_code_attempts_values> </wrong_code_attempts_values>

Comma delimited list of increasing values: int

Lock Conditionals

LOCK CONDITIONALS

The Lock Proxy supports the following conditionals:

IS_LOCKED

IS_UNKNOWN

IS_UNLOCKED

IS_FAULT

IS_BATTERY_NORMAL

IS_BATTERY_WARNING

IS_BATTERY_CRITICAL

Lock Events

LOCK EVENTS

The Lock Proxy fires the following events:

Locked (1) – UI, keypad or deadbolt.

Unlocked (2) – UI, keypad or deadbolt.

LockedManually (3) – Keypad or deadbolt.

UnlockedManually (4) – Keypad or deadbolt.

LockedProxy (5) - Locked via the Proxy.

UnlockedProxy (6) - Unlocked via the proxy.

Fault (7) -Door/Lock Jam Event. Battery too low.

BatteryNormal (8) - Battery state change from Normal.

BatteryWarning (9) - Battery state change from Warning.

BatteryCritical (10) - Battery state change from Critical.

Lock Variables

LOCK VARIABLES

The Lock Proxy supports the following variables:

LockStatus (1000) – STRING: unknown, locked, unlocked, fault

BatteryStatus (1001) – STRING: normal, warning, critical

LastActionDescription (1002) - STRING: Description of the last action for the lock. For example: "User opened Lock." "Lock was Toggled."