Join the Actions on Google Developer Challenge to win a trip to Google I/O 2018 and more than 20 other prizes.

Smart Home Thermostat Schema

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 (e.g. high/low) vs a temperature target.

Home Automation commands are frequently chained in EXECUTION intents. A user who says 'set the heat to 72' will generate a mode command followed by a temperature set.

This schema is aimed at parity with our existing thermostat functionality. Once we've migrated everything to the new architecture, we'll add significantly more thermostat support logic.

Device TYPE

action.devices.types.THERMOSTAT -­­ this type indicates that the device gets the thermostat icon and some thermostat­type synonyms/aliases. Unlike the light/outlet/switch types, it's largely 1:1 with the TRAIT (since a plug might really be a light, etc, but thermostats are their own thing). Devices of type Thermostat control temperature, whereas some heating/cooling room units have different controls and high/low modes, but not temperature controls.

Device TRAITS

action.devices.traits.TemperatureSetting -­­ this trait covers handling both temperature point and modes.

Device ATTRIBUTES

Devices with traits TemperatureSetting must report the following attributes as part of SYNC:


Attribute Description
availableThermostatModes Comma­ separated list of modes supported by this specific device. Currently supporting specific known modes from the following list; more and custom ones will be added as needed. These modes all have local expansion aliases (off == 'standby', etc).
  • off - Heating/Cooling activity disabled
  • heat - If the device supports heat.
  • cool - If the device supports cooling.
  • on - If off, on restores the previous mode of the device.
  • heatcool - If the device supports maintaining heat/cool to target a range.
thermostatTemperatureUnit The unit the device is set to by default. We'll use the same for undeclared commands; this means that the device 'speaks' with its display unit. "C" or "F".

SYNC Sample

Request
{
    "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
    "inputs": [{
        "intent": "action.devices.SYNC",
    }]
}
Response
{
    "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
    "payload": {
        "agentUserId": "1836.15267389",
        "devices": [{
            "id": "123",
            "type": "action.devices.types.THERMOSTAT",
            "traits": [
                "action.devices.traits.TemperatureSetting"
            ],
            "name": {
                "defaultNames": ["X Co Thermostat 3000"], "name": "Brand X Thermostat",
                "nicknames": ["living room thermostat"]
            },
            "willReportState": true,
            "attributes": {
                "availableThermostatModes": "off,heat,cool,on",
                "thermostatTemperatureUnit": "F"
            },
            "deviceInfo": {
                "manufacturer": "BrandX",
                "model": "3000",
                "hwVersion": "3.7",
                "swVersion": "11.2"
            },
            "customData": {
                "fooValue": 74,
                "barValue": true,
                "bazValue": "lambtwirl"
            }
        }]
    }
}

Device STATES

thermostatMode Current mode of the device, with the same values as the Attribute
thermostatTemperatureSetpoint Current temperature set point (single target), in C.
thermostatTemperatureAmbient Current observe temperature, in C.
thermostatTemperatureSetpointHigh Current high point if in heatcool mode, for a range.
thermostatTemperatureSetpointLow Current low point if in heatcool mode, for a range.
thermostatHumidityAmbient If available from device; float, 0­100.

QUERY Sample

Request
{
    "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
    "inputs": [{
        "intent": "action.devices.QUERY",
        "payload": {
            "devices": [{
                "id": "123",
                "customData": {"fooValue": 74,
                "barValue": true,
                "bazValue": "lambtwirl"
                }
            }]
        }
    }]
}
Response
{
    "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", 
    "payload": {
        "devices": {
            "123": {
                "thermostatMode": "cool",
                "thermostatTemperatureSetpoint": 23.0,
                "thermostatTemperatureAmbient": 25.1
                "thermostatHumidityAmbient": 45.3
            }
        }
    }
}

Device COMMANDS

Command Properties/Definition
action.devices.commands.ThermostatTemperatureSetpoint thermostatTemperatureSetpoint - float (in speech we generally take 1 decimal point, for Celsius users).
action.devices.commands.ThermostatTemperatureSetRange
  • thermostatTemperatureSetpointHigh - floats. The high set point for a range.
  • thermostatTemperatureSetpointLow - floats. The low set point for a range.
action.devices.commands.ThermostatSetMode thermostatMode - One of the supported modes on the device.

EXECUTE Sample

Request
{
    "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", 
    "inputs": [{
        "intent": "action.devices.EXECUTE",
        "payload": {
            "commands": [{
                "devices": [{
                    "id": "123",
                    "customData": {
                        "fooValue": 74,
                        "barValue": true,
                        "bazValue": "lambtwirl"
                    }
                }],
                "execution": [{
                    "command": "action.devices.commands.ThermostatTemperatureSetpoint",
                    "params": {
                        "thermostatTemperatureSetpoint": 22.0
                    }
                }]
            }]
        }
    }]
}
Response
{
    "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
    "payload": {
        "commands": [{
            "ids": ["123"],
            "status": "SUCCESS",
            "states": {
                "thermostatMode": "cool",
                "thermostatTemperatureSetpoint": 22.0,
                "thermostatTemperatureAmbient": 25.1
                "thermostatHumidityAmbient": 43.2
            }
        }]
    }
}

Device ERRORS

Error Definition
inHeatOrCool HeatCool/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.