Your Alexa Dashboards

Your Alexa Dashboards Settings

Alexa.ThermostatController Interface

A thermostat is a device that senses temperature and attempts to keep that temperature reading close to a setpoint, and/or within a specified temperature range.

The Alexa.ThermostatController interface describes the messages used to control thermostats using up to three setpoints, and to control thermostat modes.

Thermostat setpoints
Thermostat mode
- Representing a thermostat mode in JSON
Discovery for thermostat endpoints
Directives
Properties and Events
Additional Sample Code
Related Interfaces

Thermostat setpoints

Alexa supports thermostats with one, two or three setpoints.

A thermostat with a single setpoint can be controlled through voice or with the Alexa app. Double and triple setpoints can be queried for their current settings.

Single setpoint thermostats

Single setpoint thermostats have a single temperature setting at which it will attempt to maintain a temperature. For example, a thermostat with a single setpoint may:

Turn-on a furnace when the temperature falls below the setpoint, and turn it off when the temperature rises above that setpoint
Turn-on an air-conditioner when the temperature rises above the setpoint, and turn it off when the temperature falls below that setpoint.
Turn-on a ceiling fan when the temperature rises above a single setpoint
Turn on a water heater when the temperature falls below the single setpoint

Dual setpoint thermostats

Dual setpoint thermostats have two temperature settings, a lower and upper setpoint. For example, a thermostat with dual setpoints may:

Automatically turn-on a furnace when the ambient temperature falls below the lower setpoint, and turn on an air-conditioner if it rises above upper setpoint
Automatically turn-on and off a heater to keep the ambient temperature within the temperature range specified by lower setpoint and upper setpoint
Automatically turn-on and off an air cooling system to keep the ambient temperature within the temperature range specified by lower setpoint and upper setpoint
Open a vent baffle when the ambient temperature is below lower setpoint and the vent temperature is above lower setpoint
Open a vent baffle when the ambient temperature is above upper setpoint and the vent temperature is below upper setpoint
Automatically direct a ceiling fan to blow upwards when the temperature drops below the lower setpoint, and blow downwards when the temperature rises above an upper setpoint
Use the lower and upper setpoints to control the heating elements in a dual-element water-heater, which uses less electricity to maintain a minimum temperature

Triple setpoint thermostats

Triple setpoint thermostats have three setpoints, a target setpoint along with lower and upper sets.

These are typically used by thermostats that maintain the temperature within the lower and upper temperature range, and close to the target setpoint.

Thermostat mode

The ThermostatController interface supports the control and reporting of a thermostat’s operational mode with the ThermostatMode property, which indicates whether the system controlled by the thermostat is on, and if it’s heating or cooling, or in an automatic or economical mode. Custom modes are also supported.

Thermostat mode is important because the number of allowable setpoints may depend on the thermostat mode. In some cases, a thermostat may only support one or two setpoints based on their current mode; not all combinations of each thermostat mode with single, dual, and triple setpoints are valid. For example, a thermostat controlling an HVAC system may support only single setpoints in HEAT and COOL modes, but support dual setpoints in AUTO and ECO modes.

Representing a thermostat mode in JSON

When you specify a thermostat mode in JSON, if the mode does not require a custom name, you can represent its value as a string. Example:

{
  "name": "thermostatMode",
  "value": "AUTO"
}

When a thermostat mode requires a custom name, you must represent its value as an object. Example:

{
  "name": "thermostatMode",
  "value": {
    "value": "CUSTOM",
    "customName": "VENDOR_HEAT_COOL"
  }
}

Discovery for thermostat endpoints

Thermostats can support up to three setpoints and a temperature mode. You describe these in a discovery response with targetSetpoint, lowerSetpoint, upperSetpoint and temperatureMode reportable properties.

The following code example shows how you might describe a HVAC device that enables triple setpoints. For more information on device discovery messages, see Alexa.Discovery

Example discovery response for an HVAC device

