Alexa.ThermostatController.Configuration Interface 3

If your thermostat supports installation and setup in the Alexa app, implement the Alexa.ThermostatController.Configuration interface in your Alexa add-on. After the customer completes setup, Alexa sends the configuration details of the connected heating, ventilation, and air conditioning (HVAC) system to your add-on. You can use the configuration to update the thermostat settings. HVAC system configuration includes information, such as default temperature unit, fuel source, and terminal connections to the thermostat. Typically, you use the Alexa.ThermostatController.Configuration interface with the Alexa.ThermostatController and Alexa.TemperatureSensor interfaces. For the list of locales that the Alexa.ThermostatController.Configuration 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

The Alexa.ThermostatController.Configuration interface is different from other Alexa interfaces. Your add-on doesn’t support voice user interactions with Alexa directly. Instead, Alexa communicates with your add-on about HVAC configuration. This interface doesn’t have any user utterances.

Thermostat configuration

Thermostat configuration includes information about the connected HVAC systems.

Thermostat setup states

When the customer buys a thermostat, the device configuration is in factory default mode. The customer can use the Alexa app to configure the device based on their connected HVAC systems. After configuration is complete, the state changes to remote control, and then the customer can ask Alexa to perform an action on the thermostat. The following table shows the possible setup states.

State	Description
`FACTORY_DEFAULT`	The thermostat is in its original state, or the customer reset the device to factory default. A factory reset deletes any previous configuration stored on the device.
`DEVICE_CONTROL_ONLY`	The customer performed a partial reset. In this state, the thermostat can control the HVAC system, but the reset deletes any previous configuration stored on the device, except HVAC configuration. For example, a partial reset deletes account details, Wi-Fi credentials, schedules, and operating temperature range values.
`REMOTE_CONTROL`	The customer completed thermostat configuration and the thermostat is fully operational. Customers can define a schedule and control the thermostat remotely through the Alexa app or the device app.

HVAC system types

The following table shows the types HVAC systems that can connect to a thermostat.

Type	Description
CONVENTIONAL_STANDARD_GAS	Forced air heating system that uses natural gas. Valid for heating and auxiliary heating systems.
CONVENTIONAL_HIGH_EFFICIENCY_GAS	Highly efficient forced air heating system that uses natural gas. Valid for heating and auxiliary heating systems.
CONVENTIONAL_OIL	Forced air heating system that uses oil. Valid for heating and auxiliary heating systems.
CONVENTIONAL_ELECTRIC	Forced air heating system that uses electricity. Valid for heating and auxiliary heating systems.
CONVENTIONAL_HOT_WATER_FAN_COIL	Forced air heating system that uses hot water coils. Valid for heating and auxiliary heating systems.
AIR_TO_AIR_HEATPUMP	Heat pump that uses outside air as a heat source and indoor air as a heat sink. For cooling, the pump uses indoor air as a heat source and outdoor air as a heat sink. Valid for heating and cooling systems.
GEO_THERMAL_HEATPUMP	Heat pump that uses the ground temperature as a heat source and indoor air as a heat sink. For cooling, the pump uses indoor air as a heat source and ground temperature air as a heat sink. Valid for heating and cooling systems.
RADIANT_HOT_WATER	A heating system that circulates hot water through a series of pipes to heat the air. Valid for heating systems.
RADIANT_FAN_COIL	A heating and cooling system that uses fan coils. Valid for heating and cooling systems.
RADIANT_STEAM	A heating system that passes steam through radiators to heat the air. Valid for heating systems.
CENTRAL_AIR_CONDITIONING	A cooling system that uses a condenser unit and an air circulation system to cool the air. Valid for cooling systems.

Terminal purposes

Each terminal connection on the thermostat connects to an HVAC system for a specific purpose. The following table shows the terminal purposes and descriptions.

Purpose	Description
`AUXILIARY`	Controls the auxiliary or emergency heating or cooling system.
`COMMON`	Completes the 24-volt power circuit to power the thermostat.
`COOLING`	Controls the cooling system.
`DEHUMIDIFIER`	Controls the dehumidifier.
`FAN`	Controls the air circulation fan.
`HEATING`	Controls the heating system.
`HUMIDIFIER`	Controls the humidifier.
`OTHER`	Indicates a purpose specific to this thermostat or a purpose that isn’t well known.
`POWER`	Supplies power to the thermostat and to any actuated connected systems.
`SENSOR`	Used to read values from sensor. The sensors might be external to the thermostat.
`STATUS`	Indicates the status of the thermostat or the HVAC system. For example, a red light might turn on to indicate heating system failure.
`VALVE_CHANGE_OVER`	Controls system operation mode change between heating and cooling by reversing the valve on the heat pump.

Terminal names

The following table shows commonly used terminal names, the terminal purpose, and a description of the function of the connected wire. Some HVAC systems might have other terminal connections.

