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 skill. After the customer completes setup, Alexa sends the configuration details of the connected heating, ventilation, and air conditioning (HVAC) system to your skill. 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 skill doesn't support voice user interactions with Alexa directly. Instead, Alexa communicates with your skill 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 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.

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 skill that accepts thermostat configuration and supports the Alexa.ThermostatController and Alexa.EndpointHealth interfaces. In this example, the thermostat device supports setupState and temperatureScale properties.

Directives

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

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.

This directive doesn't have a payload.

GetComponentConfiguration directive example

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

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

If you handle a GetComponentConfiguration directive successfully, respond with an Alexa.Response event.

The following example shows a GetComponentConfiguration response.

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

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

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

SetComponentConfiguration directive payload

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

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

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

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.

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

SetupDevice directive payload

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

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.

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.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": "2020-02-26T16: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.

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

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 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": "22024-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

Was this page helpful?

Last updated: Aug 23, 2024