Alexa.ThermostatController Interface 3

Implement the Alexa.ThermostatController interface in your Alexa skill so that users can control smart thermostats. A thermostat can control devices, such as furnaces, air conditioners, and water heaters. For details about Smart Home skills, see Understand Smart Home Skills.

A thermostat is a device that senses temperature, and attempts to keep the temperature at a specified setpoint or within a specified temperature range. You can use the ThermostatController interface for devices with up to two setpoints, different thermostat modes, and programmable thermostat schedules. Typically you use the ThermostatController interface with the Alexa.TemperatureSensor interface.

Implement the other Alexa.ThermostatController interfaces based on the features that your device supports:

For the list of languages that the ThermostatController interface supports, see List of Alexa Interfaces and Supported Languages. For the definitions of the message properties, see Alexa Interface Message and Property Reference.

Utterances

When you use the Alexa.ThermostatController interface, the Alexa service provides the voice interaction model for you. The following examples show some user utterances:

Alexa, set thermostat to twenty.
Alexa, set the AC to seventy-five.
Alexa, make it warmer in here.
Alexa, make it cooler in here.
Alexa, set thermostat to automatic.
Alexa, turn off the heat.
Alexa, resume thermostat schedule.
Alexa, what mode is my thermostat set to?

After the user says one of these utterances, Alexa sends a corresponding directive or report state request to your skill.

Thermostat setpoint types

Alexa supports thermostats with one or two setpoints.

Single-setpoint thermostats
A single-setpoint thermostat has a single temperature setting that it attempts to maintain. For example, a thermostat with a single setpoint might turn on the furnace when the temperature falls below the setpoint, and turn off the furnace when the temperature rises above the setpoint.
Dual-setpoint thermostats
A dual-setpoint thermostat has two temperature settings, a lower and upper setpoint. The thermostat maintains the temperature within the range between the setpoints.

A thermostat can support different setpoints when in different modes. For details, see Reportable properties.

Thermostat scheduling

If your device supports a user request to set the temperature or thermostat mode on a weekly schedule, implement the Alexa.ThermostatController.Schedule interface.

Reportable properties

The following table shows the properties that the Alexa.ThermostatController interface defines. You identify the properties that you support in your discovery response. All the properties are optional. Include only the properties that match the components of your thermostat device.

Property Description Type
targetSetpoint The thermostat should maintain the temperature at this setpoint. Single-setpoint thermostats use this property. Temperature
lowerSetpoint The thermostat should maintain the temperature above this setpoint. Dual-setpoint thermostats use this property. Temperature
upperSetpoint The thermostat should maintain the temperature below this setpoint. Dual-setpoint thermostats use this property. Temperature
thermostatMode The current mode of the thermostat. ThermostatMode

A thermostat can support different setpoints when in different modes. For example, a thermostat might support only a target setpoint when in HEAT or COOL mode, and support lower and upper setpoints when in AUTO or ECO mode.

Discovery

You describe endpoints that support Alexa.ThermostatController by using the standard discovery mechanism described in Alexa.Discovery.

Set retrievable to true for the properties that you report when Alexa sends your skill a state report request. Set proactivelyReported to true for the properties that you proactively report to Alexa in a change report.

Use THERMOSTAT for the display category. For the full list of display categories, see display categories.

Configuration object

In addition to the usual discovery response fields, for ThermostatController, include a configuration object that contains the following fields.

Field Description Type Required
supportedModes Modes that the device supports. Array of ThermostatMode strings. No
supportsScheduling Set to true if a user can specify a setpoint for an amount of time. For example, the user can set the temperature to 70 degrees for 30 minutes. The default is false. Boolean No

Discover response example

The following example shows a Discover.Response message for an Alexa skill that controls a thermostat and supports the Alexa.ThermostatController and Alexa.TemperatureSensor interfaces. In this example, the endpoint is a dual-setpoint thermostat, with three modes.

Discover response example for an air conditioner

Typically air conditioners support a single setpoint, and only have a cooling mode. Unlike thermostats, which are usually on all the time, users turn air conditioners on and off. For an air conditioner, Amazon recommends that you also implement the Alexa.PowerController interface, and keep the PowerController synchronized with the ThermostatController as shown in the following list:

  • When the thermostat controller mode is set to COOL, the power controller power state is set to ON.
  • When the thermostat controller mode is set to OFF, the power controller power state is set to OFF.

