Alexa.ThermostatController.HVAC.Components Interface 1.0

Implement the Alexa.ThermostatController.HVAC.Components interface in your Alexa skill so that Alexa can estimate the energy use of your connected thermostat device or heating, ventilation, and air conditioning (HVAC) system. The HVAC.Components interface is intended to help users manage their energy usage with the Alexa energy dashboard. For details, see Smart Home Energy Overview.

Typically you use the HVAC.Components interface in conjunction with the Alexa.ThermostatController and Alexa.TemperatureSensor interfaces.

You can model an HVAC system as heating systems, cooling systems, and ventilation fans. Each of these components can support multiple stages, such as low, medium, and high. To estimate the power consumption of your connected HVAC system, you must notify Alexa about how long the HVAC system stays in each stage.

For the list of locales that the HVAC.Components 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.HVAC.Components interface doesn't have any user utterances. Instead, your skill reports energy usage to Alexa.

Component operating stages

The following table illustrates the possible operating stages for the HVAC components. You identify the number of stages that your components support in your discovery response.

If a component supports 3 stages If a component supports 2 stages If a component supports 1 stage
- OFF — Off
- STAGE_1 — Low
- STAGE_2 — Medium
- STAGE_3 — High		 - OFF — Off
- STAGE_1 — Low
- STAGE_2 — High		 - OFF — Off
- STAGE_1 — On

Properties

The following table illustrates the properties that the Alexa.ThermostatController.HVAC.Components 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 or HVAC system.

Property Description Type
primaryHeaterOperation The current operating stage of the primary heating component. Usually the main heating mechanism is a heat pump. String
auxiliaryHeaterOperation Whether the auxiliary heating is on or off. Valid values are ON and OFF. Usually the auxiliary heating mechanism uses electric resistance heating. String
coolerOperation The current operating stage of the cooling component. String
fanOperation The current operating stage of the ventilation component. String

Discovery

You describe endpoints that support Alexa.ThermostatController.HVAC.Components 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.

In addition to the usual discovery response fields, for HVAC.Components, 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 or HVAC system.

Field Description Type
numberOfPrimaryHeaterOperations The number of operating stages that the primary heating component supports. You must include this field if you support the primaryHeaterOperation property. Valid values are 1, 2, and 3. Integer
numberOfCoolerOperations The number of operating stages that the cooling component supports. You must include this field if you support the coolerOperation property. Valid values are 1, 2, and 3. Integer
numberOfFanOperations The number of operating stages that the ventilation fan component supports. You must include this field if you support the fanOperation property. Valid values are 1, 2, and 3. If your ventilation fan supports more than three speeds, divide your speeds into three ranges and map your speed ranges to the operating stages. Integer

Discover response example

The following example shows a Discover.Response message for an Alexa skill that controls a thermostat and supports the Alexa.ThermostatController.HVAC.Components, Alexa.ThermostatController, and Alexa.TemperatureSensor interfaces. In this example, the endpoint is a dual-setpoint thermostat, with two modes, and that doesn't support scheduling.

In this example, the HVAC system supports primaryHeaterOperation, auxiliaryHeaterOperation, and fanOperation, but doesn't support coolerOperation.

For an example of a Discover.Response for an air conditioner, see Discover response example for an air conditioner.

Copied to clipboard.

