Skip to main content

Check Your Device's Health

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

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

Device health does not account for some issues that impact devices. Some of these include joining or removing devices, device firmware updates, problems updating the device state on the client, and platform-event loss.

Please note that push notifications are not enabled in this release. Push notifications for health related events will be implemented at a later time.

The Devices API is used to track the health status of a device or hub.

Opt-in for Health Check​

Devices must opt-in to have their health status checked on the Platform. To enroll, the healthCheck capability must be set when the device is installed. Hubs do not need to be explicitly enrolled; when a hub is onboarded it is automatically enrolled.

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

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.

Use the Devices API to Check Device and Hub Health​

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

Authorization: Bearer <token>

For information on using tokens, see Authorization and Permissions.

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.

note

Regular "online" events sent by a device are not considered state changes. lastUpdatedDate will record when an "offline" event is sent.

Get a Hub's 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 hub, its lastUpdatedDate, and the hubRadioState, which indicates the state of the Bluetooth, Zigbee, and ZWave radios on the hub.