Labs: SmartThings Health and Battery Reports

[josh]

By popular request, we put together some new features 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.

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

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.

[Travis_Mielonen]

This is great! Thanks!

[Techno_Vol]

@josh

HTTP Actions

Thanks! Works great.

[Reda_Book]

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

[Bry]

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!

[BeardedTechGuy]

Well I know what I am doing this weekend!

[josh]

@Bry

As an enhancement, it would be great to have the ability to filter.

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)

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), ", ")

[Bry]

@josh

What would you want to filter on?

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!!!

[RichB]

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

[plb44]

So far so good, working fine

Thanks!

[josh]

@RichB

is it drawing from the same info

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.

[John_Johnston]

Thanks for this.
So I’m not the best at this so a little help would be great.
I’ve managed to get the token from Smartthings and the http example to check the health of my devices.

Now what do i have to do in order to get a notification sent to my phone if any device goes offline? I use push bullet and can successfully get notifications so I have that part set up but I don’t know how to create a rule to make this work.
Can anyone help?
Thanks.

[josh]

The HTTP Action help article has some good insights:

HTTP Rule Action - SharpTools Knowledge Base

As noted in the original post, the textSummary property is the easiest one to use as it has a human readable list of device names that you can use directly in notification.

@josh

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

So a basic example might look something like the following:

Per the written instructions above, here’s how we access that textSummary variable:

I would note that this is a simple example that always sends the notification every day at the specified time regardless of if there are devices offline or not. I would start with that just to make sure you’ve got the basics down.

Once you’ve got that, you could add some logic if you’d like. For example, some people will add an IF Condition and will only send the notification if there’s content in the textSummary (eg. if there are offline devices). Other people like to use more advanced features like filtering on the list of offline devices to exclude certain device names or other things which requires expressions as demonstrated further up in the thread.

[John_Johnston]

Thank you so much mate I got this working.
I just have one last query and I see there’s another post about it but I’m unsure on where to add any of this into the rule. So I have around 4 devices that I’d like to filter out and not notify me when offline. Do I add this onto the same rule, and how would I go about doing this? Like I said, I’ve seen the other post about this but really unsure on exactly where to add this.

Edit : is there a way to have this trigger every hour or so rather than daily, or would I have to create more duplicate rules and simply change the times on them?

Thank you.

[josh]

@John_Johnston

I just have one last query and I see there’s another post about it but I’m unsure on where to add any of this into the rule

You would use a Set Variable action and choose Expression for the source. Then use the snippet mentioned in the thread further above to filter things… then use the value from the variable you set in your notification.

@John_Johnston

Edit : is there a way to have this trigger every hour or so rather than daily, or would I have to create more duplicate rules and simply change the times on them?

You can add multiple Timer triggers to a single rule. We don’t currently support ‘Every XX hours’ type of triggers. Some community members have come up with creative approaches to accomplish that, but it’s not something we officially support or recommend.

[John_Johnston]

Thank you.
So I have to take this out now? Does that go somewhere else now?

I also don’t see expression variable. Sorry.

[josh]

@John_Johnston

I also don’t see expression variable. Sorry.

Check the screenshot from my post. What it’s doing is using the Set Variable action where you will set a variable based on the result of an expression.

This comes after the HTTP Action in your rule flow since the expression needs the value from the HTTP action… and it comes before your notification (or IF Condition) since the notification or condition needs the result of the Set Variable action.

So you select Set Variable as the action, select the variable you want to store the result in (or create a Text variable first and then select it), then tap the Expressions tab as shown in my screenshot in the source, then fill in the expression based on my example snippet further up in the thread.

Keep in mind that using expressions is a bit of an advanced feature, so you can’t always just copy-paste… in this case, you would need to change the values in the exclusions section of my sample expression from above.

@John_Johnston

So I have to take this out now? Does that go somewhere else now?

You would use the variable that you used as the target in the Set Variable action since that has the filtered list of device names.

[John_Johnston]

Sorry mate I’m really stuck. Far too advanced for me.
I’ve no idea what I’m doing here unfortunately:(

[John_Johnston]

@josh

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

Here’s my attempt at it and I know it’s clearly wrong but hopefully you can tell me where I’m going wrong.
‘Big Mo’ is an openclose sensor that id like to exclude. I have 3 more devices Id like to exclude but trying with one for now. It says invalid variable.

Thanks.

[John_Johnston]

I managed to suss it out. I don’t know how but I did.

Thank you for the help mate