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.
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.
A device's connection
state can have one of three values:
ONLINEmeans a device can be expected to respond to a command (actuator devices) or report an event (sensor devices).
UNHEALTHYmeans 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.
OFFLINEmeans a device with
UNHEALTHYstatus cannot be contacted by the platform. The check interval is defined here.
connectivity can have the following values:
CONNECTEDmeans that a "hub connected" event has been received by SmartThings Cloud, and no "hub disconnected" event has been received.
DISCONNECTEDmeans 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
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
This call returns the health of a device by its ID. You must include
deviceID in the path to specify a device.
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.
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
This call returns the health of a hub by its ID. You must include
hubDeviceID in the path to specify a hub.
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.