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 Thermostat 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 Thermostats have common controls such as INCREASE SET POINT, DECREASE SET POINT and SET PRESET. The Thermostat proxy allows for a common user interface to control all Thermostats. 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 Thermostat Proxy in conjunction with O.S. Release 3.4.2

What’s New in 3.4.1

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

What’s New in 3.4.0

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

What’s New in 3.3.2

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

What’s New in 3.3.1

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

What’s New in 3.3.0

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

What’s New in 3.2.3

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

What’s New in 3.2.2

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

What’s New in 3.2.1

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

What’s New in 3.2.0

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

What was New in 3.1.2

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

What was New in 3.1.0

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

What was New in O.S.3

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

What was New in 4.3.0

New Capabilities

Modified Capabilities

Variables

LOCK_SCREEN_MODE

Events

LOCK_SCREEN_MODE_CHANGED

New Notifications

Modified Notifications

SCHEDULE_ENTRY_CHANGED

Dynamic Notifications

New Commands

Modified Commands

Thermostat Capabilities

THERMOSTAT CAPABILITIES

The following Capabilities are supported with the Thermostat Proxy.

Note the reference to the Dynamic Capabilities Changed notification in many of the capabilities defined below. Using the Dynamic Capabilities notify is a way for a protocol driver to send updates about some capabilities that can be changed when settings change on the hardware. An example would be a thermostat that now includes a humidifier. The thermostat would need to tell the proxy it can now do humidification. The <can_humidify></can_humidify> capability is designated as a capability that can be changed using Dynamic Capabilities Changed. The capability can be passed as a parameter in the notify to update the thermostat proxy regarding humidification ability.

Additionally, please see the Samples folder delivered in this SDK for additional Thermostat (V2) code examples.

can_calibrate

Indicates if the device is capable of calibrating itself. Enables the SET_CALIBRATION command. Valid values: True/False.

can_change_scale

Boolean to enable/disable Navigator UIs and ComposerPro from being able to change the scale of the hardware. Valid values: True/False. This capability can be changed through a DYNAMIC_CAPABILITIES_CHANGED notification.

can_cool

Indicates if this thermostat supports cooling and indicates to UIs and Programming that the device could execute this functionality. Valid values: True/False. This capability can be changed through a DYNAMIC_CAPABILITIES_CHANGED notification.

can_dehumidify

Boolean to enable/disable can_dehumidity capability, if the device supports this feature, default is True. This capability can be changed through a DYNAMIC_CAPABILITIES_CHANGED notification. This is older functionality that indicated to UI's and Programming that the device could execute this functionality. However, their limitation is that they do not take into account if the current HVAC mode supported them. HVAC Modes replaced their functionality, but older drivers still use them and they do work. Control4 recommends the use of HVAC Modes now and that this capability be set to false in the driver's configuration file.

can_do_auto

Indicates if this thermostat can automatically switch from heat to cool and indicates to UIs and Programming that the device could execute this functionality. If the device can deadband enforcement, it will be done on the UIs as specified with the deadband capabilities. Valid values: True/False. This capability can be changed through a DYNAMIC_CAPABILITIES_CHANGED notification.

can_fixed_schedule_and_presets

Introduced in 4.3.0. Indicates support for both the legacy schedule plus presets. When <can_fixed_schedule_and_presets> is true then <can_preset> and <can_preset_schedule> should be set to false. This capability allows the driver to use the legacy scheduler along with supporting presets. This capability can be changed through a DYNAMIC_CAPABILITIES_CHANGED notification.

can_heat

Indicates if this thermostat supports heating and indicates to UIs and Programming that the device could execute this functionality. Valid values: True/False. This capability can be changed through a DYNAMIC_CAPABILITIES_CHANGED notification.

can_humidify

Boolean to enable/disable can_humidity capability, if the device supports this feature, default is True. It indicates to UIs and Programming that the device could execute this functionality. This capability can be changed through a DYNAMIC_CAPABILITIES_CHANGED notification.

can_inc_dec_setpoints

Boolean indicating if the device has internal commands to increment and decrement both heat and cool set points independently. If false the proxy will take the current setpoint and +/- 1 (or the resolution) and send a DYNAMIC_CAPABILITIES_CHANGED command with the new setpoint value, which could potentially send 81 three times if someone did programming of Increment Setpoint and the current setpoint was 80, rather than sending 83 as someone might expect from Composer Programming of 3 increment commands without a sleep between that provides enough time for the hardware to set each increment and return the new setpoint to director before the next Increment occurs.

can_lock_buttons

Indicates if the buttons on the TSTAT can be locked out to prevent changes. Valid values: True/False.

can_lock_screen

Introduced in 4.3.0. Indicates if the screen on the thermostat device is able to be locked. The modes that are supported are provided by the <lock_screen_modes> capability. This capability can be changed through a DYNAMIC_CAPABILITIES_CHANGED notification.

lock_screen_modes

Introduced in 4.3.0. Comma delimited string of possible screen-lock modes. Used with '<can_lock_screen'. For example: Unlocked,Partially Locked,Fully Locked. This capability can be changed through a DYNAMIC_CAPABILITIES_CHANGED notification.

can_preset

Boolean indicating if the device supports the preset functionality including custom_fields. This capability can be changed through a DYNAMIC_CAPABILITIES_CHANGED notification.

can_preset_schedule

Boolean indicating if the thermostat will support the SET_EVENTS commands for running presets based on scheduling created in Navigators. This capability can be changed through a DYNAMIC_CAPABILITIES_CHANGED notification.

current_temperature_max_c

Double indicating the maximum temperature that the thermostat will report in C. Default is 48. This capability can be changed through a DYNAMIC_CAPABILITIES_CHANGED notification.

current_temperature_min_c

Double indicating the minimum temperature that the thermostat will report in C. Default is -40. This capability can be changed through a DYNAMIC_CAPABILITIES_CHANGED notification.

current_temperature_max_f

Double indicating the maximum temperature that the thermostat will report in F. Default is 120. This capability can be changed through a DYNAMIC_CAPABILITIES_CHANGED notification.

current_temperature_min_f

Double indicating the minimum temperature that the thermostat will report in F. Default is -40. This capability can be changed through a DYNAMIC_CAPABILITIES_CHANGED notification.

current_temperature_resolution_c

Double indicating the increments that the temperature will follow, such as .1, .5, 1, 2, 5, etc. Default is 1. This capability can be changed through a DYNAMIC_CAPABILITIES_CHANGED notification.

current_temperature_resolution_f

Double indicating the increments that the temperature will follow, such as .2, .5, 1, 2, 5, etc. Default is 1. Note .2 is the lowest F resolution supported. This capability can be changed through a DYNAMIC_CAPABILITIES_CHANGED notification.

fan_modes

This is a comma delimited list of possible fan modes this thermostat supports. For example: Auto, Low, Medium, High with no spaces after the comma. This capability can be changed through a DYNAMIC_CAPABILITIES_CHANGED notification.

fan_states

This is a comma delimited list of all the possible states that the HVAC system fan supports. For example: Off, On, Low, Med, Circulate with no spaces after the commas. This capability can be changed through a DYNAMIC_CAPABILITIES_CHANGED notification.

has_humidity

Boolean indicating if the device can report the current humidity. This capability can be changed through a DYNAMIC_CAPABILITIES_CHANGED notification.

has_extras

Boolean indicating if the device has extras commands support. This capability can be changed through a DYNAMIC_CAPABILITIES_CHANGED notification.

has_connection_status

Boolean indicating if the device reports online/offline status of the hardware device, this is often forgotten about but very important to implement in new protocol drivers drivers.

has_outdoor_temperature

Boolean indicating if the device can provide an outdoor temperature. This capability can be changed through a DYNAMIC_CAPABILITIES_CHANGED notification.

has_remote_sensor

Indicates if this thermostat has a remote sensor. Valid values: True/False.

has_single_setpoint

Boolean indicating if the device is single setpoint. can_heat, can_cool and can_auto should be set to false if this option is used. It indicates to UIs and Programming that the device could execute this functionality. This capability can be changed through a DYNAMIC_CAPABILITIES_CHANGED notification.

has_temperature

Boolean indicating if the device can provide a temperature of the thermostat/room. This capability can be changed through a DYNAMIC_CAPABILITIES_CHANGED notification.

has_vacation_mode

Vacation support has been deprecated. This capability should always be set to false.

hold_modes

This is a comma delimited list of the possible hold modes this thermostat supports. Valid values include: Off, 2 Hours, Until Next, Permanent with no spaces after the commas. This capability can be changed through a DYNAMIC_CAPABILITIES_CHANGED notification.

hold_until_mode

Introduced in 4.3.0. Controls whether Hold Until uses time semantics or date,time semantics. The default is date,time. Some thermostats only supports setting the hold until mode within a 24 hour period and only supplies the time. If this is the case then set <hold_until_mode> to "time".

hold_until_resolution

Introduced in 4.3.0. Minute resolution used for Hold Until rounding and UI input behavior. Double indicating the increments that the hold_until will follow, such as 1, .5, 10 etc. Default is 5.

humidity_modes

A comma separated list of all the modes the device supports. For example: "Off,Humidify,Dehumidify,Auto" with no spaces after the commas. This capability can be changed through a DYNAMIC_CAPABILITIES_CHANGED notification.

humidity_states

A comma separated list of all the modes the device supports. Usually something like "Off,Humidifying,Dehumidifying", with no spaces after the commas.

hvac_modes

A comma separated list of all the modes the device supports. For example: "Off,Heat,Cool", with no spaces after the commas.

hvac_states

This is a comma delimited list that represents all of the possible states that the HVAC system supports. For example: Off, Heat, Cool, Heating, Stage 1 Cool, etc with no spaces after the commas

outdoor_temperature_resolution_c

Double indicating the increments that the temperature will follow, such as .2, .5, 1, 2, 5, etc. Default is 1. Note that .2 is the lowest C resolution supported. This capability can be changed through a DYNAMIC_CAPABILITIES_CHANGED notification.

outdoor_temperature_resolution_f

preset_fields

XML of fields for settings that are potentially unique to the protocol driver, yet will be displayed in the UI during the creation or modification of presets for scheduling. This capability can be changed through a DYNAMIC_CAPABILITIES_CHANGED notification.

scheduling

A boolean indicating if the device supports a programmed schedule. If it is true, it should have a schedule_default entry in the capabilities section in the driver.xml file. Mutually exclusive to Preset Scheduling unless can_fixed_schedule_and_presets is true. In 4.3.0, scheduling and schedule_default can be handled dynamically. If either capability is missing from the static capability set, thermostatV2 proxy treats it through the dynamic capability flow. If scheduling is true and the driver is not providing schedule_default through that dynamic flow, the driver should provide a schedule_default block in driver.xml.

schedule_default

An XML block indicating the default schedule for the device. Legacy scheduling is mutually exclusive to preset scheduling unless can_fixed_schedule_and_presets is true which was introduced in 4.3.0. In 4.3.0, scheduling and schedule_default can be handled dynamically. If either capability is missing from the static capability set, thermostatV2 proxy treats it through the dynamic capability flow. If scheduling is true and the driver is not providing schedule_default through that dynamic flow, the driver should provide a schedule_default block in driver.xml. See the example below.

<schedule_default>
    <schedule_day_info Entries = "6" DefaultHeat = "200" DefaultCool = "278">
        <schedule_entry Name = "Wake" Time = "360" Enabled = "True" CanChangeName="False" CanDelete="False"/>
        <schedule_entry Name = "Leave" Time = "480" Enabled = "True" CanChangeName="False" CanDelete="False"/>
        <schedule_entry Name = "Return" Time = "1080" Enabled = "True" CanChangeName="False" CanDelete="False"/>
        <schedule_entry Name = "Sleep" Time = "1320" Enabled = "True" CanChangeName="False" CanDelete="False"/>
        <schedule_entry Name = "Custom 1" Time = "1380" Enabled = "False" CanChangeName="True" CanDelete="True"/>
        <schedule_entry Name = "Custom 2" Time = "1380" Enabled = "False" CanChangeName="True" CanDelete="True"/>
    </schedule_day_info>
</schedule_default>

Example of driver providing the schedule default

local DEFAULT_SCHEDULE_ENTRIES = {
    { EntryIndex = 1, TimeHour = 6, TimeMinute = 0, Enabled = true, HeatSetpoint = 70, CoolSetpoint = 74, Scale = "F", CanChangeName = false, CanDelete = false, EntryName = "Wake" },
    { EntryIndex = 2, TimeHour = 9, TimeMinute = 0, Enabled = true, HeatSetpoint = 71, CoolSetpoint = 75, Scale = "F", CanChangeName = false, CanDelete = false, EntryName = "Away" },
    { EntryIndex = 3, TimeHour = 16, TimeMinute = 0, Enabled = true, HeatSetpoint = 72, CoolSetpoint = 76, Scale = "F", CanChangeName = false, CanDelete = false, EntryName = "Home" },
    { EntryIndex = 4, TimeHour = 22, TimeMinute = 0, Enabled = true, HeatSetpoint = 73, CoolSetpoint = 77, Scale = "F", CanChangeName = false, CanDelete = false, EntryName = "Sleep" },
    { EntryIndex = 5, TimeHour = 22, TimeMinute = 40, Enabled = true, HeatSetpoint = 74, CoolSetpoint = 78, Scale = "F", CanChangeName = true, CanDelete = true, EntryName = "Custom 1" },
    { EntryIndex = 6, TimeHour = 23, TimeMinute = 0, Enabled = true, HeatSetpoint = 75, CoolSetpoint = 79, Scale = "F", CanChangeName = true, CanDelete = true, EntryName = "Custom 2" }
}

function SetDefaultSchedule()
    for dayIndex = 0, 6 do
        for _, entry in ipairs(DEFAULT_SCHEDULE_ENTRIES) do
            SetScheduleEntry(
                dayIndex,
                entry.EntryIndex,
                entry.TimeHour,
                entry.TimeMinute,
                entry.Enabled,
                entry.HeatSetpoint,
                entry.CoolSetpoint,
                entry.Scale,
                entry.CanChangeName,
                entry.CanDelete,
                entry.EntryName
            )
        end
    end
end

function SetScheduleEntry(dayOfWeek, entryIndex, timeHour, timeMinute, isEnabled, heatSetpoint, coolSetpoint, scale, canChangeName, canDelete, entryName)
    LogTrace("SetScheduleEntry  %s %s %s %s %s %s %s %s %s %s %s", tostring(dayOfWeek), tostring(entryIndex), tostring(timeHour), tostring(timeMinute), tostring(isEnabled), tostring(heatSetpoint), tostring(coolSetpoint), tostring(scale), tostring(canChangeName), tostring(canDelete), tostring(entryName))

local zeroBasedEntryIndex = tonumber(entryIndex)
    if(zeroBasedEntryIndex == nil) then
        zeroBasedEntryIndex = 1
    end
    zeroBasedEntryIndex = zeroBasedEntryIndex - 1

local params = {
        DayIndex = tostring(dayOfWeek),
        EntryIndex = tostring(zeroBasedEntryIndex),
        EnabledFlag = tostring(isEnabled),
        TimeMinutes = tostring((tonumber(timeHour) or 0) * 60 + (tonumber(timeMinute) or 0)),
        HeatSetpoint = tostring(heatSetpoint),
        CoolSetpoint = tostring(coolSetpoint),
        Units = tostring(scale)
    }

if(canChangeName ~= nil) then
        params.CanChangeName = tostring(toboolean(canChangeName))
    end

if(canDelete ~= nil) then
        params.CanDelete = tostring(toboolean(canDelete))
    end

if(entryName ~= nil and tostring(entryName) ~= "") then
        params.EntryName = tostring(entryName)
    end

SendNotify("SCHEDULE_ENTRY_CHANGED", params, 5001)

if(type(UpdateScheduleEntryCapabilityTracking) == "function") then
        UpdateScheduleEntryCapabilityTracking(zeroBasedEntryIndex, entryName, canChangeName, canDelete)
    end
end

schedule_entry

There is one <schedule_entry> for each schedule entry during the day. Each entry attribute defines that entry. The following table describes each of the potential attributes. CanChangeName and CanDelete were added in OS Release 4.3.0.

Attribute	Version	Value	Description
Name		String	Indicates the name of the entry that will show up in composer and navigator.
Time		Number	Indicates the name of the entry that will show up in composer and navigator. The time units are minutes since midnight, so 360 means 6:00 AM.
Enabled		True/False	Indicates whether or not this entry is initially enabled or not.
CanChangeName	4.3.0	True/False	Indicates whether or not this entry name can be changed. This is optional. Default is False.
CanDelete	4.3.0	True/False	Indicates whether or not this entry can be deleted. This is optional. Default is False.

