Smart Home Thermostat Guide
action.devices.types.THERMOSTAT
- Thermostats are temperature-managing devices, with set points and modes. This separates them from heaters and AC units which may only have modes and settings (for example, high/low) vs a temperature target.
This type indicates that the device gets the Thermostat icon and some related synonyms and aliases.
Devices of this type control temperature, whereas some heating/cooling room units have different controls and high/low modes, but not temperature controls.Device capabilities
Refer to the corresponding trait documentation for implementation details, such as attributes and states that your service should support, and how to build EXECUTE and QUERY responses.
Required traits
These traits and commands are required, if applicable to your
device. If your device does not support these traits, enter the error code of
functionNotSupported
in a QUERY or EXECUTE response. See
Errors and exceptions for more info.
Thermostat commands are frequently chained in EXECUTE
intents. A user who
says *Set the heat to 72* will generate a mode command followed by a temperature set.
Quality requirements
- Latency: must be less than or equal to 700ms.
- Reliability: must be more than or equal to 97%.
Example device: Simple thermostat
This section contains example intent payloads representing a common "Thermostat" based on the device type and traits above. If you add or remove traits in your implementation, modify your responses accordingly to reflect those changes.
Sample SYNC response
{ "requestId": "6894439706274654512", "inputs": [ { "intent": "action.devices.SYNC" } ] }
{ "requestId": "6894439706274654512", "payload": { "agentUserId": "user123", "devices": [ { "id": "123", "type": "action.devices.types.THERMOSTAT", "traits": [ "action.devices.traits.TemperatureSetting" ], "name": { "name": "Simple thermostat" }, "willReportState": true, "attributes": { "availableThermostatModes": [ "off", "heat", "cool", "heatcool", "on" ], "thermostatTemperatureRange": { "minThresholdCelsius": 15, "maxThresholdCelsius": 30 }, "thermostatTemperatureUnit": "F" }, "deviceInfo": { "manufacturer": "smart-home-inc", "model": "hs1234", "hwVersion": "3.2", "swVersion": "11.4" } } ] } }
Sample QUERY response
{ "requestId": "6894439706274654514", "inputs": [ { "intent": "action.devices.QUERY", "payload": { "devices": [ { "id": "123" } ] } } ] }
{ "requestId": "6894439706274654514", "payload": { "devices": { "123": { "status": "SUCCESS", "online": true, "thermostatMode": "cool", "thermostatTemperatureSetpoint": 23, "thermostatTemperatureAmbient": 25.1, "thermostatHumidityAmbient": 45.3 } } } }
Sample EXECUTE commands
ThermostatTemperatureSetpoint
For additional details on the command parameters,
see the
action.devices.traits.TemperatureSetting
reference.
{ "requestId": "6894439706274654516", "inputs": [ { "intent": "action.devices.EXECUTE", "payload": { "commands": [ { "devices": [ { "id": "123" } ], "execution": [ { "command": "action.devices.commands.ThermostatTemperatureSetpoint", "params": { "thermostatTemperatureSetpoint": 22 } } ] } ] } } ] }
{ "requestId": "6894439706274654516", "payload": { "commands": [ { "ids": [ "123" ], "status": "SUCCESS", "states": { "online": true, "thermostatMode": "cool", "thermostatTemperatureSetpoint": 22, "thermostatTemperatureAmbient": 25.1 } } ] } }
ThermostatTemperatureSetRange
For additional details on the command parameters,
see the
action.devices.traits.TemperatureSetting
reference.
{ "requestId": "6894439706274654518", "inputs": [ { "intent": "action.devices.EXECUTE", "payload": { "commands": [ { "devices": [ { "id": "123" } ], "execution": [ { "command": "action.devices.commands.ThermostatTemperatureSetRange", "params": { "thermostatTemperatureSetpointHigh": 26, "thermostatTemperatureSetpointLow": 22 } } ] } ] } } ] }
{ "requestId": "6894439706274654518", "payload": { "commands": [ { "ids": [ "123" ], "status": "SUCCESS", "states": { "online": true, "thermostatMode": "heatcool", "thermostatTemperatureSetpointHigh": 26, "thermostatTemperatureSetpointLow": 22, "thermostatTemperatureAmbient": 25.1 } } ] } }
ThermostatSetMode
For additional details on the command parameters,
see the
action.devices.traits.TemperatureSetting
reference.
{ "requestId": "6894439706274654520", "inputs": [ { "intent": "action.devices.EXECUTE", "payload": { "commands": [ { "devices": [ { "id": "123" } ], "execution": [ { "command": "action.devices.commands.ThermostatSetMode", "params": { "thermostatMode": "heatcool" } } ] } ] } } ] }
{ "requestId": "6894439706274654520", "payload": { "commands": [ { "ids": [ "123" ], "status": "SUCCESS", "states": { "online": true, "thermostatMode": "heatcool", "thermostatTemperatureSetpointHigh": 26, "thermostatTemperatureSetpointLow": 22, "thermostatTemperatureAmbient": 25.1 } } ] } }
Device ERRORS
See the full list of errors and exceptions.inHeatOrCool
- Heat/Cool/Range commands failed because device is in explicit heat or cool.inHeatCool
- Heat or Cool commands failed because device is in heat or cool.lockedToRange
- Device is locked to a temperature range or mode, and the requested change can't be made.rangeTooClose
- Temperature points on a heatcool range are too close to each other.