Build Smart Home Skills for Thermostats and HVAC Devices

Smart home skills created for heating, ventilation and air conditioning (HVAC) devices give customers voice access to their thermostats, furnaces, air conditioners and fans. For example, a customer can say, "Alexa, turn up the heat" and the thermostat setting will increase. These skills also enables customers to see the status of their cloud-connected HVAC devices in the Alexa app.

This document provides a overview of concepts you should understand when building skills for HVAC devices as well as the interfaces and error messages you should be familiar with.

To create a smart home skill, you provide configuration information in the Amazon Developer Portal and code, which is hosted as an AWS Lambda function (an Amazon Web Services offering). The skill responds to directives from Alexa, and communicates with connected devices (called endpoints), such as a thermostat and sends response events back to the Alexa.

You should be familiar with the steps to create a smart home skill. For more information see:

Setpoints, temperatures and thermostat mode

Alexa supports HVAC devices with one, two or three temperature settings and a temperature mode setting. When you describe thermostat endpoints you will describe the number of temperature settings they support as setpoints.

  • Single setpoints thermostats: This type of thermostat provides a single temperature setting that the thermostat tries to maintain. For example, a thermostat with a single setpoint turn-on a furnace when the temperature falls below the setpoint, and turn it off when the temperature rises above that setpoint. These types of thermostats can be controlled with Alexa through voice or the Alexa app.

  • Dual setpoints thermostats: This type of thermostat provides 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. Customers can get the current settings of these types of thermostats from Alexa using the Alexa app.

  • Triple setpoint thermostats: This type of thermostat provides three temperature settings; a target setpoint along with lower and upper sets. Triple setpoint thermostats typically cannot be controlled via voice with Alexa. Customers can get the current settings of these types of thermostats from Alexa using the Alexa app.

  • Temperatures: You should always report temperatures in the same scale as the device, meaning if the device is set to Celsius you should report temperatures in Celsius. Likewise, if the device is set to Fahrenheit, you should report temperatures to Alexa in Fahrenheit.

  • Thermostat mode The mode of a thermostat influences the behavior of the endpoint, and how many setpoints are allowed. Some modes allow one setpoint and other modes allow two or three. For example, a thermostat controlling an HVAC system may support one setpoint in HEAT and COOL modes, but supports two setpoints in AUTO and ECO modes.

For more examples of the different types of thermostats, see ThermostatController.

Hold duration scheduling

Alexa also supports customer requests to hold a temperature for a period of time. For example, a customer can ask, "Alexa, make it warmer in here until 10 pm." and Alexa sends a directive that contains the temperature change and how long the temperature change should be applied.

If your endpoint supports hold duration scheduling, you should indicate this in the configuration object of the discovery response.

Choose capabilities

To act on customer requests to report or change thermostat device settings, or control a fan, you will need to choose the correct capabilities. Capability interfaces that describe HVAC device capabilities are described in the following table.

Operation(s) Capability Interface
Change a temperature setting, apply a temperature hold, resume programmed schedule, or provide the current settings Alexa.ThermostatController
Respond to requests for the current temperature Alexa.TemperatureSensor
Turn a fan on or off or control its speed. Alexa.PowerController, Alexa.PercentageController

Identify an HVAC endpoint

Alexa initially sends a discovery request when your skill is enabled and you describe an HVAC endpoint in the response. You provide the capabilities associated with the endpoint, and properties that you support for each capability. For an endpoint that provides thermostat control, you can optionally provide configuration to specify temperature modes and whether the endpoint supports hold scheduling. Also, because thermostats can support up to three setpoints, you describe these in a discovery response with targetSetpoint, lowerSetpoint and upperSetpoint. For more details about thermostat discovery, see the Discovery section of ThermostatController.

You also should identify the displayCategory, which enables an HVAC endpoint to display properly in the Alexa app. This could be one of the following for HVAC devices:

  • TEMPERATURE_SENSOR - Indicates an endpoint that reports/senses the temperature only
  • THERMOSTAT - Indicates endpoints that control temperature, stand-alone air conditioners, or heaters with direct temperature control.

For an endpoint that can control temperature settings and sense temperatures, you should set the display category like the following:

"displayCategories":["THERMOSTAT", "TEMPERATURE_SENSOR" ]

The following code example shows how you might describe a HVAC device that enables triple setpoints, several thermostat modes and hold duration scheduling.

For more information about 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
            },
            "configuration": {
              "supportsScheduling": true,
              "supportedModes": [
                "HEAT",
                "COOL",
                "AUTO"
              ]
            }
          },

          {
            "type": "AlexaInterface",
            "interface": "Alexa.TemperatureSensor",
            "version": "3",
            "properties": {
              "supported": [{
                "name": "temperature"
              }],
              "proactivelyReported": true,
              "retrievable": true
            }
          }
        ]
      }]
    }
  }
}

Report errors

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

Scenario Error message type Notes
Directive contains value out of the allowable range for the thermostat TEMPERATURE_VALUE_OUT_OF_RANGE This error is in the Alexa namespace and should contain a validRange object that contains two Temperature objects; minimumValue and maximumValue, which indicate the minimum and maximum temperature settings for the thermostat.
Directive contains setpoints that are too close together and cannot be used. REQUESTED_SETPOINTS_TOO_CLOSE 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 and cannot be turned on. THERMOSTAT_IS_OFF Defined in the Alexa.ThermostatController namespace
Directive requests a mode not supported by this endpoint. UNSUPPORTED_THERMOSTAT_MODE Defined in the Alexa.ThermostatController namespace
The endpoint does not support dual setpoints in the current mode. DUAL_SETPOINTS_UNSUPPORTED Defined in the Alexa.ThermostatController namespace
The thermostat doesn't support triple setpoints in the current mode. TRIPLE_SETPOINTS_UNSUPPORTED Defined in the Alexa.ThermostatController namespace
You cannot set the requested schedule. UNWILLING_TO_SET_SCHEDULE Defined in the Alexa.ThermostatController namespace
You cannot set the value because it may cause damage to the device or appliance. UNWILLING_TO_SET_VALUE Defined in the Alexa.ThermostatController namespace

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"
      }
    }
  }
}
Amazon Alexa
Amazon Appstore
Amazon Web Services
Amazon Dash Replenishment