In the example used here, there are six schedule entries.

<schedule_day_info>
   <schedule_entry Name="Awake" Time="360" Enabled="True" CanChangeName="False" CanDelete="False" />
   <schedule_entry Name="Leave" Time="480" Enabled="True" CanChangeName="False" CanDelete="False" />
   <schedule_entry Name="Return" Time="1080" Enabled="True" CanChangeName="False" CanDelete="False" />
   <schedule_entry Name="Sleep" Time="1320" Enabled="True" CanChangeName="False" CanDelete="False" />
   <schedule_entry Name="Custom 1" Time="1380" Enabled="False" CanChangeName="True" CanDelete="True" />
   <schedule_entry Name="Custom 2" Time="1380" Enabled="False" CanChangeName="True" CanDelete="True" />
</schedule_day_info>

setpoint_cool_max

Integer indicating the highest temperature the cool setpoint can be configured as. Default is 89. If used,_f and _c do not need to be set but since this value is Celsius x 10, it will result in a potentially undesired Fahrenheit conversion. This capability can be changed through a DYNAMIC_CAPABILITIES_CHANGED notification.

setpoint_cool_max_c

Integer indicating the highest temperature the cool setpoint can be configured as. Default is 90. This capability can be changed through a DYNAMIC_CAPABILITIES_CHANGED notification.

setpoint_cool_max_f

Integer indicating the highest temperature the cool setpoint can be configured as. Default is 89. This capability can be changed through a DYNAMIC_CAPABILITIES_CHANGED notification.

setpoint_cool_min

Integer indicating the lowest temperature the cool setpoint can be configured as. Default is 39. If used,_f and _c do not need to be set but since this value is Celsius x 10 it will result in a potentially undesired Fahrenheit conversion. This capability can be changed through a DYNAMIC_CAPABILITIES_CHANGED notification.

setpoint_cool_min_c

Integer indicating the lowest temperature the cool setpoint can be configured as. Default is 42. If used, _f and _c do not need to be set but since this value is Celsius x 10 it will result in a potentially undesired Fahrenheit conversion. This capability can be changed through a DYNAMIC_CAPABILITIES_CHANGED notification.

setpoint_cool_min_f

Integer indicating the lowest temperature the cool setpoint can be configured as. Default is 42. This capability can be changed through a DYNAMIC_CAPABILITIES_CHANGED notification.

setpoint_cool_resolution_c

Double indicating the increments that the setpoint will follow, such as .1, .5, 1, 2, 5, etc. Default is 1. This capability can be changed through a C notification.

setpoint_cool_resolution_f

Double indicating the increments that the setpoint will follow, such as .1, .5, 1, 2, 5, etc. Default is 1. This capability can be changed through a DYNAMIC_CAPABILITIES_CHANGED notification.

setpoint_heatcool_deadband_c

Double indicating the deadband range in Celcius that the hardware requires between heat and cool. Default is 2. Default is 2. Post operating system 2.7.0, UI's will show both heat and cool setpoints moving if in Auto and the movement will be based on this deadband value. If a user tries to move heat above cool or cool below heat, the UI's will only send the setpoint command for the primarily moving setpoint. A protocol driver will need to send two notifies back, one for heat and one for cool if in fact both setpoints were changed on the hardware. This capability can be changed through a DYNAMIC_CAPABILITIES_CHANGED notification.

setpoint_heatcool_deadband_f

Double indicating the deadband range in Fahrenheit that the hardware requires between heat and cool. Default is 2. Post operating system 2.7.0, UI's will show both heat and cool setpoints moving if in Auto and the movement will be based on this deadband value. If a user tries to move heat above cool or cool below heat, the UI's will only send the setpoint command for the primarily moving setpoint. A protocol driver will need to send two notifies back, one for heat and one for cool if in fact both setpoints were changed on the hardware. This capability can be changed through a DYNAMIC_CAPABILITIES_CHANGED notification.

setpoint_heat_max

Integer indicating the highest temperature the heat setpoint can be configured as. Default is 88. If used, _f and_c do not need to be set but since this value is Celsius x 10 it will result in a potentially undesired Fahrenheit conversion. This capability can be changed through a DYNAMIC_CAPABILITIES_CHANGED notification.

setpoint_heat_max_c

Integer indicating the highest temperature the heat setpoint can be configured as. Default is 31. Best to use _f and _c and not the older celsius x 10 capability. This capability can be changed through a DYNAMIC_CAPABILITIES_CHANGED notification.

setpoint_heat_max_f

Integer indicating the highest temperature the heat setpoint can be configured as. Default is 89. Best to use _f and _c and not the older celsius x 10 capability. This capability can be changed through a DYNAMIC_CAPABILITIES_CHANGED notification.

setpoint_heat_min

Integer indicating the lowest temperature the heat setpoint can be configured as. Default is 40. If used, _f and _c do not need to be set but since this value is Celsius x 10 it will result in a potentially undesired Fahrenheit conversion. This capability can be changed through a DYNAMIC_CAPABILITIES_CHANGED notification.

setpoint_heat_min_c

Integer indicating the lowest temperature the heat setpoint can be configured as. Default is 4. Best to use _f and _c and not the older Celsius x 10 capability. This capability can be changed through a DYNAMIC_CAPABILITIES_CHANGED notification.

setpoint_heat_min_f

Integer indicating the lowest temperature the heat setpoint can be configured as. Default is 38. Best to use _f and _c and not the older celsius x 10 capability. This capability can be changed through a DYNAMIC_CAPABILITIES_CHANGED notification.

setpoint_heat_resolution_c

Double indicating the increments that the setpoint will follow, such as .1, .5, 1, 2, 5, etc. Default is 1. This capability can be changed through a DYNAMIC_CAPABILITIES_CHANGED notification.

setpoint_heat_resolution_f

Double indicating the increments that the setpoint will follow, such as .1, .5, 1, 2, 5, etc. Default is 1. This capability can be changed through a DYNAMIC_CAPABILITIES_CHANGED notification.

setpoint_dehumidify_max

Integer indicating the highest dehumidify setpoint, default 100. This capability can be changed through a DYNAMIC_CAPABILITIES_CHANGED notification.

setpoint_dehumidify_min

Integer indicating the lowest dehumidify setpoint, default 0. This capability can be changed through a DYNAMIC_CAPABILITIES_CHANGED notification.

setpoint_humidify_min

Integer indicating the lowest humidify setpoint, default 0. This capability can be changed through a DYNAMIC_CAPABILITIES_CHANGED notification.

setpoint_humidify_max

Integer indicating the highest humidify setpoint, default 100. This capability can be changed through a DYNAMIC_CAPABILITIES_CHANGED notification.

setpoint_humidify_resolution

Integer indicating the increments that the setpoint will follow, Default is 1. This capability can be changed through a DYNAMIC_CAPABILITIES_CHANGED notification.

setpoint_dehumidify_resolution

Integer indicating the increments that the setpoint will follow, Default is 1. This capability can be changed through a DYNAMIC_CAPABILITIES_CHANGED notification.

setpoint_single_max_c

Integer indicating the highest temperature the single setpoint can be configured as. Default is 32. This capability can be changed through a DYNAMIC_CAPABILITIES_CHANGED notification.

setpoint_single_max_f

Integer indicating the highest temperature the single setpoint can be configured as. Default is 90. This capability can be changed through a DYNAMIC_CAPABILITIES_CHANGED notification.

setpoint_single_min_c

Integer indicating the lowest temperature the single setpoint can be configured as. Default is 4. This capability can be changed through a DYNAMIC_CAPABILITIES_CHANGED notification.

setpoint_single_min_f

Integer indicating the lowest temperature the single setpoint can be configured as. Default is 38. This capability can be changed through a DYNAMIC_CAPABILITIES_CHANGED notification.

setpoint_heat_resolution_f

Double indicating the increments that the setpoint will follow, such as .2, .5, 1, 2, 5, etc. Default is 1. Note .2 is the lowest F resolution supported. This capability can be changed through a DYNAMIC_CAPABILITIES_CHANGED notification.

Thermostat Conditionals

THERMOSTAT CONDITIONALS

The following Conditionals are supported with the Thermostat Proxy and can be used in ComposerPro Programming. Please see the Samples folder delivered in this SDK for Thermostat (V2) code examples.

IF_COOL_SETPOINT - simple integer test against the current cool setpoint.
IF_FAN_MODE - simple boolean test to see if the fan is in a given mode.
IF_FAN_STATE - simple boolean test to see if the fan is in a given state.
IF_HEAT_SETPOINT - simple integer test against the current heat setpoint.
IF_HOLD_MODE - simple boolean test to see if the hold mode is in a given mode.
IF_HUMIDIFY_SETPOINT - simple integer test on an int number to see if the current humidify setpoint is a supplied value.
IF_HUMIDITY - numeric comparison against the current humidity value.
IF_HUMIDITY_MODE - simple boolean test on a string to see if the humidity mode is in a given mode.
IF_HUMIDITY_STATE - simple boolean test on a string to see if the humidity state is in a given mode.
IF_HVAC_MODE - simple boolean test to see if the HVAC is in a given mode.
IF_HVAC_STATE - simple boolean test to see if the HVAC is in a given state.
IF_DEHUMIDIFY_SETPOINT - numeric comparison against the current dehumidify setpoint.
IF_OUTDOOR_TEMPERATURE - simple integer test to see if the current temperature is a supplied value. No manipulation is done on the units for the temperature. If the thermostat is configured to be Celsius, the value to compare it with should be in Celsius as well.
IF_PRESET - simple boolean test to see if the preset is in a given name.
IF_SINGLE_SETPOINT - numeric comparison against the current single setpoint.
IF_TEMPERATURE - simple integer test to see if the current temperature is a supplied value. No manipulation is done on the units for the temperature. If the thermostat is configured to be celsius, the value to compare it with should be in Celsius as well.

Thermostat Connections

THERMOSTAT CONNECTION CLASSES

The Thermostat Proxy has three output connections. These include:

Temperature (Class: TEMPERATURE_VALUE) - Used to send temperature received from the proxy driver to other driver(s)
Outdoor Temperature (Class: TEMPERATURE_VALUE) - Used to send temperature received from the proxy driver to other driver(s)
Humidity (Class: HUMIDITY_VALUE) - Used to send humidity received from the proxy driver to other driver(s)

TEMPERATURE AND OUTDOOR VALUE CONNECTION CLASS COMMANDS

GET_SENSOR_VALUE

Used to require remote temperature sensor data via the control input connection binding. Note that command handling is not implemented in some drivers with a temperature control output connection. Sensor data cannot be be requested from these drivers.

Signature

GET_SENSOR_VALUE ()

| Parameter |

None

VALUE_INITIALIZED

The value has been initialized. OnBindingChanged will cause this command to be sent automatically when the sending device goes Online.

Signature

VALUE_INITIALIZED ()

Parameter	Description
str	STATUS : Default is the status after first loading a driver and the value has never been set. `active` - Status if the value is active. `last_known` - The Last value received. The device either went offline or it has not been heard from since a reboot.
int	TIMESTAMP: Timestamp of when the last value was received.

VALUE_CHANGED

The value has changed.

Signature

VALUE_CHANGED ()

Parameter	Description
int	CELSIUS - Float - Celsius temperature value.
int	FAHRENHEIT - Float - Fahrenheit temperature value.
int	TIMESTAMP - Timestamp When the change occurred.

VALUE_UNAVAILABLE

The value is possibly no longer accurate. OnBindingChanged, device went Offline, etc

Signature

VALUE_CHANGED ()

Parameter	Description
str	STATUS: offline - Device went offline or was unbound

HUMIDITY VALUE CONNECTION CLASS COMMANDS

Please see the Samples folder delivered in this SDK for Thermostat (V2) code examples.

VALUE_INITIALIZED

The value has been initialized. OnBindingChanged will cause this command to be sent automatically when the sending device goes Online.

Signature

VALUE_INITIALIZED ()

Parameter	Description
str	STATUS: Default is the status after first loading a driver and the value has never been set. `active` - Status if the value is active. `last_known` - The Last value received. The device either went offline or it has not been heard from since a reboot.
int	TIMESTAMP: Timestamp of when the change occurred.

VALUE_CHANGED

The value has changed.

Signature

VALUE_CHANGED ()

Parameter	Description
int	VALUE
int	TIMESTAMP: Timestamp of when the change occurred.

VALUE_UNAVAILABLE

The value is possibly no longer accurate. OnBindingChanged, device went Offline, etc

Signature

VALUE_UNAVAILABLE ()

Parameter	Description
str	STATUS: offline - Device went offline or was unbound.

Thermostat Events

THERMOSTAT EVENTS

The Thermostat Proxy fires the following events. If any of the registered variables change value, an event is fired; however those events are generated by the Variable Manager, and the proxy doesn't concern itself with those. Like most old proxies, events could be eliminated by just having programming use the registered variables.

In the past some UI's listened for variables not DataToUI calls. In 2.7.0 all UI's no longer listen to variable changed events, but it's worth noting that old UI's did.

Temperature Change (Event=100)

Heat Setpoint Changed (Event=101)

Cool Setpoint Changed (Event=102)

HVAC Mode Changed (Event=103)

Fan Mode Changed (Event=104)

Hold Mode Changed (Event=105)

HVAC State Changed (Event=106)

Fan State Changed (Event=107)

Outdoor Temperature Changed (Event=109)

Humidity Changed (Event=110)

Humidity Mode Changed (Event=111)

Humidity State Changed (Event=112)

Humidify Setpoint Changed (Event=113)

Dehumidify Setpoint Changed (Event=114)

Message Changed (Event=115)

Preset Changed (Event=116)

Single Setpoint Changed (Event=117)

Lock Screen Mode Changed (Event=118)

Thermostat Notifications

ALLOWED_FAN_MODES_CHANGED

Updates the allowed fan mode list for the thermostat.

Name

ALLOWED_FAN_MODES_CHANGED ()

Parameters

Name	Type	Description
`Modes`	LIST	Required. A comma-delimited list of available fan modes.

Updated variables

FanModes (ID = 1121)
FanMode (ID = 1105)

Lua example

local ModesStr = "On,Auto,Circulate,Schedule,Low,Medium,High"
local Params = {
    MODES = tostring(ModesStr)
}

C4:SendToProxy(bindingID, "ALLOWED_FAN_MODES_CHANGED", Params, "NOTIFY")

-- if using the template code you can use SendNotify
--SendNotify("ALLOWED_FAN_MODES_CHANGED", Params, BindingID)

Returns

None

ALLOWED_HOLD_MODES_CHANGED

Updates the available hold modes for the thermostat.

Name

ALLOWED_HOLD_MODES_CHANGED

Parameters

Name	Type	Description
`MODES`	LIST	Required. A comma-delimited list of available hold modes.

Updated variables

HoldModes (ID = 1122)
HoldMode (ID = 1106)

Lua example

local ModesStr = "Next Period,Hold Until,Permanently,Remove Hold"
local Params = {
    MODES = tostring(ModesStr)
}

C4:SendToProxy(bindingID, "ALLOWED_HOLD_MODES_CHANGED", Params, "NOTIFY")

-- if using the template code you can use SendNotify
--SendNotify("ALLOWED_HOLD_MODES_CHANGED", Params, BindingID)

Returns

None.

ALLOWED_HUMIDITY_MODES_CHANGED

Changes the value of the variable HUMIDITY_MODES_LIST

Name

ALLOWED_HUMIDITY_MODES_CHANGED ()

Parameter	Type	Description
`Modes`	LIST	A comma delimited list of available modes. Will do the same thing as `humidity_modes` capability

Returns

None

ALLOWED_HVAC_MODES_CHANGED

Changes the value of the variable HVAC_MODES_LIST

Name

ALLOWED_HVAC_MODES_CHANGED ()

Parameter	Type	Description
`Modes`	LIST	A comma delimited list of available modes.
	BOOL	Option parameters: `CAN_HEAT`, `CAN_COOL`, `CAN_AUTO`. These modify the capabilities: `can_heat`, `can_cool`, `can_do_auto`.

Returns

None

BUTTONS_LOCK_CHANGED

Used to inform the proxy if the buttons on the device should be locked or not.

Name

ALLOWED_HVAC_MODES_CHNAGED ()

Parameter	Type	Description
LOCK	BOOL	If the buttons on the device should be locked or not.

Returns

None

CONNECTION

Notification that should be sent to the proxy when the connected state changes..

Name

CONNECTION ()

Parameter	Description	Description
CONNECTED	BOOL	true/false.

Returns

None

COOL_SETPOINT_CHANGED

Notification that should be sent to the proxy when the cooling setpoint has changed.

Name

COOL_SETPOINT_CHANGED ()