{
   "event":{
      "header":{
         "namespace":"Alexa.Discovery",
         "name":"Discover.Response",
         "payloadVersion":"3",
         "messageId":"5f8a426e-01e4-4cc9-8b79-65f8bd0fd8a4"
      },
      "payload":{
         "endpoints":[
            {
               "endpointId":"appliance-002",
               "friendlyName":"Hallway Thermostat",
               "description":"Smart Thermostat by Sample Manufacturer",
               "manufacturerName":"Sample Manufacturer",
               "displayCategories":[
                  "THERMOSTAT"
               ],
               "cookie":{

               },
               "capabilities":[
                  {
                     "type":"AlexaInterface",
                     "interface":"Alexa.ThermostatController",
                     "version":"3",
                     "properties":{
                        "supported":[
                           {
                              "name":"lowerSetpoint"
                           },
                           {
                              "name":"targetSetpoint"
                           },
                           {
                              "name":"upperSetpoint"
                           },
                           {
                              "name":"thermostatMode"
                           }
                        ],
                        "proactivelyReported":true,
                        "retrievable":true
                     }
                  },
                  {
                     "type":"AlexaInterface",
                     "interface":"Alexa.TemperatureSensor",
                     "version":"3",
                     "properties":{
                        "supported":[
                           {
                              "name":"temperature"
                           }
                        ],
                        "proactivelyReported":false,
                        "retrievable":true
                     }
                  }
               ]
            }
         ]
      }
   }
}

Directives

The control and query directives in this interface are supported in skills that target the following languages:

English (Australia)
English (Canada)
English (U.K.)
English (U.S.)
German

See Develop Smart Home Skills in Multiple Languages for more information.

SetTargetTemperature

A request to set the temperature of an endpoint. A customer can make a request to set a single temperature by voice, and two or three temperatures with the Alexa app.

“Alexa, set thermostat to 20”

Example single mode request:

{
  "directive": {
    "header": {
      "namespace": "Alexa.ThermostatController",
      "name": "SetTargetTemperature",
      "payloadVersion": "3",
      "messageId": "1bd5d003-31b9-476f-ad03-71d471922820",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "access-token-from-skill"
      },
      "endpointId": "appliance-001",
      "cookie": {}
    },
    "payload": {
      "targetSetpoint": {
        "value": 20.0,
        "scale": "CELSIUS"
      }
    }
  }
}

Example dual mode request:

{
  "directive": {
    "header": {
      "namespace": "Alexa.ThermostatController",
      "name": "SetTargetTemperature",
      "payloadVersion": "3",
      "messageId": "1bd5d003-31b9-476f-ad03-71d471922820",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "access-token-from-skill"
      },
      "endpointId": "appliance-001",
      "cookie": {}
    },
    "payload": {
      "lowerSetpoint": {
        "value": 68.0,
        "scale": "FAHRENHEIT"
      },
      "upperSetpoint": {
        "value": 78.0,
        "scale": "FAHRENHEIT"
      }
    }
  }
}

Example triple mode request:

{
  "directive": {
    "header": {
      "namespace": "Alexa.ThermostatController",
      "name": "SetTargetTemperature",
      "payloadVersion": "3",
      "messageId": "1bd5d003-31b9-476f-ad03-71d471922820",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "access-token-from-skill"
      },
      "endpointId": "appliance-001",
      "cookie": {}
    },
    "payload": {
      "targetSetpoint": {
        "value": 73,
        "scale": "FAHRENHEIT"
      },
      "lowerSetpoint": {
        "value": 68.0,
        "scale": "FAHRENHEIT"
      },
      "upperSetpoint": {
        "value": 78.0,
        "scale": "FAHRENHEIT"
      }
    }
  }
}

Payload details

Field	Description	Type	Required
`targetSetpoint`	Indicates the target temperature to set on the device. Sent for single and triple mode thermostats.	Temperature object	Yes, for single and triple-mode temperature modes.
`lowerSetpoint`	Indicates the lower temperature setpoint for the device. temperature. Sent for dual and triple setpoint temperature modes.	Temperature object	Yes, for dual and triple mode temperature modes.
`upperSetpoint`	Indicates the upper temperature setpoint for the device. Sent for dual and triple setpoint temperature modes	Temperature object	Yes, for dual and triple mode temperature modes.
`temperature.value`	A floating point number that indicates the temperature to set for the endpoint.	number	Yes
`temperature.scale`	Indicates the temperature scale for the temperature value. Supported values: “CELSIUS”, “FAHRENHEIT” or “KELVIN”	string	Yes

