Subscribing to Device Online or Offline Status

Developer Programs
1

Hi all,

I am trying to subscribe to detect when the state of my device goes from online to offline but I am confused to what capability to subscribe to and where to update them. The device handler I am using is located here.

Reading the documentation on Health Check when I issue a GET request to the endpoint

/devices/<deviceId>/health

This is actually updating my device status to online or offline, it returns something like the response below

{
    "deviceId": "daf43d66-6c3b-4553-80af-6a0b1cf97418",
    "state": "OFFLINE",
    "lastUpdatedDate": "2020-11-26T20:08:08.217Z"
}

Which capability is this tied to in my device handler?
How should I update the capability in the device handler?
Where should I update in the device handler?

The device handler does have the capability "Health Check" in its definition but it is not updated anywhere in the device handler. However the above endpoint still seems to updating my device.

When I issue a request to get the status of a device at the endpoint

https://api.smartthings.com/v1/devices/{Device_ID}/status

I can see the status of the Health Check capabaility, one of its attributes is healthStatus but it has a constant value of null.

"healthCheck": {
                "checkInterval": {
                    "value": 1860,
                    "unit": "s",
                    "data": {
                        "protocol": "zwave",
                        "hubHardwareId": "0036",
                        "offlinePingable": "0",
                        "deviceScheme": "TRACKED"
                    },
                    "timestamp": "2020-11-26T13:11:50.222Z"
                },
                "healthStatus": {
                    "value": null,
                    "data": {},
                    "timestamp": "2020-11-26T13:14:39.628Z"
                },
                "DeviceWatch-Enroll": {
                    "value": null,
                    "timestamp": "2020-11-26T13:14:36.830Z"
                },
                "DeviceWatch-DeviceStatus": {
                    "value": null,
                    "data": {},
                    "timestamp": "2020-11-26T13:14:39.657Z"
                }
            }

I do set the checkInterval in the installed function. (This was there by default in the original device handler I haven’t changed it)

def installed() {
	log.debug "installed()..."
	sendEvent(name: "checkInterval", value: 1860, displayed: false, data: [protocol: "zwave", hubHardwareId: device.hub.hardwareID, offlinePingable: "0"])
	response(refresh())
}

The end goal is to subscribe to the devices capability which monitors its status if its online/offline using the Node SDK but I’d like to know how and where this is updating in the device handler.

Any help on Health Check or Health Status is welcome!

2

You could create a schedule to make the request to /devices/<deviceId>/health and when the device is offline, send the event to DeviceWatch-DeviceStatus.
For you to take control over the DeviceWatch events, you need to enroll as follows:

//initialize
sendEvent(name: "DeviceWatch-DeviceStatus", value: "online")
sendEvent(name: "DeviceWatch-Enroll", value: [protocol: "cloud", scheme:"untracked"].encodeAsJson(), displayed: false)

//event to change the deviceStatus
sendEvent(name: "DeviceWatch-DeviceStatus", value: "offline")

Then, to create the subscription for a specific device health you’ll have to use that attribute.

context.api.subscriptions.subscribeToDevices(deviceConfig, 'healthCheck', 'DeviceWatch-DeviceStatus', 'healthEventHandler')

//payload example
{
  eventId: 'xxxx-xxxx-xxxx',
  locationId: 'xxxx-xxxx-xxxx',
  ownerId: 'xxxx-xxxx-xxxx',
  ownerType: 'LOCATION',
  deviceId: 'xxxx-xxxx-xxxx',
  componentId: 'main',
  capability: 'healthCheck',
  attribute: 'DeviceWatch-DeviceStatus',
  value: 'offline',
  valueType: 'string',
  stateChange: true,
  data: {},
  subscriptionName: 'healthEventHandler_0'
}

Or, you can use the health subscription part of the SDK, this is at a location level, so, you will receive the events from all the devices in it.

context.api.subscriptions.subscribeToDeviceHealth('healthEventHandler')

//eventHandler
.subscribedDeviceHealthEventHandler('healthEventHandler', (context, event) => {  })

//payload example
{
  eventId: 'xxxx-xxxx-xxxx',
  locationId: 'xxxx-xxxx-xxxx',
  deviceId: 'xxxx-xxxx-xxxx',
  hubId: 'xxxx-xxxx-xxxx',
  status: 'ONLINE',
  reason: 'NONE'
}
3

Hi @nayelyz,
Thanks for the reply!

What is called in the device handler when a device goes offline? Like is there a function called or?

Where would be best place to put this code in a device handler?