Can someone explain HealthCheck, checkinterval, healthStatus, DeviceWatch-Enroll and DeviceWatch-DeviceStatus?

Developer Programs
1

Hi all,

I am reading the Health Check documentation and it is extremely vague.

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.

I get this point I think, in my device handler I need to have:

capability "Health Check"

Cant seem to find it in the capability reference though.

Querying my endpoint https://api.smartthings.com/v1/devices/{device_ID}/status the healthCheck capability is there and it has 4 attributes:

  1. checkInterval
  2. healthStatus
  3. DeviceWatch-Enroll
  4. DeviceWatch-DeviceStatus

checkinterval

Taken from the Health Check documentation

  • Health check is a routine on the SmartThings platform that updates the connectivity status of a device or hub.

Is the routine check Interval that I see defined in a lot of device handlers installed methods? Something like shown below?

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

If so where is the documentation on checkInterval?
How does checkInterval determine if a device is online/offline?
What attribute does checkInterval change?
What is offlinePingable?

healthStatus

This is constantly a value of null and does not seem to update at all even when the checkInterval is set in the device handler.

How is healthStatus updated?
Is it linked in anyway to checkInterval?
Do you have to manually update this?

DeviceWatch-Enroll

I have had some luck with this but still don’t understand why I need it if I have checkInterval setup why am I enrolling the device as well?
What am I enrolling into here?
@nayelyz gave a snippet here on what to put in your handler if you want to use it.

DeviceWatch-DeviceStatus

This one seems to be linked to the DeviceWatch-Enroll somehow. You can update the state of it by using the code shown in the snippet below.

sendEvent(name: "DeviceWatch-DeviceStatus", value: "online")
sendEvent(name: "DeviceWatch-DeviceStatus", value: "offline")

The above code does work to change the value of the device to either online or offline at the endpoint https://api.smartthings.com/v1/devices/{Device_ID}/health

How should this be used in a device handler practically through?
How could you ping a device and then detect no response in the device handler using the ping method?
Maybe a timer and if the device hasn’t received a message in X amount of time set online or offline?
Has anyone done something like this in there device handler?
Should you do something like this or leave it to checkInterval and whatever I have enrolled in with DeviceWatch-Enroll

The most detailed explanation I have seen is from @orangebucket here but even he is gives a warning that it should be taken lightly as there is no information on the subject.

Any clarity on how to monitor, update and keep track of a device status properly would be of help!

Thanks,
Warren

2

You’re right, and you can query the capability definition in the API using the SmartThings CLI.

smartthings capabilities healthCheck -j

Here’s the feedback I collected for your questions:

Check Interval

There’s no official documentation about checkInterval, but here I can clarify your doubts.

Yes, remember the value is in seconds.

When the hub hasn’t received a message from a device within the checkInterval time, it will ping the device.
For example, if the checkInterval for a device is 1 hour (3,600 seconds) and the hub has not received a message from it in the past 60 minutes then the hub will ping the device.

Not sure what is being asked. Do you mean, if an attribute changes when the ping command isn’t successful?

This is a deprecated method of prioritizing checking the status of certain high-priority devices. This value is currently ignored and can be removed.

This method is called once the checkInterval has run out.

Health Status

This is not actively used and can be ignored.

DeviceWatch

DeviceWatch-DeviceStatus is only needed when manually setting a device as online or offline such as cloud-connected devices that use a Groovy device handler.

For the vast majority of devices, setting checkInterval is the only needed action to track a device.
DeviceWatch-Enroll should only be used to set a device as untracked if it was previously set as tracked (or to set manually the state as mentioned above).

1 Like
3

It appears there was a change this week in how the online/offline is being determined for checkInternval.

I have an attribute defined in the metadata

metadata { ...
    definition (
        attribute "lastSeen", "string"
    }
}

Then I have this to keep it “online” or “offline”

sendEvent(name: "lastSeen", value: dateValue, displayed: false)

This is the CheckInterval -

sendEvent(name: "checkInterval", value: 30 * 60 + 2 * 60, displayed: false, data: [protocol: "lan", hubHardwareId: device.hub.hardwareID])

It has been working flawlessly until sometime this week, it is appearing as “Offline” now, although the “lastSeen” value is still being updated.

Would you be able to advise whether this is the new intended behavior or bug? Or what is “the right way” to implement this?

Thanks @nayelyz

1 Like
4

Hi @nayelyz,

Thank you for the detailed reply!

Yes so say the ping does not return anything back, what attribute is updated to OFFLINE?

When I ping a device however manually issuing the ping command it does not seem to update the device status at https://api.smartthings.com/v1/devices/{Device_ID}/health is there something after that the checkInterval does to detect no response?

5

Do you mean that you used this custom attribute to show the offline/online value in the app?

I need to confirm some information with the engineering dept., then, I’ll share it with you two, please give me some time.

1 Like
6

This is for a virtual device. I use this custom attribute as the “message” to inform/pong the hub that the status should be marked as “online”.

I think the message must come from an attribute that has been defined in a custom or standard capability now. It ignores messages that are defined in the DTH metadata’s attribute.

7

Hi @nayelyz,

I have been testing the check interval with very low values 10 seconds say, however the checkInterval always seems to revert back to 1860 seconds.

sendEvent(name: "checkInterval", value: 10, displayed: false, data: [protocol: "zwave", hubHardwareId: device.hub.hardwareID, offlinePingable: "0"])

image
I’m not saying its a good idea to have it set at 10 seconds but I’m just wondering if there is a minimum value for the seconds interval?

8

No attribute of the HealthCheck capability is updated with the “offline”/“online” value, you can only get the current status in the devices/deviceId/health endpoint.

When you tried this, did the state of the device actually changed? Because the update of the device health is not observable unless it changes from “online” to “offline” or “offline” to “online”. The lastUpdatedDate property is only modified when this happens.

Let me check more details about the minimum and maximum values. Meanwhile, make sure your device isn’t using a draft version of the DTH.

2 Likes
9

@nayelyz , did you ever get any information around min values for checkInterval?

I’m seeing devices registered with values like 1920 seconds, and in fact I’m not seeing the ping() method being called, nor is the status being marked OFFLINE once the timeout is reached. The DTH does have the Health Check capability and I’m pretty sure it worked in the past.

  • Is there some minimum value that ST won’t bother ping()ing before? 1 hour? 4 hours?
  • Does the ping() happen on an increment of the device’s last activity+ timeout? Or is it based on a time of day schedule at Smartthings itself? In other words, if the checkInterval is 1 hour, does the ping happen (more or less) on 1 hour + the last activity of the device, or is it something at SmartThings runs every hour and everything that is over its limit gets queued for a ping()?
  • Or is Health Check / checkInterval no longer functional in 2022?

Thanks!