Terminal name	Terminal purpose	Description
`AUX`	`AUXILIARY`	Signals the secondary HVAC system when the primary system fails or can’t function in full capacity.
`O/B`	`VALVE_CHANGE_OVER`	For heat pumps, this wire signals cooling-to-heating and heating-to-cooling change.
`C`	`COMMON`	24-volt common wire that enables continuous power flow. This terminal is necessary to power the thermostat.
`DH` or `U`	`DEHUMIDIFIER`	Controls the dehumidifier to reduce humidity.
`E`	`AUXILIARY`	Turns on emergency heat mode.
`G` or `F`	`FAN`	Controls the blower fan for air circulation in the living space.
`H` or `U`	`HUMIDIFIER`	Controls the humidifier to increase humidity.
`K`	`OTHER`	Combines Y and F wires on some thermostats.
`L` or `A`	`STATUS`	Light terminal that indicates device operational status.
`R` or `V`	`POWER`	Powers the HVAC system. An HVAC system might have separate Rc and Rh terminals.
`Rc`	`POWER`	Power for the cooling system.
`Rh`	`POWER`	Power for the heating system.
`S1`, `S2`	`SENSOR`	Connections to outdoor temperature sensors.
`W`	`HEATING`	Connection to a single-stage heating system or to the first stage in a multi-stage heating system.
`W2`	`HEATING`	Connection to the second stage in a multi-stage heating system or to an auxiliary heating system.
`W3`	`HEATING`	Connection to the third stage in a multi-stage heating system or to the second stage in a multi-stage auxiliary system.
`Y`	`COOLING`	Connection to a single-stage cooling system or to the first stage in a multi-stage cooling system.
`Y2`	`COOLING`	Connection to the second stage in a multi-stage cooling system or to an auxiliary system.
`Y3`	`COOLING`	Connection to the third stage in a multi-stage cooling system.

Properties and objects

The Alexa.ThermostatController.Configuration interface includes the following properties and objects.

Reportable properties

The following table shows the properties that the Alexa.ThermostatController.Configuration 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
`setupState`	Current state of thermostat configuration. Before the customer can perform any action on the thermostat, Alexa must know the state of the thermostat setup.	String
`temperatureScale`	Current temperature scale configured on the thermostat.	String

ComponentConfigurationConstraints object

The ComponentConfigurationConstraints object defines the constraints that your thermostat device enforces during configuration. All fields are optional. Include only the constraints that apply.

Property	Description	Type	Required
`supportedTerminals`	List of terminals available on the thermostat. Don’t include this field if the thermostat can detect the terminals without input from the customer. This list defines the terminals that you can use in `TerminalInformation.connections`.	Array of `TerminalDescription` objects	No
`maximumStages.heating`	Maximum number of heating stages supported. Default: 3	Integer	No
`maximumStages.cooling`	Maximum number of cooling stages supported. Default: 3	Integer	No
`maximumStages.combined`	Maximum number of heating stages supported. Default: 3	Integer	No
`supportedSwitchOverTypes`	List of switch-over types supported. Switch-over types indicate how switching between heating and cooling occurs. If you don’t include this field, Alexa assumes that the thermostat supports all switch-over types. You must include at least one entry in the array. Valid values: `AUTOMATIC`, `MANUAL`	Array of strings	No
`lockoutTemperature.heating.minimum`	Minimum lockout temperature for heating. Default: 35.0 °F, 2.0 °C Valid values: 50–90 °F, 11.5–32 °C	`Temperature` object	No
`lockoutTemperature.heating.maximum`	Maximum lockout temperature for heating. Default: 50.0 °F, 10.0 °C Valid values: 50–90 °F, 11.5–32 °C	`Temperature` object	No
`lockoutTemperature.cooling.minimum`	Minimum lockout temperature for cooling. Default: 50.0 °F, 10 °C Valid values: 50–90 °F, 11.5–32 °C	`Temperature` object	No
`lockoutTemperature.cooling.maximum`	Maximum lockout temperature for cooling. Default: 65.0 °F, 18.0 °C Valid values: 50–90 °F, 11.5–32 °C	`Temperature` object	No
`lockoutTemperature.increment`	Increments that the customer uses to set the minimum and maximum lockout temperature. Define these increments in multiples of 1.0 °F or 0.5 °C. Default: 1.0 °F, 0.5 °C Maximum values: 5.0 °F, 2.5 °C	`Temperature` object	No

TerminalDescription objects

Property	Description	Type	Required
`name`	Name of the terminal. For commonly used terminal names, see Terminal names.	String	Yes
`purpose`	Purpose the terminal serves. Alexa uses this information to provide the customer with help during setup. The information isn’t needed for thermostat operation. For valid values, see Terminal purpose. Default: `OTHER`	Integer	No

ComponentConfiguration object

The ComponentConfiguration object provides information about connected terminals, HVAC systems, and other configuration required for the thermostat to operate.

Property	Description	Type
`terminalInformation`	Identifies the wires connected to terminals on the thermostat.	`TerminalInformation` object
`systemInformation`	Information about the HVAC system.	`SystemInformation` object

TerminalInformation object

The TerminalInformation object provides connection details of HVAC system wiring to the terminals on the thermostat. This object is an array of TerminalConnection objects.

TerminalConnection object

The TerminalConnection object provides information about each terminal on the thermostat.

Property	Description	Type
`name`	Name of the terminal. For commonly used terminal names, see Terminal names.	String of 1– 5 characters
`state`	Connection state of the terminal. Valid values: `NOT_CONNECTED`, `CONNECTED`.	String
`connectionType`	(Optional) Type of connection to the common terminal. An external connection is from an adapter. Valid values: `EXTERNAL`, `INTERNAL`.	String

SystemInformation object

The SystemInformation object provides information about the HVAC systems connected to the thermostat.

Property	Description	Type
`systemConfigurations`	List of configuration for heating, cooling, and auxiliary systems. Include for systems that have configuration only.	Array of `SystemConfiguration` objects
`coolingSystem`	Configuration of the cooling system.	`CoolingSystem` object
`heatingSystem`	Configuration of the heating system.	`HeatingSystem` object
`multimodeConfiguration`	Configuration for a single system that handles heating and cooling.	`MultimodeConfiguration` object
`lockoutTemperatures`	Outside temperatures beyond which the thermostat should shut off the HVAC system and, if configured, switch to an auxiliary system.	`LockoutTemperatures` object

SystemConfiguration object

Use the SystemConfiguration object to define the configuration for the HVAC system. Typically, systems that use heat pumps require configuration.

