Alexa.DeviceUsage.Meter Interface
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. For details about Smart Home skills, see Understand the Smart Home Skill API.
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.
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 languages that the Meter
interface supports, see List of Alexa Interfaces and Supported Languages.
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": "<message id>"
},
"payload": {
"endpoints": [
{
"endpointId": "<unique ID of the endpoint>",
"manufacturerName": "<the manufacturer name of the endpoint>",
"description": "<a description that is 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
ReportMeasurements
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": "<message id>",
"correlationToken": "<an opaque correlation token>",
"payloadVersion": "1.0"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "<an OAuth2 bearer token>"
},
"endpointId": "<endpoint id>",
"cookie": {}
},
"payload": {}
}
}
ReportMeasurements response event
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.
ReportMeasurements response event example
{
"event": {
"header": {
"namespace": "Alexa",
"name": "Response",
"messageId": "<message id>",
"correlationToken": "<an opaque correlation token>",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "<an OAuth2 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
Support the ReduceResolution
directive so that Alexa can notify you when you are sending messages to the Alexa event gateway too frequently.
ReduceResolution directive payload details
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 directive example
The following example illustrates a ReduceResolution
directive that Alexa sends to your skill.
{
"directive": {
"header": {
"namespace": "Alexa.DeviceUsage.Meter",
"name": "ReduceResolution",
"messageId": "<message id>",
"correlationToken": "<an opaque correlation token>",
"payloadVersion": "1.0"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "<an OAuth2 bearer token>"
},
"endpointId": "<endpoint id>",
"cookie": {}
},
"payload": {
"limit": 7200,
"duration": "PT6H"
}
}
}
ReduceResolution response event
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.
ReduceResolution response event example
{
"event": {
"header": {
"namespace": "Alexa",
"name": "Response",
"messageId": "<message id>",
"correlationToken": "<an opaque correlation token>",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "<an OAuth2 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
Support the InvalidMeasurementError
directive so that Alexa can notify you when you have sent an invalid data point.
InvalidMeasurementError directive payload details
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 directive example
The following example illustrates a InvalidMeasurementError
directive that Alexa sends to your skill.
{
"directive": {
"header": {
"namespace": "Alexa.DeviceUsage.Meter",
"name": "InvalidMeasurementError",
"messageId": "<message id>",
"correlationToken": "<an opaque correlation token>",
"payloadVersion": "1.0"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "<an OAuth2 bearer token>"
},
"endpointId": "<endpoint id>",
"cookie": {}
},
"payload": {
"electricity": {
"errorCode": "NEGATIVE_VALUE",
"timeOfError": "2020-07-05T12:00:00Z"
}
}
}
}
InvalidMeasurementError response event
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.
InvalidMeasurementError response event example
{
"event": {
"header": {
"namespace": "Alexa",
"name": "Response",
"messageId": "<message id>",
"correlationToken": "<an opaque correlation token>",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "<an OAuth2 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
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 payload details
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.
MeasurementsReport event example
{
"event": {
"header": {
"namespace": "Alexa.DeviceUsage.Meter",
"name": "MeasurementsReport",
"messageId": "<a unique identifier, preferably a version 4 UUID>",
"payloadVersion": "1.0"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "<an OAuth2 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": {}
}
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": "<message id>"
},
"payload": {
"endpoints": [
{
"endpointId": "<unique ID of the endpoint>",
"manufacturerName": "<the manufacturer name of the endpoint>",
"description": "<a description that is 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.