{
  "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": "Manufacturer of the endpoint",
          "description": "Smart Thermostat by Thermostat Maker",
          "friendlyName": "Hallway Thermostat",
          "displayCategories": ["THERMOSTAT", "TEMPERATURE_SENSOR"],
          "cookie": {},
          "capabilities": [
            {
              "type": "AlexaInterface",
              "interface": "Alexa.ThermostatController.HVAC.Components",
              "version": "1.0",
              "properties": {
                "supported": [
                  {
                    "name": "primaryHeaterOperation"
                  },
                  {
                    "name": "auxiliaryHeaterOperation"
                  },
                  {
                    "name": "fanOperation"
                  },
                ],
                "retrievable": true,
                "proactivelyReported": true
              },
              "configuration": {
                "numberOfPrimaryHeaterOperations": 3,
                "numberOfFanOperations": 2
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa.ThermostatController",
              "version": "3.1",
              "properties": {
                "supported": [
                  {
                    "name": "lowerSetpoint"
                  },
                  {
                    "name": "upperSetpoint"
                  },
                  {
                    "name": "thermostatMode"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              },
              "configuration": {
                "supportedModes": [ "HEAT", "AUTO" ],
                "supportsScheduling": false
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa.TemperatureSensor",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "temperature"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa.EndpointHealth",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "connectivity"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa",
              "version": "3"
            }
          ]
        }
      ]
    }
  }
}

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 HVAC system supports primaryHeaterOperation, auxiliaryHeaterOperation, and fanOperation, but doesn't support coolerOperation.

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.0 bearer token"
      },
      "endpointId": "Endpoint ID"
    },
    "payload": {}
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.ThermostatController.HVAC.Components",
        "name": "primaryHeaterOperation",
        "value": "STAGE_2",
        "timeOfSample": "2024-01-01T08:00:00.05Z",
        "uncertaintyInMilliseconds": 0
      },
      {
        "namespace": "Alexa.ThermostatController.HVAC.Components",
        "name": "auxiliaryHeaterOperation",
        "value": "OFF",
        "timeOfSample": "2024-01-01T08:00:00.15Z",
        "uncertaintyInMilliseconds": 0
      },
      {
        "namespace": "Alexa.ThermostatController.HVAC.Components",
        "name": "fanOperation",
        "value": "STAGE_1",
        "timeOfSample": "2024-01-01T08:00:00.25Z",
        "uncertaintyInMilliseconds": 0
      },
      {
        "namespace": "Alexa.ThermostatController",
        "name": "thermostatMode",
        "value": "HEAT",
        "timeOfSample": "2024-01-01T08:15:01.05Z",
        "uncertaintyInMilliseconds": 500
      },
      {
        "namespace": "Alexa.ThermostatController",
        "name": "targetSetpoint",
        "value": {
          "value": 20.0,
          "scale": "CELSIUS"
        },
        "timeOfSample": "2024-01-01T08:01:00.15Z",
        "uncertaintyInMilliseconds": 500
      },
      {
        "namespace": "Alexa.TemperatureSensor",
        "name": "temperature",
        "value": {
          "value": 19.9,
          "scale": "CELSIUS"
        },
        "timeOfSample": "2024-01-01T08:10:00.05Z",
        "uncertaintyInMilliseconds": 1000
      }
    ]
  }
}

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.

ChangeReport event example for normal mode

The following example illustrates a ChangeReport after the primary heat stage increases. In this example, the HVAC system supports primaryHeaterOperation, auxiliaryHeaterOperation, and fanOperation, but doesn't support coolerOperation.

Copied to clipboard.