Property	Description	Type
`type`	Type of system. Valid values: `AIR_TO_AIR_HEATPUMP`, `GEO_THERMAL_HEATPUMP`.	String
`configuration`	Configuration of the system.	`HeatPumpConfiguration` object

HeatPumpConfiguration object

The following table shows the details of the HeatPumpConfiguration object.

Property	Description	Type
`reversingValve`	Indicates when to reverse the heat pump value. Valid values: `ON_HEAT`, `ON_COOL`.	String

CoolingSystem object

Use the CoolingSystem object to define the stages of cooling.

Property	Description	Type
`stages`	Type of heating cooling at each stage. An element in the array corresponds to the stage of the cooling system. For example, the first element in the array defines stage one.	Array of `SystemStage` objects

HeatingSystem object

Use the HeatingSystem object to define the stages of heating.

Property	Description	Type
`stages`	Type of heating system at each stage. An element in the array corresponds to the stage of the heating system. For example, the first element in the array defines stage one.	Array of `SystemStage` objects
`auxiliaryHeatingSystem`	(Optional) Type of auxiliary heating system. The thermostat turns on the auxiliary heating system when the primary system can’t generate enough heat or stops working. The auxiliary system is never a heat pump and works in a single stage.	`AuxiliaryHeatingSystem` object

SystemStage object

The SystemStage object represents the system associated with the stage.

Property	Description	Type
`type`	System associated with the stage. For valid values, see HVAC system types.	String

AuxiliaryHeatingSystem object

The AuxiliaryHeatingSystem object identifies the type of auxiliary heating system.

Property	Description	Type
`type`	Type of auxiliary heating system. For valid values, see HVAC system types.	String

MultimodeConfiguration object

The MultimodeConfiguration object identifies switch-over for HVAC systems that support both heating and cooling in a single system.

Property	Description	Type
`switchOverType`	Indicates how switching between heating and cooling occurs. For example, the thermostat can automatically switch between modes, or the customer switches between modes manually. Valid values: `AUTOMATIC`, `MANUAL`.	String

LockoutTemperatures object

The LockoutTemperatures object indicates the outside temperature at which the thermostat switches to the auxiliary system. Both heating and cooling systems might have defined lockout temperatures.

Property	Description	Type
`heating`	At this outside temperature, the thermostat stops the primary heating system and starts the auxiliary heating system. Valid values: 50–90 °F, 11.5–32 °C	`Temperature` object
`cooling`	At this outside temperature, the thermostat stops the primary cooling system and starts the auxiliary cooling system. Valid values: 50–90 °F, 11.5–32 °C	`Temperature` object

Discovery

You describe endpoints that support Alexa.ThermostatController.Configuration by using the standard discovery mechanism described in Alexa.Discovery. Set retrievable to true for the properties that you report when Alexa sends your add-on 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. If your thermostat device supports remote configuration, include the setupState property. If your device supports changing the temperature scale, include the temperatureScale property.

Configuration object

In addition to the usual discovery response fields, for Alexa.ThermostatController.Configuration, include a configuration object that contains the following fields. All the fields are optional. Include only the fields that match the components of your thermostat device.

Property	Description	Type	Required
`supportedResetStates`	States that the thermostat supports. Include this field only if the customer can reset the thermostat in the Alexa app. If not included, Alexa doesn’t send the `ResetDeviceConfiguration` directive.	Array of `ThermostatSetupState` strings	No
`componentConfigurationConstraints`	Defines the configuration constraints supported by the thermostat. Alexa uses the constraints to validate the HVAC system information provided by the customer or technician. Include this field only if the thermostat supports updating component configuration. If not included, Alexa doesn’t send `GetComponentConfiguration` and `SetComponentConfiguration` directives.	`ComponentConfigurationConstraints` object	No
`requiredSetupInformation`	Minimum configuration required to set up the thermostat and change the `setUpState` to `REMOTE_CONTROL`. If you don’t include this field, the customer can’t set up the thermostat in the Alexa app, and Alexa doesn’t send the `SetupDevice` directive. Use values that correspond to the configuration names on your device, such as `componentConfiguration`, `temperatureScale`, or other device-specific values.	Array of strings	No
`supportedTemperatureScales`	List of temperature scales that the thermostat supports. Default: [`CELSIUS`, `FAHRENHEIT`]	Array of temperature scale strings	No

Discover response example

The following example shows a Discover.Response message for an Alexa add-on that accepts thermostat configuration and supports the Alexa.ThermostatController and Alexa.EndpointHealth interfaces. In this example, the thermostat device supports setupState and temperatureScale properties.

Show/hide Discovery response

