Set Hold
The set hold function sets the thermostat into a hold with the specified temperature. Creates a hold for the specified duration. Note that an event is created regardless of whether the program is in the same state as the requested state.
There is also support for creating a hold by passing a holdClimateRef request parameter/value pair to this function (See Event). When an existing and valid Climate.climateRef value is passed to this function, the coolHoldTemp, heatHoldTemp and fan mode from that Climate are used in the creation of the hold event. The values from that Climate will take precedence over any coolHoldTemp, heatHoldTemp and fan mode parameters passed into this function separately.
To resume from a hold and return to the program, use the ResumeProgram function.
Since Version: 1
Type: setHold
Hold Types
| Hold Type | Description |
|---|---|
| dateTime | Use the provided startDate, startTime, endDate and endTime for the event. If start date/time is not provided, it will be assumed to be right now. End date/time is required. |
| nextTransition | The end date/time will be set to the next climate transition in the program. |
| indefinite | The hold will not end and require to be cancelled explicitly. |
| holdHours | Use the value in the "holdHours" parameter to set the end date/time for the event. |
Hold types ease the calculation of end times for holds. You are always free to provide the startDate and startTime for the hold and it will be honoured, except where documented. The endDate and endTime depend on the hold type chosen. Default is indefinite.
Note that setting a hold when there is a currently active DemandResponse regardless of the holdType being used, will enforce that the hold endDate and endTime will inherit the endDate and endTime from that active DemandResponse.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| coolHoldTemp | Integer | yes | The temperature to set the cool hold at. |
| heatHoldTemp | Integer | yes | The temperature to set the heat hold at. |
| holdClimateRef | String | no | The Climate to use as reference for setting the coolHoldTemp, heatHoldTemp and fan settings for this hold. If this value is passed the coolHoldTemp and heatHoldTemp are not required. |
| startDate | String | no | The start date in thermostat time. |
| startTime | String | no | The start time in thermostat time. |
| endDate | String | no | The end date in thermostat time. |
| endTime | String | no | The end time in thermostat time. |
| holdType | Enum | no | The hold duration type. Valid values: dateTime, nextTransition, indefinite, holdHours. |
| holdHours | Integer | no | The number of hours to hold for, used and required if holdType='holdHours'. |
The SetHold function takes a full Event as its payload; all the required properties of the Event must be provided.
The two properties Event.isTemperatureAbsolute and Event.isTemperatureRelative indicate what type of temperature hold is being used. If both of these are false then the event is not using any temperature control, and thus it is a fan hold. This same logic applies when reading the running event off of a thermostat object.
Note: two properties Runtime.desiredCoolRange and Runtime.desiredHeatRange indicate the current valid temperature ranges. These fields should be queried before using the SetHold function in order to mitigate against the desired setpoints being adjusted by the server when the values are not within the valid ranges.
See Example 5: Creating a temperature hold for more information on how to create temperature holds.