The following example shows a Discover.Response message for an Alexa skill that controls an air conditioner and supports the ThermostatController and Alexa.PowerController interfaces. The response includes the Alexa.TemperatureSensor interface for an air conditioner that displays the temperature.

Directives

Alexa sends the following Alexa.ThermostatController interface directives to your skill.

SetTargetTemperature directive

Support the SetTargetTemperature directive so that users can specify the temperature that they want a thermostat to maintain. The user can optionally specify the duration for the new temperature setting.

The following examples show user utterances:

Alexa, set bedroom thermostat to twenty.
Alexa, set living room air conditioner to seventy-five.
Alexa, set the kitchen AC to twenty-five degrees for four hours.

SetTargetTemperature directive example (single-setpoint thermostat)

The following example shows a SetTargetTemperature directive that Alexa sends to your skill.


{
  "directive": {
    "header": {
      "namespace": "Alexa.ThermostatController",
      "name": "SetTargetTemperature",
      "messageId": "Unique version 4 UUID",
      "correlationToken": "Opaque correlation token",
      "payloadVersion": "3.1"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2 bearer token"
      },
      "endpointId": "endpoint id",
      "cookie": {}
    },
    "payload": {
      "targetSetpoint": {
        "value": 20.0,
        "scale": "CELSIUS"
      }
    }
  }
}

SetTargetTemperature directive example (dual-setpoint thermostat)

The following example shows a SetTargetTemperature directive that Alexa sends to your skill for a dual-setpoint thermostat.

{
  "directive": {
    "header": {
      "namespace": "Alexa.ThermostatController",
      "name": "SetTargetTemperature",
      "messageId": "Unique version 4 UUID",
      "correlationToken": "Opaque correlation token",
      "payloadVersion": "3.1"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2 bearer token"
      },
      "endpointId": "endpoint id",
      "cookie": {}
    },
    "payload": {
      "lowerSetpoint": {
        "value": 68.0,
        "scale": "FAHRENHEIT"
      },
      "upperSetpoint": {
        "value": 72.0,
        "scale": "FAHRENHEIT"
      }
    }
  }
}

SetTargetTemperature directive payload

Field Description Type
targetSetpoint Thermostat should maintain the temperature at this setpoint. The directive includes this field for single-setpoint thermostats. Temperature object
lowerSetpoint Thermostat should maintain the temperature above this setpoint. The directive includes this field for dual-setpoint thermostats. Temperature object
upperSetpoint Thermostat should maintain the temperature below this setpoint. The directive includes this field for dual-setpoint thermostats. Temperature object
schedule Duration of time that the thermostat should maintain the specified setpoints. Apply the new setpoints immediately, for the duration specified. This field is included only if the user specifies it, and you indicated that you support it in your discovery response. TimeInterval object

SetTargetTemperature response

If you handle a SetTargetTemperature directive successfully, respond with an Alexa.Response event. In the context object, include the values of all relevant properties.

The following example shows a SetTargetTemperature response for a single-setpoint thermostat.

The following example shows a SetTargetTemperature response for a dual-setpoint thermostat.

SetTargetTemperature directive error handling

If you can't handle a SetTargetTemperature directive successfully, respond with an Alexa.ThermostatController.ErrorResponse event. You can also respond with a generic Alexa.ErrorResponse event if your error isn't specific to temperature or thermostats.

AdjustTargetTemperature directive

Support the AdjustTargetTemperature directive so that users can adjust the temperature that they want a thermostat to maintain.

The following examples show user utterances:

Alexa, make it warmer in here.
Alexa, make it cooler in here.

AdjustTargetTemperature directive example

The following example shows an AdjustTargetTemperature directive that Alexa sends to your skill.

{
  "directive": {
    "header": {
      "namespace": "Alexa.ThermostatController",
      "name": "AdjustTargetTemperature",
      "messageId": "Unique version 4 UUID",
      "correlationToken": "Opaque correlation token",
      "payloadVersion": "3.1"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2 bearer token"
      },
      "endpointId": "endpoint id",
      "cookie": {}
    },
    "payload": {
      "targetSetpointDelta": {
        "value": -2.0,
        "scale": "CELSIUS"
      }
    }
  }
}

AdjustTargetTemperature directive payload