Parameter	Type	Description
SETPOINT	NUM	New cooling setpoint temperature.
SCALE	STR	The values allowed are KELVIN, K, CELSIUS, C, FAHRENHEIT, or F.

Returns

None

DEHUMIDIFY_SETPOINT_CHANGED

The dehumidify setpoint has changed.

Name

DEHUMIDIFY_SETPOINT_CHANGED ()

Parameter	Description
int	SETPOINT: (0-100). To UI comes through as `dehumidify_setpoint`

Returns

None

DYNAMIC_CAPABILITIES_CHANGED

Dynamic Capabilities is a way for a protocol driver to send updates about some thermostat capabilities that can be changed when settings change on the hardware. An example would be a thermostat that has a humidifier added and would need to tell the proxy it can now do humidification as well as what the min, max, resolution and other changes are for the setpoint.

There are two types of capabilities, static and dynamic.

Static capabilities are defined in the <capabilities> section of the driver's driver.xml file and are immutable. For a complete list of Thermostat capabilities, please see the Thermostat Proxy Capabilities section.

Dynamic capabilities, as discussed in this section, are updated by the driver through the C4:SendToProxy() command. See the Lua Example below. A Lua table needs to be created defining the parameter name and it's value. Dynamic capabilities are not required to be in the driver.xml file. If it is not included it will initialize with the default value and can be updated at any time by the driver. If the thermostat device does not support changing the configuration then it is recommended it be used as a static capability. Listed in the table below are all of the possible DYNAMIC_CAPABILITIES_CHANGED notification parameters. The Capability column lists the capability associated with the notification that will be updated. For a more detailed list of the Dynamic Capability Notifications, please see Thermostat Dynamic Notifications section.

Name

DYNAMIC_CAPABILITIES_CHANGED ()

Dynamic Capability Notifications

Parameter	Type	Default	Capability
CAN_AUTO	BOOL	false	`can_do_auto`
CAN_CHANGE_SCALE	BOOL	true	`can_change_scale`
CAN_COOL	BOOL	false	`can_cool`
CAN_DEHUMIDIFY	BOOL	false	`can_dehumidify`
CAN_FIXED_SCHEDULE_AND_PRESETS	BOOL	false	`can_fixed_schedule_and_presets`
CAN_HEAT	BOOL	true	`can_heat`
CAN_HUMIDIFY	BOOL	false	`can_humidify`
CAN_LOCK_SCREEN	BOOL	false	`can_lock_screen`
CAN_PRESET	BOOL	false	`can_preset`
CAN_PRESET_SCHEDULE	BOOL	false	`can_preset_schedule`
COOL_SETPOINT_MAX_C	INT	100	`setpoint_cool_max_c`
COOL_SETPOINT_MAX_F	INT	100	`setpoint_cool_max_f`
COOL_SETPOINT_MIN_C	INT	0	`setpoint_cool_min_c`
COOL_SETPOINT_MIN_F	INT	0	`setpoint_cool_min_f`
COOL_SETPOINT_RESOLUTION_C	INT	1	`setpoint_cool_resolution_c`
COOL_SETPOINT_RESOLUTION_F	INT	1	`setpoint_cool_resolution_f`
DEHUMIDIFY_SETPOINT_MAX	INT	100	`setpoint_dehumidify_max`
DEHUMIDIFY_SETPOINT_MIN	INT	0	`setpoint_dehumidify_min`
DEHUMIDIFY_SETPOINT_RESOLUTION	INT	1	`setpoint_dehumidify_resolution`
HAS_EXTRAS	BOOL	false	`has_extras`
HAS_HEAT_PUMP	BOOL	false	`has_heat_pump`
HAS_HUMIDITY	BOOL	false	`has_humidity`
HAS_OUTDOOR_TEMPERATURE	BOOL	false	`has_outdoor_temperature`
HAS_SCHEDULE	BOOL	false	`has_schedule`
HAS_SINGLE_SETPOINT	BOOL	false	`has_single_setpoint`
HAS_TEMPERATURE	BOOL	true	`has_temperature`
HEATCOOL_SETPOINTS_DEADBAND_C	INT	2	`setpoint_heatcool_deadband_c`
HEATCOOL_SETPOINTS_DEADBAND_F	INT	2	`setpoint_heatcool_deadband_f`
HEAT_SETPOINT_MAX_C	INT	100	`setpoint_heat_max_c`
HEAT_SETPOINT_MAX_F	INT	100	`setpoint_heat_max_f`
HEAT_SETPOINT_MIN_C	INT	0	`setpoint_heat_min_c`
HEAT_SETPOINT_MIN_F	INT	0	`setpoint_heat_min_f`
HEAT_SETPOINT_RESOLUTION_C	INT	1	`setpoint_heat_resolution_c`
HEAT_SETPOINT_RESOLUTION_F	INT	1	`setpoint_heat_resolution_f`
HOLD_UNTIL_MODE	STRING	`date,time`	`hold_until_mode`
HOLD_UNTIL_RESOLUTION	INT	5	`hold_until_resolution`
HUMIDITY_SETPOINTS_DEADBAND	INT	10	`setpoint_humidity_deadband`
HUMIDIFY_SETPOINT_MAX	INT	100	`setpoint_humidify_max`
HUMIDIFY_SETPOINT_MIN	INT	0	`setpoint_humidify_min`
HUMIDIFY_SETPOINT_RESOLUTION	INT	1	`setpoint_humidify_resolution`
LOCK_SCREEN_MODES	STRING	""	`lock_screen_modes`
OUTDOOR_TEMPERATURE_RESOLUTION_C	INT	1	`outdoor_temperature_resolution_c`
OUTDOOR_TEMPERATURE_RESOLUTION_F	INT	1	`outdoor_temperature_resolution_f`
SINGLE_SETPOINT_MAX_C	INT	100	`setpoint_single_max_c`
SINGLE_SETPOINT_MAX_F	INT	100	`setpoint_single_max_f`
SINGLE_SETPOINT_MIN_C	INT	0	`setpoint_single_min_c`
SINGLE_SETPOINT_MIN_F	INT	0	`setpoint_single_min_f`
SINGLE_SETPOINT_RESOLUTION_C	INT	1	`setpoint_single_resolution_c`
SINGLE_SETPOINT_RESOLUTION_F	INT	1	`setpoint_single_resolution_f`
TEMPERATURE_MAX_C	INT	50	`current_temperature_max_c`
TEMPERATURE_MAX_F	INT	120	`current_temperature_max_f`
TEMPERATURE_MIN_C	INT	-40	`current_temperature_min_c`
TEMPERATURE_MIN_F	INT	-40	`current_temperature_min_f`
TEMPERATURE_RESOLUTION_C	INT	1	`current_temperature_resolution_c`
TEMPERATURE_RESOLUTION_F	INT	1	`current_temperature_resolution_f`

Lua example

local CanHeat = true

local Params = {
    CAN_HEAT = tostring(CanHeat)
}

C4:SendToProxy(bindingID, "DYNAMIC_CAPABILITIES_CHANGED", Params, "NOTIFY")

-- if using the template code you can use SendNotify
--SendNotify("DYNAMIC_CAPABILITIES_CHANGED", Params, BindingID)

EXTRAS_SETUP_CHANGED

Update the Extras Setup, displayed in the UI

Name

EXTRAS_SETUP_CHANGED ()

Parameter	Description	Description
XML	XML	XML text string of XML matching the Preset Schedule schema. Comes through to the UI as `extras_setup`. Note that as of OS 3, sending only a singular XML string is supported. For example, sending an array of Extras can result in Navigator performance issues.

Returns

None

EXTRAS_STATE_CHANGED

Update the Extras Setup, displayed in the UI

Name

EXTRAS_STATE_CHANGED ()

Parameter	Type	Description
XML	XML	XML text string of XML matching the Preset Schedule schema. To UI comes through as `extras_state`.

Returns

None

FAN_MODE_CHANGED

Notification that should be sent to the proxy when Fan mode has changed. Changes the variables: FAN_MODE, V1 FANMODE, .

Name

FAN_MODE_CHANGED ()

Parameter	Type	Description
MODE	STR	One of the supported modes for example: Auto, On.

Returns

None

FAN_STATE_CHANGED

Notification that should be sent to the proxy when the fan state has changed.

Name

FAN_STATE_CHANGED ()

Parameter	Type	Description
STATE	STR	One of the following Off, On.

Returns

None

FORCE_INFO

A no-payload trigger that tells the thermostat proxy to refresh the current UI state from its internal values. When a proxy receives a FORCE_INFO notification, it re-sends the current scale, temperature, HVAC mode, fan mode, hold mode, HVAC state, fan state, and heat/cool setpoints back to the UI so the display stays synchronized without requiring a separate variable-specific notification.

Name

FORCE_INFO ()

Parameter	Type	Default	Capability	Description
none	None	N/A	N/A	This notification has no payload. It forces the proxy to refresh current information back to the UI.

Lua example

local Params = {}

C4:SendToProxy(bindingID, "FORCE_INFO", Params, "NOTIFY")

-- if using the template code you can use SendNotify
--SendNotify("FORCE_INFO", Params, BindingID)

What this refreshes

The proxy uses FORCE_INFO to push the most recent values for the following items back to the UI:

scale
current temperature
HVAC mode
fan mode
hold mode
HVAC state
fan state
heat setpoint
cool setpoint
display temperature values

This is a refresh trigger, not a state-change command. It does not require any parameters and does not update the target device; it simply re-sends the current data from the proxy to the UI.

HEAT_SETPOINT_CHANGED

Notification that should be sent to the proxy when the heating setpoint has changed.

Name

HEAT_SETPOINT_CHANGED ()

Parameter	Type	Description
SETPOINT	NUM	New heating setpoint temperature.
SCALE	STR	The scale being used for the setpoint. The values allowed are KELVIN, K, CELSIUS, C, FAHRENHEIT, or F.

Returns

None

HOLD_MODE_CHANGED

Notification that should be sent to the proxy when hold mode has changed. Changes the variables HOLD_MODE, ANA_HOLDMODE. Fires event HOLD_MODE_CHANGED.

Name

HOLD_MODE_CHANGED ()

Parameter	Type	Range	Description
MODE	STR		Required: Mode name. If MODE is "Hold Until" then the following parameters will be sent:
YEAR	INT	0-99 (YY)	Required if MODE is "Hold Until" and if `hold_until_mode` capability is "date,time".
MONTH	INT	1-12	Required if MODE is "Hold Until" and if `hold_until_mode` capability is "date,time".
DAY	INT	1-31	Required if MODE is "Hold Until" and if `hold_until_mode` capability is "date,time".
HOUR	INT	0-23	Required if MODE is "Hold Until".
MINUTE	INT	0-59	Required if MODE is "Hold Until".

HUMIDIFY_SETPOINT_CHANGED

The humidity setpoint has changed. To UI comes through as humidify_setpoint

Name

HUMIDIFY_SETPOINT_CHANGED ()

Parameter	Type	Description
SETPOINT	NUM	(0-100)

Returns

None

HUMIDITY_CHANGED

The actual humidity percent (integer 0-100) value detected by the thermostat has changed. To UI comes through as humidity.

Name

HUMIDITY_CHANGED ()

Parameter	Description	Description
HUMIDITY	INT	HUMIDITY: (0-100)

Returns

None

HUMIDITY_MODE_CHANGED

MODE, typically: humidify, humidifyAuto (aggressiveness), dehumidify or auto). To UI comes through as humidity_mode

Name

HUMIDITY_MODE_CHANGED ()

Parameter	Type	Description
MODE	STR	Typically: humidify, humidifyAuto (aggressiveness), dehumidify or auto).

Returns

None

HUMIDITY_STATE_CHANGED

State has changed on the thermostat. To UI comes through as humidity_state.

Name

HUMIDITY_STATE_CHANGED ()

Parameter	Type	Description
STATE	STR	Typically: humidify, humidifyAuto (aggressiveness), dehumidify or auto

Returns

None

HVAC_MODE_CHANGED

Notification sent when the mode of the HVAC system has changed. Changes the variable HVAC_MODE.

Name

HVAC_MODE_CHANGED ()

Parameter	Type	Description
MODE	STR	One of the supported modes for example: Off, Heat,Cool, Auto, Emergency

Returns

None

HVAC_STATE_CHANGED

Notification that should be sent to the proxy when the HVAC state has changed. Changes the variable HVAC_STATE.

Name

HVAC_STATE_CHANGED ()

Parameter	Type	Description
STATE:	STR	One of the supported HVAC states for example: Off, Heat, Cool

Returns

None

LOCK_SCREEN_MODE_CHANGED

Updates the current lock screen mode. This notification is new in 4.3.0.

Name

LOCK_SCREEN_MODE_CHANGED

Parameters

Name	Type	Description
`MODE`	STRING	Required. The new lock screen mode value. Modes come from the `lock_screen_modes` capability.

Updated variables

LockScreenMode (ID = 1151)

Lua example

local Params = {
    MODE = "Partially Locked"
}

C4:SendToProxy(bindingID, "LOCK_SCREEN_MODE_CHANGED", Params, "NOTIFY")

-- if using the template code you can use SendNotify
--SendNotify("LOCK_SCREEN_MODE_CHANGED", Params, BindingID)

Returns

None.

MESSAGE_CHANGED

Update the text message displayed in the UI. Multiple lines can be specified by using \n to separate lines, although UI's will display each line in its own way. Could be a paragraph, ticker scrolling, cycling, etc. To UI comes through as message.

Name

MESSAGE_CHANGED ()

Parameter	Type	Description
MESSAGE	STR	Text string, max length of the string is not set, though driver developers need to keep in mind that this information shows up in Navigators in a ticker or similar scrolling text display and should not be cluttered but kept to key things like HVAC system errors, and CRITICAL information.

Returns

Parameter	Type	Description
XML	XML	XML text string of XML matching the Preset Schedule schema

Sample preset_fields XML

<preset_fields>
    <field
        id = "heat_setpoint_f"
        type = "number"
        label = "Heat Below"
        min = "50"
        max = "90"
        res = "1"/>
    <field
        id = "heat_setpoint_c"
        type = "number"
        label = "Heat Below"
        min = "10"
        max = "32"
        res = "0.5"/>
    <field
        id = "cool_setpoint_f"
        type = "number"
        label = "Cool Above"
        min = "50"
        max = "90"
        res = "1"/>
    <field
        id = "cool_setpoint_c"
        type = "number"
        label = "Cool Above"
        min = "10"
        max = "32"
        res = "0.5"/>
    <field
        id = "humidify_setpoint"
        type = "number"
        label = "Humidify Setpoint"
        min = "0"
        max = "90"
        res = "5"/>
    <field
        id = "dehumidify_setpoint"
        type = "number"
        label = "Dehumidify Setpoint"
        min = "10"
        max = "100"
        res = "5"/>
    <field id = "hvac_mode" type = "list" label = "HVAC Mode">
        <list>
            <item text = "Off" value = "Off"/>
            <item text = "Heat" value = "Heat"/>
            <item text = "Cool" value = "Cool"/>
        </list>
    </field>
    <field id = "humidity_mode" type = "list" label = "Humidity Mode">
        <list>
            <item text = "Off" value = "Off"/>
            <item text = "Humidify" value = "Humidify"/>
            <item text = "Dehumidify" value = "Dehumidify"/>
            <item text = "Auto" value = "Auto"/>
        </list>
    </field>
    <field id = "fan_mode" type = "list" label = "Fan Mode">
        <list>
            <item text = "On" value = "On"/>
            <item text = "Auto" value = "Auto"/>
            <item text = "Circulate" value = "Circulate"/>
        </list>
    </field>
</preset_fields>

REMOTE_SENSOR_CHANGED

Updates the remote sensor usage state the proxy tracks for the thermostat. The protocol driver sends this after the thermostat updates its remote sensor state, for example in response to a SET_REMOTE_SENSOR command. Only applies when has_remote_sensor is enabled.

Name

REMOTE_SENSOR_CHANGED ()

Parameter	Type	Description
IN_USE	BOOL	True/False indicating if the remote sensor should be used.

Returns

None

SCALE_CHANGED

Changes the scale the proxy tracks for the temperature. This is primarily important for Composer Pro when programming as it will use this scale for setting temperatures. Navigators also use this scale.

Name

SCALE_CHANGED ()

Parameter	Type	Description
SCALE	STR	CELSIUS, FAHRENHEIT, C, c, F, f

Returns

None

SCHEDULE_ENTRY_CHANGED

Notification that should be sent to the proxy when a change is made to the HVAC schedules. Every entry that is changed will send one protocol notification.

Name

SCHEDULE_ENTRY_CHANGED ()

