Alexa.DeviceUsage.Estimation Interface 1.0


Implement the Alexa.DeviceUsage.Estimation interface in your Alexa skill to report an estimate of your device energy use. Use the Alexa.DeviceUsage.Estimation interface with your devices that don't measure energy use directly, such thermostats. 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. If your device has a thermostat connected to an HVAC system, you can use the Alexa.ThermostatController.HVAC.Components interface to report estimated energy consumption instead.

The Alexa.DeviceUsage.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 Alexa.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 Alexa.DeviceUsage.Estimation interface doesn't have any user utterances. Instead, your skill communicates with Alexa about your typical energy consumption, so that Alexa can estimate energy usage for the user.

Power profiles

The power profile defines the typical power consumption of your device. The following tables shows the supported power profile types. You must implement all the required interfaces for the power profile that you select. Include the power profile in your discovery response.

Type Description Required interfaces

POWER

Use this profile when the power consumption of your device has two power states: on and off..

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

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

Alexa.PowerController
Alexa.BrightnessController
Alexa.ColorController

PowerProfile object

Use the PowerProfile object to define the power profile that your endpoint uses.

The following example shows a power profile for a light bulb.

Copied to clipboard.

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

The following table shows the properties of the PowerProfile object.

Property Description Type Required

type

Type of power profile.
Valid values: POWER, BRIGHTNESS, BRIGHTNESS_COLOR.

String

Yes

standbyWattage

Energy the device consumes when it's off, or in standby mode. You can set amount to zero, but typically devices draw a small, non-zero amount of energy when turned off.

PowerQuantity object

Yes

maximumWattage

Maximum amount of energy that the device consumes when it's on.
Include when type is BRIGHTNESS or BRIGHTNESS_COLOR.

PowerQuantity object

No

onWattage

Typical amount of energy that the device consumes when it's on.
Include when type is POWER.

PowerQuantity object

No

PowerQuantity object

The PowerQuantity object defines the amount of energy consumed.

Property Description Type Required

value

Amount of energy.

Number

Yes

units

Unit of energy measurement.
Valid value: WATTS.

String

Yes

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 Alexa.DeviceUsage.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.EndpointHealth",
                        "version": "3",
                        "properties": {
                            "supported": [{
                                "name": "connectivity"
                            }],
                            "proactivelyReported": true,
                            "retrievable": true
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa",
                        "version": "3"
                    }
                ]
            }]
        }
    }
}

Was this page helpful?

Last updated: Nov 22, 2023