Field Description Type
targetSetpointDelta Amount by which to change the temperature. The amount can be positive or negative. Temperature object

AdjustTargetTemperature response

If you handle an AdjustTargetTemperature directive successfully, respond with an Alexa.Response event. In the context object, include the values of all relevant properties.

The following example shows an AdjustTargetTemperature response for a single-setpoint thermostat.

Copied to clipboard.

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "messageId": "Unique identifier, preferably a version 4 UUID",
      "correlationToken": "Opaque correlation token that matches the request",
      "payloadVersion": "3"
    },
    "endpoint": {
      "endpointId": "endpoint id"
    },
    "payload": {}
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.ThermostatController",
        "name": "thermostatMode",
        "value": "HEAT",
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 500
      },
      {
        "namespace": "Alexa.ThermostatController",
        "name": "targetSetpoint",
        "value": {
          "value": 18.0,
          "scale": "CELSIUS"
        },
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 500
      },
      {
        "namespace": "Alexa.TemperatureSensor",
        "name": "temperature",
        "value": {
          "value": 20.0,
          "scale": "CELSIUS"
        },
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 1000
      }
    ]
  }
}

AdjustTargetTemperature directive error handling

If you can't handle an AdjustTargetTemperature directive successfully, respond with an Alexa.ThermostatController.ErrorResponse event. You can also respond with a generic Alexa.ErrorResponse event if your error isn't specific to temperature or thermostats.

SetThermostatMode directive

Support the SetThermostatMode directive so that users can set the mode of a device. The user must say, "Alexa, set the [user thermostat device name] to [available mode]."

SetThermostatMode directive example

The following example shows a SetThermostatMode directive that Alexa sends to your skill.

{
  "directive": {
    "header": {
      "namespace": "Alexa.ThermostatController",
      "name": "SetThermostatMode",
      "messageId": "Unique version 4 UUID",
      "correlationToken": "Opaque correlation token",
      "payloadVersion": "3.1"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2 bearer token"
      },
      "endpointId": "endpoint id",
      "cookie": {}
    },
    "payload": {
      "thermostatMode" : {
        "value": "COOL"
      }
    }
  }
}

SetThermostatMode directive payload

Field Description Type
thermostatMode Mode to set for the thermostat. ThermostatMode object

SetThermostatMode response event

If you handle a SetThermostatMode directive successfully, respond with an Alexa.Response event. In the context object, include the values of all relevant properties.

The following example shows a SetThermostatMode response.

Copied to clipboard.

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "messageId": "Unique identifier, preferably a version 4 UUID",
      "correlationToken": "Opaque correlation token that matches the request",
      "payloadVersion": "3"
    },
    "endpoint": {
      "endpointId": "endpoint id"
    },
    "payload": {}
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.ThermostatController",
        "name": "thermostatMode",
        "value": "COOL",
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 500
      },
      {
        "namespace": "Alexa.ThermostatController",
        "name": "targetSetpoint",
        "value": {
          "value": 17.0,
          "scale": "CELSIUS"
        },
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 500
      },
      {
        "namespace": "Alexa.TemperatureSensor",
        "name": "temperature",
        "value": {
          "value": 19.0,
          "scale": "CELSIUS"
        },
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 1000
      }
    ]
  }
}

SetThermostatMode directive error handling

If you can't handle a SetThermostatMode directive successfully, respond with an Alexa.ThermostatController.ErrorResponse event. You can also respond with a generic Alexa.ErrorResponse event if your error isn't specific to temperature or thermostats.

ResumeSchedule directive

Support the ResumeSchedule directive so that users can resume the programmed schedule of their thermostat after they overrode it. For example, a user might use the vacation override when they go away, and resume the normal program when they return.

ResumeSchedule directive example

The following example shows a ResumeSchedule directive that Alexa sends to your skill to resume the thermostat schedule.

{
  "directive": {
    "header": {
      "namespace": "Alexa.ThermostatController",
      "name": "ResumeSchedule",
      "messageId": "Unique version 4 UUID",
      "correlationToken": "Opaque correlation token",
      "payloadVersion": "3.1"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2 bearer token"
      },
      "endpointId": "endpoint id",
      "cookie": {}
    },
    "payload": {}
  }
}

ResumeSchedule directive payload

The ResumeSchedule directive doesn't define a payload.

ResumeSchedule response