Parameter	Type	Description
DayIndex	NUM	Number representing day of week: 0= Sunday, 1=Monday
EntryIndex	NUM	0 to the number of entries the day can support. 0 = the first entry, 1 = the second entry.
TimeMinutes	NUM	Number of minutes past midnight for the entry change. For example 360= 6:00AM.
EnabledFlag	BOOL	Enables or disables a schedule. By default, the first four schedules are enabled.
HeatSetpoint	NUM	Temperature designated to start the heating system.
CoolSetpoint:	NUM	Temperature designated to start the cooling system.
Units	STR	F or C – Fahrenheit or Celsius.

Returns

None

SCHEDULE_ENTRY_DELETED

Notification that should be sent to the proxy when a schedule entry is deleted.

Name

SCHEDULE_ENTRY_DELETED This notification is new in 4.3.0.

Parameters

Name	Type	Description
`ENTRY_INDEX`	INTEGER	Required. The schedule entry index to delete.
`DAY_INDEX`	INTEGER	Optional. The day index to target. If omitted, the delete is applied across all days.

Updated variables

EntireSchedule (ID = 1113)

Lua example

local Params = {
    ENTRY_INDEX = "2",
    DAY_INDEX = "0"
}

C4:SendToProxy(bindingID, "SCHEDULE_ENTRY_DELETED", Params, "NOTIFY")

-- if using the template code you can use SendNotify
--SendNotify("SCHEDULE_ENTRY_DELETED", Params, BindingID)

Returns

None.

This notification is new in 4.3.0. If a specific DAY_INDEX is provided, the handler deletes that one schedule entry for that day; otherwise, it applies the delete across all days. After the update, it refreshes the affected schedule data and sends the updated schedule to the UI.

SCHEDULE_ENTRY_NAME_CHANGED

New in 4.3.0.

Parameters

ENTRY_INDEX — required. The schedule entry index to rename.
ENTRY_NAME — required. The new name to assign to the schedule entry.
DAY_INDEX — optional. If supplied, only that day’s entry is renamed. If omitted, the same entry index is renamed across all days in the week.

Updated variables

None

Lua example

local entryIndex = 2
local dayIndex = 1

local Params = {
    ENTRY_INDEX = tostring(entryIndex),
    DAY_INDEX = tostring(dayIndex),
    ENTRY_NAME = tostring("Wake")
}

C4:SendToProxy(bindingID, "SCHEDULE_ENTRY_NAME_CHANGED", Params, "NOTIFY")

-- if using the template code you can use SendNotify
--SendNotify("SCHEDULE_ENTRY_NAME_CHANGED", Params, BindingID)

When DAY_INDEX is omitted:

local entryIndex = 2
local dayIndex = 1

local Params = {
    ENTRY_INDEX = tostring(entryIndex),
    ENTRY_NAME = tostring("Wake")
}

C4:SendToProxy(bindingID, "SCHEDULE_ENTRY_NAME_CHANGED", Params, "NOTIFY")

-- if using the template code you can use SendNotify
--SendNotify("SCHEDULE_ENTRY_NAME_CHANGED", Params, BindingID)

This applies the rename to the same entry index on every day of the schedule.

Returns

None

SCHEDULE_ENTRY_RESTORED

New in 4.3.0.

Parameters

ENTRY_INDEX — required. The schedule entry index to restore.
DAY_INDEX — optional. If supplied, only that day’s entry is restored. If omitted, the same entry index is restored across all days in the week.

Updated variables

None directly.
The handler updates the schedule entry state in memory and refreshes the UI schedule data:
- ConSendDataToUI(GetScheduleEntry(entry)) when a single day is targeted
- ConSendDataToUI(GetSchedule()) when the restore applies across the week
- BC_SendSingleScheduleEntry(entry) or BC_SendSchedule()

Lua example

local entryIndex = 2
local dayIndex = 1

local Params = {
    ENTRY_INDEX = tostring(entryIndex),
    DAY_INDEX = tostring(dayIndex),
}

C4:SendToProxy(bindingID, "SCHEDULE_ENTRY_RESTORED", Params, "NOTIFY")

-- if using the template code you can use SendNotify
--SendNotify("SCHEDULE_ENTRY_RESTORED", Params, BindingID)

When DAY_INDEX is omitted:

local entryIndex = 2
local dayIndex = 1

local Params = {
    ENTRY_INDEX = tostring(entryIndex),
}

C4:SendToProxy(bindingID, "SCHEDULE_ENTRY_RESTORED", Params, "NOTIFY")

-- if using the template code you can use SendNotify
--SendNotify("SCHEDULE_ENTRY_RESTORED", Params, BindingID)

This restores the same entry index on every day of the schedule.

Returns

None

SINGLE_SETPOINT_CHANGED

Used to inform the proxy that the single setpoint has changed. This notification changes variables SINGLE_SETPOINT_F and SINGLE_SETPOINT_C. It fires the event Single Setpoint Changed.

Name

SINGLE_SETPOINT_CHANGED ()

Parameter	Type	Description
SETPOINT	INT	The new temperature setpoint value.
SCALE	STR	The scale being used for the setpoint. The values allowed are CELSIUS, C, FAHRENHEIT, or F

Returns

None

TEMPERATURE_CHANGED

Notification that should be sent to the proxy when the temperature has changed.

Name

TEMPERATURE_CHANGED ()

Parameter	Type	Description
TEMPERATURE	NUM	New temperature value.
SCALE:	STR	The scale being used for the temperature. The values allowed are KELVIN, K, CELSIUS, C, FAHRENHEIT, or F.

Returns

None

Thermostat Dynamic Notifications

CAN_AUTO

Name

CAN_AUTO ()

Parameter	Type	Default	Capability	Description
CAN_AUTO	BOOL	False	`can_do_auto`	True/False. Thermostat supports auto heating and cooling.

Lua example

local CanDoAuto = true

local Params = {
    CAN_AUTO = tostring(CanDoAuto)
}

C4:SendToProxy(bindingID, "DYNAMIC_CAPABILITIES_CHANGED", Params, "NOTIFY")

-- if using the template code you can use SendNotify
--SendNotify("DYNAMIC_CAPABILITIES_CHANGED", Params, BindingID)

CAN_CHANGE_SCALE

Name

CAN_CHANGE_SCALE ()

Parameter	Type	Default	Capability	Description
CAN_CHANGE_SCALE	BOOL	False	`can_change_scale`	True/False. Thermostat supports ability to change scale.

Lua example

local CanChangeScale = true

local Params = {
    CAN_CHANGE_SCALE = tostring(CanChangeScale)
}

C4:SendToProxy(bindingID, "DYNAMIC_CAPABILITIES_CHANGED", Params, "NOTIFY")

-- if using the template code you can use SendNotify
--SendNotify("DYNAMIC_CAPABILITIES_CHANGED", Params, BindingID)

CAN_COOL

Name

CAN_COOL ()

Parameter	Type	Default	Capability	Description
CAN_COOL	BOOL	False	`can_cool`	True/False. Thermostat supports cooling.

Lua example

local CanCool = true

local Params = {
    CAN_COOL = tostring(CanCool)
}

C4:SendToProxy(bindingID, "DYNAMIC_CAPABILITIES_CHANGED", Params, "NOTIFY")

-- if using the template code you can use SendNotify
--SendNotify("DYNAMIC_CAPABILITIES_CHANGED", Params, BindingID)

CAN_DEHUMIDIFY

Name

CAN_DEHUMIDIFY ()

Parameter	Type	Default	Capability	Description
CAN_DEHUMIDIFY	BOOL	False	`can_dehumidify`	True/False. Thermostat supports dehumidification.

Lua example

local CanDehumidify = true

local Params = {
    CAN_DEHUMIDIFY = tostring(CanDehumidify)
}

C4:SendToProxy(bindingID, "DYNAMIC_CAPABILITIES_CHANGED", Params, "NOTIFY")

-- if using the template code you can use SendNotify
--SendNotify("DYNAMIC_CAPABILITIES_CHANGED", Params, BindingID)

CAN_FIXED_SCHEDULE_AND_PRESETS

An optional parameter included in a DYNAMIC_CAPABILITIES_CHANGED notification received by the proxy via a C4:SendToProxy call. It is a string-based Boolean value (True/False) used to enable or disable the can_fixed_schedule_and_presets capability. When set to True, the thermostat supports fixed scheduling with presets; when set to False, the capability is disabled. If the parameter is not provided, the default is False.

Name

CAN_FIXED_SCHEDULE_AND_PRESETS ()

Parameter	Type	Default	Capability	Description
CAN_FIXED_SCHEDULE_AND_PRESETS	BOOL	False	`can_fixed_schedule_and_presets`	True/False. Thermostat supports fixed schedule and preset combinations.

Lua example

local CanFixedScheduleAndPresets = true

local Params = {
    CAN_FIXED_SCHEDULE_AND_PRESETS = tostring(CanFixedScheduleAndPresets)
}

C4:SendToProxy(bindingID, "DYNAMIC_CAPABILITIES_CHANGED", Params, "NOTIFY")

-- if using the template code you can use SendNotify
--SendNotify("DYNAMIC_CAPABILITIES_CHANGED", Params, BindingID)

CAN_HEAT

Name

CAN_HEAT ()

Parameter	Type	Default	Capability	Description
CAN_HEAT	BOOL	True	`can_heat`	True/False. Thermostat supports heating.

Lua example

local CanHeat = true

local Params = {
    CAN_HEAT = tostring(CanHeat)
}

C4:SendToProxy(bindingID, "DYNAMIC_CAPABILITIES_CHANGED", Params, "NOTIFY")

-- if using the template code you can use SendNotify
--SendNotify("DYNAMIC_CAPABILITIES_CHANGED", Params, BindingID)

CAN_HUMIDIFY

Name

CAN_HUMIDIFY ()

Parameter	Type	Default	Capability	Description
CAN_HUMIDIFY	BOOL	False	`can_humidify`	True/False. Thermostat supports humidification.

Lua example

local CanHumidify = true

local Params = {
    CAN_HUMIDIFY = tostring(CanHumidify)
}

C4:SendToProxy(bindingID, "DYNAMIC_CAPABILITIES_CHANGED", Params, "NOTIFY")

-- if using the template code you can use SendNotify
--SendNotify("DYNAMIC_CAPABILITIES_CHANGED", Params, BindingID)

CAN_LOCK_SCREEN

An optional parameter included in a DYNAMIC_CAPABILITIES_CHANGED notification received by the proxy via a C4:SendToProxy call. It is a string-based Boolean value (True/False) used to enable or disable the can_lock_screen capability. When set to True, the device reports that the Screen on the thermostat device can be locked; when set to False, the capability is disabled. If the parameter is not provided, the default is False. The modes that are supported are provided by the <lock_screen_modes> capability.

Name

CAN_LOCK_SCREEN ()

Parameter	Type	Default	Capability	Description
CAN_LOCK_SCREEN	BOOL	False	`can_lock_screen`	True/False. Thermostat supports screen locking.

Lua example

local CanLockScreen = true

local Params = {
    CAN_LOCK_SCREEN = tostring(CanLockScreen)
}

C4:SendToProxy(bindingID, "DYNAMIC_CAPABILITIES_CHANGED", Params, "NOTIFY")

-- if using the template code you can use SendNotify
--SendNotify("DYNAMIC_CAPABILITIES_CHANGED", Params, BindingID)

CAN_PRESET

Name

CAN_PRESET ()

Parameter	Type	Default	Capability	Description
CAN_PRESET	BOOL	False	`can_preset`	True/False. Thermostat supports presets.

Lua example

local CanPreset = true

local Params = {
    CAN_PRESET = tostring(CanPreset)
}

C4:SendToProxy(bindingID, "DYNAMIC_CAPABILITIES_CHANGED", Params, "NOTIFY")

-- if using the template code you can use SendNotify
--SendNotify("DYNAMIC_CAPABILITIES_CHANGED", Params, BindingID)

CAN_PRESET_SCHEDULE

Name

CAN_PRESET_SCHEDULE ()

Parameter	Type	Default	Capability	Description
CAN_PRESET_SCHEDULE	BOOL	False	`can_preset_schedule`	True/False. Thermostat supports preset scheduling.

Lua example

local CanPresetSchedule = true

local Params = {
    CAN_PRESET_SCHEDULE = tostring(CanPresetSchedule)
}

C4:SendToProxy(bindingID, "DYNAMIC_CAPABILITIES_CHANGED", Params, "NOTIFY")

-- if using the template code you can use SendNotify
--SendNotify("DYNAMIC_CAPABILITIES_CHANGED", Params, BindingID)

COOL_SETPOINT_MAX_C

An optional parameter included in a DYNAMIC_CAPABILITIES_CHANGED notification received by the proxy via a C4:SendToProxy call. It is a string-based integer value used to update the maximum cool setpoint in Celsius. The value is passed through the payload as a string representation of the number and is applied to the corresponding setpoint_cool_max_c capability. If the parameter is not provided, the default is 32.

Name

COOL_SETPOINT_MAX_C ()

Parameter	Type	Default	Capability	Range	Description
COOL_SETPOINT_MAX_C	INT	32	`setpoint_cool_max_c`	0-100 and < `setpoint_cool_min_c`	Maximum cool setpoint in Celsius.

Lua example

local CoolSetpointMaxC = 32

local Params = {
    COOL_SETPOINT_MAX_C = tostring(CoolSetpointMaxC)
}

C4:SendToProxy(bindingID, "DYNAMIC_CAPABILITIES_CHANGED", Params, "NOTIFY")

-- if using the template code you can use SendNotify
--SendNotify("DYNAMIC_CAPABILITIES_CHANGED", Params, BindingID)

COOL_SETPOINT_MAX_F

An optional parameter included in a DYNAMIC_CAPABILITIES_CHANGED notification received by the proxy via a C4:SendToProxy call. It is a string-based integer value used to update the maximum cool setpoint in Fahrenheit. The value is passed through the payload as a string representation of the number and is applied to the corresponding setpoint_cool_max_f capability. If the parameter is not provided, the default is 90.

Name

COOL_SETPOINT_MAX_F ()

Parameter	Type	Default	Capability	Range	Description
COOL_SETPOINT_MAX_F	INT	90	`setpoint_cool_max_f`	0-100 and < `setpoint_cool_min_f`	Maximum cool setpoint in Fahrenheit.

Lua example

local CoolSetpointMaxF = 90

local Params = {
    COOL_SETPOINT_MAX_F = tostring(CoolSetpointMaxF)
}

C4:SendToProxy(bindingID, "DYNAMIC_CAPABILITIES_CHANGED", Params, "NOTIFY")

-- if using the template code you can use SendNotify
--SendNotify("DYNAMIC_CAPABILITIES_CHANGED", Params, BindingID)

COOL_SETPOINT_MIN_C

An optional parameter included in a DYNAMIC_CAPABILITIES_CHANGED notification received by the proxy via a C4:SendToProxy call. It is a string-based integer value used to update the minimum cool setpoint in Celsius. The value is passed through the payload as a string representation of the number and is applied to the corresponding setpoint_cool_min_c capability. If the parameter is not provided, the default is 5.

Name

COOL_SETPOINT_MIN_C ()

Parameter	Type	Default	Capability	Range	Description
COOL_SETPOINT_MIN_C	INT	5	`setpoint_cool_min_c`	0-100 and > `setpoint_cool_max_c`	Minimum cool setpoint in Celsius.

Lua example

local CoolSetpointMinC = 10

local Params = {
    COOL_SETPOINT_MIN_C = tostring(CoolSetpointMinC)
}

C4:SendToProxy(bindingID, "DYNAMIC_CAPABILITIES_CHANGED", Params, "NOTIFY")

-- if using the template code you can use SendNotify
--SendNotify("DYNAMIC_CAPABILITIES_CHANGED", Params, BindingID)

COOL_SETPOINT_MIN_F

An optional parameter included in a DYNAMIC_CAPABILITIES_CHANGED notification received by the proxy via a C4:SendToProxy call. It is a string-based integer value used to update the minimum cool setpoint in Fahrenheit. The value is passed through the payload as a string representation of the number and is applied to the corresponding setpoint_cool_min_f capability. If the parameter is not provided, the default is 39.

Name

COOL_SETPOINT_MIN_F ()

Parameter	Type	Default	Capability	Range	Description
COOL_SETPOINT_MIN_F	INT	39	`setpoint_cool_min_f`	0-100 and < `setpoint_cool_max_f`	Minimum cool setpoint in Fahrenheit.

Lua example

local CoolSetpointMinF = 60

local Params = {
    COOL_SETPOINT_MIN_F = tostring(CoolSetpointMinF)
}

C4:SendToProxy(bindingID, "DYNAMIC_CAPABILITIES_CHANGED", Params, "NOTIFY")