AdjustTargetTemperature

A request to adjust the temperature of an endpoint up or down.

“Alexa, make it warmer in here”

“Alexa, make it cooler in here”

Example Request to Increase the Temperature:

{
  "directive": {
    "header": {
      "namespace": "Alexa.ThermostatController",
      "name": "AdjustTargetTemperature",
      "payloadVersion": "3",
      "messageId": "1bd5d003-31b9-476f-ad03-71d471922820",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "access-token-from-skill"
      },
      "endpointId": "appliance-001",
      "cookie": {}
    },
    "payload": {
      "targetSetpointDelta": {
        "value": 2.0,
        "scale": "FAHRENHEIT"
      }
    }
  }
}

Example request to decrease the temperature:

{
  "directive": {
    "header": {
      "namespace": "Alexa.ThermostatController",
      "name": "AdjustTargetTemperature",
      "payloadVersion": "3",
      "messageId": "1bd5d003-31b9-476f-ad03-71d471922820",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "access-token-from-skill"
      },
      "endpointId": "appliance-001",
      "cookie": {}
    },
    "payload": {
      "targetSetpointDelta": {
        "value": -2.0,
        "scale": "FAHRENHEIT"
      }
    }
  }
}

Payload details

Field	Description	Type	Required
`targetSetpointDelta`	Indicates the temperature adjustment value to a single setpoint. Positive and negative temperature values indicate a directive to increase or decrease the target setpoint, respectively.	Temperature object	Yes
`targetSetpointDelta.value`	A signed floating point number that indicates the change in temperature.	number	Yes
`targetSetpointDelta.scale`	Indicates the temperature scale. Supported values: “CELSIUS”, “FAHRENHEIT” or “KELVIN”	string	Yes

SetThermostatMode

A request to set the mode for the thermostat to a specified or custom value.

Note: Note that the format of customer utterances for this directive are currently very specific. Make sure this format is reflected in your skill long description and example phrases.

“Alexa, set thermostat name to mode”

“Alexa, set thermostat to automatic”

“Alexa, set kitchen to off”

Example Request to Set Mode to COOL

{
  "directive": {
    "header": {
      "namespace": "Alexa.ThermostatController",
      "name": "SetThermostatMode",
      "payloadVersion": "3",
      "messageId": "1bd5d003-31b9-476f-ad03-71d471922820",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "access-token-from-skill"
      },
      "endpointId": "appliance-001",
      "cookie": {}
    },
    "payload": {
      "thermostatMode" : {
        "value": "COOL"
      }
    }
  }
}

Example Request to Set Mode to OFF

This example shows a directive that sets the thermostat mode to OFF.

{
  "directive": {
    "header": {
      "namespace": "Alexa.ThermostatController",
      "name": "SetThermostatMode",
      "payloadVersion": "3",
      "messageId": "1bd5d003-31b9-476f-ad03-71d471922820",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "access-token-from-skill"
      },
      "endpointId": "appliance-001",
      "cookie": {}
    },
    "payload": {
      "thermostatMode": {
        "value": "OFF"
      }
    }
  }
}

Example Request to Set Mode to CUSTOM

This examples sets the thermostat mode to custom and also specifies the customName field.

{
  "directive": {
    "header": {
      "namespace": "Alexa.ThermostatController",
      "name": "SetThermostatMode",
      "payloadVersion": "3",
      "messageId": "1bd5d003-31b9-476f-ad03-71d471922820",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "access-token-from-skill"
      },
      "endpointId": "appliance-001",
      "cookie": {}
    },
    "payload": {
      "thermostatMode": {
        "value": "CUSTOM",
        "customName": "[A custom name registered with Alexa Smart Home]"
      }
    }
  }
}

Payload details

Field	Description	Type	Required
`thermostatMode`	Indicates the desired thermostat mode for the device. Supported values: “AUTO”, “COOL”, “ECO”, “HEAT” and “OFF”	ThermostatMode	Yes

Properties and Events

For this interface, you must reply:

Synchronously, which means you send a Response to Alexa from the Lambda function.

When you send a Response, you should include the state of reportable properties in the context of the message.

Note: Note that when you report a Temperature property, you should always report it in the same scale as the device. For example, if a thermostat is set to display the temperature in Fahrenheit (F), report the temperature scale as FAHRENHEIT.