{
    "event": {
        "header": {
            "namespace": "Alexa.Discovery",
            "name": "Discover.Response",
            "payloadVersion": "3",
            "messageId": "Unique identifier, preferably a version 4 UUID"
        },
        "payload": {
            "endpoints": [{
                "endpointId": "Unique ID of the endpoint",
                "manufacturerName": "Sample Manufacturer",
                "description": "Description that appears in the Alexa app",
                "friendlyName": "Your device name, displayed in the Alexa app",
                "displayCategories": ["THERMOSTAT"],
                "additionalAttributes": {
                    "manufacturer": "Sample Manufacturer",
                    "model": "Sample Model",
                    "serialNumber": "Serial number of the device",
                    "firmwareVersion": "Firmware version of the device",
                    "softwareVersion": "Software version of the device",
                    "customIdentifier": "Optional custom identifier for the device"
                },
                "cookie": {},
                "capabilities": [{
                        "type": "AlexaInterface",
                        "interface": "Alexa.ThermostatController",
                        "version": "3.2",
                        "properties": {
                            "supported": [{
                                    "name": "targetSetpoint"
                                },
                                {
                                    "name": "lowerSetpoint"
                                },
                                {
                                    "name": "upperSetpoint"
                                },
                                {
                                    "name": "thermostatMode"
                                }
                            ],
                            "proactivelyReported": true,
                            "retrievable": true
                        },
                        "configuration": {
                            "supportedModes": [
                                "HEAT",
                                "COOL",
                                "AUTO",
                                "OFF"
                            ],
                            "supportsScheduling": true
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa.ThermostatController.Configuration",
                        "version": "3",
                        "properties": {
                            "supported": [{
                                    "name": "setupState"
                                },
                                {
                                    "name": "temperatureScale"
                                }
                            ],
                            "proactivelyReported": true,
                            "retrievable": true
                        },
                        "configuration": {
                            "supportedResetStates": [
                                "FACTORY_DEFAULT",
                                "DEVICE_CONTROL_ONLY"
                            ],
                            "componentConfigurationConstraints": {
                                "supportedTerminals": [{
                                        "name": "S1",
                                        "purpose": "SENSOR"
                                    },
                                    {
                                        "name": "S2",
                                        "purpose": "SENSOR"
                                    },
                                    {
                                        "name": "Y",
                                        "purpose": "COOLING"
                                    },
                                    {
                                        "name": "Y2",
                                        "purpose": "COOLING"
                                    },
                                    {
                                        "name": "G",
                                        "purpose": "FAN"
                                    },
                                    {
                                        "name": "C",
                                        "purpose": "COMMON"
                                    },
                                    {
                                        "name": "A",
                                        "purpose": "STATUS"
                                    },
                                    {
                                        "name": "E",
                                        "purpose": "AUXILIARY"
                                    },
                                    {
                                        "name": "W",
                                        "purpose": "HEATING"
                                    },
                                    {
                                        "name": "W2",
                                        "purpose": "HEATING"
                                    },
                                    {
                                        "name": "K",
                                        "purpose": "OTHER"
                                    },
                                    {
                                        "name": "R",
                                        "purpose": "POWER"
                                    },
                                    {
                                        "name": "Rc",
                                        "purpose": "POWER"
                                    }
                                ],
                                "maximumStages": {
                                    "heating": 2,
                                    "cooling": 2,
                                    "combined": 2
                                },
                                "supportedSwitchOverTypes": [
                                    "MANUAL"
                                ],
                                "lockoutTemperature": {
                                    "heating": {
                                        "minimum": {
                                            "value": 40,
                                            "scale": "FAHRENHEIT"
                                        },
                                        "maximum": {
                                            "value": 70,
                                            "scale": "FAHRENHEIT"
                                        }
                                    },
                                    "cooling": {
                                        "minimum": {
                                            "value": 50,
                                            "scale": "FAHRENHEIT"
                                        },
                                        "maximum": {
                                            "value": 80,
                                            "scale": "FAHRENHEIT"
                                        }
                                    },
                                    "increment": {
                                        "value": 1,
                                        "scale": "FAHRENHEIT"
                                    }
                                }
                            },
                            "requiredSetupInformation": [
                                "componentConfiguration",
                                "temperatureScale"
                            ],
                            "supportedTemperatureScales": [
                                "CELSIUS",
                                "FAHRENHEIT"
                            ]
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa.EndpointHealth",
                        "version": "3.1",
                        "properties": {
                            "supported": [{
                                "name": "connectivity"
                            }],
                            "proactivelyReported": true,
                            "retrievable": true
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa",
                        "version": "3"
                    }
                ]
            }]
        }
    }
}

Directives

Alexa sends the following Alexa.ThermostatController.Configuration interface directives to your add-on.

GetComponentConfiguration directive

Support the GetComponentConfiguration directive so that Alexa can display the HVAC system details to the customer or set up another thermostat connected to the same HVAC system.

GetComponentConfiguration directive example

The following example shows a GetComponentConfiguration directive that Alexa sends to your add-on.

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

GetComponentConfiguration directive payload

The GetComponentConfiguration directive doesn’t define any payload parameters. The directive includes an empty payload object.

GetComponentConfiguration response

If you handle a GetComponentConfiguration directive successfully, respond with an Alexa.Response event. The following example shows a GetComponentConfiguration response.

Show/hide GetComponentConfiguration response

{
    "event": {
        "header": {
            "namespace": "Alexa.ThermostatController.Configuration",
            "name": "GetComponentConfiguration.Response",
            "messageId": "Unique identifier, preferably a version 4 UUID",
            "correlationToken": "Opaque correlation token that matches the request",
            "payloadVersion": "3"
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "OAuth2.0 bearer token"
            },
            "endpointId": "endpoint id",
            "cookie": {}
        },
        "payload": {
            "componentConfiguration": {
                "terminalInformation": {
                    "connections": [{
                            "name": "S1",
                            "state": "NOT_CONNECTED"
                        },
                        {
                            "name": "S2",
                            "state": "NOT_CONNECTED"
                        },
                        {
                            "name": "Y",
                            "state": "NOT_CONNECTED"
                        },
                        {
                            "name": "Y2",
                            "state": "NOT_CONNECTED"
                        },
                        {
                            "name": "G",
                            "state": "CONNECTED"
                        },
                        {
                            "name": "C",
                            "state": "CONNECTED",
                            "connectionType": "INTERNAL"
                        },
                        {
                            "name": "A",
                            "state": "NOT_CONNECTED"
                        },
                        {
                            "name": "O/B",
                            "state": "NOT_CONNECTED"
                        },
                        {
                            "name": "W2",
                            "state": "NOT_CONNECTED"
                        },
                        {
                            "name": "E",
                            "state": "NOT_CONNECTED"
                        },
                        {
                            "name": "W",
                            "state": "CONNECTED"
                        },
                        {
                            "name": "K",
                            "state": "NOT_CONNECTED"
                        },
                        {
                            "name": "R",
                            "state": "CONNECTED"
                        },
                        {
                            "name": "Rc",
                            "state": "NOT_CONNECTED"
                        }
                    ]
                },
                "systemInformation": {
                    "heatingSystem": {
                        "stages": [{
                            "type": "RADIANT_FAN_COIL"
                        }]
                    },
                    "coolingSystem": {
                        "stages": [{
                            "type": "CENTRAL_AIR_CONDITIONING"
                        }]
                    },
                    "multimodeConfiguration": {
                        "switchOverType": "MANUAL"
                    }
                }
            }
        }
    },
    "context": {
        "properties": []
    }
}

Response payload

On success, return the configuration stored on the thermostat device.

Property	Description	Type	Required
`componentConfiguration`	Provides information about connected terminals, HVAC systems, and other configuration required for the thermostat to operate.	`ComponentConfiguration` object	Yes

GetComponentConfiguration directive error handling

If you can’t handle a GetComponentConfiguration directive successfully, respond with an Alexa.ThermostatController.Configuration.ErrorResponse event. You can also respond with a generic Alexa.ErrorResponse event if your error isn’t specific to thermostats.

ResetDeviceConfiguration directive

Support the ResetDeviceConfiguration directive so that Alexa can set the state of the thermostat device.

ResetDeviceConfiguration directive example

The following example shows a ResetDeviceConfiguration directive that Alexa sends to your add-on.

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

ResetDeviceConfiguration directive payload

The following table shows the payload details for the ResetDeviceConfiguration directive that Alexa sends to your add-on.

Property	Description	Type	Required
`targetState`	Indicates the desired state of the device. The requested value reflects the configuration that you specified in the `supportedResetStates` field of the discovery response. Valid values: `FACTORY_DEFAULT`, `DEVICE_CONTROL_ONLY`	String	Yes

ResetDeviceConfiguration response

If you handle a ResetDeviceConfiguration directive successfully and the device can reset the configuration to the target state, respond with an Alexa.Response event. If a SetupDevice or ResetDeviceConfiguration request is already in progress, return Alexa.ErrorResponse with error type set to ALREADY_IN_OPERATION.

ResetDeviceConfiguration directive error handling

If you can’t handle a ResetDeviceConfiguration directive successfully, don’t change the configuration on the device and respond with an Alexa.ThermostatController.Configuration.ErrorResponse event. You can also respond with a generic Alexa.ErrorResponse event if your error isn’t specific to thermostats.

SetComponentConfiguration directive

Support the SetComponentConfiguration directive so that Alexa can provide HVAC configuration to your device. The customer provides this information during thermostat setup or configuration updates in the Alexa app.

SetComponentConfiguration directive example

The following example shows a SetComponentConfiguration directive that Alexa sends to your add-on.

Show/hide SetComponentConfiguration directive

{
  "directive": {
    "header": {
      "namespace": "Alexa.ThermostatController.Configuration",
      "name": "SetComponentConfiguration",
      "messageId": "Unique version 4 UUID",
      "correlationToken": "Opaque correlation token",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2 bearer token"
      },
      "endpointId": "endpoint id",
      "cookie": {}
    },
    "payload": {
      "componentConfiguration": {
        "terminalInformation": {
          "connections": [
            {
              "name": "S1",
              "state": "NOT_CONNECTED"
            },
            {
              "name": "S2",
              "state": "NOT_CONNECTED"
            },
            {
              "name": "Y",
              "state": "NOT_CONNECTED"
            },
            {
              "name": "Y2",
              "state": "NOT_CONNECTED"
            },
            {
              "name": "G",
              "state": "CONNECTED"
            },
            {
              "name": "C",
              "state": "CONNECTED",
              "connectionType": "INTERNAL"
            },
            {
              "name": "A",
              "state": "NOT_CONNECTED"
            },
            {
              "name": "O/B",
              "state": "NOT_CONNECTED"
            },
            {
              "name": "W2",
              "state": "NOT_CONNECTED"
            },
            {
              "name": "E",
              "state": "NOT_CONNECTED"
            },
            {
              "name": "W",
              "state": "CONNECTED"
            },
            {
              "name": "K",
              "state": "NOT_CONNECTED"
            },
            {
              "name": "R",
              "state": "CONNECTED"
            },
            {
              "name": "Rc",
              "state": "NOT_CONNECTED"
            }
          ]
        },
        "systemInformation": {
          "heatingSystem": {
            "stages": [
              {
                "type": "RADIANT_FAN_COIL"
              }
            ]
          },
          "coolingSystem": {
            "stages": [
              {
                "type": "CENTRAL_AIR_CONDITIONING"
              }
            ]
          },
          "multimodeConfiguration": {
            "switchOverType": "MANUAL"
          }
        }
      }
    }
  }
}

SetComponentConfiguration directive payload

The following table shows the payload details for the SetComponentConfiguration directive that Alexa sends to your add-on.

Property	Description	Type	Required
`componentConfiguration`	HVAC and wiring configuration. Included if you specified component configuration in the `requiredSetupInformation` of the discovery response.	`ComponentConfiguration` object	Yes

SetComponentConfiguration response

If you handle a SetComponentConfiguration directive successfully and the device can apply the configuration settings, respond with an Alexa.Response. If the device is already fully set up and can’t accept configuration updates, return Alexa.ThermostatController.Configuration.ErrorResponse with error type set to CONFIGURATION_UPDATE_NOT_ALLOWED. If the specified configuration isn’t supported by the device, Alexa.ErrorResponse with error type set to INVALID_VALUE.

SetComponentConfiguration directive error handling

If you can’t handle a SetComponentConfiguration directive successfully, don’t change the configuration on the device and respond with an Alexa.ThermostatController.Configuration.ErrorResponse. You can also respond with a generic Alexa.ErrorResponse if your error isn’t specific to thermostats.

SetTemperatureScale directive

Support the SetTemperatureScale directive so that customers can update the temperature scale on the device. You specify the list of supported temperature scales in the supportedTemperatureScales field in the discovery response.

SetTemperatureScale directive example

The following example shows a SetTemperatureScale directive that Alexa sends to your add-on.

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

SetTemperatureScale directive payload

The following table shows the payload details for the SetTemperatureScale directive that Alexa sends to your add-on.

Property	Description	Type	Required
`temperatureScale`	Temperature scale to display on the device.	String	Yes

SetTemperatureScale response

If you handle a SetTemperatureScale directive successfully, respond with an Alexa.Response event. A successful response confirms that the endpoint completed the requested action.

SetTemperatureScale directive error handling

If you can’t handle a SetTemperatureScale directive successfully, respond with an Alexa.ThermostatController.Configuration.ErrorResponse event. You can also respond with a generic Alexa.ErrorResponse event if your error isn’t specific to thermostats.

SetupDevice directive

Support the SetupDevice directive so that you can get the information that the customer configured during the thermostat setup. Configuration information includes HVAC settings and temperature scale.

SetupDevice directive example

The following example shows a SetupDevice directive that Alexa sends to your add-on.

Show/hide SetupDevice directive

{
    "directive": {
        "header": {
            "namespace": "Alexa.ThermostatController.Configuration",
            "name": "SetupDevice",
            "messageId": "Unique version 4 UUID",
            "correlationToken": "Opaque correlation token",
            "payloadVersion": "3"
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "OAuth2 bearer token"
            },
            "endpointId": "endpoint id",
            "cookie": {}
        },
        "payload": {
            "componentConfiguration": {
                "terminalInformation": {
                    "connections": [{
                            "name": "S1",
                            "state": "NOT_CONNECTED"
                        },
                        {
                            "name": "S2",
                            "state": "NOT_CONNECTED"
                        },
                        {
                            "name": "Y",
                            "state": "NOT_CONNECTED"
                        },
                        {
                            "name": "Y2",
                            "state": "NOT_CONNECTED"
                        },
                        {
                            "name": "G",
                            "state": "CONNECTED"
                        },
                        {
                            "name": "C",
                            "state": "CONNECTED",
                            "connectionType": "EXTERNAL"
                        },
                        {
                            "name": "U1",
                            "state": "NOT_CONNECTED"
                        },
                        {
                            "name": "U2",
                            "state": "NOT_CONNECTED"
                        },
                        {
                            "name": "A",
                            "state": "NOT_CONNECTED"
                        },
                        {
                            "name": "O/B",
                            "state": "NOT_CONNECTED"
                        },
                        {
                            "name": "W2",
                            "state": "NOT_CONNECTED"
                        },
                        {
                            "name": "E",
                            "state": "NOT_CONNECTED"
                        },
                        {
                            "name": "W",
                            "state": "CONNECTED"
                        },
                        {
                            "name": "K",
                            "state": "NOT_CONNECTED"
                        },
                        {
                            "name": "R",
                            "state": "CONNECTED"
                        },
                        {
                            "name": "Rc",
                            "state": "NOT_CONNECTED"
                        }
                    ]
                },
                "systemInformation": {
                    "heatingSystem": {
                        "stages": [{
                            "type": "RADIANT_FAN_COIL"
                        }]
                    },
                    "coolingSystem": {
                        "stages": [{
                            "type": "CENTRAL_AIR_CONDITIONING"
                        }]
                    },
                    "multimodeConfiguration": {
                        "switchOverType": "MANUAL"
                    }
                }
            },
            "temperatureScale": "FAHRENHEIT"
        }
    }
}

