Alexa.DeviceUsage.Estimation Interface 1.0

Note: Sign in to the developer console to build or publish your skill.

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.

Note: Energy consumption reported with the Alexa.DeviceUsage.Estimation interface doesn't display on the Alexa energy dashboard.

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?

Provide feedback

Last updated: Nov 22, 2023