If you handle a ResumeSchedule directive successfully, respond with an Alexa.Response event. In the context object, include the values of all relevant properties.

The following example shows a ResumeSchedule response.

Copied to clipboard.

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "messageId": "Unique identifier, preferably a version 4 UUID",
      "correlationToken": "Opaque correlation token that matches the request",
      "payloadVersion": "3"
    },
    "endpoint": {
      "endpointId": "endpoint id"
    },
    "payload": {}
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.ThermostatController",
        "name": "thermostatMode",
        "value": "HEAT",
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 500
      },
      {
        "namespace": "Alexa.ThermostatController",
        "name": "targetSetpoint",
        "value": {
          "value": 18.0,
          "scale": "CELSIUS"
        },
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 500
      },
      {
        "namespace": "Alexa.TemperatureSensor",
        "name": "temperature",
        "value": {
          "value": 17.9,
          "scale": "CELSIUS"
        },
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 1000
      }
    ]
  }
}

ResumeSchedule directive error handling

If you can't handle a ResumeSchedule directive successfully, respond with an Alexa.ThermostatController.ErrorResponse event. You can also respond with a generic Alexa.ErrorResponse event if your error isn't specific to temperature or thermostats.

State reporting

Alexa sends a ReportState directive to request information about the state of an endpoint. When Alexa sends a ReportState directive, you send a StateReport event in response. The response contains the current state of all retrievable properties in the context object. You identify your retrievable properties in your discovery response. For details about state reports, see Understand State and Change Reporting.

StateReport response example

The following example shows a StateReport response.

Copied to clipboard.

{
    "event": {
        "header": {
            "namespace": "Alexa",
            "name": "StateReport",
            "messageId": "Unique identifier, preferably a version 4 UUID",
            "correlationToken": "Opaque correlation token that matches the request",
            "payloadVersion": "3"
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "OAuth2 bearer token"
            },
            "endpointId": "endpoint id"
        },
        "payload": {}
    },
    "context": {
        "properties": [{
                "namespace": "Alexa.ThermostatController",
                "name": "thermostatMode",
                "value": "HEAT",
                "timeOfSample": "2017-02-03T16:20:50.52Z",
                "uncertaintyInMilliseconds": 500
            },
            {
                "namespace": "Alexa.ThermostatController",
                "name": "targetSetpoint",
                "value": {
                    "value": 20.0,
                    "scale": "CELSIUS"
                },
                "timeOfSample": "2017-02-03T16:20:50.52Z",
                "uncertaintyInMilliseconds": 500
            },
            {
                "namespace": "Alexa.TemperatureSensor",
                "name": "temperature",
                "value": {
                    "value": 19.9,
                    "scale": "CELSIUS"
                },
                "timeOfSample": "2017-02-03T16:20:50.52Z",
                "uncertaintyInMilliseconds": 1000
            },
            {
                "namespace": "Alexa.EndpointHealth",
                "name": "connectivity",
                "value": {
                    "value": "OK"
                },
                "timeOfSample": "2017-02-03T16:20:50.52Z",
                "uncertaintyInMilliseconds": 0
            }
        ]
    }
}

StateReport response example for an air conditioner

The following example shows a StateReport response for an air conditioner.

Copied to clipboard.

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "StateReport",
      "messageId": "Unique identifier, preferably a version 4 UUID",
      "correlationToken": "Opaque correlation token that matches the request",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2 bearer token"
      },
      "endpointId": "endpoint id"
    },
    "payload": {}
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.ThermostatController",
        "name": "thermostatMode",
        "value": "COOL",
        "timeOfSample": "2020-02-26T18:20:50Z",
        "uncertaintyInMilliseconds": 500
      },
      {
        "namespace": "Alexa.ThermostatController",
        "name": "targetSetpoint",
        "value": {
          "value": 20.0,
          "scale": "CELSIUS"
        },
        "timeOfSample": "2020-02-26T18:20:50Z",
        "uncertaintyInMilliseconds": 500
      },
      {
        "namespace": "Alexa.PowerController",
        "name": "powerState",
        "value": "ON",
        "timeOfSample": "2020-02-26T18:20:50Z",
        "uncertaintyInMilliseconds": 500
      },
      {
          "namespace": "Alexa.EndpointHealth",
          "name": "connectivity",
          "value": {
              "value": "OK"
          },
          "timeOfSample": "2020-02-26T18:20:50Z",
          "uncertaintyInMilliseconds": 0
      }
    ]
  }
}