SetupDevice directive payload

The following table shows the payload details for the SetupDevice directive that Alexa sends to your add-on.

Property	Description	Type	Required
`componentConfiguration`	HVAC and wiring configuration. Included if you specified component configuration in the `requiredSetupInformation` of the discovery response.	`ComponentConfiguration` object	No
`temperatureScale`	Preferred temperature scales to display in the Alexa app and on the thermostat device. Included if you specified temperature scale in the `requiredSetupInformation` of the discovery response.	String	No

SetupDevice response

If you handle a SetupDevice directive successfully and the device can apply the configuration settings, set the setupState for the device to REMOTE_CONTROL and respond with an Alexa.Response event. If a SetupDevice or ResetDeviceConfiguration request is already in progress, return Alexa.ErrorResponse with error type set to ALREADY_IN_OPERATION. If the device is already fully set up and can’t accept configuration updates, return Alexa.ThermostatController.Configuration.ErrorResponse with error type set to CONFIGURATION_UPDATE_NOT_ALLOWED.

SetupDevice directive error handling

If you can’t handle a SetupDevice directive successfully, don’t change the configuration on the device and respond with an Alexa.ThermostatController.Configuration.ErrorResponse event. You can also respond with a generic Alexa.ErrorResponse event if your error isn’t specific to 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

