Updated Device Handler Documentation


(Jim Anderson) #1

Today we updated our [Device Handler Guide][1] in our developer documentation. It includes a reorganization of existing content, as well as expanded content. Like most things, it’s not “done” - there’s more work to do to better build out the documentation around device handlers (and other areas of the documentation, obviously). But we believe in not letting perfect be the enemy of good, and incremental progress.

You’ll probably find a few typos, gaps, or areas that need more clarification. If you’re so inclined, you’re welcome to create a pull request for our documentation, which is publicly available in GitHub [here][2].

We hope you enjoy the updates (we can enjoy documentation, can’t we :slight_smile: )

Sincerely,

Your friendly docs team (aka Jim)
[1]: http://docs.smartthings.com/en/latest/device-type-developers-guide/index.html
[2]: https://github.com/SmartThingsCommunity/Documentation


ST's Hue (Connect) app doesn't follow ST's Device Handler Guidelines
(Jim Anderson) #2

p.s. - to see the updates, you might need to do a hard refresh (CMD-SHIFT-R).

Freaked me out when I clicked the link and didn’t see the updates! :stuck_out_tongue_winking_eye:


(Patrick Stuart [@pstuart]) #3

@Jim, Couple of things…

First, why no docs on imageCarousel input type? Is this not supported?

Can you provide examples of ho\w status and reply would work with zigbee along with the zwave examples?

In the IDE simulator, what does raw message actually do?

Probably should add a disclaimer that when using input preferences in device types are not supported in the IDE and have to be linked to a physically installed device to pull values.

You added ZLL cluster info for fingerprinting, but no existing deviceTypes exist to take advantage… Does Hub v1 support ZLL?

http://docs.smartthings.com/en/latest/device-type-developers-guide/parse.html

3rd paragraph, zigbee is spelled wrong…

In the zigbee primer, it might be nice to add info on how to get the clusters with the get clusters command which doesn’t log to the device, but to the global IDE / location handler of smartApps.

Same with the pairing / joining of zigbee devices, the clusters are reported on pairing to global live logging in IDE. If a match is found it will be presented in the app. If no match is found, it will be unknown or Thing… You then have to manually assign the deviceType in the devices in IDE>


#4

Really like the Quick Start! Nicely done, and much needed. :blush:


#5

In the Overview, this totally confused me:

Consider the example of the “Switch” capability. There are many unique switch devices - in-wall switches, Z-Wave switches, ZigBee switches, etc. All these unique devices have a device handler, and the device handlers support the “Switch” capability. This allows SmartApps to only require a device that supports the “Switch” capability, and thus work with a variety of manufacturer and model-specific switches.

There are many zwave in wall switches–some you can buy from the SmartThings shop. And plenty of zigbee in wall switches you can buy elsewhere.

“In wall” is the form of the device. Zigbee/Zwave/Bluetooth/WiFi etc is the communication protocol the switch supports. Two separate concepts.

Also, I think it’s important to list some of the other forms.

For example: a light switch on the Wall is a “switch” in this context, but so is a smart coffee maker, a humidifier, an air conditioner: any networked device that can be turned on or off just by receiving the command to do so.

In addition, you can buy a “smart switch” or smart powerstrip that plugs into an existing outlet and then lets you plug a nonnetworked device into that. You send the on or off to the smart device plugged into the receptacle but it can essentially make a dumb coffeemaker into a smart one. And in this context it’s still a “switch.”

Finally, in this context a smart lightbulb is also considered a “switch” because it also accepts the on and off commands.


#6

Also, check out this definition of switches, actuators, and controllers. I really like it. A controller includes devices like the Aeon Minimote, the SmartenIT 3 toggle remote, the Enerwave SC7 screen controller, etc. Very important in many home automation setups.

http://www.vesternet.com/downloads/dl/file/id/62/z_wave_aeon_labs_micro_smart_energy_illuminator_manual.pdf


(Jim Anderson) #7

You’re definition of a “couple” is different than mine. :slight_smile: And… wow you read fast. And carefully.

I’m going to document it. I’ll do this today.

I’ll follow up on the rest of the items later. We’ll add a lot of these suggestions to our documentation backlog.


(Jim Anderson) #8

I think this is a really, really good point. I’ll update this. Thanks for the idea!


(Kevin Shuk) #9

I’m surprised no-one has thrown a party over this yet.

Under Tiles > Tile definitions > controlTile():

You can also specify a custom range by using a range parameter. It is a string, and is in the form “(…)”

Tried it out, and whaddya know? It works! And the slider tool tip agrees with the expanded range values! (just in the app - not in the simulator yet)


(Scott G) #10

Let the party begin!! This is perfect for the Osram Lightify that is color temp tunable. Only took me a few minutes to switch from a messy conversion from 0-100 into the real kelvin range 2700-6500. Simplifies the code a ton too!


(Scott G) #11

@Jim Speaking of the new tiles that are defined in the updated docs, how does the carousel tile actually work? Does it store the last X values of the variable? Can you define X? I’m wondering if it could be used for sensor devices to quickly see what the last few readings were. Thanks!


(Jim Anderson) #12

Good questions.

I’ll get more information around this in the near future (might be a week+ since I’m traveling next week). I just wanted to make sure it was at least called out as something that can be used.