Change reporting

You send a ChangeReport event to report changes proactively in the state of an endpoint. You identify the properties that you proactively report in your discovery response. For details about change reports, see Understand State and Change Reporting.

ChangeReport event example

The following example shows a ChangeReport event.

Copied to clipboard.

{  
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "ChangeReport",
      "messageId": "Unique identifier, preferably a version 4 UUID",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2.0 bearer token"
      },
      "endpointId": "endpoint id"
    },
    "payload": {
      "change": {
        "cause": {
          "type": "PHYSICAL_INTERACTION"
        },
        "properties": [
          {
            "namespace": "Alexa.ThermostatController",
            "name": "thermostatMode",
            "value": "COOL",
            "timeOfSample": "2020-02-26T18:20:50Z",
            "uncertaintyInMilliseconds": 500
          },
          {
            "namespace": "Alexa.ThermostatController",
            "name": "targetSetpoint",
            "value": {
              "value": 18.0,
              "scale": "CELSIUS"
            },
            "timeOfSample": "2020-02-26T18:20:50Z",
            "uncertaintyInMilliseconds": 500
          },
          {
            "namespace": "Alexa.TemperatureSensor",
            "name": "temperature",
            "value": {
              "value": 19.1,
              "scale": "CELSIUS"
            },
            "timeOfSample": "2020-02-26T18:20:50Z",
            "uncertaintyInMilliseconds": 1000
          }
        ]
      }
    }
  },
  "context": {
      "properties": [{
          "namespace": "Alexa.EndpointHealth",
          "name": "connectivity",
          "value": {
              "value": "OK"
          },
          "timeOfSample": "2020-02-26T18:20:50Z",
          "uncertaintyInMilliseconds": 0
      }]
  }
}

ChangeReport air conditioner example

The following example shows a ChangeReport event for an air conditioner.

Copied to clipboard.

{
    "event": {
        "header": {
            "namespace": "Alexa",
            "name": "ChangeReport",
            "messageId": "Unique identifier, preferably a version 4 UUID",
            "payloadVersion": "3"
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "OAuth2.0 bearer token"
            },
            "endpointId": "endpoint id"
        },
        "payload": {
            "change": {
                "cause": {
                    "type": "RULE_TRIGGER"
                },
                "properties": [{
                        "namespace": "Alexa.ThermostatController",
                        "name": "thermostatMode",
                        "value": "COOL",
                        "timeOfSample": "2020-02-26T18:20:50Z",
                        "uncertaintyInMilliseconds": 500
                    },
                    {
                        "namespace": "Alexa.ThermostatController",
                        "name": "targetSetpoint",
                        "value": {
                            "value": 18.0,
                            "scale": "CELSIUS"
                        },
                        "timeOfSample": "2020-02-26T18:20:50Z",
                        "uncertaintyInMilliseconds": 500
                    },
                    {
                        "namespace": "Alexa.TemperatureSensor",
                        "name": "temperature",
                        "value": {
                            "value": 19.1,
                            "scale": "CELSIUS"
                        },
                        "timeOfSample": "2020-02-26T18:20:50Z",
                        "uncertaintyInMilliseconds": 1000
                    }
                ]
            }
        }
    },
    "context": {
        "properties": [{
            "namespace": "Alexa.EndpointHealth",
            "name": "connectivity",
            "value": {
                "value": "OK"
            },
            "timeOfSample": "2020-02-26T18:20:50Z",
            "uncertaintyInMilliseconds": 0
        }]
    }
}

Requiring user verification

When a user attempts to set a temperature or change the thermostat mode, you can optionally require the user to verify the action before Alexa performs it. To require user verification, specify which directives you require verification for in your Discover.Response. For details, see the verificationsRequired object and example for a thermostat that requires user verification.

The following example shows a sample conversation when you require user verification:

Alexa, set the temperature to sixty-five degrees on the living room air conditioner.
Set living room air conditioner to sixty-five degrees?
Yes.
OK, living room air conditioner is set to sixty-five degrees.

アレクサ、リビングのエアコンを25度にして。
リビングのエアコンで、設定温度を25度にするんですね？
はい。
リビングのエアコンを冷房25度に設定しました。