Alexa.EndpointHealth Interface 3.2
Implement the Alexa.EndpointHealth
interface in your Alexa skill so that you can report the detected health of devices to Alexa. Device health includes connectivity status, battery health, signal strength, and throughput. When a device encounters an issue, you report the reason so that Alexa can inform the customer of device degradation. Device degradation can include such things as low battery power or connectivity failure due to Wi-Fi password change.
You implement the Alexa.EndpointHealth
interface with other interfaces that provide functionality for your device. For example, if your device is a thermostat, you would implement Alexa.ThermostatController
so the user can control the thermostat, Alexa.TemperatureSensor
so the thermostat can sense and report temperature, and Alexa.EndpointHealth
so that you can report the connectivity status of the thermostat.
Alexa.EndpointHealth
to provide the best experience for your users.
Implementing Alexa.EndpointHealth
is optional, except in the following cases:- You must implement
Alexa.EndpointHealth
for devices that are sensors, such as motion sensors and temperature sensors.- You must implement
Alexa.EndpointHealth
for your device if you plan to pursue certification in the Works with Alexa or Certified for Humans program.For the list of languages that the Alexa.EndpointHealth
interface supports, see List of Alexa Interfaces and Supported Languages. For the definitions of the message properties, see Alexa Interface Message and Property Reference.
Properties and objects
The Alexa.EndpointHealth
interface includes the following properties and objects.
Connectivity property
The Connectivity
property represents the connectivity status of a device. Connectivity
is a required property.
The connectivity
property is an object that contains the following fields.
Field | Description | Type |
---|---|---|
value |
The connectivity status of the device. Valid values: OK , UNREACHABLE . |
String |
reason |
(Optional) When the device is unreachable, this property gives the failure reason. For valid values, see connectivity reasons. |
String |
Connectivity property example
{
"name": "connectivity",
"value": {
"value": "UNREACHABLE",
"reason": "WIFI_BAD_PASSWORD"
}
}
Connectivity reason values
The following table shows the valid values, descriptions, and possible resolutions for each connectivity failure reason
.
Value | Description |
---|---|
WIFI_BAD_PASSWORD |
The device failed to connect to Wi-Fi due to a bad password. |
WIFI_AP_NOT_FOUND |
The device can't find the Wi-Fi access point. The device might be too far from the router or near another device that causes interference, such as a baby monitor, microwave, or other electronic device. |
WIFI_ROUTER_UNREACHABLE |
The device can't send data to the router, or receive data from the router. The internet might be down or the router might need a reboot. |
WIFI_AP_CHANNEL_QUALITY_LOW |
The device can connect to the access point, but the channel quality is low. |
INTERNET_UNREACHABLE |
The device can connect to the access point, but doesn't have internet access. The router or device might need a reboot, or the internet might be down. |
CAPTIVE_PORTAL_CHECK_FAILED |
The device is trying to connect to a captive portal. The interface doesn't support captive portals. Airports and hotels commonly use captive portal networks. These networks ask the user to agree to specific terms before connecting to the network. The customer must select a different network. |
UNKNOWN |
The reason for connectivity failure isn't known. |
Battery property
Use the Battery
property to report the health of the device battery and/or the device charging status. This property is optional. Use this property if the device has a battery.
The Battery
property is an object that contains the following fields.
Field | Description | Type |
---|---|---|
health |
(Optional) The health of the device battery. | Health object |
chargingHealth |
(Optional) The device charging health. | ChargingHealth object |
levelPercentage |
(Optional) The battery level in percentage. Valid values: 0 – 100. |
Integer |
Battery property example
{
"name": "battery",
"value": {
"health": {
"state": "WARNING",
"reasons": [
"COLD",
"LOW_CHARGE"
]
},
"chargingHealth": {
"state": "WARNING",
"reason": "LOW_POWER"
},
"levelPercentage": 10
}
}
Health object
Use the Health
property to report the health of the device battery and, if applicable, the reasons for poor battery health. This property is optional.
The Health
property is an object that contains the following fields.
Field | Description | Type |
---|---|---|
state |
The health of the battery. WARNING indicates that the battery is working, but the customer must charge or replace the battery soon. CRITICAL indicates that the device can't operate in the current battery state. Valid values: OK , WARNING , CRITICAL . |
String |
reasons |
(Optional) When the battery health is poor, this property gives the reasons for failure. Include at least one reason. For valid values, see battery health reasons. |
Array of string |
Battery health reason values
The following table shows the valid values and descriptions of the device battery health.
Value | Description |
---|---|
COLD |
The battery is cold. |
DEAD |
The battery is dead. |
LOW_CHARGE |
The battery level is low. |
NO_BATTERY |
The device doesn't have a battery. |
OVERHEATED |
The battery overheated. |
OVER_VOLTAGE |
The device battery is receiving excess voltage. |
WIRED |
The device battery is charging, or the device is operating in wired mode. |
UNKNOWN |
The reason for the battery issue isn't known. |
ChargingHealth object
Use the chargingHealth
property to report the state of device charging and, if applicable, the reason for poor charging health. This property is optional.
The chargingHealth
property is an object that contains the following fields.
Field | Description | Type |
---|---|---|
state |
The health of charging. WARNING indicates that the device charger needs attention. CRITICAL indicates that the device charger isn't usable. Valid values: OK , WARNING , CRITICAL . |
String |
reason |
(Optional) When the charging health is poor, this property gives the reason. For valid values, see charger state reasons. | String |
Charger state reason values
The following table gives valid values and descriptions of the device charger.
Value | Description |
---|---|
LOW_POWER |
The charger power is too low for the device. |
INCOMPATIBLE_CHARGER |
The charger isn't compatible with the device. |
UNKNOWN |
The reason for the charger state isn't known. |
RadioDiagnostics property
Use the RadioDiagnostics
property to report the signal strength and other diagnostic data of the radio network to which the device connects. This property is optional.
The RadioDiagnostics
property is an array of objects that contains the following fields.
Field | Description | Type |
---|---|---|
radioType |
The communication protocol used by the device. Valid values: WIFI , BLUETOOTH , ZIGBEE , ZWAVE , BLE , BLE_MESH . |
String |
signalStrength |
Contains information about the signal strength of the radio network. | SignalStrength object |
signalToNoiseRatio |
(Optional) Contains information about the signal-to-noise ratio of the radio network. | SignalToNoiseRatio object |
RadioDiagnostics property example
{
"name": "radioDiagnostics",
"value": [
{
"radioType": "WIFI",
"signalStrength": {
"quality": "GOOD",
"rssiInDBM": -40
},
"signalToNoiseRatio": {
"snrInDB": 45,
"quality": "GOOD"
}
},
{
"radioType": "BLUETOOTH",
"signalStrength": {
"quality": "GOOD",
"rssiInDBM": -35
},
"signalToNoiseRatio": {
"snrInDB": 20,
"quality": "FAIR"
}
}
]
}
SignalStrength object
Use the SignalStrength
property to report information about the signal strength of the radio network to which the device connects. This property is optional.
The SignalStrength
property is an object that contains the following fields.
Field | Description | Type |
---|---|---|
quality |
The quality of the signal. Quality means different things for different types of devices and networks. You define how the signal strength affects your device. GOOD means that the strength is good enough for normal operation of the device. FAIR indicates that the strength is OK, but the device might have intermittent issues. POOR indicates that the signal strength is too low to operate the device. Valid values: GOOD , FAIR , POOR . |
String |
rssiInDBM |
The received signal strength indicator (RSSI) defines the approximation of the signal quality. The value is a measure of the power of the Wi-Fi signal at the receiver in decibels relative to one milliwatt (dBm). Minimum value: -1000. Maximum value: 1000. |
Integer |
SignalToNoiseRatio object
Use the SignalToNoiseRatio
property to report the signal-to-noise ratio of the radio network to which the device connects. This property is optional.
The SignalToNoiseRatio
property is an object that contains the following fields.
Field | Description | Type |
---|---|---|
quality |
Indicates how the signal-to-noise ratio affects the device performance. GOOD means that the signal-to-noise ratio is good enough for normal operation of the device. FAIR indicates that the signal-to-noise ratio is low and might cause device issues. POOR indicates that the signal-to-noise ratio is so low that it hampers the operation of the device. Valid values: GOOD , FAIR , POOR . |
String |
snrInDB |
The signal-to-noise ratio in decibels (dB). This value indicates the ratio between the desired signal strength and the power of the unwanted background noise. If the energy of the background noise is strong enough, it can affect the signal quality, even if the RSSI is high. Minimum value: 0. Maximum value: 1000. |
Integer |
NetworkThroughput property
The Alexa.EndpointHealth
interface uses the NetworkThroughput
property to report the calculated throughput of the network to which the device connects and how the throughput affects the device. This property is optional.
The NetworkThroughput
property is an object that contains the following fields.
Field | Description | Type |
---|---|---|
quality |
Indicates how the network throughput affects the device performance. You define how the throughput affects your device. GOOD means that the throughput is good enough for normal operation of the device. FAIR indicates that the throughput is intermittently low and might cause occasional device issues. POOR indicates that the throughput is so low that it hampers the operation of the device. Valid values: GOOD , FAIR , POOR . |
String |
bitsPerSecond |
(Optional) The network throughput measured in bits per second (bps). Throughput is the average data rate of successful data and message delivery over a specific communication link. Minimum value: 0. |
Long |
NetworkThroughput property example
{
"name": "networkThroughput",
"value": {
"quality": "GOOD",
"bitsPerSecond": 20000000
}
}
Discovery
You describe endpoints that support the Alexa.EndpointHealth
interface by using the standard discovery mechanism described in Alexa.Discovery
.
Set retrievable
to true
for all the properties that you report when Alexa sends your skill a state report request. Set proactivelyReported
to true
for properties that you proactively report to Alexa in a change report. When you implement Alexa.EndpointHealth
, set retrievable
to true
and proactivelyReported
to true
for the properties that you support.
connectivity
property. For Alexa to let customers know the health of their device before the customer gets frustrated, include as many of the other endpoint health properties as you can. Discover response example
The following example shows a Discover.Response
message for an endpoint that supports the Alexa.EndpointHealth
and Alexa.LockController
interfaces.
{
"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": "Sample Manufacturer",
"description": "Description to be shown in the Alexa app",
"friendlyName": "Your device name, displayed in the Alexa app, for example Front Door>",
"displayCategories": ["SMARTLOCK"],
"additionalAttributes": {
"manufacturer": "Sample Manufacturer",
"model": "Sample Model",
"serialNumber": "Serial number of the device",
"firmwareVersion": "Firmware version of the device",
"softwareVersion": "Software version of the device",
"customIdentifier": "Optional custom identifier for the device"
},
"cookie": {},
"capabilities": [{
"type": "AlexaInterface",
"interface": "Alexa.LockController",
"version": "3",
"properties": {
"supported": [{
"name": "lockState"
}],
"proactivelyReported": true,
"retrievable": true
}
},
{
"type": "AlexaInterface",
"interface": "Alexa.EndpointHealth",
"version": "3.2",
"properties": {
"supported": [{
"name": "connectivity"
},
{
"name": "battery"
},
{
"name": "radioDiagnostics"
},
{
"name": "networkThroughput"
}
],
"proactivelyReported": true,
"retrievable": true
}
},
{
"type": "AlexaInterface",
"interface": "Alexa",
"version": "3"
}
]
}]
}
}
}
Directives
The Alexa.EndpointHealth
interface doesn't define any directives itself. When you implement Alexa.EndpointHealth
, you must include the connectivity property when you respond to directives defined by other interfaces.
Directive response event example
In the following example, a device supports the Alexa.PowerController
and Alexa.EndpointHealth
interfaces, and is sending an Alexa.Response
to the Alexa.PowerController.TurnOn
directive.
{
"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": {
"properties": [{
"namespace": "Alexa.PowerController",
"name": "powerState",
"value": "ON",
"timeOfSample": "2017-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 500
},
{
"namespace": "Alexa.EndpointHealth",
"name": "connectivity",
"value": {
"value": "OK"
},
"timeOfSample": "2017-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 0
},
{
"namespace": "Alexa.EndpointHealth",
"name": "battery",
"value": {
"health": {
"state": "OK"
},
"levelPercentage": 100
},
"timeOfSample": "2021-10-15T14:20:00Z",
"uncertaintyInMilliseconds": 0
}
]
}
}
State reporting
Alexa sends a Alexa.ReportState
directive to request information about the state of an endpoint. When Alexa sends a Alexa.ReportState
directive, you send a Alexa.StateReport
event in response. The response contains the current state of all retrievable properties in the context object. You identify your retrievable properties in your discovery response. For details about state reports, see Understand State and Change Reporting.
When you implement Alexa.EndpointHealth
, include the connectivity
property in your Alexa.StateReport
.
StateReport response example
The following example shows a Alexa.StateReport
for an endpoint that supports the Alexa.EndpointHealth
, Alexa.ThermostatController
, and Alexa.TemperatureSensor
interfaces.
{
"event": {
"header": {
"namespace": "Alexa",
"name": "StateReport",
"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": {
"properties": [{
"namespace": "Alexa.ThermostatController",
"name": "thermostatMode",
"value": "HEAT",
"timeOfSample": "2017-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 500
},
{
"namespace": "Alexa.ThermostatController",
"name": "targetSetpoint",
"value": {
"value": 20.0,
"scale": "CELSIUS"
},
"timeOfSample": "2017-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 500
},
{
"namespace": "Alexa.TemperatureSensor",
"name": "temperature",
"value": {
"value": 19.9,
"scale": "CELSIUS"
},
"timeOfSample": "2017-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 1000
},
{
"namespace": "Alexa.EndpointHealth",
"name": "connectivity",
"value": {
"value": "OK"
},
"timeOfSample": "2017-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 0
},
{
"namespace": "Alexa.EndpointHealth",
"name": "battery",
"value": {
"health": {
"state": "OK"
},
"chargingHealth": {
"state": "OK"
},
"levelPercentage": 100
},
"timeOfSample": "2021-10-15T14:20:00Z",
"uncertaintyInMilliseconds": 0
}
]
}
}
Change reporting
To report changes proactively in the state of an endpoint, you send a Alexa.ChangeReport
event. You identify the properties that you report proactively in your discovery response. For details about change reports, see Understand State and Change Reporting.
When you implement Alexa.EndpointHealth
, include the connectivity
property in your Alexa.ChangeReport
.
connectivity
property has changed, put it in the payload field. If the value of the connectivity
property hasn't changed, put it in the context field.ChangeReport event with unchanged health properties example
The following example shows a Alexa.ChangeReport
for an endpoint that supports the Alexa.EndpointHealth
and Alexa.Networking.AccessController
interfaces. In this change report, the networkAccess
property value changed, and the other Alexa.EndpointHealth
properties haven't changed.
{
"event": {
"header": {
"namespace": "Alexa",
"name": "ChangeReport",
"messageId": "Unique identifier, preferably a version 4 UUID",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "OAuth2.0 bearer token"
},
"endpointId": "Endpoint ID"
},
"payload": {
"change": {
"cause": {
"type": "APP_INTERACTION"
},
"properties": [{
"namespace": "Alexa.Networking.AccessController",
"name": "networkAccess",
"value": "ALLOWED",
"timeOfSample": "2021-10-15T14:20:00Z",
"uncertaintyInMilliseconds": 0
}]
}
}
},
"context": {
"properties": [{
"namespace": "Alexa.EndpointHealth",
"name": "connectivity",
"value": {
"value": "OK"
},
"timeOfSample": "2021-10-15T14:20:00Z",
"uncertaintyInMilliseconds": 0
}, {
"namespace": "Alexa.EndpointHealth",
"name": "battery",
"value": {
"health": {
"state": "OK"
},
"chargingHealth": {
"state": "OK"
},
"levelPercentage": 100
},
"timeOfSample": "2021-10-15T14:20:00Z",
"uncertaintyInMilliseconds": 0
}, {
"namespace": "Alexa.EndpointHealth",
"name": "radioDiagnostics",
"value": [{
"radioType": "WIFI",
"signalStrength": {
"quality": "GOOD",
"rssiInDBM": -40
},
"signalToNoiseRatio": {
"snrInDB": 45,
"quality": "GOOD"
}
},
{
"radioType": "BLUETOOTH",
"signalStrength": {
"quality": "GOOD",
"rssiInDBM": -35
},
"signalToNoiseRatio": {
"snrInDB": 20,
"quality": "FAIR"
}
}
],
"timeOfSample": "2021-10-15T14:20:00Z",
"uncertaintyInMilliseconds": 0
}, {
"namespace": "Alexa.EndpointHealth",
"name": "networkThroughput",
"value": {
"quality": "GOOD",
"bitsPerSecond": 20000000
},
"timeOfSample": "2021-10-15T14:20:00Z",
"uncertaintyInMilliseconds": 0
}]
}
}
ChangeReport event with battery health changed example
The following example shows a Alexa.ChangeReport
for an endpoint that supports the Alexa.EndpointHealth
and Alexa.Networking.AccessController
interfaces. In this change report, the value of the battery
property changed, and the value of the networkAccess
property and other endpoint health properties haven't changed.
{
"event": {
"header": {
"namespace": "Alexa",
"name": "ChangeReport",
"messageId": "Unique identifier, preferably a version 4 UUID",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "OAuth2.0 bearer token"
},
"endpointId": "Endpoint ID"
},
"payload": {
"change": {
"cause": {
"type": "PERIODIC_POLL"
},
"properties": [{
"namespace": "Alexa.EndpointHealth",
"name": "battery",
"value": {
"health": {
"state": "WARNING",
"reasons": ["LOW_CHARGE"]
},
"levelPercentage": 45
},
"timeOfSample": "2021-11-15T14:20:00Z",
"uncertaintyInMilliseconds": 0
}]
}
}
},
"context": {
"properties": [{
"namespace": "Alexa.Networking.AccessController",
"name": "networkAccess",
"value": "ALLOWED",
"timeOfSample": "2021-11-15T14:20:00Z",
"uncertaintyInMilliseconds": 0
},
{
"namespace": "Alexa.EndpointHealth",
"name": "connectivity",
"value": {
"value": "OK"
},
"timeOfSample": "2021-11-15T14:20:00Z",
"uncertaintyInMilliseconds": 0
},
{
"namespace": "Alexa.EndpointHealth",
"name": "radioDiagnostics",
"value": [{
"radioType": "WIFI",
"signalStrength": {
"quality": "GOOD",
"rssiInDBM": -40
},
"signalToNoiseRatio": {
"snrInDB": 45,
"quality": "GOOD"
}
},
{
"radioType": "BLUETOOTH",
"signalStrength": {
"quality": "GOOD",
"rssiInDBM": -35
},
"signalToNoiseRatio": {
"snrInDB": 20,
"quality": "FAIR"
}
}
],
"timeOfSample": "2021-11-15T14:20:00Z",
"uncertaintyInMilliseconds": 0
}, {
"namespace": "Alexa.EndpointHealth",
"name": "networkThroughput",
"value": {
"quality": "GOOD",
"bitsPerSecond": 20000000
},
"timeOfSample": "2021-11-15T14:20:00Z",
"uncertaintyInMilliseconds": 0
}
]
}
}
Related topics
Last updated: Oct 19, 2022