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

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

Copied to clipboard.

{
    "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.

Copied to clipboard.

{
  "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

Copied to clipboard.

{
  "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

Copied to clipboard.

{
  "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

Copied to clipboard.

{
  "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

Copied to clipboard.

{  
  "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

Copied to clipboard.

{
  "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.