-- if using the template code you can use SendNotify
--SendNotify("DYNAMIC_CAPABILITIES_CHANGED", Params, BindingID)

COOL_SETPOINT_RESOLUTION_C

An optional parameter included in a DYNAMIC_CAPABILITIES_CHANGED notification received by the proxy via a C4:SendToProxy call. It is a string-based integer value used to update the cool setpoint resolution in Celsius. The value is passed through the payload as a string representation of the number and is applied to the corresponding setpoint_cool_resolution_c capability. If the parameter is not provided, the default is 1.

Name

COOL_SETPOINT_RESOLUTION_C ()

Parameter	Type	Default	Capability	Range	Description
COOL_SETPOINT_RESOLUTION_C	INT	1	`setpoint_cool_resolution_c`	0.01-100	Cool setpoint resolution in Celsius (ie 1,3,5,10,etc).

Lua example

local CoolSetpointResolutionC = .5

local Params = {
    COOL_SETPOINT_RESOLUTION_C = tostring(CoolSetpointResolutionC)
}

C4:SendToProxy(bindingID, "DYNAMIC_CAPABILITIES_CHANGED", Params, "NOTIFY")

-- if using the template code you can use SendNotify
--SendNotify("DYNAMIC_CAPABILITIES_CHANGED", Params, BindingID)

COOL_SETPOINT_RESOLUTION_F

An optional parameter included in a DYNAMIC_CAPABILITIES_CHANGED notification received by the proxy via a C4:SendToProxy call. It is a string-based integer value used to update the cool setpoint resolution in Fahrenheit. The value is passed through the payload as a string representation of the number and is applied to the corresponding setpoint_cool_resolution_f capability. If the parameter is not provided, the default is 1.

Name

COOL_SETPOINT_RESOLUTION_F ()

Parameter	Type	Default	Capability	Range	Description
COOL_SETPOINT_RESOLUTION_F	INT	1	`setpoint_cool_resolution_f`	0.01-100	Cool setpoint resolution in Fahrenheit (ie 1,3,5,10,etc).

Lua example

local CoolSetpointResolutionF = .5

local Params = {
    COOL_SETPOINT_RESOLUTION_F = tostring(CoolSetpointResolutionF)
}

C4:SendToProxy(bindingID, "DYNAMIC_CAPABILITIES_CHANGED", Params, "NOTIFY")

-- if using the template code you can use SendNotify
--SendNotify("DYNAMIC_CAPABILITIES_CHANGED", Params, BindingID)

DEHUMIDIFY_SETPOINT_MAX

An optional parameter included in a DYNAMIC_CAPABILITIES_CHANGED notification received by the proxy via a C4:SendToProxy call. It is a string-based integer value used to update the maximum dehumidify setpoint. The value is passed through the payload as a string representation of the number and is applied to the corresponding setpoint_dehumidify_max capability. If the parameter is not provided, the default is 100.

Name

DEHUMIDIFY_SETPOINT_MAX ()

Parameter	Type	Default	Capability	Range	Description
DEHUMIDIFY_SETPOINT_MAX	INT	100	`setpoint_dehumidify_max`	0-100	Maximum dehumidify setpoint.

Lua example

local DehumidifySetpointMax = 60

local Params = {
    DEHUMIDIFY_SETPOINT_MAX = tostring(DehumidifySetpointMax)
}

C4:SendToProxy(bindingID, "DYNAMIC_CAPABILITIES_CHANGED", Params, "NOTIFY")

-- if using the template code you can use SendNotify
--SendNotify("DYNAMIC_CAPABILITIES_CHANGED", Params, BindingID)

DEHUMIDIFY_SETPOINT_MIN

An optional parameter included in a DYNAMIC_CAPABILITIES_CHANGED notification received by the proxy via a C4:SendToProxy call. It is a string-based integer value used to update the minimum dehumidify setpoint. The value is passed through the payload as a string representation of the number and is applied to the corresponding setpoint_dehumidify_min capability. If the parameter is not provided, the default is 0.

Name

DEHUMIDIFY_SETPOINT_MIN ()

Parameter	Type	Default	Capability	Range	Description
DEHUMIDIFY_SETPOINT_MIN	INT	0	`setpoint_dehumidify_min`	0-100	Minimum dehumidify setpoint.

Lua example

local DehumidifySetpointMin = 30

local Params = {
    DEHUMIDIFY_SETPOINT_MIN = tostring(DehumidifySetpointMin)
}

C4:SendToProxy(bindingID, "DYNAMIC_CAPABILITIES_CHANGED", Params, "NOTIFY")

-- if using the template code you can use SendNotify
--SendNotify("DYNAMIC_CAPABILITIES_CHANGED", Params, BindingID)

DEHUMIDIFY_SETPOINT_RESOLUTION

An optional parameter included in a DYNAMIC_CAPABILITIES_CHANGED notification received by the proxy via a C4:SendToProxy call. It is a string-based integer value used to update the dehumidify setpoint resolution. The value is passed through the payload as a string representation of the number and is applied to the corresponding setpoint_dehumidify_resolution capability. If the parameter is not provided, the default is 1.

Name

DEHUMIDIFY_SETPOINT_RESOLUTION ()

Parameter	Type	Default	Capability	Range	Description
DEHUMIDIFY_SETPOINT_RESOLUTION	INT	1	`setpoint_dehumidify_resolution`	0-100	Dehumidify setpoint resolution.

Lua example

local DehumidifySetpointResolution = 5

local Params = {
    DEHUMIDIFY_SETPOINT_RESOLUTION = tostring(DehumidifySetpointResolution)
}

C4:SendToProxy(bindingID, "DYNAMIC_CAPABILITIES_CHANGED", Params, "NOTIFY")

-- if using the template code you can use SendNotify
--SendNotify("DYNAMIC_CAPABILITIES_CHANGED", Params, BindingID)

HAS_EXTRAS

An optional parameter included in a DYNAMIC_CAPABILITIES_CHANGED notification received by the proxy via a C4:SendToProxy call. It is a string-based Boolean value (True/False) used to enable or disable the has_extras capability. When set to True, the driver needs to provide the <extras> XML containing the definition of all the Extras needed by the UI. This is provided by the EXTRAS_SETUP_CHANGED notification. extra the exposes the thermostat features; when set to False, the capability is disabled and the driver does not provide any Extras. If the parameter is not provided, the default is False.

Name

HAS_EXTRAS ()

Parameter	Type	Default	Capability	Description
HAS_EXTRAS	BOOL	False	`has_extras`	True/False. Thermostat exposes "Extras" feature.

Lua example

local HasExtras = true

local Params = {
    HAS_EXTRAS = tostring(HasExtras)
}

C4:SendToProxy(bindingID, "DYNAMIC_CAPABILITIES_CHANGED", Params, "NOTIFY")

-- if using the template code you can use SendNotify
--SendNotify("DYNAMIC_CAPABILITIES_CHANGED", Params, BindingID)

HAS_HEAT_PUMP

Name

HAS_HEAT_PUMP ()

Parameter	Type	Default	Capability	Description
HAS_HEAT_PUMP	BOOL	False	`has_heat_pump`	True/False. Thermostat is configured as a heat pump.

Lua example

local HasHeatPump = true

local Params = {
    HAS_HEAT_PUMP = tostring(HasHeatPump)
}

C4:SendToProxy(bindingID, "DYNAMIC_CAPABILITIES_CHANGED", Params, "NOTIFY")

-- if using the template code you can use SendNotify
--SendNotify("DYNAMIC_CAPABILITIES_CHANGED", Params, BindingID)

HAS_HUMIDITY

Name

HAS_HUMIDITY ()

Parameter	Type	Default	Capability	Description
HAS_HUMIDITY	BOOL	False	`has_humidity`	True/False. Thermostat exposes humidity data.

Lua example

local HasHumidity = true

local Params = {
    HAS_HUMIDITY = tostring(HasHumidity)
}

C4:SendToProxy(bindingID, "DYNAMIC_CAPABILITIES_CHANGED", Params, "NOTIFY")

-- if using the template code you can use SendNotify
--SendNotify("DYNAMIC_CAPABILITIES_CHANGED", Params, BindingID)

HAS_OUTDOOR_TEMPERATURE

An optional parameter included in a DYNAMIC_CAPABILITIES_CHANGED notification received by the proxy via a C4:SendToProxy call. It is a string-based Boolean value (True/False) used to enable or disable the has_outdoor_temperature capability. When set to True, the thermostat supports and exposes outdoor temperature data; when set to False, the capability is disabled. If the parameter is not provided, the default is False.

Name

HAS_OUTDOOR_TEMPERATURE ()

Parameter	Type	Default	Capability	Description
HAS_OUTDOOR_TEMPERATURE	BOOL	False	`has_outdoor_temperature`	True/False. Thermostat exposes outdoor temperature.

Lua example

local HasOutdoorTemperature = true

local Params = {
    HAS_OUTDOOR_TEMPERATURE = tostring(HasOutdoorTemperature)
}

C4:SendToProxy(bindingID, "DYNAMIC_CAPABILITIES_CHANGED", Params, "NOTIFY")

-- if using the template code you can use SendNotify
--SendNotify("DYNAMIC_CAPABILITIES_CHANGED", Params, BindingID)

HAS_SCHEDULE

Introduced is OS Version 4.3.0. An optional parameter included in a DYNAMIC_CAPABILITIES_CHANGED notification received by the proxy via a C4:SendToProxy call. It is a string-based Boolean value (True/False) used to enable or disable the has_schedule capability. When set to True, the device reports that a schedule is supported and the proxy should create or restore schedule state. When set to False, the schedule capability is disabled and the schedule is removed. If the parameter is not provided, the default is False.

Name

HAS_SCHEDULE ()

Parameter	Type	Default	Capability	Description
HAS_SCHEDULE	BOOL	False	`has_schedule`	True/False. Thermostat supports a schedule.

Lua example

local HasSchedule = true

local Params = {
    HAS_SCHEDULE = tostring(HasSchedule)
}

C4:SendToProxy(bindingID, "DYNAMIC_CAPABILITIES_CHANGED", Params, "NOTIFY")

-- if using the template code you can use SendNotify
--SendNotify("DYNAMIC_CAPABILITIES_CHANGED", Params, BindingID)

HAS_SINGLE_SETPOINT

Name

HAS_SINGLE_SETPOINT ()

Parameter	Type	Default	Capability	Range	Description
HAS_SINGLE_SETPOINT	BOOL	False	`has_single_setpoint`		True/False. Thermostat supports single-setpoint operation.

Lua example

local HasSingleSetpoint = true

local Params = {
    HAS_SINGLE_SETPOINT = tostring(HasSingleSetpoint)
}

C4:SendToProxy(bindingID, "DYNAMIC_CAPABILITIES_CHANGED", Params, "NOTIFY")

-- if using the template code you can use SendNotify
--SendNotify("DYNAMIC_CAPABILITIES_CHANGED", Params, BindingID)

HAS_TEMPERATURE

Name

HAS_TEMPERATURE ()

Parameter	Type	Default	Capability	Description
HAS_TEMPERATURE	BOOL	True	`has_temperature`	True/False. Thermostat exposes temperature data.

Lua example

local HasTemperature = true

local Params = {
    HAS_TEMPERATURE = tostring(HasTemperature)
}

C4:SendToProxy(bindingID, "DYNAMIC_CAPABILITIES_CHANGED", Params, "NOTIFY")

-- if using the template code you can use SendNotify
--SendNotify("DYNAMIC_CAPABILITIES_CHANGED", Params, BindingID)

HEATCOOL_SETPOINTS_DEADBAND_C

An optional parameter included in a DYNAMIC_CAPABILITIES_CHANGED notification received by the proxy via a C4:SendToProxy call. It is a string-based integer value used to update the heat/cool deadband in Celsius. The value is passed through the payload as a string representation of the number and is applied to the corresponding setpoint_heatcool_deadband_c capability. If the parameter is not provided, the default is 2.

Name

HEATCOOL_SETPOINTS_DEADBAND_C ()

Parameter	Type	Default	Capability	Range	Description
HEATCOOL_SETPOINTS_DEADBAND_C	INT	2	`setpoint_heatcool_deadband_c`		Heat/cool deadband in Celsius.

Lua example

local HeatCoolSetpointsDeadbandC = 2

local Params = {
    HEATCOOL_SETPOINTS_DEADBAND_C = tostring(HeatCoolSetpointsDeadbandC)
}

C4:SendToProxy(bindingID, "DYNAMIC_CAPABILITIES_CHANGED", Params, "NOTIFY")

-- if using the template code you can use SendNotify
--SendNotify("DYNAMIC_CAPABILITIES_CHANGED", Params, BindingID)

HEATCOOL_SETPOINTS_DEADBAND_F

An optional parameter included in a DYNAMIC_CAPABILITIES_CHANGED notification received by the proxy via a C4:SendToProxy call. It is a string-based integer value used to update the heat/cool deadband in Fahrenheit. The value is passed through the payload as a string representation of the number and is applied to the corresponding setpoint_heatcool_deadband_f capability. If the parameter is not provided, the default is 2.

Name

HEATCOOL_SETPOINTS_DEADBAND_F ()

Parameter	Type	Default	Capability	Range	Description
HEATCOOL_SETPOINTS_DEADBAND_F	INT	2	`setpoint_heatcool_deadband_f`		Heat/cool deadband in Fahrenheit.

Lua example

local HeatCoolSetpointsDeadbandF = 2

local Params = {
    HEATCOOL_SETPOINTS_DEADBAND_F = tostring(HeatCoolSetpointsDeadbandF)
}

C4:SendToProxy(bindingID, "DYNAMIC_CAPABILITIES_CHANGED", Params, "NOTIFY")

-- if using the template code you can use SendNotify
--SendNotify("DYNAMIC_CAPABILITIES_CHANGED", Params, BindingID)

HEAT_SETPOINT_MAX_C

An optional parameter included in a DYNAMIC_CAPABILITIES_CHANGED notification received by the proxy via a C4:SendToProxy call. It is a string-based integer value used to update the maximum heat setpoint in Celsius. The value is passed through the payload as a string representation of the number and is applied to the corresponding setpoint_heat_max_c capability. If the parameter is not provided, the default is 100.

Name

HEAT_SETPOINT_MAX_C ()

Parameter	Type	Default	Capability	Range	Description
HEAT_SETPOINT_MAX_C	INT	31	`setpoint_heat_max_c`	0-100 and < `setpoint_heat_min_c`	Maximum heat setpoint in Celsius.

Lua example

local HeatSetpointMaxC = 32

local Params = {
    HEAT_SETPOINT_MAX_C = tostring(HeatSetpointMaxC)
}

C4:SendToProxy(bindingID, "DYNAMIC_CAPABILITIES_CHANGED", Params, "NOTIFY")

-- if using the template code you can use SendNotify
--SendNotify("DYNAMIC_CAPABILITIES_CHANGED", Params, BindingID)

HEAT_SETPOINT_MAX_F

An optional parameter included in a DYNAMIC_CAPABILITIES_CHANGED notification received by the proxy via a C4:SendToProxy call. It is a string-based integer value used to update the maximum heat setpoint in Fahrenheit. The value is passed through the payload as a string representation of the number and is applied to the corresponding setpoint_heat_max_f capability. If the parameter is not provided, the default is 100.

Name

HEAT_SETPOINT_MAX_F ()

Parameter	Type	Default	Capability	Range	Description
HEAT_SETPOINT_MAX_F	INT	89	`setpoint_heat_max_f`	0-100 and < `setpoint_heat_min_f`	Maximum heat setpoint in Fahrenheit.

Lua example

local HeatSetpointMaxF = 90

local Params = {
    HEAT_SETPOINT_MAX_F = tostring(HeatSetpointMaxF)
}

C4:SendToProxy(bindingID, "DYNAMIC_CAPABILITIES_CHANGED", Params, "NOTIFY")

-- if using the template code you can use SendNotify
--SendNotify("DYNAMIC_CAPABILITIES_CHANGED", Params, BindingID)

HEAT_SETPOINT_MIN_C

An optional parameter included in a DYNAMIC_CAPABILITIES_CHANGED notification received by the proxy via a C4:SendToProxy call. It is a string-based decimal value used to update the minimum heat setpoint in Celsius. The value must be expressed as a string so it can be passed through the proxy notification payload format. If the parameter is not provided, the default is 0.

Name

HEAT_SETPOINT_MIN_C ()

Parameter	Type	Default	Capability	Range	Description
HEAT_SETPOINT_MIN_C	INT	4	`setpoint_heat_min_c`	0-100 and > `setpoint_heat_max_c`	Minimum heat setpoint in Celsius.

Lua example

