Vos consoles Alexa
Se connecter
Se connecter
Merci de votre visite. Cette page est disponible en anglais uniquement.

Alexa.ThermostatController Interface

A thermostat is a device that senses temperature and attempts to keep that temperature reading close to a setpoint, or within a specified temperature range. The Alexa.ThermostatController interface describes the messages that are used to control or query thermostats using up to three setpoints, set or query thermostat mode, resume a programmed thermostat schedule.

For the list of locales that are supported for the ThermostatController interface, see List of Capability Interfaces and Supported Locales.

Utterances

When you use the Alexa.ThermostatController interface, the voice interaction model is already built for you. The following examples show some customer utterances:

Alexa, set thermostat to 20.
Alexa, set the AC to 75.
Alexa, set the AC to 25 degrees for 4 hours.
Alexa, make it warmer in here.
Alexa, make it cooler in here.
Alexa, make it warmer in here until 10 PM.
Alexa, set thermostat to automatic.
Alexa, turn off the heat until 8 PM.
Alexa, resume thermostat schedule.

After the customer says one of these utterances, Alexa sends a corresponding directive to your skill.

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. This property indicates whether the system controlled by the thermostat is on, if it's heating or cooling mode, or in an automatic or economical mode. For more information, see ThermostatMode.

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.

Hold duration scheduling

A thermostat can optionally support hold durations, meaning users can request a time limit be applied to their control requests such as "Alexa set the AC to 72 for 4 hours".
You indicate an endpoint's support for hold scheduling with a configuration object in the discovery response for the endpoint. Then, when your endpoint receives a control directive that includes a schedule object, you apply the request immediately for the duration specified.

Currently customer requests to set a temperature or temperature mode at a future time (Example: "Alexa, at 4 pm, set the heat to 68") are not supported.

Discovery

Thermostats can support up to three setpoints, a temperature mode and duration hold scheduling. You indicate the properties that a thermostat supports in your discovery response, and you can optionally include a configuration object to indicate whether a thermostat supports scheduling, and a list of supported thermostat modes for the thermostat. For more information, see properties.

When you provide a discovery response, you should include a configuration object that contains the fields described in the following table.

Property Description Type Required
supportsScheduling True to indicate that you can send this endpoint schedule objects in a control request; otherwise false. Boolean No
supportedModes Specifies the temperature modes supported for this endpoint. An array of ThermostatMode Values. No

If the endpoint description does not contain a configuration object or the configuration doesn't contain a supportsScheduling field, it is assumed that the thermostat does not support scheduling and control requests will not include scheduling information.

The following code example shows how you might describe a HVAC device that enables triple setpoints, and three thermostat modes, which are reported in the configuration object. In this example, the endpoint does not support scheduling.

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": "ff746d98-ab02-4c9e-9d0d-b44711658414"
    },
    "payload": {
      "endpoints": [{
        "endpointId": "uniqueIdOfThermostatEndpoint",
        "manufacturerName": "the manufacturer name of the endpoint",
        "friendlyName": "Thermostat",
        "description": "a description that is shown to the customer",
        "displayCategories": [
          "THERMOSTAT"
        ],
        "cookie": {
          "key1": "arbitrary key/value pairs for skill to reference this endpoint.",
          "key2": "There can be multiple entries",
          "key3": "but they should only be used for reference purposes.",
          "key4": "This is not a suitable place to maintain current endpoint state."
        },
        "capabilities": [{
            "type": "AlexaInterface",
            "interface": "Alexa.ThermostatController",
            "version": "3",
            "properties": {
              "supported": [{
                  "name": "targetSetpoint"
                },
                {
                  "name": "lowerSetpoint"
                },
                {
                  "name": "upperSetpoint"
                },
                {
                  "name": "thermostatMode"
                }
              ],
              "proactivelyReported": true,
              "retrievable": true
            },
            "configuration": {
              "supportsScheduling": false,
              "supportedModes": [
                "HEAT",
                "COOL",
                "AUTO"
              ]
            }
          },
          {
            "type": "AlexaInterface",
            "interface": "Alexa.TemperatureSensor",
            "version": "3"
          }
        ]
      }]
    }
  }
 }

Directives

SetTargetTemperature directive

Use the SetTargetTemperature directive to set the temperature of an endpoint. You can include a schedule that specifies the duration of the new setting. A customer can set a single temperature by voice, and one, two, or three temperatures by using the Alexa app.

