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.
- Setpoints, temperatures and thermostat mode
- Hold duration scheduling
- Choose capabilities
- Identify an HVAC endpoint
- Report errors
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"
}
}
}
}