local HeatSetpointMinC = 5

local Params = {
    HEAT_SETPOINT_MIN_C = tostring(HeatSetpointMinC)
}

C4:SendToProxy(bindingID, "DYNAMIC_CAPABILITIES_CHANGED", Params, "NOTIFY")

-- if using the template code you can use SendNotify
--SendNotify("DYNAMIC_CAPABILITIES_CHANGED", Params, BindingID)

HEAT_SETPOINT_MIN_F

An optional parameter included in a DYNAMIC_CAPABILITIES_CHANGED notification received by the proxy via a C4:SendToProxy call. It is a string-based decimal value used to update the minimum heat setpoint in Fahrenheit. The value must be expressed as a string so it can be passed through the proxy notification payload format. If the parameter is not provided, the default is 0.

Name

HEAT_SETPOINT_MIN_F ()

Parameter	Type	Default	Capability	Range	Description
HEAT_SETPOINT_MIN_F	INT	31	`setpoint_heat_min_f`	0-100 and < `setpoint_heat_max_f`	Minimum heat setpoint in Fahrenheit.

Lua example

local HeatSetpointMinF = 40.0

local Params = {
    HEAT_SETPOINT_MIN_F = tostring(HeatSetpointMinF)
}

C4:SendToProxy(bindingID, "DYNAMIC_CAPABILITIES_CHANGED", Params, "NOTIFY")

-- if using the template code you can use SendNotify
--SendNotify("DYNAMIC_CAPABILITIES_CHANGED", Params, BindingID)

HEAT_SETPOINT_RESOLUTION_C

An optional parameter included in a DYNAMIC_CAPABILITIES_CHANGED notification received by the proxy via a C4:SendToProxy call. It is a string-based integer value used to update the heat setpoint resolution in Celsius. The value is passed through the payload as a string representation of the number and is applied to the corresponding setpoint_heat_resolution_c capability. If the parameter is not provided, the default is 1.

Name

HEAT_SETPOINT_RESOLUTION_C ()

Parameter	Type	Default	Capability	Description
HEAT_SETPOINT_RESOLUTION_C	INT	1	`setpoint_heat_resolution_c`	Heat setpoint resolution in Celsius.

Lua example

local HeatSetpointResolutionC = .5

local Params = {
    HEAT_SETPOINT_RESOLUTION_C = tostring(HeatSetpointResolutionC)
}

C4:SendToProxy(bindingID, "DYNAMIC_CAPABILITIES_CHANGED", Params, "NOTIFY")

-- if using the template code you can use SendNotify
--SendNotify("DYNAMIC_CAPABILITIES_CHANGED", Params, BindingID)

HEAT_SETPOINT_RESOLUTION_F

An optional parameter included in a DYNAMIC_CAPABILITIES_CHANGED notification received by the proxy via a C4:SendToProxy call. It is a string-based integer value used to update the heat setpoint resolution in Fahrenheit. The value is passed through the payload as a string representation of the number and is applied to the corresponding setpoint_heat_resolution_f capability. If the parameter is not provided, the default is 1.

Name

HEAT_SETPOINT_RESOLUTION_F ()

Parameter	Type	Default	Capability	Description
HEAT_SETPOINT_RESOLUTION_F	INT	1	`setpoint_heat_resolution_f`	Heat setpoint resolution in Fahrenheit.

Lua example

local HeatSetpointResolutionF = 2

local Params = {
    HEAT_SETPOINT_RESOLUTION_F = tostring(HeatSetpointResolutionF)
}

C4:SendToProxy(bindingID, "DYNAMIC_CAPABILITIES_CHANGED", Params, "NOTIFY")

-- if using the template code you can use SendNotify
--SendNotify("DYNAMIC_CAPABILITIES_CHANGED", Params, BindingID)

HOLD_UNTIL_MODE

An optional parameter included in a DYNAMIC_CAPABILITIES_CHANGED notification received by the proxy via a C4:SendToProxy call. It is a string value used to update the hold-until mode list. The value is passed through the payload as text, and it updates the corresponding hold_until_mode capability. If the parameter is not provided, the default is date,time.

Name

HOLD_UNTIL_MODE ()

Parameter	Type	Default	Capability	Description
HOLD_UNTIL_MODE	STRING	date,time	`hold_until_mode`	Hold-until mode list supported by the thermostat.

Lua example

local HoldUntilMode = "date,time"

local Params = {
    HOLD_UNTIL_MODE = HoldUntilMode
}

C4:SendToProxy(bindingID, "DYNAMIC_CAPABILITIES_CHANGED", Params, "NOTIFY")

-- if using the template code you can use SendNotify
--SendNotify("DYNAMIC_CAPABILITIES_CHANGED", Params, BindingID)

HOLD_UNTIL_RESOLUTION

An optional parameter included in a DYNAMIC_CAPABILITIES_CHANGED notification received by the proxy via a C4:SendToProxy call. It is a string-based integer value used to update the hold-until resolution. The value is passed through the payload as a string representation of the number and is applied to the corresponding hold_until_resolution capability. If the parameter is not provided, the default is 5.

Name

HOLD_UNTIL_RESOLUTION ()

Parameter	Type	Default	Capability	Description
HOLD_UNTIL_RESOLUTION	INT	5	`hold_until_resolution`	Hold-until resolution value.

Lua example

local HoldUntilResolution = 5

local Params = {
    HOLD_UNTIL_RESOLUTION = tostring(HoldUntilResolution)
}

C4:SendToProxy(bindingID, "DYNAMIC_CAPABILITIES_CHANGED", Params, "NOTIFY")

-- if using the template code you can use SendNotify
--SendNotify("DYNAMIC_CAPABILITIES_CHANGED", Params, BindingID)

HUMIDITY_SETPOINT_DEADBAND

An optional parameter included in a DYNAMIC_CAPABILITIES_CHANGED notification received by the proxy via a C4:SendToProxy call. It is a string-based integer value used to update the humitity setpoint deadband. The value is passed through the payload as a string representation of the number and is applied to the corresponding setpoint_humidity_deadband capability. If the parameter is not provided, the default is 10.

Name

HUMIDITY_SETPOINT_DEADBAND ()

Parameter	Type	Default	Capability	Range	Description
HUMIDITY_SETPOINT_DEADBAND	INT	10	`setpoint_humidity_deadband`		What the deadband between humidify and dehumidify is.

Lua example

local HeatCoolSetpointsDeadbandC = 2

local Params = {
    HUMIDITY_SETPOINT_DEADBAND = tostring(HeatCoolSetpointsDeadbandC)
}

C4:SendToProxy(bindingID, "DYNAMIC_CAPABILITIES_CHANGED", Params, "NOTIFY")

-- if using the template code you can use SendNotify
--SendNotify("DYNAMIC_CAPABILITIES_CHANGED", Params, BindingID)

HUMIDIFY_SETPOINT_MAX

An optional parameter included in a DYNAMIC_CAPABILITIES_CHANGED notification received by the proxy via a C4:SendToProxy call. It is a string-based integer value used to update the maximum humidify setpoint. The value is passed through the payload as a string representation of the number and is applied to the corresponding setpoint_humidify_max capability. If the parameter is not provided, the default is 100.

Name

HUMIDIFY_SETPOINT_MAX ()

Parameter	Type	Default	Capability	Range	Description
HUMIDIFY_SETPOINT_MAX	INT	100	`setpoint_humidify_max`	0-100	Maximum humidify setpoint.

Lua example

local HumidifySetpointMax = 60

local Params = {
    HUMIDIFY_SETPOINT_MAX = tostring(HumidifySetpointMax)
}

C4:SendToProxy(bindingID, "DYNAMIC_CAPABILITIES_CHANGED", Params, "NOTIFY")

-- if using the template code you can use SendNotify
--SendNotify("DYNAMIC_CAPABILITIES_CHANGED", Params, BindingID)

HUMIDIFY_SETPOINT_MIN

An optional parameter included in a DYNAMIC_CAPABILITIES_CHANGED notification received by the proxy via a C4:SendToProxy call. It is a string-based integer value used to update the minimum humidify setpoint. The value is passed through the payload as a string representation of the number and is applied to the corresponding setpoint_humidify_min capability. If the parameter is not provided, the default is 0.

Name

HUMIDIFY_SETPOINT_MIN ()

Parameter	Type	Default	Capability	Range	Description
HUMIDIFY_SETPOINT_MIN	INT	0	`setpoint_humidify_min`	0-100	Minimum humidify setpoint.

Lua example

local HumidifySetpointMin = 30

local Params = {
    HUMIDIFY_SETPOINT_MIN = tostring(HumidifySetpointMin)
}

C4:SendToProxy(bindingID, "DYNAMIC_CAPABILITIES_CHANGED", Params, "NOTIFY")

-- if using the template code you can use SendNotify
--SendNotify("DYNAMIC_CAPABILITIES_CHANGED", Params, BindingID)

HUMIDIFY_SETPOINT_RESOLUTION

An optional parameter included in a DYNAMIC_CAPABILITIES_CHANGED notification received by the proxy via a C4:SendToProxy call. It is a string-based integer value used to update the humidify setpoint resolution. The value is passed through the payload as a string representation of the number and is applied to the corresponding setpoint_humidify_resolution capability. If the parameter is not provided, the default is 1.

Name

HUMIDIFY_SETPOINT_RESOLUTION ()

Parameter	Type	Default	Capability	Range	Description
HUMIDIFY_SETPOINT_RESOLUTION	INT	1	`setpoint_humidify_resolution`	0-100	Humidify setpoint resolution.

Lua example

local HumidifySetpointResolution = 5

local Params = {
    HUMIDIFY_SETPOINT_RESOLUTION = tostring(HumidifySetpointResolution)
}

C4:SendToProxy(bindingID, "DYNAMIC_CAPABILITIES_CHANGED", Params, "NOTIFY")

-- if using the template code you can use SendNotify
--SendNotify("DYNAMIC_CAPABILITIES_CHANGED", Params, BindingID)

LOCK_SCREEN_MODES

An optional parameter included in a DYNAMIC_CAPABILITIES_CHANGED notification received by the proxy via a C4:SendToProxy call. It is a string value used to update the list of supported lock screen modes. The value is passed through the payload as text, and it updates the corresponding lock_screen_modes capability. If the parameter is not provided, the default is date,time.

Name

LOCK_SCREEN_MODES ()

Parameter	Type	Default	Capability	Description
LOCK_SCREEN_MODES	STRING	""	`lock_screen_modes`	List of supported lock screen modes.

Lua example

local LockScreenModes = "Unlocked,Partially Locked,Fully Locked"

local Params = {
    LOCK_SCREEN_MODES = LockScreenModes
}

C4:SendToProxy(bindingID, "DYNAMIC_CAPABILITIES_CHANGED", Params, "NOTIFY")

-- if using the template code you can use SendNotify
--SendNotify("DYNAMIC_CAPABILITIES_CHANGED", Params, BindingID)

OUTDOOR_TEMPERATURE_RESOLUTION_C

An optional parameter included in a DYNAMIC_CAPABILITIES_CHANGED notification received by the proxy via a C4:SendToProxy call. It is a string-based integer value used to update the outdoor temperature resolution in Celsius. The value is passed through the payload as a string representation of the number and is applied to the corresponding outdoor_temperature_resolution_c capability. If the parameter is not provided, the default is 1.

Name

OUTDOOR_TEMPERATURE_RESOLUTION_C ()

Parameter	Type	Default	Capability	Description
OUTDOOR_TEMPERATURE_RESOLUTION_C	INT	1	`outdoor_temperature_resolution_c`	Outdoor temperature resolution in Celsius.

Lua example

local OutdoorTemperatureResolutionC = .5

local Params = {
    OUTDOOR_TEMPERATURE_RESOLUTION_C = tostring(OutdoorTemperatureResolutionC)
}

C4:SendToProxy(bindingID, "DYNAMIC_CAPABILITIES_CHANGED", Params, "NOTIFY")

-- if using the template code you can use SendNotify
--SendNotify("DYNAMIC_CAPABILITIES_CHANGED", Params, BindingID)

OUTDOOR_TEMPERATURE_RESOLUTION_F

An optional parameter included in a DYNAMIC_CAPABILITIES_CHANGED notification received by the proxy via a C4:SendToProxy call. It is a string-based integer value used to update the outdoor temperature resolution in Fahrenheit. The value is passed through the payload as a string representation of the number and is applied to the corresponding outdoor_temperature_resolution_f capability. If the parameter is not provided, the default is 1.

Name

OUTDOOR_TEMPERATURE_RESOLUTION_F ()

Parameter	Type	Default	Capability	Range	Description
OUTDOOR_TEMPERATURE_RESOLUTION_F	INT	1	`outdoor_temperature_resolution_f`	0.01-100	Outdoor temperature resolution in Fahrenheit (ie 1,3,5,10,etc).

Lua example

local OutdoorTemperatureResolutionF = .5

local Params = {
    OUTDOOR_TEMPERATURE_RESOLUTION_F = tostring(OutdoorTemperatureResolutionF)
}

C4:SendToProxy(bindingID, "DYNAMIC_CAPABILITIES_CHANGED", Params, "NOTIFY")

-- if using the template code you can use SendNotify
--SendNotify("DYNAMIC_CAPABILITIES_CHANGED", Params, BindingID)

SINGLE_SETPOINT_MAX_C

An optional parameter included in a DYNAMIC_CAPABILITIES_CHANGED notification received by the proxy via a C4:SendToProxy call. It is a string-based integer value used to update the maximum single setpoint in Celsius. The value is passed through the payload as a string representation of the number and is applied to the corresponding setpoint_single_max_c capability. If the parameter is not provided, the default is 32.

Name

SINGLE_SETPOINT_MAX_C ()

Parameter	Type	Default	Capability	Range	Description
SINGLE_SETPOINT_MAX_C	INT	32	`setpoint_single_max_c`	0-100 and < `setpoint_single_min_c`	Maximum single setpoint in Celsius.

Lua example

local SingleSetpointMaxC = 31

local Params = {
    SINGLE_SETPOINT_MAX_C = tostring(SingleSetpointMaxC)
}

C4:SendToProxy(bindingID, "DYNAMIC_CAPABILITIES_CHANGED", Params, "NOTIFY")

-- if using the template code you can use SendNotify
--SendNotify("DYNAMIC_CAPABILITIES_CHANGED", Params, BindingID)

SINGLE_SETPOINT_MAX_F

An optional parameter included in a DYNAMIC_CAPABILITIES_CHANGED notification received by the proxy via a C4:SendToProxy call. It is a string-based integer value used to update the maximum single setpoint in Fahrenheit. The value is passed through the payload as a string representation of the number and is applied to the corresponding setpoint_single_max_f capability. If the parameter is not provided, the default is 90.

Name

SINGLE_SETPOINT_MAX_F ()

Parameter	Type	Default	Capability	Range	Description
SINGLE_SETPOINT_MAX_F	INT	90	`setpoint_single_max_f`	0-100 and < `setpoint_single_min_f`	Maximum single setpoint in Fahrenheit.

Lua example

local SingleSetpointMaxF = 90

local Params = {
    SINGLE_SETPOINT_MAX_F = tostring(SingleSetpointMaxF)
}

C4:SendToProxy(bindingID, "DYNAMIC_CAPABILITIES_CHANGED", Params, "NOTIFY")

-- if using the template code you can use SendNotify
--SendNotify("DYNAMIC_CAPABILITIES_CHANGED", Params, BindingID)

SINGLE_SETPOINT_MIN_C

An optional parameter included in a DYNAMIC_CAPABILITIES_CHANGED notification received by the proxy via a C4:SendToProxy call. It is a string-based integer value used to update the minimum single setpoint in Celsius. The value is passed through the payload as a string representation of the number and is applied to the corresponding setpoint_single_min_c capability. If the parameter is not provided, the default is 5.

Name

SINGLE_SETPOINT_MIN_C ()

Parameter	Type	Default	Capability	Range	Description
SINGLE_SETPOINT_MIN_C	INT	5	`setpoint_single_min_c`	0-100 and > `setpoint_single_max_c`	Minimum single setpoint in Celsius.

Lua example

local SingleSetpointMinC = 4

local Params = {
    SINGLE_SETPOINT_MIN_C = tostring(SingleSetpointMinC)
}

C4:SendToProxy(bindingID, "DYNAMIC_CAPABILITIES_CHANGED", Params, "NOTIFY")

-- if using the template code you can use SendNotify
--SendNotify("DYNAMIC_CAPABILITIES_CHANGED", Params, BindingID)

SINGLE_SETPOINT_MIN_F

