Alexa.DeviceUsage.Meter Interface 1.0
Implement the Alexa.DeviceUsage.Meter
interface in your Alexa skill so that users can view their energy use. Use the Meter
interface with your devices that measure energy use, such as electricity and natural gas meters. The Meter
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 doesn't measure energy consumption directly, such as a light bulb or a television, use the Alexa.DeviceUsage.Estimation interface instead.
Unlike other interfaces, proactive reporting isn't optional. When you support the Meter
interface, you must send proactive events to the Alexa event gateway. You are required to send MeasurementsReport events.
For the list of locales that the Meter
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 Meter
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.
Data measurement resolution
You set a default resolution, in seconds, for how often you report data measurements of energy use. Amazon recommends a minimum resolution of 3,600 (hourly) and a maximum resolution of 86,400 (daily).
The resolution you specify determines how the data appears to the user. Alexa doesn't assume a constant rate of energy use between data points, and doesn't imply that to the user. Unless there is an extended period of zero energy use, your data reporting shouldn't fall below your default resolution.
If you report data more frequently than hourly, your data isn't all recorded.
If you report data less frequently than daily, useful data doesn't appear to the user.
Properties and objects
Interval objects
Interval objects represent the amount of energy used over a period of time.
Interval object details
Field | Description | Type | Required |
---|---|---|---|
usage |
The amount of energy used during the period of time between start and end . |
Number | Yes |
start |
The start time of the interval. | A string in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ . |
Yes |
end |
The end time of the interval. | A string in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ . |
Yes |
Interval object example
{
"usage": 113.2,
"start": "2020-07-05T08:00:00Z",
"end": "2020-07-05T09:00:00Z"
}
Discovery
You describe endpoints that support Alexa.DeviceUsage.Meter
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 Meter
, include a configurations
object that contains an energySources
object that contains an electricity
object, a naturalGas
object, or both. The electricity
object and the naturalGas
object each contain the following fields.
Field | Description | Type |
---|---|---|
unit |
The unit of measure for the energy source. One of MILLIWATT_HOUR , BTU , CUBIC_FOOT . |
String |
measuringMethod |
The method you use to measure energy use. MEASURED if your device has dedicated hardware to physically measure energy use; otherwise, ESTIMATED . |
String |
defaultResolution |
The resolution of your data readings, in seconds. Amazon recommends a minimum resolution of 3,600 (hourly) and a maximum resolution of 86,400 (daily). For details, see data measurement resolution. | Number |
Discover response example
The following example shows a Discover.Response
message for a meter that supports the Alexa.DeviceUsage.Meter
interface.
{
"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": "Meter",
"displayCategories": ["OTHER"],
"cookie": {},
"capabilities": [
{
"type": "AlexaInterface",
"interface": "Alexa.DeviceUsage.Meter",
"version": "1.0",
"configurations": {
"energySources": {
"electricity": {
"unit": "MILLIWATT_HOUR",
"measuringMethod": "ESTIMATED",
"defaultResolution": 3600
},
"naturalGas": {
"unit": "CUBIC_FOOT",
"measuringMethod": "MEASURED",
"defaultResolution": 86400
}
}
}
},
{
"type": "AlexaInterface",
"interface": "Alexa",
"version": "3"
}
]
}
]
}
}
}
Directives and events
The Alexa.DeviceUsage.Meter
interface defines the following directives and events.
ReportMeasurements directive
Support the ReportMeasurements
directive so that Alexa can request data from you. The payload of the ReportMeasurements
directive is empty.
ReportMeasurements directive example
The following example illustrates a ReportMeasurements
directive that Alexa sends to your skill.
{
"directive": {
"header": {
"namespace": "Alexa.DeviceUsage.Meter",
"name": "ReportMeasurements",
"messageId": "Unique version 4 UUID",
"correlationToken": "Opaque correlation token",
"payloadVersion": "1.0"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "OAuth2.0 bearer token"
},
"endpointId": "Endpoint ID",
"cookie": {}
},
"payload": {}
}
}
ReportMeasurements response
If you handle a ReportMeasurements
directive successfully, first respond with an Alexa.Response event. You can respond synchronously or asynchronously. If you respond asynchronously, include a correlation token and a scope with an authorization token. The payload for the response is empty.
After you send your Response
event, send a MeasurementsReport event to report your data to Alexa.
The following example shows a ReportMeasurements
response.
{
"event": {
"header": {
"namespace": "Alexa",
"name": "Response",
"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": {}
}
ReportMeasurements directive error handling
If you can't handle a ReportMeasurements
directive successfully, respond with an Alexa.ErrorResponse event.
ReduceResolution directive
Support the ReduceResolution
directive so that Alexa can notify you when you are sending messages to the Alexa event gateway too frequently.
ReduceResolution directive example
The following example illustrates a ReduceResolution
directive that Alexa sends to your skill.
{
"directive": {
"header": {
"namespace": "Alexa.DeviceUsage.Meter",
"name": "ReduceResolution",
"messageId": "Unique version 4 UUID",
"correlationToken": "Opaque correlation token",
"payloadVersion": "1.0"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "OAuth2.0 bearer token"
},
"endpointId": "Endpoint ID",
"cookie": {}
},
"payload": {
"limit": 7200,
"duration": "PT6H"
}
}
}
ReduceResolution directive payload
Field | Description | Type |
---|---|---|
limit |
The upper bound for the resolution of the data you report to Alexa, in seconds. This limit overrides the defaultResolution that you report in your discovery response. If you continue to report data at a higher resolution, you might encounter throttling exceptions, and some data points might be dropped. |
Number |
duration |
Reduce the resolution for this amount of time. The time period is represented in ISO 8601 duration format. If the duration field isn't present, reduce the resolution until you receive a new ReduceResolution directive. |
String |
ReduceResolution response
If you handle a ReduceResolution
directive successfully, respond with an Alexa.Response event. You can respond synchronously or asynchronously. If you respond asynchronously, include a correlation token and a scope with an authorization token. The payload for the response is empty.
The following example shows a ReduceResolution
response.
{
"event": {
"header": {
"namespace": "Alexa",
"name": "Response",
"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": {}
}
ReduceResolution directive error handling
If you can't handle a ReduceResolution
directive successfully, respond with an Alexa.ErrorResponse event.
InvalidMeasurementError directive
Support the InvalidMeasurementError
directive so that Alexa can notify you when you have sent an invalid data point.
InvalidMeasurementError directive example
The following example illustrates a InvalidMeasurementError
directive that Alexa sends to your skill.
{
"directive": {
"header": {
"namespace": "Alexa.DeviceUsage.Meter",
"name": "InvalidMeasurementError",
"messageId": "Unique version 4 UUID",
"correlationToken": "Opaque correlation token",
"payloadVersion": "1.0"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "OAuth2.0 bearer token"
},
"endpointId": "Endpoint ID",
"cookie": {}
},
"payload": {
"electricity": {
"errorCode": "NEGATIVE_VALUE",
"timeOfError": "2020-07-05T12:00:00Z"
}
}
}
}
InvalidMeasurementError directive payload
The payload contains a field named electricity
or naturalGas
. The field is an object that contains the following fields.
Field | Description | Type |
---|---|---|
errorCode |
The error code for the invalid data, such as NEGATIVE_VALUE . For the full list of error codes, see error codes. |
String |
timeOfError |
The end timestamp of the data that you sent. |
A string in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ . |
InvalidMeasurementError response
If you handle a InvalidMeasurementError
directive successfully, respond with an Alexa.Response event. You can respond synchronously or asynchronously. If you respond asynchronously, include a correlation token and a scope with an authorization token. The payload for the response is empty.
The following example shows an InvalidMeasurementError
response.
{
"event": {
"header": {
"namespace": "Alexa",
"name": "Response",
"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": {}
}
InvalidMeasurementError directive error handling
If you can't handle a InvalidMeasurementError
directive successfully, respond with an Alexa.ErrorResponse event.
MeasurementsReport event
Send a MeasurementsReport
event to the Alexa event gateway to proactively report a batch of one or more energy use measurements to Alexa.
Send MeasurementsReport
events to the Alexa event gateway at times that are uniformly distributed throughout the day, to the second, for all events generated by your skill for all customers. For example, you can add a random wait time to each event before sending it. You can send batches of data based on the size and age of the data, instead of the time of day.
MeasurementsReport event example
{
"event": {
"header": {
"namespace": "Alexa.DeviceUsage.Meter",
"name": "MeasurementsReport",
"messageId": "Unique identifier, preferably a version 4 UUID",
"payloadVersion": "1.0"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "OAuth2.0 bearer token"
},
"endpointId": "Endpoint ID"
},
"payload": {
"electricityIntervals": [
{
"usage": 113.2,
"start": "2020-07-05T08:00:00Z",
"end": "2020-07-05T09:00:00Z"
},
{
"usage": 101.1,
"start": "2020-07-05T09:00:00Z",
"end": "2020-07-05T10:00:00Z"
},
{
"usage": 0,
"start": "2020-07-05T10:00:00Z",
"end": "2020-07-05T10:51:30Z"
},
{
"usage": 127.3,
"start": "2020-07-05T11:02:30Z",
"end": "2020-07-05T12:00:00Z"
}
]
}
},
"context": {}
}
MeasurementsReport event payload
The payload for the MeasurementsReport contains at least one of the following fields:
electricityIntervals
— An array of Interval objects.naturalGasIntervals
— An array of Interval objects.
AddOrUpdateReport
You must proactively send an Alexa.Discovery.AddOrUpdateReport
message if the feature support of your endpoint changes. For example, if you change your default reporting schedule from hourly to daily you must send an AddOrUpdateReport
message. For details, see AddOrUpdateReport event.
AddOrUpdateReport event example
{
"event": {
"header": {
"namespace": "Alexa.Discovery",
"name": "AddOrUpdateReport",
"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": "Meter",
"displayCategories": ["OTHER"],
"cookie": {},
"capabilities": [
{
"type": "AlexaInterface",
"interface": "Alexa.DeviceUsage.Meter",
"version": "1.0",
"configurations": {
"energySources": {
"electricity": {
"unit": "MILLIWATT_HOUR",
"measuringMethod": "ESTIMATED",
"defaultResolution": 86400
},
"naturalGas": {
"unit": "CUBIC_FOOT",
"measuringMethod": "MEASURED",
"defaultResolution": 86400
}
}
}
},
{
"type": "AlexaInterface",
"interface": "Alexa",
"version": "3"
}
]
}
]
}
}
}
Troubleshooting
Error codes
The following are the error codes that Alexa sends in the InvalidMeasurementError directive.
Error Code | Description |
---|---|
NEGATIVE_VALUE |
You reported a negative value for energy usage. |
IN_FUTURE |
You reported a value with a timestamp in the future. Any data reported with a timestamp that's more than a few seconds in the future is rejected. A few seconds is considered a minor clock inaccuracy. |
INVALID_INTERVAL_START_END |
You reported an interval that starts after it ends. |
INTERVAL_OVERLAP |
You reported an interval that overlaps with an interval that you reported previously. |
Other possible issues
Alexa sends an InvalidMeasurementError directive that contains an error code if you send invalid data. If you send messages to the Alexa Gateway too frequently, Alexa sends you a ReduceResolution directive.
In addition, if you notice unexpected behavior, consider the following issues:
- Avoid sending duplicate data to the Alexa Event Gateway.
- Alexa expects your data to be as current as possible. Don't send data that's more than one day old.
- It's important for timestamps to be accurate. Synchronize with Coordinated Universal Time (UTC) regularly.
- Intervals shouldn't be longer than the
defaultResolution
you sent in your discovery response. - In case the device resets unexpectedly, gaps between intervals can occur.
- Send batched updates in chronological order.
Related topics
Last updated: Oct 19, 2022