Alexa.ThermostatController.HVAC.Components Interface

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.

An HVAC system can be modeled 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.

Utterances

The Alexa.ThermostatController.HVAC.Components interface is different than other Alexa interfaces in that you aren't directly supporting voice user interactions with Alexa. Instead, you are communicating with Alexa about energy usage, so that Alexa can report energy use to the user. There are no user utterances associated with this interface.

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": "<message id>"
    },
    "payload": {
      "endpoints": [
        {
          "endpointId": "<unique ID of the endpoint>",
          "manufacturerName": "<the manufacturer name 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",
              "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",
              "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 event 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": "<message id>",
      "correlationToken": "<an opaque correlation token>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "endpointId": "<endpoint id>"
    },
    "payload": {}
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.ThermostatController.HVAC.Components",
        "name": "primaryHeaterOperation",
        "value": "STAGE_2",
        "timeOfSample": "2017-02-03T16:20:50Z",
        "uncertaintyInMilliseconds": 0
      },
      {
        "namespace": "Alexa.ThermostatController.HVAC.Components",
        "name": "auxiliaryHeaterOperation",
        "value": "OFF",
        "timeOfSample": "2017-02-03T16:20:50Z",
        "uncertaintyInMilliseconds": 0
      },
      {
        "namespace": "Alexa.ThermostatController.HVAC.Components",
        "name": "fanOperation",
        "value": "STAGE_1",
        "timeOfSample": "2017-02-03T16:20:50Z",
        "uncertaintyInMilliseconds": 0
      },
      {
        "namespace": "Alexa.ThermostatController",
        "name": "thermostatMode",
        "value": "HEAT",
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 500
      },
      {
        "namespace": "Alexa.ThermostatController",
        "name": "targetSetpoint",
        "value": {
          "value": 20.0,
          "scale": "CELSIUS"
        },
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 500
      },
      {
        "namespace": "Alexa.TemperatureSensor",
        "name": "temperature",
        "value": {
          "value": 19.9,
          "scale": "CELSIUS"
        },
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 1000
      } 
    ]
  }
}

Change reporting

You send a ChangeReport event to proactively report changes 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": "<message id>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<an OAuth2 bearer token>"
      },
      "endpointId": "<endpoint id>"
    },
    "payload": {
      "change": {
        "cause": {
          "type": "PERIODIC_POLL"
        },
        "properties": [
          {
            "namespace": "Alexa.ThermostatController.HVAC.Components",
            "name": "PrimaryHeaterOperation",
            "value": "STAGE_2",
            "timeOfSample": "2017-02-03T16:20:50Z",
            "uncertaintyInMilliseconds": 0
          }
        ]
      }
    }
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.ThermostatController.HVAC.Components",
        "name": "auxiliaryHeaterOperation",
        "value": "OFF",
        "timeOfSample": "2017-02-03T16:20:50Z",
        "uncertaintyInMilliseconds": 0
      },
      {
        "namespace": "Alexa.ThermostatController.HVAC.Components",
        "name": "fanOperation",
        "value": "STAGE_1",
        "timeOfSample": "2017-02-03T16:20:50Z",
        "uncertaintyInMilliseconds": 0
      },
      {
        "namespace": "Alexa.ThermostatController",
        "name": "thermostatMode",
        "value": "AUTO",
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 500
      },
      {
        "namespace": "Alexa.ThermostatController",
        "name": "targetSetpoint",
        "value": {
          "value": 18.0,
          "scale": "CELSIUS"
        },
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 500
      },
      {
        "namespace": "Alexa.TemperatureSensor",
        "name": "temperature",
        "value": {
          "value": 19.1,
          "scale": "CELSIUS"
        },
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 1000
      },
      {
        "namespace": "Alexa.EndpointHealth",
        "name": "connectivity",
        "value": {
          "value": "OK"
        },
        "timeOfSample": "2020-07-05T12:01:23Z",
        "uncertaintyInMilliseconds": 0
      }
    ]
  }
}

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": "<message id>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<an OAuth2 bearer token>"
      },
      "endpointId": "<endpoint id>"
    },
    "payload": {
      "change": {
        "cause": {
          "type": "PERIODIC_POLL"
        },
        "properties": [
          {
            "namespace": "Alexa.ThermostatController.HVAC.Components",
            "name": "auxiliaryHeaterOperation",
            "value": "ON",
            "timeOfSample": "2017-02-03T16:20:50Z",
            "uncertaintyInMilliseconds": 0
          },
          {
            "namespace": "Alexa.ThermostatController.HVAC.Components",
            "name": "fanOperation",
            "value": "STAGE_2",
            "timeOfSample": "2017-02-03T16:20:50Z",
            "uncertaintyInMilliseconds": 0
          }
        ]
      }
    }
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.ThermostatController.HVAC.Components",
        "name": "PrimaryHeaterOperation",
        "value": "OFF",
        "timeOfSample": "2017-02-03T16:20:50Z",
        "uncertaintyInMilliseconds": 0
      },
      {
        "namespace": "Alexa.ThermostatController",
        "name": "thermostatMode",
        "value": "AUTO",
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 500
      },
      {
        "namespace": "Alexa.ThermostatController",
        "name": "targetSetpoint",
        "value": {
          "value": 18.0,
          "scale": "CELSIUS"
        },
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 500
      },
      {
        "namespace": "Alexa.TemperatureSensor",
        "name": "temperature",
        "value": {
          "value": 19.1,
          "scale": "CELSIUS"
        },
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 1000
      },
      {
        "namespace": "Alexa.EndpointHealth",
        "name": "connectivity",
        "value": {
          "value": "OK"
        },
        "timeOfSample": "2020-07-05T12:01:23Z",
        "uncertaintyInMilliseconds": 0
      }
    ]
  }
}