An optional parameter included in a DYNAMIC_CAPABILITIES_CHANGED notification received by the proxy via a C4:SendToProxy call. It is a string-based integer value used to update the minimum single setpoint in Fahrenheit. The value is passed through the payload as a string representation of the number and is applied to the corresponding setpoint_single_min_f capability. If the parameter is not provided, the default is 39.

Name

SINGLE_SETPOINT_MIN_F ()

Parameter	Type	Default	Capability	Range	Description
SINGLE_SETPOINT_MIN_F	INT	39	`setpoint_single_min_f`	0-100 and > `setpoint_single_min_c`	Minimum single setpoint in Fahrenheit.

Lua example

local SingleSetpointMinF = 40

local Params = {
    SINGLE_SETPOINT_MIN_F = tostring(SingleSetpointMinF)
}

C4:SendToProxy(bindingID, "DYNAMIC_CAPABILITIES_CHANGED", Params, "NOTIFY")

-- if using the template code you can use SendNotify
--SendNotify("DYNAMIC_CAPABILITIES_CHANGED", Params, BindingID)

SINGLE_SETPOINT_RESOLUTION_C

An optional parameter included in a DYNAMIC_CAPABILITIES_CHANGED notification received by the proxy via a C4:SendToProxy call. It is a string-based integer value used to update the single setpoint resolution in Celsius. The value is passed through the payload as a string representation of the number and is applied to the corresponding setpoint_single_resolution_c capability. If the parameter is not provided, the default is 1.

Name

SINGLE_SETPOINT_RESOLUTION_C ()

Parameter	Type	Default	Capability	Description
SINGLE_SETPOINT_RESOLUTION_C	INT	1	`setpoint_single_resolution_c`	Single setpoint resolution in Celsius.

Lua example

local SingleSetpointResolutionC = .5

local Params = {
    SINGLE_SETPOINT_RESOLUTION_C = tostring(SingleSetpointResolutionC)
}

C4:SendToProxy(bindingID, "DYNAMIC_CAPABILITIES_CHANGED", Params, "NOTIFY")

-- if using the template code you can use SendNotify
--SendNotify("DYNAMIC_CAPABILITIES_CHANGED", Params, BindingID)

SINGLE_SETPOINT_RESOLUTION_F

An optional parameter included in a DYNAMIC_CAPABILITIES_CHANGED notification received by the proxy via a C4:SendToProxy call. It is a string-based integer value used to update the single setpoint resolution in Fahrenheit. The value is passed through the payload as a string representation of the number and is applied to the corresponding setpoint_single_resolution_f capability. If the parameter is not provided, the default is 1.

Name

SINGLE_SETPOINT_RESOLUTION_F ()

Parameter	Type	Default	Capability	Description
SINGLE_SETPOINT_RESOLUTION_F	INT	1	`setpoint_single_resolution_f`	Single setpoint resolution in Fahrenheit.

Lua example

local SingleSetpointResolutionF = 1

local Params = {
    SINGLE_SETPOINT_RESOLUTION_F = tostring(SingleSetpointResolutionF)
}

C4:SendToProxy(bindingID, "DYNAMIC_CAPABILITIES_CHANGED", Params, "NOTIFY")

-- if using the template code you can use SendNotify
--SendNotify("DYNAMIC_CAPABILITIES_CHANGED", Params, BindingID)

TEMPERATURE_MAX_C

An optional parameter included in a DYNAMIC_CAPABILITIES_CHANGED notification received by the proxy via a C4:SendToProxy call. It is a string-based integer value used to update the maximum current temperature in Celsius. The value is passed through the payload as a string representation of the number and is applied to the corresponding current_temperature_max_c capability. If the parameter is not provided, the default is 50.

Name

TEMPERATURE_MAX_C ()

Parameter	Type	Default	Capability	Range	Description
TEMPERATURE_MAX_C	INT	50	`current_temperature_max_c`		Maximum current temperature in Celsius.

Lua example

local TemperatureMaxC = 50

local Params = {
    TEMPERATURE_MAX_C = tostring(TemperatureMaxC)
}

C4:SendToProxy(bindingID, "DYNAMIC_CAPABILITIES_CHANGED", Params, "NOTIFY")

-- if using the template code you can use SendNotify
--SendNotify("DYNAMIC_CAPABILITIES_CHANGED", Params, BindingID)

TEMPERATURE_MAX_F

An optional parameter included in a DYNAMIC_CAPABILITIES_CHANGED notification received by the proxy via a C4:SendToProxy call. It is a string-based integer value used to update the maximum current temperature in Fahrenheit. The value is passed through the payload as a string representation of the number and is applied to the corresponding current_temperature_max_f capability. If the parameter is not provided, the default is 120.

Name

TEMPERATURE_MAX_F ()

Parameter	Type	Default	Capability	Description
TEMPERATURE_MAX_F	INT	120	`current_temperature_max_f`	Maximum current temperature in Fahrenheit.

Lua example

local TemperatureMaxF = 120

local Params = {
    TEMPERATURE_MAX_F = tostring(TemperatureMaxF)
}

C4:SendToProxy(bindingID, "DYNAMIC_CAPABILITIES_CHANGED", Params, "NOTIFY")

-- if using the template code you can use SendNotify
--SendNotify("DYNAMIC_CAPABILITIES_CHANGED", Params, BindingID)

TEMPERATURE_MIN_C

An optional parameter included in a DYNAMIC_CAPABILITIES_CHANGED notification received by the proxy via a C4:SendToProxy call. It is a string-based integer value used to update the minimum current temperature in Celsius. The value is passed through the payload as a string representation of the number and is applied to the corresponding current_temperature_min_c capability. If the parameter is not provided, the default is -40.

Name

TEMPERATURE_MIN_C ()

Parameter	Type	Default	Capability	Description
TEMPERATURE_MIN_C	INT	-40	`current_temperature_min_c`	Minimum current temperature in Celsius.

Lua example

local TemperatureMinC = -40

local Params = {
    TEMPERATURE_MIN_C = tostring(TemperatureMinC)
}

C4:SendToProxy(bindingID, "DYNAMIC_CAPABILITIES_CHANGED", Params, "NOTIFY")

-- if using the template code you can use SendNotify
--SendNotify("DYNAMIC_CAPABILITIES_CHANGED", Params, BindingID)

TEMPERATURE_MIN_F

An optional parameter included in a DYNAMIC_CAPABILITIES_CHANGED notification received by the proxy via a C4:SendToProxy call. It is a string-based integer value used to update the minimum current temperature in Fahrenheit. The value is passed through the payload as a string representation of the number and is applied to the corresponding current_temperature_min_f capability. If the parameter is not provided, the default is -40.

Name

TEMPERATURE_MIN_F ()

Parameter	Type	Default	Capability	Description
TEMPERATURE_MIN_F	INT	-40	`current_temperature_min_f`	Minimum current temperature in Fahrenheit.

Lua example

local TemperatureMinF = -40

local Params = {
    TEMPERATURE_MIN_F = tostring(TemperatureMinF)
}

C4:SendToProxy(bindingID, "DYNAMIC_CAPABILITIES_CHANGED", Params, "NOTIFY")

-- if using the template code you can use SendNotify
--SendNotify("DYNAMIC_CAPABILITIES_CHANGED", Params, BindingID)

TEMPERATURE_RESOLUTION_C

An optional parameter included in a DYNAMIC_CAPABILITIES_CHANGED notification received by the proxy via a C4:SendToProxy call. It is a string-based integer value used to update the current temperature resolution in Celsius. The value is passed through the payload as a string representation of the number and is applied to the corresponding current_temperature_resolution_c capability. If the parameter is not provided, the default is 1.

Name

TEMPERATURE_RESOLUTION_C ()

Parameter	Type	Default	Capability	Description
TEMPERATURE_RESOLUTION_C	INT	1	`current_temperature_resolution_c`	Current temperature resolution in Celsius.

Lua example

local TemperatureResolutionC = 1

local Params = {
    TEMPERATURE_RESOLUTION_C = tostring(TemperatureResolutionC)
}

C4:SendToProxy(bindingID, "DYNAMIC_CAPABILITIES_CHANGED", Params, "NOTIFY")

-- if using the template code you can use SendNotify
--SendNotify("DYNAMIC_CAPABILITIES_CHANGED", Params, BindingID)

TEMPERATURE_RESOLUTION_F

An optional parameter included in a DYNAMIC_CAPABILITIES_CHANGED notification received by the proxy via a C4:SendToProxy call. It is a string-based integer value used to update the current temperature resolution in Fahrenheit. The value is passed through the payload as a string representation of the number and is applied to the corresponding current_temperature_resolution_f capability. If the parameter is not provided, the default is 1.

Name

TEMPERATURE_RESOLUTION_F ()

Parameter	Type	Default	Capability	Description
TEMPERATURE_RESOLUTION_F	INT	1	`current_temperature_resolution_f`	Current temperature resolution in Fahrenheit.

Lua example

local TemperatureResolutionF = 1

local Params = {
    TEMPERATURE_RESOLUTION_F = tostring(TemperatureResolutionF)
}

C4:SendToProxy(bindingID, "DYNAMIC_CAPABILITIES_CHANGED", Params, "NOTIFY")

-- if using the template code you can use SendNotify
--SendNotify("DYNAMIC_CAPABILITIES_CHANGED", Params, BindingID)

Thermostat Proxy Commands

SET_PRESET

Runs a Preset regardless if there is an event scheduled for it.

Name

SET_PRESET ()

Parameter	Type	Description
NAME	STR	Preset Name

Returns

None

DEC_SETPOINT_COOL

Decreases the cool setpoint. This command is handled by the proxy.

If can_inc_dec_setpoints is true, the proxy sends a DEC_SETPOINT_COOL command to the protocol driver.

If can_inc_dec_setpoints is false, the proxy calculates the new cool setpoint locally based on the configured resolution and then sends a SET_SETPOINT_COOL command to the protocol driver with the updated value.

None

DEC_SETPOINT_HEAT

Decreases the heat setpoint. This command is handled by the proxy.

If can_inc_dec_setpoints is true, the proxy sends an DEC_SETPOINT_HEAT command to the protocol driver.

If can_inc_dec_setpoints is false, the proxy calculates the new heat setpoint locally based on the configured resolution and then sends a SET_SETPOINT_HEAT command to the protocol driver with the updated value.

When the thermostat is in Fahrenheit mode, the setpoint is increased by the value in HEAT_SETPOINT_RESOLUTION_F (typically 1). When it is in Celsius mode, it is increased by the value in HEAT_SETPOINT_RESOLUTION_C (typically 1).

Name

DEC_SETPOINT_HEAT ()

Parameter

None

Command Sent to Protocol Driver

If can_inc_dec_setpoints is true: DEC_SETPOINT_HEAT If can_inc_dec_setpoints is false: SET_SETPOINT_HEAT with the calculated new setpoint value

Notification

When the thermostat actually changes the heat setpoint, the protocol driver should send back a notification in the form:

HEAT_SETPOINT_CHANGED
Parameters:
- SETPOINT
- SCALE

When the thermostat is in Fahrenheit mode, the decrement is based on SINGLE_SETPOINT_RESOLUTION_F (typically 1). When it is in Celsius mode, the decrement is based on SINGLE_SETPOINT_RESOLUTION_C (typically 1).

Name

DEC_SETPOINT_SINGLE ()

Parameter

None

Command Sent to Protocol Driver

If can_inc_dec_setpoints is true: DEC_SETPOINT_SINGLE If can_inc_dec_setpoints is false: SET_SETPOINT_SINGLE with the calculated new setpoint value

Notification

When the thermostat actually changes the setpoint, the protocol driver should send back a notification in the form:

SETPOINT_CHANGED
Parameters:
- SETPOINT
- SCALE

See the thermostat setpoint notification documentation for the exact parameter details and valid values.

Returns

None

DELETE_SCHEDULE_ENTRY

Deletes a schedule entry for one day or the full week, depending on whether DAY_INDEX is provided.

Introduced in OS Release 4.3.0.

Name

DELETE_SCHEDULE_ENTRY ()

Parameter	Type	Description
ENTRY_INDEX	INT	`ENTRY_INDEX` is the zero-based index of the schedule entry for the selected day. In this implementation, the value is effectively offset by one relative to `schedule_entries_per_day`: if `schedule_entries_per_day` is 6, the valid entry indexes are 0 through 6, which represents 7 entries total. This is a legacy quirk of the schedule model, and the default value is 6 unless the default schedule overrides it through the `Entries` attribute on the `schedule_day_info` element in the `schedule_default` capability defined in the driver.xml file.
DAY_INDEX	INT	`DAY_INDEX` is the zero-based index of the day in the weekly schedule. Valid values are 0 through 6, corresponding to the days of the week in the thermostat’s schedule model. This value is used with `ENTRY_INDEX` to identify the target schedule row: `DAY_INDEX` selects the day, and `ENTRY_INDEX` selects the entry within that day. If `DAY_INDEX` is provided, the command applies only to that day; if it is omitted, the command applies across all days for the selected entry index. The driver validates the value against the schedule’s weekly range and rejects invalid day values.

Command Sent to Protocol Driver

DELETE_SCHEDULE_ENTRY

Notification

SCHEDULE_ENTRY_DELETED

Parameters:

EntryIndex
DayIndex (optional, included when the command applies to a specific day)

This notification is sent when a schedule entry is deleted. If the delete is scoped to a single day, both EntryIndex and DayIndex are included. If the delete applies across all days, the notification may include only EntryIndex.

Returns

None

INC_SETPOINT_COOL

Increases the cool setpoint. This command is handled by the proxy.

If can_inc_dec_setpoints is true, the proxy sends an INC_SETPOINT_COOL command to the protocol driver.

None

INC_SETPOINT_HEAT

Increases the heat setpoint. This command is handled by the proxy.

None

INC_SETPOINT_SINGLE

Increases the single setpoint. This command is handled by the proxy.

If can_inc_dec_setpoints is true, the proxy sends an INC_SETPOINT_SINGLE command to the protocol driver.

If can_inc_dec_setpoints is false, the proxy calculates the new setpoint locally based on the configured resolution and then sends a SET_SETPOINT_SINGLE command to the protocol driver with the updated setpoint value.

When the thermostat is in Fahrenheit mode, the increment is based on SINGLE_SETPOINT_RESOLUTION_F (typically 1). When it is in Celsius mode, the increment is based on SINGLE_SETPOINT_RESOLUTION_C (typically 1).

Name

INC_SETPOINT_SINGLE ()

Parameter

None

Command Sent to Protocol Driver

If can_inc_dec_setpoints is true: INC_SETPOINT_SINGLE If can_inc_dec_setpoints is false: SET_SETPOINT_SINGLE with the calculated new setpoint value

Notification

When the thermostat actually changes the setpoint, the protocol driver should send back a notification in the form:

SETPOINT_CHANGED
Parameters:
- SETPOINT
- SCALE

See the thermostat setpoint notification documentation for the exact parameter details and valid values.

Returns

None

PRESET_ADD

Adds a new Preset Schedule Preset (If protocol driver has the can_preset_schedule or can_fixed_schedule_and_presets capability)

Name

PRESET_ADD ()

Parameter	Type	Description
NAME	STR	Preset Name. Required.
PRESET_FIELDS	XML	If a UI or Driver sends a bound call with a string that has invalid XML syntax, this field will be set to `<preset_field/>` and an error message will be logged to director.log when this occurs. Note that only a driver OR UI should specify the `_f or c.` For example: `heat_setpoint_f`, `cool_setpoint_f`, `heat_setpoint_c`, `cool_setpoint_c` but not both. The proxy will auto insert the missing `_f or _c` based on the scales resolution if it detects one side is not supplied. This makes it so UI's and drivers do not need to calculate the correct value for the scale. However, if a driver or UI does want to calculate it, the proxy will leave the value alone. In the same manner the proxy will not correct or anything if the `_f and _c` do not resolve to the equivalent temperature.
PRESET_EDIT (new to 4.3.0)		`PRESET_EDIT` is an optional parameter that describes how the preset may be edited by the UI or client. It is passed through the proxy and normalized before being stored. Allowed values: - `all` — the preset can be edited in all fields - `name` — only the preset name may be edited - `read_only` — the preset is read-only and cannot be edited If this parameter is omitted, the proxy defaults to `all`. The value is not used to change the preset data itself; it is metadata used to control edit permissions and is preserved with the preset definition.

Command Sent to Protocol Driver

SET_PRESETS - sends the current preset XML payload to the protocol driver.

Returns

None

PRESET_DELETE

Deletes an existing preset. Preset delete is enabled in the UIs if can_preset_schedule or can_fixed_schedule_and_presets capability is enabled. PRESET_ID was introduced in 4.3.0. Do not use PRESET_ID if the driver supports earlier versions.

