"Device Handler for Dummies"? Any suggestions for a newbie? [Groovy/Classic App Edition, 2017]

Hey guys! I have never done this but am interested in learning how to write/modify a device handler. I started getting my feet wet last year with a little bit of smartapp development so now it’s time to get more up on the device handler side of things. Where are your recommendations for me as far as things to read/watch that could help me start down this road? I am currently interested in the Zigbee, Zwave side of devices. I have looked at the SmartThings Documentation that is available in the IDE thus far.

Thanks for any and all suggestions.

When you say you’ve looked at the documentation in the IDE, do you mean the developer docs? They’re available from a link on the top right of the first page of the forum, so from here, click on community in the upper right of the page, then on developer docs in the upper right of that page.

Is there Something specific you weren’t sure about, because those are pretty detailed.

Anyway, I’m sure the experienced coders will have much more to add, but here’s just a quick list of some of the resources for people just starting out:

Zigbee

http://docs.smartthings.com/en/latest/device-type-developers-guide/building-zigbee-device-handlers.html

I know I’ve mentioned this one before, but the following is my favorite thread as an example for how someone who didn’t have much experience with zigbee devices was able to write a zigbee device type handler with the help of the community. You can see each individual step they took any information they gathered at each point.

And here’s a doc listing all the zigbee home automation clusters.

https://www.nxp.com/documents/user_manual/JN-UG-3076.pdf

Remember that all of the above only applies to devices that are certified for the zigbee home automation profile (ZHA 1.2) or the zigbee light link profile (ZLL).

Unlike Z wave, zigbee allows for many different profiles and they are not all compatible.

But if it’s a certified ZHA device, you have a good chance of being able to write a device type handler for it that will work well with smartthings.

Zwave

http://docs.smartthings.com/en/latest/device-type-developers-guide/z-wave-primer.html

Z wave is somewhat simpler because you don’t have to look at the raw data and it’s easy to look up the commands that any particular certified Z wave device supports by checking the official Z wave alliance products site:

http://products.z-wavealliance.org

So you can often write a device type handler for Z wave device without actually owning the device. That’s generally not true for zigbee.

The easiest way is to just start from an existing device type handler that uses the same command sets as the new device, and then modify as needed.

(And I know I say this a lot, but for the record, Zwave does not have “clusters.” That’s a zigbee term. Z wave has “command sets.” “Supported” command sets are the ones that the device can receive and act on. “Controlled” command sets are the ones that the device can transmit.

SmartThings decided that in their multi-protocol world they would call everything clusters. Drives me crazy every time. :stuck_out_tongue_winking_eye: )

Official zwave public specification listing all the commandsets:

Note there’s no way to add support for a commandset to a device that doesn’t have it without flashing the firmware on that device. So it’s always best just to start with the official Z wave alliance description of the device and look at the commandsets that are listed there. Then you know what commandsets your DTH has to process.

And @zcapr17 has just released a “tweaker” DTH which can be used to discover the endpoints, associations, and supported zwave commandsets for any mains-powered zwave device. Very cool. :sunglasses:

Official Developers Website

There’s also an official developers website, but I don’t know how many people use it. It’s mostly just pointers into the developer docs.

http://developer.smartthings.com/developers/tools#building

SDC 2016

SmartThings did a presentation at the 2016 Samsung developers conference on how a device manufacturer would “onboard” their device to SmartThings. Which basically means creating a device type handler for it.

If you’re a visual learner and you like slides and pictorial representation, this might be helpful. It’s basically the same information as is in the developer docs, but, you know, with pictures. :wink:

Part 1: Z-Wave and Zigbee devices

Part 2: LAN devices

@slagle or @jim might have more suggestions for official resources.

5 Likes

I am trying to learn device handlers by looking at the code for examples and I am looking at @ChadCK device handler here.

Can somebody shed some light or point me in the direction of the documentation please?

What is the function of the state “default” line that is being used in all the tiles? I can’t find info on that in the SmartThings documentation when I do the search. Thanks for any assistance.

  standardTile("lowSpeed", "device.currentState", inactiveLabel: false, width: 2, height: 2) {
    	state "default", label: 'LOW', action: "lowSpeed", icon:"st.Home.home30", backgroundColor: "#ffffff"
  	state "LOW", label:'LOW', action: "lowSpeed", icon:"st.Home.home30", backgroundColor: "#79b821"
  	state "ADJUSTING.LOW", label:'LOW', action: "lowSpeed", icon:"st.Home.home30", backgroundColor: "#2179b8"
  	}
  standardTile("medSpeed", "device.currentState", inactiveLabel: false, width: 2, height: 2) {
  	state "default", label: 'MED', action: "medSpeed", icon:"st.Home.home30", backgroundColor: "#ffffff"
  	state "MED", label: 'MED', action: "medSpeed", icon:"st.Home.home30", backgroundColor: "#79b821"
        state "ADJUSTING.MED", label:'MED', action: "medSpeed", icon:"st.Home.home30", backgroundColor: "#2179b8"
  }
  standardTile("highSpeed", "device.currentState", inactiveLabel: false, width: 2, height: 2) {
  	state "default", label: 'HIGH', action: "highSpeed", icon:"st.Home.home30", backgroundColor: "#ffffff"
  	state "HIGH", label: 'HIGH', action: "highSpeed", icon:"st.Home.home30", backgroundColor: "#79b821"
        state "ADJUSTING.HIGH", label:'HIGH', action: "highSpeed", icon:"st.Home.home30", backgroundColor: "#2179b8"
  }
  standardTile("refresh", "device.switch", inactiveLabel: false, decoration: "flat", width: 2, height: 2) {
  	state "default", label:"", action:"refresh.refresh", icon:"st.secondary.refresh"

It is used when determining the current attribute state. Docs here: http://docs.smartthings.com/en/latest/device-type-developers-guide/tiles-metadata.html#state-selection-algorithm

2 Likes

Thanks!

@Jim So when I look through the example device handler code from SmartThings I don’t see the examples using this line of code? I am not getting why it would be necessary to use?

Based on your link, it says to now use defaultState:true. I did a search now on “defaultState” to see examples to see it being used and what this means and the only thing that comes up is the description which is vague. The couple examples from SmartThings is using the old method

PS- I must have been working too late, I have no idea why the search didn’t hit on this? I tried “search” on it again this morning and it’s the first thing up.

1 Like

Note that smartthings is in the process of moving to a new platform, new app, and new hub, so a lot is going to change. No timeline for when everything will be switched over, but it will be eventually. See the following thread for discussion of the new platform:

2 Likes