In this example, the thermostat device supports both setupState and temperatureScale.

{
    "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.Configuration",
                "name": "setupState",
                "value": "REMOTE_CONTROL",
                "timeOfSample": "2024-01-01T08:00:00.05Z",
                "uncertaintyInMilliseconds": 1000
            },
            {
                "namespace": "Alexa.ThermostatController.Configuration",
                "name": "temperatureScale",
                "value": "CELSIUS",
                "timeOfSample": "2024-01-01T08:00:00.05Z",
                "uncertaintyInMilliseconds": 500
            },
            {
                "namespace": "Alexa.ThermostatController",
                "name": "thermostatMode",
                "value": "HEAT",
                "timeOfSample": "2024-01-01T08:00:00.05Z",
                "uncertaintyInMilliseconds": 500
            },
            {
                "namespace": "Alexa.ThermostatController",
                "name": "targetSetpoint",
                "value": {
                    "value": 20.0,
                    "scale": "CELSIUS"
                },
                "timeOfSample": "2024-01-01T08:00:00.05Z",
                "uncertaintyInMilliseconds": 500
            },
            {
                "namespace": "Alexa.EndpointHealth",
                "name": "connectivity",
                "value": {
                    "value": "OK"
                },
                "timeOfSample": "2024-01-01T16:20:00.00Z",
                "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. The payload contains the values of properties that have changed, the context contains the values of other relevant properties.

Device reset example

The following example shows a ChangeReport after the customer attempts to reset the thermostat by pressing buttons on the device.

{  
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "ChangeReport",
      "messageId": "Unique identifier, preferably a version 4 UUID",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2 bearer token"
      },
      "endpointId": "endpoint id"
    },
    "payload": {
      "change": {
        "cause": {
            "type": "PHYSICAL_INTERACTION"
          },
          "properties": [
            {
              "namespace": "Alexa.ThermostatController.Configuration",
              "name": "setupState",
              "value": "DEVICE_CONTROL_ONLY",
              "timeOfSample": "2024-01-11T18:15:00.35Z",
              "uncertaintyInMilliseconds": 500
            }
          ]
        }
      }
    },
  "context": {
      "properties": [{
              "namespace": "Alexa.ThermostatController.Configuration",
              "name": "temperatureScale",
              "value": "CELSIUS",
              "timeOfSample": "2024-01-01T08:00:00.05Z",
              "uncertaintyInMilliseconds": 500
          },
          {
              "namespace": "Alexa.ThermostatController",
              "name": "thermostatMode",
              "value": "HEAT",
              "timeOfSample": "2024-01-01T08:00:00.05Z",
              "uncertaintyInMilliseconds": 500
          },
          {
              "namespace": "Alexa.ThermostatController",
              "name": "targetSetpoint",
              "value": {
                  "value": 20.0,
                  "scale": "CELSIUS"
              },
              "timeOfSample": "2024-01-01T08:00:00.05Z",
              "uncertaintyInMilliseconds": 500
          },
          {
              "namespace": "Alexa.EndpointHealth",
              "name": "connectivity",
              "value": {
                  "value": "OK"
              },
              "timeOfSample": "2024-01-11T18:00:00.05Z",
              "uncertaintyInMilliseconds": 0
          }
      ]
  }
}

