Vos consoles Alexa
Se connecter
Se connecter
Merci de votre visite. Cette page est disponible en anglais uniquement. Nous travaillons actuellement sur la version française. Merci de votre compréhension.

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 that are used to:

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 for thermostat endpoints

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.

Endpoint configuration

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

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

  • English, all locales
  • French (FR)
  • German
  • Italian
  • Spanish (ES)

See [Develop Smart Home Skills in Multiple Languages][develop-smart-home-skills-in-multiple-languages#decide-languages] for more information.

SetTargetTemperature

A request to set the temperature of an endpoint, which optionally includes a schedule object that specifies the duration of the new setting. A customer can make a request to set a single temperature by voice, and two or three temperatures with the Alexa app.

For example:

User: Alexa, set thermostat to 20
User: Alexa, set the AC to 75

Example with a schedule:

User: Alexa, set the AC to 25 degrees for 4 hours.

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 single setpoint 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"
      }
    }
  }
}

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

AdjustTargetTemperature

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

User: Alexa, make it warmer in here
User: 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 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

SetThermostatMode

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

User: Alexa, set thermostat name to mode
User: Alexa, set thermostat to automatic

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 AUTO

This examples sets the thermostat mode to AUTO.

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

Payload details

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

ResumeSchedule

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

User: Alexa, resume thermostat schedule

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

Payload details

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

Properties and Events

For this capability, 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 the interface properties in the context of the message.

Properties

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

If a request completes successfully, you send a Response event that indicates the setpoints and the current thermostatMode value.

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. For more information, see Alexa.ErrorResponse Interface.

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

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.