Labs: SmartThings Health and Battery Reports

SharpTools.io (web) Announcements
1

By popular request, we put together a few HTTP endpoints on the SharpTools Labs server to make it easier for SmartThings users to check the status of devices in their home, including offline status and battery levels.

Labs Health and Battery (1)
Labs Health and Battery (1)1200×628 65.5 KB

Like previous Labs experiences, you can integrate these features into your SharpTools rules using HTTP Actions. To do so, you’ll need a SmartThings Personal Access Token with at least the List and See All Devices access which you’ll use as the token property in the examples below:

Health Check

The Health Check endpoint returns a list of devices which are reported as ‘offline’ in SmartThings.

https://lab.sharptools.dev/smartthings/healthcheck?token=YOUR-TOKEN

Response Properties:

  • textSummary: a human readable list of device names; can be used directly in notifications
  • items: an array of objects which each include a deviceId and name property

:information_source: The textSummary property is an easy to read summary that can be used directly in notifications or stored in a variable to be viewed on your dashboard. The items property is useful for advanced use cases where you want to remap the data or have more control over the formatting.

As noted in the HTTP Actions help article linked above, in order to access the response data, you’ll access the relevant Context Variable → Response Data at which point you’ll enter one of the property names mentioned above. The full variable used in your rule might end up looking something like: $context.response.data.textSummary

Battery Check

The Battery Check endpoint returns a list of devices which are below the provided threshold (30% by default).

https://lab.sharptools.dev/smartthings/batterycheck?token=XXX&threshold=20

As indicated in the example above, you can provide an optional threshold value to adjust the upper limit for battery values included in the report.

Response Properties:

  • textSummary: a human readable list of device names; can be used directly in notifications
  • items: an array of objects which each include a deviceId, name, and batteryLevel property

The format of the response is very similar to the healthcheck endpoint with the addition of the battery level within the human readable textSummary property and the inclusion of a batteryLevel property within each object in items.

Other Notes

Please note that these endpoints were designed to be used in a report-like nature. In other words, you might schedule a daily rule which would check these endpoints and you could conditionally determine if you want to send a notification summary or not.

There is currently some light caching on the endpoints to prevent abuse, but we will monitor and adjust accordingly as needed.

Please note that this is intended for SharpTools Premium users as an added benefit, but it is not an official ‘production’ feature and thus may not have the same level of stability / support as core features.

Looking for something similar for Hubitat? While there isn’t exactly the same concept of ‘offline’ device status in Hubitat, community developers have put together Device Watchdog and Device Activity Check which accomplish a similar thing by checking for the last time that a device reported an update.

15 Likes
2

This is great! Thanks!

1 Like
3

Thanks! Works great.

1 Like
4

This is exactly what I was looking for. Thank you!!

5

Works perfectly, thanks!

As an enhancement, it would be great to have the ability to filter. I have a number of “holiday” devices, bulbs and the like, that I don’t use year-round, so they are removed and stored. But they are still present in the hub. These devices show offline as they should, but it would be great to have a way to exclude them!

2 Likes
6

Well I know what I am doing this weekend!

7

What would you want to filter on?

Note that you can filter using an expression to filter and map the raw items as you see fit:

items = $context.response.data.items
exclusions = ["Motion Elliot"]
filteredItems = filter(items, not(contains(exclusions, item.name)))
join(map(filteredItems, item.name), ", ")

Or if you’re curious what that looks like with some sample data as a reference:

Example with Sample Data (tap to expand)

:information_source: You could copy and paste this content into an expression block within a rule and run it to see the result. Sometimes it’s helpful to use test data like this to refine your expression.

items = [
    {
      "deviceId": "1XXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
      "name": "Motion Elliot",
    },
    {
      "deviceId": "2XXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
      "name": "Aeon Multisensor",
    },
    {
      "deviceId": "3XXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
      "name": "Simulated Offline",
    },
    {
      "deviceId": "4XXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
      "name": "Front Door",
    }
  ]
exclusions = ["Motion Elliot"]
filteredItems = filter(items, not(contains(exclusions, item.name)))
join(map(filteredItems, item.name), ", ")
1 Like
8

I’d filter on the device name to eliminate devices purposely offline.

I will take a look at using an expression!

Thanks. This fills a huge hole!!!

1 Like
9

Is this the same as or better than just checking the battery attribute of each device or is it drawing from the same info?

10

So far so good, working fine

Thanks!

1 Like
11

It is roughly drawing from the same information. The difference with this Battery Report is it queries the battery state of all devices in your SmartThings account in one go, so it’s much more efficient when you want to check the battery status of a large number of devices at once.

If you just want to check the status of a single device’s battery in a rule, then you could use whatever approach you’re currently using. If you want to check the state of many devices (or all devices) at once, this would be a better approach.

1 Like