Temperature scale change example

The following example shows a ChangeReport after the customer uses the Alexa app to change the temperature scale.

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "ChangeReport",
      "messageId": "Unique identifier, preferably a version 4 UUID",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2 bearer token"
      },
      "endpointId": "endpoint id"
    },
    "payload": {
      "change": {
        "cause": {
          "type": "APP_INTERACTION"
        },
        "properties": [
          {
            "namespace": "Alexa.ThermostatController.Configuration",
            "name": "temperatureScale",
            "value": "FAHRENHEIT",
            "timeOfSample": "2024-01-21T12:07:00.05Z",
            "uncertaintyInMilliseconds": 500
          }
        ]
      }
    }
  },
  "context": {
      "properties": [{
             "namespace": "Alexa.ThermostatController.Configuration",
             "name": "setupState",
             "value": "DEVICE_CONTROL_ONLY",
             "timeOfSample": "2024-01-01T08:00:00.05Z",
             "uncertaintyInMilliseconds": 500
          },
          {
              "namespace": "Alexa.ThermostatController",
              "name": "thermostatMode",
              "value": "HEAT",
              "timeOfSample": "2024-01-01T08:00:00.05Z",
              "uncertaintyInMilliseconds": 500
          },
          {
              "namespace": "Alexa.ThermostatController",
              "name": "targetSetpoint",
              "value": {
                  "value": 20.0,
                  "scale": "CELSIUS"
              },
              "timeOfSample": "2024-01-01T08:00:00.05Z",
              "uncertaintyInMilliseconds": 500
          },
          {
              "namespace": "Alexa.EndpointHealth",
              "name": "connectivity",
              "value": {
                  "value": "OK"
              },
              "timeOfSample": "2024-01-21T12:00:00.15Z",
              "uncertaintyInMilliseconds": 0
          }
      ]
  }
}

AddOrUpdateReport

You must proactively send an Alexa.Discovery.AddOrUpdateReport event if the feature support of your endpoint changes. For example, if the configuration constraints change after a firmware update. For details, see AddOrUpdateReport event.

AddOrUpdateReport event example

Show/hide AddOrUpdateReport event