Sample customer utterances:

User: Alexa, set bedroom thermostat to 20
User: Alexa, set living room air conditioner to 75
User: Alexa, set the kitchen AC to 25 degrees for 4 hours.

SetTargetTemperature payload details

Field Description Type Required
targetSetpoint Indicates the target temperature to set on the device. Sent for single and triple mode thermostats. Temperature 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 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 Yes, for dual and triple mode temperature modes.
schedule Indicates the scheduling parameters for the temperature change. The temperature change should be applied immediately and persist for the specified duration. A TimeInterval that contains start and duration fields. The start value is always the current time and the duration value is the customer-requested duration. No

SetTargetTemperature directive 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"
      }
    }
  }
}

SetTargetTemperature directive example (single set point with a schedule)

{
  "directive": {
    "header": {
      "namespace": "Alexa.ThermostatController",
      "name": "SetTargetTemperature",
      "messageId": "[MessageID]",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "access-token-from-skill"
      },
      "endpointId": "appliance-001",
      "cookie": {}
    },
    "payload": {
      "targetSetpoint": {
        "value": 25.0,
        "scale": "CELSIUS"
      },
      "schedule": {
        "start": "2017-06-22T21:35Z",
        "duration": "PT25M"
      }
    }
  }
}

SetTargetTemperature directive 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"
      }
    }
  }
}

SetTargetTemperature directive 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"
      }
    }
  }
}

AdjustTargetTemperature directive

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

Sample customer utterances:

User: Alexa, make it warmer in here
User: Alexa, make it cooler in here

AdjustTargetTemperature directive payload details

Field Description Type Required
targetSetpointDelta Indicates the temperature adjustment value and scale for the value for a single setpoint. Positive and negative temperature values indicate a directive to increase or decrease the target setpoint, respectively. Temperature Yes

AdjustTargetTemperature directive example (decrease 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"
      }
    }
  }
}

SetThermostatMode directive

A request to set the mode for the thermostat to a specified value. The customer must say Alexa, set customer thermostat device name to available mode.

Sample customer utterances:

User: Alexa, set living room thermostat to automatic

SetThermostatMode directive payload details

Field Description Type Required
thermostatMode Indicates the thermostat mode for the device. A ThermostatMode Object. Yes

SetThermostatMode directive example

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

ResumeSchedule directive

A request to resume a thermostat's programmed heating or cooling schedule.

Sample customer utterances:

User: Alexa, resume living room thermostat schedule

ResumeSchedule directive payload details

Field Description Type Required
None No required or optional fields in the payload. N/A N/A

ResumeSchedule directive example

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

Responses

If you handle a directive successfully, respond with a Response event. For this capability, you must reply synchronously, which means you send a response to Alexa from the Lambda function.

Response properties

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

Property Name Type Description
targetSetpoint Temperature The target temperature setpoint, which is used for single and triple mode thermostat values.
lowerSetpoint Temperature The lower temperature threshold, which is used for reporting dual and triple mode thermostat values.
upperSetpoint Temperature The upper temperature threshold, which is used for reporting dual and triple mode thermostat values.
thermostatMode ThermostatMode The thermostat mode, such as COOL or HEAT. For more information, see ThermostatMode Values.

Response examples

Response example for single setpoint and HEAT mode

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

Response example for dual setpoint and AUTO mode

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

Response example for triple setpoint and AUTO mode

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

Error Handling

If an error occurs, respond with an ErrorResponse event. For more information, see Alexa.ErrorResponse Interface.

Error response payload details

Payload.Type value Description Additional Payload
TEMPERATURE_VALUE_OUT_OF_RANGE Indicates temperature value is outside the allowable range. This error is in the Alexa namespace. For more information, see Example TEMPERATURE_VALUE_OUT_OF_RANGE error. A validRange object that contains two Temperature objects named minimumValue and maximumValue, that indicate the minimum and maximum temperature settings for the thermostat.
REQUESTED_SETPOINTS_TOO_CLOSE Setpoints are too close together. For more information, see the REQUESTED_SETPOINTS_TOO_CLOSE. A Temperature object named minimumTemperatureDelta that indicates the minimum allowable difference between setpoints.
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_SCHEDULE You cannot set the requested schedule. None
UNWILLING_TO_SET_VALUE You cannot set the value because it may cause damage to the device or appliance. None

Error response example when the thermostat is off

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

Error response example when the set points are too close together

{
  "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.