{  
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "ChangeReport",
      "messageId": "Unique identifier, preferably a version 4 UUID",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2.0 bearer token"
      },
      "endpointId": "Endpoint ID"
    },
    "payload": {
      "change": {
        "cause": {
          "type": "PERIODIC_POLL"
        },
        "properties": [
          {
            "namespace": "Alexa.ThermostatController.HVAC.Components",
            "name": "PrimaryHeaterOperation",
            "value": "STAGE_2",
            "timeOfSample": "2024-01-01T09:01:00.05Z",
            "uncertaintyInMilliseconds": 0
          }
        ]
      }
    }
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.ThermostatController.HVAC.Components",
        "name": "auxiliaryHeaterOperation",
        "value": "OFF",
        "timeOfSample": "2024-01-01T08:00:00.05Z",
        "uncertaintyInMilliseconds": 0
      },
      {
        "namespace": "Alexa.ThermostatController.HVAC.Components",
        "name": "fanOperation",
        "value": "STAGE_1",
        "timeOfSample": "2024-01-01T08:00:00.15Z",
        "uncertaintyInMilliseconds": 0
      },
      {
        "namespace": "Alexa.ThermostatController",
        "name": "thermostatMode",
        "value": "AUTO",
        "timeOfSample": "2024-01-01T08:00:00.25Z",
        "uncertaintyInMilliseconds": 500
      },
      {
        "namespace": "Alexa.ThermostatController",
        "name": "targetSetpoint",
        "value": {
          "value": 18.0,
          "scale": "CELSIUS"
        },
        "timeOfSample": "2024-01-01T08:01:00.05Z",
        "uncertaintyInMilliseconds": 500
      },
      {
        "namespace": "Alexa.TemperatureSensor",
        "name": "temperature",
        "value": {
          "value": 19.1,
          "scale": "CELSIUS"
        },
        "timeOfSample": "2024-01-01T09:00:00.05Z",
        "uncertaintyInMilliseconds": 500
      },
      {
        "namespace": "Alexa.EndpointHealth",
        "name": "connectivity",
        "value": {
          "value": "OK"
        },
        "timeOfSample": "2024-01-01T08:00:00.00Z",
        "uncertaintyInMilliseconds": 1000
      }
    ]
  }
}

ChangeReport event example for emergency mode

The following example illustrates a ChangeReport after the auxiliary heat comes on, and the ventilation fan stage increases. In this example, the HVAC system supports primaryHeaterOperation, auxiliaryHeaterOperation, and fanOperation, but doesn't support coolerOperation.

Copied to clipboard.

{  
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "ChangeReport",
      "messageId": "Unique identifier, preferably a version 4 UUID",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2.0 bearer token"
      },
      "endpointId": "Endpoint ID"
    },
    "payload": {
      "change": {
        "cause": {
          "type": "PERIODIC_POLL"
        },
        "properties": [
          {
            "namespace": "Alexa.ThermostatController.HVAC.Components",
            "name": "auxiliaryHeaterOperation",
            "value": "ON",
            "timeOfSample": "2024-01-01T12:05:00.05Z",
            "uncertaintyInMilliseconds": 100
          },
          {
            "namespace": "Alexa.ThermostatController.HVAC.Components",
            "name": "fanOperation",
            "value": "STAGE_2",
            "timeOfSample": "2024-01-01T12:05:10.05Z",
            "uncertaintyInMilliseconds": 100
          }
        ]
      }
    }
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.ThermostatController.HVAC.Components",
        "name": "PrimaryHeaterOperation",
        "value": "OFF",
        "timeOfSample": "2024-01-01T08:00:00.25Z",
        "uncertaintyInMilliseconds": 0
      },
      {
        "namespace": "Alexa.ThermostatController",
        "name": "thermostatMode",
        "value": "AUTO",
        "timeOfSample": "2024-01-01T08:01:00.25Z",
        "uncertaintyInMilliseconds": 500
      },
      {
        "namespace": "Alexa.ThermostatController",
        "name": "targetSetpoint",
        "value": {
          "value": 18.0,
          "scale": "CELSIUS"
        },
        "timeOfSample": "2024-01-01T08:00:00.25Z",
        "uncertaintyInMilliseconds": 500
      },
      {
        "namespace": "Alexa.TemperatureSensor",
        "name": "temperature",
        "value": {
          "value": 19.1,
          "scale": "CELSIUS"
        },
        "timeOfSample": "2024-01-01T12:01:00.25Z",
        "uncertaintyInMilliseconds": 1000
      },
      {
        "namespace": "Alexa.EndpointHealth",
        "name": "connectivity",
        "value": {
          "value": "OK"
        },
        "timeOfSample": "2024-01-01T12:00:00.25Z",
        "uncertaintyInMilliseconds": 0
      }
    ]
  }
}
Was this page helpful?

Last updated: Aug 23, 2024