{
    "event": {
        "header": {
            "namespace": "Alexa.Discovery",
            "name": "AddOrUpdateReport",
            "payloadVersion": "3",
            "messageId": "Unique identifier, preferably a version 4 UUID"
        },
        "payload": {
            "endpoints": [{
                "endpointId": "Unique ID of the endpoint",
                "manufacturerName": "Sample Manufacturer",
                "description": "Description that appears in the Alexa app",
                "friendlyName": "Your device name, displayed in the Alexa app",
                "displayCategories": ["THERMOSTAT"],
                "additionalAttributes": {
                    "manufacturer": "Sample Manufacturer",
                    "model": "Sample Model",
                    "serialNumber": "Serial number of the device",
                    "firmwareVersion": "New firmware version of the device",
                    "softwareVersion": "Software version of the device",
                    "customIdentifier": "Optional custom identifier for the device"
                },
                "cookie": {},
                "capabilities": [{
                        "type": "AlexaInterface",
                        "interface": "Alexa.ThermostatController",
                        "version": "3.2",
                        "properties": {
                            "supported": [{
                                    "name": "targetSetpoint"
                                },
                                {
                                    "name": "lowerSetpoint"
                                },
                                {
                                    "name": "upperSetpoint"
                                },
                                {
                                    "name": "thermostatMode"
                                }
                            ],
                            "proactivelyReported": true,
                            "retrievable": true
                        },
                        "configuration": {
                            "supportedModes": [
                                "HEAT",
                                "COOL",
                                "AUTO",
                                "OFF"
                            ],
                            "supportsScheduling": true
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa.ThermostatController.Configuration",
                        "version": "3",
                        "properties": {
                            "supported": [{
                                    "name": "setupState"
                                },
                                {
                                    "name": "temperatureScale"
                                }
                            ],
                            "proactivelyReported": true,
                            "retrievable": true
                        },
                        "configuration": {
                            "supportedResetStates": [
                                "FACTORY_DEFAULT",
                                "DEVICE_CONTROL_ONLY"
                            ],
                            "componentConfigurationConstraints": {
                                "supportedTerminals": [{
                                        "name": "S1",
                                        "purpose": "SENSOR"
                                    },
                                    {
                                        "name": "S2",
                                        "purpose": "SENSOR"
                                    },
                                    {
                                        "name": "Y",
                                        "purpose": "COOLING"
                                    },
                                    {
                                        "name": "Y2",
                                        "purpose": "COOLING"
                                    },
                                    {
                                        "name": "G",
                                        "purpose": "FAN"
                                    },
                                    {
                                        "name": "C",
                                        "purpose": "COMMON"
                                    },
                                    {
                                        "name": "U1",
                                        "purpose": "HUMIDIFIER"
                                    },
                                    {
                                        "name": "U2",
                                        "purpose": "DEHUMIDIFIER"
                                    },
                                    {
                                        "name": "A",
                                        "purpose": "STATUS"
                                    },
                                    {
                                        "name": "E",
                                        "purpose": "AUXILIARY"
                                    },
                                    {
                                        "name": "W",
                                        "purpose": "HEATING"
                                    },
                                    {
                                        "name": "W2",
                                        "purpose": "HEATING"
                                    },
                                    {
                                        "name": "K",
                                        "purpose": "OTHER"
                                    },
                                    {
                                        "name": "R",
                                        "purpose": "POWER"
                                    },
                                    {
                                        "name": "Rc",
                                        "purpose": "POWER"
                                    }
                                ],
                                "maximumStages": {
                                    "heating": 2,
                                    "cooling": 2,
                                    "combined": 2
                                },
                                "supportedSwitchOverTypes": [
                                    "MANUAL"
                                ],
                                "lockoutTemperature": {
                                    "heating": {
                                        "minimum": {
                                            "value": 40,
                                            "scale": "FAHRENHEIT"
                                        },
                                        "maximum": {
                                            "value": 70,
                                            "scale": "FAHRENHEIT"
                                        }
                                    },
                                    "cooling": {
                                        "minimum": {
                                            "value": 50,
                                            "scale": "FAHRENHEIT"
                                        },
                                        "maximum": {
                                            "value": 80,
                                            "scale": "FAHRENHEIT"
                                        }
                                    },
                                    "increment": {
                                        "value": 1,
                                        "scale": "FAHRENHEIT"
                                    }
                                }
                            },
                            "requiredSetupInformation": [
                                "componentConfiguration",
                                "temperatureScale"
                            ],
                            "supportedTemperatureScales": [
                                "CELSIUS",
                                "FAHRENHEIT"
                            ]
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa.EndpointHealth",
                        "version": "3.1",
                        "properties": {
                            "supported": [{
                                "name": "connectivity"
                            }],
                            "proactivelyReported": true,
                            "retrievable": true
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa",
                        "version": "3"
                    }
                ]
            }]
        }
    }
}

Last modified on September 30, 2026

​Utterances

​Thermostat configuration

​Thermostat setup states

​HVAC system types

​Terminal purposes

​Terminal names

​Properties and objects

​Reportable properties

​ComponentConfigurationConstraints object

​TerminalDescription objects

​ComponentConfiguration object

​TerminalInformation object

​TerminalConnection object

​SystemInformation object

​SystemConfiguration object

​HeatPumpConfiguration object

​CoolingSystem object

​HeatingSystem object

​SystemStage object

​AuxiliaryHeatingSystem object

​MultimodeConfiguration object

​LockoutTemperatures object

​Discovery

​Configuration object

​Discover response example

​Directives

​GetComponentConfiguration directive

​GetComponentConfiguration directive example

​GetComponentConfiguration directive payload

​GetComponentConfiguration response

Response payload

​GetComponentConfiguration directive error handling

​ResetDeviceConfiguration directive

​ResetDeviceConfiguration directive example

​ResetDeviceConfiguration directive payload

​ResetDeviceConfiguration response

​ResetDeviceConfiguration directive error handling

​SetComponentConfiguration directive

​SetComponentConfiguration directive example

​SetComponentConfiguration directive payload

​SetComponentConfiguration response

​SetComponentConfiguration directive error handling

​SetTemperatureScale directive

​SetTemperatureScale directive example

​SetTemperatureScale directive payload

​SetTemperatureScale response

​SetTemperatureScale directive error handling

​SetupDevice directive

​SetupDevice directive example

​SetupDevice directive payload

​SetupDevice response

​SetupDevice directive error handling

​State reporting

​StateReport response example

​Change reporting

​Device reset example

​Temperature scale change example

​AddOrUpdateReport

​AddOrUpdateReport event example

​Related topics