The preferred identifier is PRESET_ID; it is used instead of NAME when both are present. PRESET_ID and NAME are mutually exclusive, and the command rejects the request if neither is supplied.

If PRESET_ID is provided, the proxy clears NAME and deletes the matching preset by ID. If PRESET_ID is absent, it deletes the preset matching the provided NAME. This follows the 4.3.0 behavior, where PRESET_ID was added as the preferred parameter for preset deletion.

Name

PRESET_DELETE ()

Parameter	Type	Description
NAME	STR	Preset Name. Before 4.3.0 is Required. 4.3.0+ it is Mutually exclusive.
PRESET_ID (new to 4.3.0)	INT	Preset ID. Preferred parameter. Mutually exclusive

Command Sent to Protocol Driver

SET_PRESETS - sends the current preset XML payload to the protocol driver.

Returns

None

PRESET_EVENT_ADD

Adds a preset schedule event to run at the specified day and time. This command is only valid when the protocol driver supports either the can_preset_schedule capability or the can_fixed_schedule_and_presets capability (4.3.0+).

Name

PRESET_EVENT_ADD ()

Parameter	Description	Description
PRESET	STR	Preset name. Required before 4.3.0. In 4.3.0+, this is mutually exclusive with PRESET_ID.
PRESET_ID (new to 4.3.0)	INT	Preset ID. Added in 4.3.0. Preferred over PRESET when both are present. Mutually exclusive with PRESET.
WEEKDAY	INT	Day of the week. Valid range is 0-6, with Sunday = 0.
HOUR	INT	Hour of the day. Valid range is 0-23.
MINUTE	INT	Minute of the hour. Valid range is 0-59.

Returns

None

Command Sent to Protocol Driver

SET_PRESETS — sends the current preset XML payload to the protocol driver.

Usage Note

Adding an event at the same time as a different preset event will result in the different preset event being deleted and the new one being put in at that time.

PRESET_EVENT_DELETE

Deletes a Preset Schedule Preset. This command is only valid when the protocol driver supports either the can_preset_schedule capability or the can_fixed_schedule_and_presets capability (4.3.0+).

Name

PRESET_EVENT_DELETE ()

Parameter	Type	Description
PRESET	STR	Preset name. Required before 4.3.0. In 4.3.0+, this is mutually exclusive with PRESET_ID.
PRESET_ID (new to 4.3.0)	INT	Preset ID. Added in 4.3.0. Preferred over PRESET when both are present. Mutually exclusive with PRESET.
WEEKDAY	INT	Day of the week. Valid range is 0-6, with Sunday = 0. Using -1 will match any weekday.
HOUR	INT	Hour of the day. Valid range is 0-23. Using -1 Will match any Hour.
MINUTE	INT	Minute of the hour. Valid range is 0-59. Using -1 will match any Minute.

Returns

None

Command Sent to Protocol Driver

SET_PRESETS — sends the current preset XML payload to the protocol driver.

PRESET_EVENT_MODIFY

Modifies an existing Preset Schedule Event. This command is only valid when the protocol driver supports either the can_preset_schedule capability or the can_fixed_schedule_and_presets capability (4.3.0+).

Name

PRESET_EVENT_MODIFY ()

Parameter	Type	Description
PRESET	STR	Event Name
PRESET_ID (new to 4.3.0)	INT	Preset ID. Added in 4.3.0. Preferred over PRESET when both are present. Mutually exclusive with PRESET.
WEEKDAY:	INT	Day of the week. Valid range is 0-6, with Sunday = 0.
HOUR	INT	0-23
MINUTE	INT	0-60
NEW WEEKDAY	INT	New day of the week. Valid range is 0-6, with Sunday = 0
NEW HOUR	INT	New hour of the day. Valid range is 0-23.
NEW MINUTE	INT	New minute of the hour. Valid range is 0-59.

Returns

None

Command Sent to Protocol Driver

SET_PRESETS — sends the current preset XML payload to the protocol driver.

Usage Note

Modifying an event to the same time as a different preset event will result in the different preset event being deleted and the new one being put in at that time.

PRESET_MODIFY

Name

PRESET_MODIFY ()

Parameter	Type	Description
NAME	STR	Preset Name. In 4.3.0+, this is mutually exclusive with PRESET_ID.
PRESET_ID (new to 4.3.0)	INT	Preset ID. Added in 4.3.0. Preferred over PRESET when both are present. Mutually exclusive with PRESET.
PRESET_FIELDS	XML	XML DATA
NEW_NAME	STR	New Preset Name

Returns

None

Command Sent to Protocol Driver

SET_PRESETS — sends the current preset XML payload to the protocol driver.

Example

<preset_fields>
  <field id="heat_setpoint_f" value="65">
  <field id="cool_setpoint_f" value="75">
  <field id="humidify_setpoint" value="50">
  <field id="fan_mode" value="On">
</preset_fields>

PRESET_RENAME

Renames an existing preset by its PRESET_ID. This command was added in 4.3.0.

Name

PRESET_RENAME ()

Parameters

Parameter	Type	Description
`PRESET_ID`	INT	Required. The identifier of the preset to rename.
`NEW_NAME`	STR	Required. The new preset name. Must be a valid preset name and may not contain a comma.

Notes

PRESET_RENAME is the 4.3.0 replacement for rename operations that previously relied on name-based matching.
The preset is resolved by PRESET_ID; a name is not used for lookup.
The new name must be valid and unique among existing presets.
If the rename succeeds, the proxy updates the preset definition and updates any scheduled preset events that reference the renamed preset.

Proxy behavior after completion

After a successful rename, the proxy updates the preset state, refreshes the preset list shown to the UI, and sends the updated preset data to the protocol driver as needed. Any preset event entries associated with that preset are also updated so the scheduler continues to reference the current preset name.

Command Sent to Protocol Driver

SET_PRESETS - sends the updated preset XML payload to the protocol driver.

Returns

None

RESTORE_SCHEDULE_ENTRY

Restores a previously deleted schedule entry. This command was added in 4.3.0.

Name

RESTORE_SCHEDULE_ENTRY ()

Parameters

Parameter	Type	Description
`ENTRY_INDEX`	INT	Required. The schedule entry index to restore.
`DAY_INDEX`	INT	Optional. If supplied, only the specified day is restored. If omitted, the restore applies across all days for that entry index.

Notes

ENTRY_INDEX is zero-based and refers to the schedule entry within the selected day.
DAY_INDEX is zero-based and valid from 0 to 6. 0 = Sunday.
If DAY_INDEX is omitted, the command attempts to restore the deleted entry on all days at that entry index.
The command only restores entries that are currently marked as deleted.
If no matching deleted entry is found, the restore request is ignored.

Command Sent to Protocol Driver

RESTORE_SCHEDULE_ENTRY - sends the restore operation to the protocol driver with the relevant DAY_INDEX and ENTRY_INDEX values.

Returns

None

SET_BUTTONS_LOCK

Used to indicate if the buttons on the thermostat should be locked out from controlling the temperature.

Name

SET_BUTTONS_LOCK ()

Parameter	Type	Description
LOCK	BOOL	1 or 0 indicating if the buttons should be locked out or not.

SET_CALIBRATION

Name

SET_CALIBRATION ()

Parameter	Type	Description
`CALIBRATION`	INT	Required. The calibration value to apply.

Notes

This command is only valid when the thermostat supports calibration.
The proxy updates the in-memory calibration value and forwards the value to the protocol driver using the thermostat’s native command format.
Calibration is a driver/hardware-level adjustment and is not a UI-only setting.

Command Sent to Protocol Driver

SET_CALIBRATION - sends the calibration value to the protocol driver.

Returns

None

SET_EVENT

Used in conjunction with Preset Scheduling. This command is sent to the protocol driver when the preset scheduler determines it's time for a new event to be run for Preset Scheduling.

Sets a single thermostat event payload. This command is NOT handled by the proxy and must be implemented in the protocol driver. This command is available through programming and is used when the thermostat exposes event-driven behavior that must be forwarded to the connected device.

Name

SET_EVENT ()

Parameter	Type	Description
PRESET	STRING	Name of the Preset that was triggered.

Command Sent to Protocol Driver

SET_EVENT

Notification

Once the protocol driver has handled the SET_EVENT command or the the driver receives a notification from the thermostat that the preset changed, then a PRESET_CHANGED notification should be sent to the proxy.

SET_EVENTS

Used in conjunction with Preset Scheduling. This command is sent to the protocol driver for updating all of the preset events.

Name

SET_EVENTS ()

Parameter	Type	Description
XML	STRING	XML of all of the current preset scheduler events

Command Sent to Protocol Driver

SET_EVENTS

Notification

No notifications returned with this command.

SET_LOCK_SCREEN_MODE

Sets the Lock Screen Mode on the thermostat.

Name

SET_LOCK_SCREEN_MODE ()

Parameters

Parameter	Type	Description
`MODE`	STR	Required. The lock screen mode to apply.

Notes

This command is new in 4.3.0.
The valid values for MODE are defined by the thermostat capability lock_screen_modes.
- Example: xml <lock_screen_modes>Unlocked,Partially Locked,Fully Locked</lock_screen_modes>
The value passed to the command must match one of the supported lock screen modes reported by the thermostat.

Command Sent to Protocol Driver

Name

SET_PRESET ()

Parameter	Type	Description
NAME	STRING	Required: Preset name.

Notification

Once the thermostat has been updated, the protocol driver should send back the PRESET_CHANGED notification.

SET_PRESETS

Sets one or more thermostat preset values in a grouped operation. This command is NOT handled by the proxy and must be implemented in the protocol driver. This command is available through programming and is used when the thermostat supports preset batching or bulk preset updates.

Name

SET_PRESETS ()

Parameter	Type	Description
PRESET_FIELDS	XML	Required:

Sample PRESET_FIELDS XML

<preset_fields>
    <field id = "heat_setpoint_f" value = "50"/>
    <field id = "cool_setpoint_f" value = "86"/>
    <field id = "humidify_setpoint" value = "20"/>
    <field id = "dehumidify_setpoint" value = "56"/>
    <field id = "hvac_mode" value = "Off"/>
    <field id = "humidity_mode" value = "Humidify"/>
    <field id = "fan_mode" value = "On"/>
    <field id = "heat_setpoint_c" value = "10"/>
    <field id = "cool_setpoint_c" value = "30"/>
</preset_fields>

SET_REMOTE_SENSOR

Sets the thermostat remote sensor usage state. This command is only available when has_remote_sensor is enabled.

Name

SET_REMOTE_SENSOR ()

Parameter	Type	Description
IN_USE	BOOL	Required: True/False

Parameter

IN_USE

Notification

When the thermostat actually updates the remote sensor state, the protocol driver should send back the REMOTE_SENSOR_CHANGED notification.

SET_SCALE

Sets the thermostat temperature scale. This command is available through programming and is used to switch the thermostat between Celsius and Fahrenheit scale values. This command is only available when can_change_scale is enabled.

Name

SET_SCALE ()

Parameter	Type	Description
SCALE	STRING	Required: CELSIUS, FAHRENHEIT, C, c, F, f

Notification

When the thermostat actually changes the scale, the protocol driver should send back the SCALE_CHANGED notification.

SET_SETPOINT_COOL

Sets the cool setpoint.

Name

SET_SETPOINT_COOL ()

Parameters

Parameter	Type	Description
`FAHRENHEIT`	LEVEL	Optional. Cool setpoint in Fahrenheit.
`CELSIUS`	LEVEL	Optional. Cool setpoint in Celsius.

Notes

At least one temperature parameter must be supplied.
The proxy clamps the requested value to the thermostat’s supported cool setpoint range and resolution.
If the thermostat supports both Fahrenheit and Celsius, the proxy accepts whichever scale is provided and converts as needed.
For this command, the proxy updates the current cool setpoint and sends the corresponding protocol-driver command.

Command Sent to Protocol Driver

SET_SETPOINT_COOL - sends the cool setpoint value to the protocol driver.

Returns

None

SET_SETPOINT_DEHUMIDIFY

Sets the dehumidify setpoint. This command is available through programming and is only available if the can_dehumidify is enabled. The protocol driver must apply the setpoint and notify the proxy when the value changes.

Name

SET_SETPOINT_DEHUMIDIFY ()

Parameter	Type	Description
SETPOINT	INT	Required: The value is an integer percentage from 0 to 100, depending on the thermostat’s setpoint_dehumidify_min and setpoint_dehumidify_max values.

Notification

When the thermostat actually changes the dehumidify setpoint, the protocol driver should send back a [DEHUMIDIFY_SETPOINT_CHANGED]2 notification.

SET_SETPOINT_HEAT

Sets the heat setpoint.

Name

SET_SETPOINT_HEAT ()

Parameters

Parameter	Type	Description
`FAHRENHEIT`	LEVEL	Optional. Heat setpoint in Fahrenheit.
`CELSIUS`	LEVEL	Optional. Heat setpoint in Celsius.

Notes

At least one temperature parameter must be supplied.
The proxy clamps the requested value to the thermostat’s supported heat setpoint range and resolution.
If the thermostat supports both Fahrenheit and Celsius, the proxy accepts whichever scale is provided and converts as needed.

Command Sent to Protocol Driver

SET_SETPOINT_HEAT - sends the heat setpoint value to the protocol driver.

Returns

None

SET_SETPOINT_HUMIDIFY

Sets the humidify setpoint. This command is available through programming and is only available if the can_humidify is enabled. The protocol driver must apply the setpoint and notify the proxy when the value changes.

Name

SET_SETPOINT_HUMIDIFY ()

Parameter	Type	Description
SETPOINT	INT	Required: The value is an integer percentage from 0 to 100, depending on the thermostat’s setpoint_humidify_min and setpoint_humidify_max values.

Notification

When the thermostat actually changes the humidify setpoint, the protocol driver should send back a HUMIDIFY_SETPOINT_CHANGED notification.

SET_SETPOINT_SINGLE

Sets the single setpoint.

Name

SET_SETPOINT_SINGLE ()

Parameters

Parameter	Type	Description
`FAHRENHEIT`	LEVEL	Optional. Single setpoint in Fahrenheit.
`CELSIUS`	LEVEL	Optional. Single setpoint in Celsius.

Notes

At least one temperature parameter must be supplied.
The proxy clamps the requested value to the thermostat’s supported single-setpoint range and resolution.
If the thermostat supports both Fahrenheit and Celsius, the proxy accepts whichever scale is provided and converts as needed.
This command is used for thermostats that expose a single active setpoint rather than separate heat/cool setpoints.

Command Sent to Protocol Driver

SET_SETPOINT_SINGLE - sends the single setpoint value to the protocol driver.

Returns

None

UPDATE_SCHEDULE_ENTRY_ENABLED_FLAG

New to 4.3.0. Updates the enabled state of a single schedule entry for one day.

Name

UPDATE_SCHEDULE_ENTRY_ENABLED_FLAG ()

Parameter	Type	Description
`ENTRY_INDEX`	INT	Required. The schedule entry index to enable/disable the entry.
`DAY_INDEX`	INT	Required. The schedule day index to enable/disable the entry.
ENABLED_FLAG	BOOL	True/False. Enable or Disables a schedule entry.

Command Sent to Protocol Driver

UPDATE_SCHEDULE_ENTRY_ENABLED_FLAG - sends the schedule entry enabled flag to the protocol driver with the relevant DAY_INDEX, ENTRY_INDEX and ENABLED_FLAG values.

Returns

None

UPDATE_SCHEDULE_ENTRY_NAME

New in 4.3.0.

Parameters

ENTRY_INDEX — required; zero-based index of the schedule entry within each day.
NEW_NAME — required; the replacement name to apply to the entry.

Notes

This command applies to all days in the week at the specified ENTRY_INDEX.
It does not use DAY_INDEX; the proxy loops through every day and updates each matching entry.
The target index must be valid for the thermostat’s GetEntriesPerDay() range.
Before renaming any day, the proxy validates every day in the week. If any entry at that index is not re-nameable, the command is rejected and no rename is applied.

Proxy behavior after completion

The proxy checks that the schedule exists and that ENTRY_INDEX is in range.
It verifies that NEW_NAME is present.
It then loops through all 7 days and calls SetEntryName(newName) on each matching entry that is allowed to be renamed.
For each day, it sends the update to the protocol driver using the per-day DAY_INDEX, ENTRY_INDEX, and ENTRY_NAME values.

Command sent to the protocol driver

UPDATE_SCHEDULE_ENTRY_NAME
Payload includes:
- DAY_INDEX
- ENTRY_INDEX
- ENTRY_NAME

This is sent once per affected day, not as a single all-days command.

Returns

None

Thermostat Proxy Variables

Hidden: false

Updated by: TEMPERATURE_CHANGED notification