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

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.

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

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

  • English (Canada)
  • English (UK)
  • English (US)
  • German

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

SetTargetTemperature

A request to set the temperature of an endpoint.

“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.

“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 in from the Lambda function.

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

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": {}
  }
}

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.