How Do I Create/Modify A Device Handler?

Developer Programs Writing Device Types
1

I have a few Ecolink door/widow sensors.
I would like one of them to show up in ST as Locked or Unlocked rather than Open or Closed.
Right now I’m using one to monitor the locked/unlocked status of a conventional deadbolt lock.

It sounds as though modifying an existing DH is the way to go.
How do I go about doing that?
Are there any tutorials or lists of steps to do this?
Is there a better approach to take?

Any assistance would be welcome.

2

You probably already know this, but just in case, a “device type” is the same thing as a “device handler.” Smartthings has changed the terminology from time to time, so you will see both terms used in the docs and the forums.

Smartthings code uses a groovy variant.

Have you had a chance to look at the developer docs yet? Go to the first page of the forums by using the community link at the top right. Then go to the developer docs via the link at the top right of that page. They have examples There. If you have any questions, you can come back and ask in this part of the forum. :sunglasses:

And if you have any questions about how to “publish” a device handler to your account after you modified it, this FAQ should help:

1 Like
3

Thanks. I’ll take look at that.

4

I don’t think you’ll find any step by step tutorials, as it varies by device. You just have to get in there and experiment. In general though, you can follow these steps to get you most of the way there (for the “modify” scenario):

  1. Find the device handler you’ll be using as a basis. This can be done one of two ways. The first is easy, but doesn’t always work (long known and unsolved problem with ST). The second way requires some searching to find what you’re looking for, but once found, is easy.
  • In the IDE, goto My Device Handlers > +Create New Device Handler > From Template. Scroll the list and select the desired dh. Now, here’s the part that doesn’t always work… after selecting the desired template, scroll to the top of code window and ensure that your selection is displayed. Approximately 50% of the time it won’t. If you are lucky and it is there, simply hit the Create button. If you wan’t to change its name, you can do so now (or later) by editing the metadata “name:” field. Then Save > Publish, For Me. To associate your device with the new dh, goto My Devices in the IDE and then click/tap the device name in the left column.From there, Edit and select your new handled from the drop-down Type control (it will be near the end of the list).
  • The second way is to go to the public GitHub repository. Select “smartapps” or “devicetypes” (other name for device handler) and then search using the Find file button. Notice that your cursor will be positioned after "SmartThingsPublic / " near the top of the page. If you know the name or part of it, type it here for on-the-fly context-sensitive search, otherwise just manually scroll. Select the one you want, then press/tap Raw. Copy the raw code and paste it into the IDE at My Device Handlers > +Create New Device Handler > From Code. From here, the steps are similar to above (Create > Save > Publish, For Me).

That completes the steps to installing and associating the device handler with your device. From there, it’s a matter of seeing what text or icons you can add to the UI that will render properly and display what you want. This is part black magic and part luck, but the area of interest is in the tiles() section near the top of the code. you should be able to look at other examples online (or by installing dummy handlers that you can later delete).

I hope I didn’t leave anything out. Post back if anything is unclear or if you have questions.

2 Likes
5

JDRoberts and Mr_Lucky,

I opened the template for the Z-Wave Door/Window Sensor. I assume that is what my device is using now.
My thought was that I could just change any reference to Open and Closed to Locked and Unlocked.

Looks a little more involved.

I took that template code and pasted it into “From Code”.
The only change I made so far was to add my name in the Author comment line and today’s date.
Figured I will go through the motions of saving this to test the process.

When I click “Create” I get this error:
Java.lang.IllegalArgumentException: Metadata definition not found

I didn’t change any of the metadata.
I only made these changes in comment lines:

  • Author: SmartThings Modified by B Tilley
  • Date: 2013-11-3 Modified 3/4/16

How do I proceed from here?

6

Update:

I got it.
Modifying the GitHub version of the DH I have been using did the trick.
Took a bit of trial & Error, but I got it.

I see Locked or Unlocked now in ST.

Thanks for everyone’s help.

7

btcompute, any way you could share the code you used to do this? I’ve been trying to figure out the same thing … making a door/window sensor show as Locked/Unlocked instead … but I’m a complete beginner to all of this and I’m having the same problems you did with the Metadata error messages. Thanks!

8

Rich-o-matic
RICH PESKE
16h
btcompute, any way you could share the code you used to do this? I’ve been trying to figure out the same thing … making a door/window sensor show as Locked/Unlocked instead … but I’m a complete beginner to all of this and I’m having the same problems you did with the Metadata error messages. Thanks!

Rich,

Here is what I did with limited success (more on that later).

  1. I copied the full code from GiHub for the Z-wave Door/Window Sensor Device Handler (DH):
    https://github.com/SmartThingsCommunity/SmartThingsPublic/blob/5f85cd287342e5a5ad11b2da69049bfc8a1afcb4/devicetypes/smartthings/zwave-door-window-sensor.src/zwave-door-window-sensor.groovy

This should be the same DH you are using for your door/window switches.
Get a copy and save it to your “My Device Handlers”.
Save it under a name you will understand, maybe “Z-wave door sensor Lock/Unlock”.

  1. I edited only the lines that had any reference to Open or Closed. They are lines 34,35, 41, 42, 100 and 106 (
    unless I missed something).

Here are the edited lines 34 & 35:
status “unlocked”: "command: 2001, payload: FF"
status “locked”: "command: 2001, payload: 00"
I suggest you edit the lines yourself rather than cut/paste my code. Just use my code as an example.

Lines 41, 42:
state “unlocked”, label: ‘${name}’, icon: “st.locks.lock.unlocked”, backgroundColor: “#ffa81e"
state “locked”, label: ‘${name}’, icon: “st.locks.lock.locked”, backgroundColor:”#79b821"
Note: Here I changed the icons that appear in ST app. I got those icon names from the DH for z-wave locks.

Lines 102, 104:
createEvent(name: “contact”, value: “unlocked”, descriptionText: “$device.displayName is unlocked”)
} else {
createEvent(name: “contact”, value: “locked”, descriptionText: “$device.displayName is locked”)

Make the changes and save the DH and publish “For Me”.

NOTE: this should make this sensor appear in ST as Locked or Unlock, but with one problem.

When you try to create rules for this device, most smartapps (I have been using Rule Machine) expect to see Open & Closed as status options. Therefore the rules don’t work properly.

If you don’t like this behavior, you can alwas switch back to the original DH.

I suspect that I changed too many references to Open/Closed. I need to work on the edits a bit to determine the cause of the problem.

Perhaps someone here can tell us what needs to be done to get the device to show up in ST as Locked/unlocked rather than Open/Closed.

Good luck. I hope this helps you.

1 Like
9

Wow - thanks for the great summary and the line-by-line notes! I’ll give this a try … might take me a few days to get to it, but I’ll post an update when I do.

Thanks again!