Health check

Devices connected to SmartThings Cloud may go offline for any number of reasons such as hardware or network problems. In order to provide better visibility for users of the system, the device health service will keep track of connected devices and hubs. Based on the configuration of the health settings for the device or hub, the service will determine the health of the connectivity. As the checks occur, the device or hub will be marked offline if it does not respond in the specified amount of time.

You can track a device's connectivity by having the device opt in to use the health check feature.

  • Device health relates to a device's connectivity, signal strength, battery, and other health-related events such as tamper or malfunction alerts.
  • Hub health relates to a hub's connectivity.
  • Health check is a routine on the SmartThings platform that updates the connectivity status of a device or hub.

The device and hub health APIs are used to track the health status of a device or hub.

Opt in for health check

Devices must opt-in to have its health status checked on the platform. To enroll, the capability must be set when the device is installed. Please note that hubs do not need to be explicitly enrolled, when a hub is onboarded it is automatically enrolled by the system.

Connectivity definitions

A device's connection state can have one of three values:

  • ONLINE means a device can be expected to respond to a command (actuator devices) or report an event (sensor devices).
  • UNHEALTHY means a device has been inactive longer than its designated health check interval. This is an intermediate state indicating that a device is possibly offline. This state can be caused by high network latency, low battery, or tamper events on security devices.
  • OFFLINE means a device with UNHEALTHY status cannot be contacted by the platform. The check interval is defined at the following link.

A hub's connectivity can have the following values:

  • CONNECTED means that a "hub connected" event has been received by SmartThings Cloud, and no "hub disconnected" event has been received.
  • DISCONNECTED means that a "hub disconnected" event has been received by SmartThings Cloud, and no "hub connected" event has been received in the last 60 seconds.

When a hub goes offline, all devices connected to this hub will also be marked OFFLINE.

Authorization

You must pass an OAuth token in the request header when calling each of the below API methods.

Example

Authorization: Bearer <token>

Health API

Get device health

GET /devices/<deviceId>/health

This call returns the health of a device by its ID. You must include deviceID in the path to specify a device.

OAuth scope: r:devices

Example response

{
  "deviceId": "string",
  "state": "ONLINE",
  "lastUpdatedDate": "2019-08-21T18:28:45Z"
}

The JSON response lists the connection state of the device and its lastUpdatedDate. The latter value is the timestamp of the last known state change of the device.

Get hub health

GET /installed-hubs/<hubDeviceId>/health

This call returns the health of a hub by its ID. You must include hubDeviceID in the path to specify a hub.

OAuth scope: r:hubs

Example response

{
  "hubId": "string",
  "connectivity": "CONNECTED",
  "lastUpdatedDate": "2019-08-21T18:28:45Z"
}

The JSON response lists the connectivity status of the, its lastUpdatedDate, and the hubRadioState, which indicates the state of the Bluetooth, Zigbee, and ZWave radios on the hub.

See also