Reportable Properties

Property Name	Type	Description
`targetSetpoint`	Temperature	Indicates one temperature setpoint, which is used for single and triple mode thermostat values.
`lowerSetpoint`	Temperature	Indicates the lower temperature threshold, which is used for reporting dual and triple mode thermostat values.
`upperSetpoint`	Temperature	Indicates the upper temperature threshold, which is used for reporting dual and triple mode thermostat values.
`thermostatMode`	ThermostatMode	Indicates the thermostat mode for the device. Supported values: “AUTO”, “COOL”, “ECO”, “HEAT” and “OFF”

Response

If a request completes successfully, you should send an Response event that indicates the setpoints and mode.

Single setpoint and HEAT mode example

{
  "context": {
    "properties": [ {
      "namespace": "Alexa.ThermostatController",
      "name": "targetSetpoint",
      "value": {
        "value": 25,
        "scale": "CELSIUS"
      },
      "timeOfSample": "2017-02-03T16:20:50.52Z",
      "uncertaintyInMilliseconds": 500
    }, {
      "namespace": "Alexa.ThermostatController",
      "name": "thermostatMode",
      "value": "HEAT",
      "timeOfSample": "2017-02-03T16:20:50.52Z",
      "uncertaintyInMilliseconds": 500
    } ]
  },
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "payloadVersion": "3",
      "messageId": "5f8a426e-01e4-4cc9-8b79-65f8bd0fd8a4",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
    },
    "endpoint": {
      "endpointId": "appliance-001"
    },
    "payload": {}
  }
}

Single setpoint and custom thermostat mode example

{
  "context": {
    "properties": [ {
      "namespace": "Alexa.ThermostatController",
      "name": "targetSetpoint",
      "value": {
        "value": 25,
        "scale": "CELSIUS"
      },
      "timeOfSample": "2017-02-03T16:20:50.52Z",
      "uncertaintyInMilliseconds": 500
    }, {
      "namespace": "Alexa.ThermostatController",
      "name": "thermostatMode",
      "value": {
         "value": "CUSTOM",
         "customName": "SOME_VENDOR_MODE"
       },
      "timeOfSample": "2017-02-03T16:20:50.52Z",
      "uncertaintyInMilliseconds": 500
    } ]
  },
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "payloadVersion": "3",
      "messageId": "5f8a426e-01e4-4cc9-8b79-65f8bd0fd8a4",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
    },
    "endpoint": {
      "endpointId": "appliance-001"
    },
    "payload": {}
  }
}

Dual setpoint and AUTO mode example

{
  "context": {
    "properties": [ {
      "namespace": "Alexa.ThermostatController",
      "name": "lowerSetpoint",
      "value": {
        "value": 68.0,
        "scale": "FAHRENHEIT"
      },
      "timeOfSample": "2017-02-03T16:20:50.52Z",
      "uncertaintyInMilliseconds": 500
    }, {
      "namespace": "Alexa.ThermostatController",
      "name": "upperSetpoint",
      "value": {
        "value": 74.0,
        "scale": "FAHRENHEIT"
      },
      "timeOfSample": "2017-02-03T16:20:50.52Z",
      "uncertaintyInMilliseconds": 500
    }, {
      "namespace": "Alexa.ThermostatController",
      "name": "thermostatMode",
      "value": "AUTO",
      "timeOfSample": "2017-02-03T16:20:50.52Z",
      "uncertaintyInMilliseconds": 500
    } ]
  },
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "payloadVersion": "3",
      "messageId": "5f8a426e-01e4-4cc9-8b79-65f8bd0fd8a4",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "access-token-from-Amazon"
      },
      "endpointId": "appliance-001"
    },
    "payload": {}
  }
}

Triple setpoint and AUTO mode example

