Alexa.DeviceUsage.Estimation Interface 1.0

Implement the Alexa.DeviceUsage.Estimation interface in your Alexa skill so that users can view an estimate of their energy use. Use the Estimation interface with your devices that don't measure energy use directly, such as light bulbs and televisions. The Estimation interface is intended to help users manage their energy usage with the Alexa energy dashboard. For details, see Smart Home Energy Overview.

If your device is capable of directly measuring and reporting energy consumption, such as a meter, use the Alexa.DeviceUsage.Meter interface instead.

The Estimation interface defines no properties or directives, and doesn't participate in state or change reporting. Instead, you provide a profile of your power consumption in your discovery response.

For the list of locales that the DeviceUsage.Estimation 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 Estimation 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 your typical energy consumption, so that Alexa can estimate energy use for the user. There are no user utterances associated with this interface.

Power profiles

The power profile object defines the typical power consumption of your device.

Power profile types

The following are the power profile types. You must implement all the required interfaces for the power profile that you select.

Type Description Required Interfaces
POWER Use this profile when the power consumption of your device has two power states; on and off. - PowerController
BRIGHTNESS Use this profile when the power consumption of your device varies based on the brightness of the device, such as a dimmable light bulb. - PowerController
- BrightnessController
BRIGHTNESS_COLOR Use this profile when the power consumption of your device varies based on the brightness and color of the device, such as a color-changing light bulb. - PowerController
- BrightnessController
- ColorController

The power quantity object

Power quantity object details

Field Description Type Required
value The value of the amount of energy. Number Yes
units The unit of energy measurement. Currently, the only valid value is WATTS. String Yes

The powerProfile object

powerProfile object details

Field Description Type Required
type The type of power profile. One of POWER, BRIGHTNESS, BRIGHTNESS_COLOR. String Yes
standbyWattage The energy the device consumes while turned off, or in standby mode. This can be zero, but typically devices draw a small, non-zero amount of energy when off. A power quantity object. Yes
maximumWattage The maximum energy the device consumes while turned on. A power quantity object. Yes, when type is BRIGHTNESS or BRIGHTNESS_COLOR.
onWattage The typical energy the device consumes while turned on. A power quantity object. Yes, when type is POWER.

powerProfile object example

Copied to clipboard.

{
    "powerProfile": {
        "type": "BRIGHTNESS",
        "standbyWattage": {
            "value": 0.5,
            "units": "WATTS"
        },
        "maximumWattage": {
            "value": 7,
            "units": "WATTS"
        }
    }
}

Discovery

You describe endpoints that support Alexa.DeviceUsage.Estimation using the standard discovery mechanism described in Alexa.Discovery.

For the full list of display categories, see display categories.

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

Discover response example

The following example shows a Discover.Response message for a light bulb that supports the Alexa.DeviceUsage.Estimation and Alexa.PowerController interfaces.

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": "Description to be shown in the Alexa app",
          "friendlyName": "Device name, displayed in the Alexa app",
          "displayCategories": ["LIGHT"],
          "cookie": {},
          "capabilities": [
            {
              "type": "AlexaInterface",
              "interface": "Alexa.PowerController",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "powerState"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              }
            },

            {
              "type": "AlexaInterface",
              "interface": "Alexa.DeviceUsage.Estimation",
              "version": "1.0",
              "configuration": {
                "powerProfile": {
                  "type": "POWER",
                  "standbyWattage": {
                    "value": 0.5,
                    "units": "WATTS"
                  },
                  "onWattage": {
                    "value": 5,
                    "units": "WATTS"
                  }
                }
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa",
              "version": "3"
            }
          ]
        }
      ]
    }
  }
}

Last updated: Oct 19, 2022