Alexa.DeviceUsage.Meter Interface 1.0

Implement the Alexa.DeviceUsage.Meter interface in your Alexa add-on so that customers can view their energy use. Use the Alexa.DeviceUsage.Meter interface with your devices that measure energy use, such as electric and natural gas meters. The Alexa.DeviceUsage.Meter interface is intended to help customers 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 thermostat, use the Alexa.DeviceUsage.Estimation interface instead. Unlike other interfaces, proactive reporting isn’t optional. When you support the Alexa.DeviceUsage.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 Alexa.DeviceUsage.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 Alexa.DeviceUsage.Meter interface doesn’t have any user utterances. Instead, you send energy usage events to Alexa, so that Alexa can report energy use to the customer.

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.

Reportable properties

The Alexa.DeviceUsage.Meter interface doesn’t have any reportable properties.

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.

Configurations object

In addition to the usual discovery response fields, for Alexa.DeviceUsage.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 add-on.

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

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

{
  "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: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`	`end` timestamp of the data that you sent. Defined in ISO 8601 format, `YYYY-MM-DDThh:mm:ssZ`	String

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 add-on 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:00.00Z",
          "end": "2020-07-05T09:00:00.00Z"
        },
        {
          "usage": 101.1,
          "start": "2020-07-05T09:00:00.00Z",
          "end": "2020-07-05T10:00:00.00Z"
        },
        {
          "usage": 0,
          "start": "2020-07-05T10:00:00.00Z",
          "end": "2020-07-05T10:51:00.00Z"
        },
        {
          "usage": 127.3,
          "start": "2020-07-05T11:02:00.00Z",
          "end": "2020-07-05T12:00:00.00Z"
        }
      ]
    }
  },
  "context": {}
}

MeasurementsReport event payload

You must include at least one of the following fields in the payload:

electricityIntervals
naturalGasIntervals

The following table shows the payload details for the DIR directive.

Property	Description	Type	Required
`electricityIntervals`	Amount of electricity used over a period of time. You must include at least one of `electricityIntervals` or `naturalGasIntervals`.	Array of objects	No
`electricityIntervals[].usage`	Amount of energy used between the `start` and `end` interval.	Number	Yes
`electricityIntervals[].start`	Start time of the interval. Defined in ISO 8601 format, `YYYY-MM-DDThh:mm:ssZ`	String	Yes
`electricityIntervals[].end`	End time of the interval. Defined in ISO 8601 format, `YYYY-MM-DDThh:mm:ssZ`	String	Yes
`naturalGasIntervals`	Amount of natural gas used over a period of time. You must include at least one of `electricityIntervals` or `naturalGasIntervals`.	Array of objects	No
`naturalGasIntervals[].usage`	Amount of energy used between the `start` and `end` interval.	Number	Yes
`naturalGasIntervals[].start`	Start time of the interval. Defined in ISO 8601 format, `YYYY-MM-DDThh:mm:ssZ`	String	Yes
`naturalGasIntervals[].end`	End time of the interval. Defined in ISO 8601 format, `YYYY-MM-DDThh:mm:ssZ`	String	Yes

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.

Get Started

Connect Your Device to Alexa

Certify Your Device

Developer Reference

Alexa.DeviceUsage.Meter Interface 1.0

Utterances

Data measurement resolution

Reportable properties

Discovery

Configurations object

Discover response example

Directives and events

ReportMeasurements directive

ReportMeasurements directive example

ReportMeasurements response

ReportMeasurements directive error handling

ReduceResolution directive

ReduceResolution directive example

ReduceResolution directive payload

ReduceResolution response

ReduceResolution directive error handling

InvalidMeasurementError directive

InvalidMeasurementError directive example

InvalidMeasurementError directive payload

InvalidMeasurementError response

InvalidMeasurementError directive error handling

MeasurementsReport event

MeasurementsReport event example

MeasurementsReport event payload

AddOrUpdateReport

AddOrUpdateReport event example

Troubleshooting

Error codes

Other possible issues

​Utterances

​Data measurement resolution

​Reportable properties

​Discovery

​Configurations object

​Discover response example

​Directives and events

​ReportMeasurements directive

​ReportMeasurements directive example

​ReportMeasurements response

​ReportMeasurements directive error handling

​ReduceResolution directive

​ReduceResolution directive example

​ReduceResolution directive payload

​ReduceResolution response

​ReduceResolution directive error handling

​InvalidMeasurementError directive

​InvalidMeasurementError directive example

​InvalidMeasurementError directive payload

​InvalidMeasurementError response

​InvalidMeasurementError directive error handling

​MeasurementsReport event

​MeasurementsReport event example

​MeasurementsReport event payload

​AddOrUpdateReport

​AddOrUpdateReport event example

​Troubleshooting

​Error codes

​Other possible issues

​Related topics

Utterances

Data measurement resolution

Reportable properties

Discovery

Configurations object

Discover response example

Directives and events

ReportMeasurements directive

ReportMeasurements directive example

ReportMeasurements response

ReportMeasurements directive error handling

ReduceResolution directive

ReduceResolution directive example

ReduceResolution directive payload

ReduceResolution response

ReduceResolution directive error handling

InvalidMeasurementError directive

InvalidMeasurementError directive example

InvalidMeasurementError directive payload

InvalidMeasurementError response

InvalidMeasurementError directive error handling

MeasurementsReport event

MeasurementsReport event example

MeasurementsReport event payload

AddOrUpdateReport

AddOrUpdateReport event example

Troubleshooting

Error codes

Other possible issues

Related topics