{
  "context": {
    "properties": [ {
      "namespace": "Alexa.ThermostatController",
      "name": "lowerSetpoint",
      "value": {
        "value": 68.0,
        "scale": "FAHRENHEIT"
      },
      "timeOfSample": "2017-02-03T16:20:50.52Z",
      "uncertaintyInMilliseconds": 500
    }, {
      "namespace": "Alexa.ThermostatController",
      "name": "targetSetpoint",
      "value": {
        "value": 72.0,
        "scale": "FAHRENHEIT"
      },
      "timeOfSample": "2017-02-03T16:20:50.52Z",
      "uncertaintyInMilliseconds": 500
    }, {
      "namespace": "Alexa.ThermostatController",
      "name": "upperSetpoint",
      "value": {
        "value": 76.0,
        "scale": "FAHRENHEIT"
      },
      "timeOfSample": "2017-02-03T16:20:50.52Z",
      "uncertaintyInMilliseconds": 500
    }, {
      "namespace": "Alexa.ThermostatController",
      "name": "thermostatMode",
      "value": "AUTO",
      "timeOfSample": "2017-02-03T16:20:50.52Z",
      "uncertaintyInMilliseconds": 500
    } ]
  },
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "payloadVersion": "3",
      "messageId": "5f8a426e-01e4-4cc9-8b79-65f8bd0fd8a4",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "access-token-from-Amazon"
      },
      "endpointId": "appliance-001"
    },
    "payload": {}
  }
}

ErrorResponse

If an error occurs, return an error event. The following table lists the scenario and type of error to return.

Payload.Type value	Description	Additional Payload
TEMPERATURE_VALUE_OUT_OF_RANGE	Indicates temperature value is outside the allowable range. Note that this error is in the `Alexa` namespace.	A validRange object that contains two Temperature objects; `minimumValue` and `maximumValue`, which indicate the minimum and maximum temperature settings for the thermostat.
REQUESTED_SETPOINTS_TOO_CLOSE	Setpoints are too close together.	Requires a `minimumTemperatureDelta` field of type Temperature that indicates the minimum allowable difference between setpoints. See the REQUESTED_SETPOINTS_TOO_CLOSE example.
THERMOSTAT_IS_OFF	Thermostat is off and cannot be turned on.	None
UNSUPPORTED_THERMOSTAT_MODE	The thermostat doesn’t support the specified mode.	None
DUAL_SETPOINTS_UNSUPPORTED	The thermostat doesn’t support dual setpoints in the current mode.	None
TRIPLE_SETPOINTS_UNSUPPORTED	The thermostat doesn’t support triple setpoints in the current mode.	None
UNWILLING_TO_SET_VALUE	You cannot set the value because it may cause damage to the device or appliance.	None

THERMOSTAT_IS_OFF example

{
  "event": {
    "header": {
      "namespace": "Alexa.ThermostatController",
      "name": "ErrorResponse",
      "messageId": "d3c5828a-df17-4396-a64c-1a3bd172abbd",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
      "payloadVersion": "3"
    },
    "payload": {
      "type": "THERMOSTAT_IS_OFF",
      "message": "the thermostat is off, cannot turn on due to safety reasons"
    }
  }
}

REQUESTED_SETPOINTS_TOO_CLOSE example

{
  "event": {
    "header": {
      "namespace": "Alexa.ThermostatController",
      "name": "ErrorResponse",
      "messageId": "abc-123-def-456",
      "correlationToken": "abcdef-123456",
      "payloadVersion": "3"
    },
     "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "access-token-from-Amazon"
      },
      "endpointId": "appliance-001"
    },
    "payload": {
      "type": "REQUESTED_SETPOINTS_TOO_CLOSE",
      "message": "The requested setpoints are too close together",
      "minimumTemperatureDelta": {
          "value": 2.0,
          "scale": "CELSIUS"
      }
    }
  }
}

Additional Sample Code

See the sample request and response messages in the Alexa smart home GitHub repo:

ThermostatController

Interface	Description
Alexa.TemperatureSensor	Describes directives and events related to changing settings of a thermostat endpoint.

Alexa.ThermostatController Interface

Thermostat setpoints

Single setpoint thermostats

Dual setpoint thermostats

Triple setpoint thermostats

Thermostat mode

Representing a thermostat mode in JSON

Discovery for thermostat endpoints

Directives

SetTargetTemperature

AdjustTargetTemperature

SetThermostatMode

Properties and Events

Reportable Properties

Response

ErrorResponse

THERMOSTAT_IS_OFF example

REQUESTED_SETPOINTS_TOO_CLOSE example

Additional Sample Code

Related Interfaces