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.


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.

Back To Top