New ZigBee Device ... again. New methods?


( co-founder Terry @ActionTiles; GitHub: @cosmicpuppy) #1

Continuing the discussion from New Zigbee Device (Securifi Key Fob):

Hi @JohnR or anyone…

I’m finally in a world where my reading on the Community is paying off, in that I remember reading the above paragraph and related Topics … but now I’m trying to put it to practical use.

I’m testing TI-CC2650 ZigBee Z-Stack compatible chip (also does BLE, etc.), in a SensorTag Dev Pack.
I believe I the test firmware should be delivering Temperature and Switch (On/Off) cluster(s):

Here’s the join signature…

Well… Looks like we got 0x0006 = “on/off”; and 0x0402 = “temperature measurement”, right?

Unlike the example(s) in the other topics, there are two “desc” entries. And I’ve tried to do some of the “zdo bind” commands, but no results. Now there are new functions for ZigBee, right?

Reading up on:

I apologize for being a super n00b here, but perhaps I can get a shove in the right direction, please? Thanks!

RGB and RGBW LED strip lights
Custom Zigbee Device
(Scott G) #2

Your device is configured with two endpoints (08 and 09 as seen in the ep_cnt: 2 join event). Each endpoint is configured for one of the expected clusters with endpoint 9 containing the temperature cluster and 8 the on/off cluster. Note that for endpoint 8, the 0006 is after the 01. That means the on/off cluster is an “out cluster” per ST speak or a client cluster in Zigbee, so your device will send on/off cluster commands out to other devices, not receive on/off from ST.

With two endpoints, you might have to address the endpoints manually instead of using the endpointId property (at least for one of the target clusters). Might be an interesting trial to see what the endpointId property returns.

To bind these two clusters, I think it would look like:

"zdo bind 0x${device.deviceNetworkId} 8 1 6 {${device.zigbeeId}} {}", "delay 1000",
"zdo bind 0x${device.deviceNetworkId} 9 1 0x0402 {${device.zigbeeId}} {}"

Note: the documentation for the configure section appears to be incomplete. It shows the new format for a send-me-a-report command, but the paragraph talks about the old ‘zdo bind’ command. Binding is no longer part of the zigbee documentation that I see.

(Scott G) #3

Just for reference of the “desc” entries:

desc: 09 0104 0302 00 03 0000 0003 0402 01 0003

09 = endpoint 9 for this entry
0104 = profile Id or version of Zigbee. Usually is 0104 for Home Automation or C05E for ZLL
0302 = device Id for profile. 0302 is temperature sensor.
00 = I’m not entirely sure what this is. I’ve seen 02 and 00 on most other devices. Anyone?
03 = Number of in or server clusters. Device receives commands on these clusters.
The next X number of 4 digit values are the server clusters, where X is number of server clusters in previous value.
0000 is basic cluster and has info on make/model, versions, etc…
0003 is the identify cluster and is used in pairing processes (causes a zigbee light to blink when paired for instance)
0402 is temperature measurement cluster and is used to read the value of temp sensor.
01 = Number of out or client clusters. Device sends commands using these clusters.
0003 means the device can trigger other devices to identify themselves.
Common “out” clusters are 0019 for Over The Air updates and 0003 for identify.

Cree Connected bulb reliability to automate, or lack thereof
( co-founder Terry @ActionTiles; GitHub: @cosmicpuppy) #4

Wow, Scott… Super helpful responses, bud, thanks! The breakdown of the “desc” join message is definitely confidence inspiring, as that is where the magic has to start.

But here’s where I get a bit disheartened. I’m glad (?) there are new ZigBee library methods in SmartThings, but it is hard to work with a changing spec; presuming that the various example Device Types out there are mostly using old methods?

I guess what I’d like to see (or what I can help build out of this “project”) is a FAQ and ThingsThatAreSmart.Wiki entry of how to build a complete Device Type Handler for a “mystery” ZigBee HA compliant device. The example should be simplified to one read cluster and one write … or something like that.

i.e., all the steps from grabbing and getting some meaning from the “Desc”, defining the “fingerprint” metadata{}, and then any sniffing, configure method (zdo binding?), refresh, parse, and Command methods.

What might you suggest is a nice clean “boilerplate / template” ZigBee Device Type that would be good to use as the base for a “mystery device”?

In this case, for example, the TI CC2650 SensorTag is offering “Temperature” and “Switch” … so should I start with a Smart Sense Temperature Sensor and a ZigBee Smart Outlet?

(Scott G) #5

It’ll take some time for more examples to get transitioned over to the new Zigbee methods, and I’d imagine there will be bugs to work out. I’ll probably keep using the old methods as long as they work just because I’m used to them and know exactly how they work. Or until someone ribs me for having 200 extra lines of code!

I’d be up for helping with the FAQ when I can. It’s a good idea to help others write new devices.

I would start with the SmartSense Temp/Humidity Sensor. You’ll probably be able to boil it down to just temp readings pretty easy as long as you hardcode the endpoint number as I mentioned earlier.

The “Switch” will be much harder to do anything with because it’s an “out” cluster, so it’s meant to send on/off to other devices, not receive commands from ST. Those clusters are usually configured in the device’s hardware/firmware or need to be bound directly to another device. As far as I know, ST doesn’t do device-to-device direct binds. It’s something both @JohnR and myself voted for in the thread on the new Zigbee Abstraction. The only thing I know of to do with that is to bind it to the hub, so when it sends an on/off command, you’ll see a message in parse (I used this to capture button presses from the Hue Dimmer Switch. If only it would stay connected). I just don’t know what would trigger your device to send an on/off or what it would send it to.


Tagging @Jim for that one.

(Jim Anderson) #7

@unixbeast has already updated that paragraph :smile:

(John Rucker) #8

Well heck a guy goes Christmas shopping for a couple of days and miss out on all the fun. Looks like Scott got you what you need. I like the idea of a template app for ZigBee devices based on the new tools. I would like to suggest we work with the certification team to put this together.

Good stuff Scott!!!

(Kevin Tierney) #9

I wish there was a cross reference that shows what the old code looked like and what the corresponding new code looks like. I’m sure I’ll eventually figure it out, but on initial inspection it looks a little confusing. My Zigbee Key Fob device type has been in review for months and I have this feeling I’m going to get an email asking me to re-write with the new code

(John Rucker) #10

I’m in the same boat. I have a ZigBee device type for the CoopBoss under review. If they do ask me to redo it I hope they provide a template of what they would like to see. Before I submitted my device type I tested it for two months. I would need to repeat that whole process again as I want to make sure the new tools don’t introduce new bugs.

I think someone (preferably a SmartThings ZigBee engineer) needs to go through the SmartThings sample device types and clean house. There are some poor incomplete examples out there and now with the new tools we are going to see even more variations.

(Scott G) #11

I don’t think they can ask you to re-write the Key Fob code, only because I don’t think there’s really anything in the new abstraction layer to replicate the commands you needed to make it work.

There aren’t any traditional cluster commands, read attribute commands, reporting configuration, etc… in your devicetype. They haven’t replaced the ‘zdo bind’ which you most likely need for the Fob to send button presses to the hub. You use the security enrollment process, which is a global write and a raw zigbee message for enroll response. Neither of those have a corresponding option in the new layer, but I expect they’re working on making that process easier to code.

I guess you could update the parse section to use the new zigbee.parseDescriptionAsMap() instead of just zigbee.parse(), but I don’t think it would make it any more efficient than what you have now.

( co-founder Terry @ActionTiles; GitHub: @cosmicpuppy) #12

Which would you suggest are particularly good coding examples (for the ZigBee portion of the handler)? I’d like to reference a good example of “read-only” (sensor) and another for “read-write” (sensor-actuator).


Here are some of the most recently developed Device Type Handlers that use ZigBee:

ZigBee Switch
ZigBee Switch - Power
ZigBee Dimmer
ZigBee Dimmer - Power
ZigBee Lock
ZigBee White Color Temperature Bulb
ZigBee RGBW Bulb (work in progress)

There isn’t a recent pure sensor example I can find, but I’ll ask around.[quote=“JohnR, post:10, topic:32980”]
I think someone (preferably a SmartThings ZigBee engineer) needs to go through the SmartThings sample device types and clean house. There are some poor incomplete examples out there and now with the new tools we are going to see even more variations.

Agreed! @workmonk and I have talked about reworking the examples. Sounds like a good project as we’re starting the new year.

(John Rucker) #14

etc…[quote=“tgauchat, post:12, topic:32980”]
Which would you suggest are particularly good coding examples (for the ZigBee portion of the handler)?

Well I will let someone from SmartThings answer that or someone who has at least got ZigBee device type approved. Some of the obvious “need improvement” samples out there have entire methods in them that are never called and other methods have comments in them like “not complete finish later” etc.

( co-founder Terry @ActionTiles; GitHub: @cosmicpuppy) #15

So I’m making some progress forward … and then back again…

What does it mean when the Hub Events log shows “join, Thing added” – without displaying an intervening “desc:” message?

I have previously received the “desc:” from this device and even have a stub Device Type set up that, on one attempt, successfully was assigned to the Device.

But I wanted to repeat the process (as I was attempting to fine tune the fingerprint with Manufacturer and/or Model information …).

I deleted the Device from my Location. Yet somehow the join process is skipping the Device Description step? Does this mean the Device is not sending the Description anymore? I’ll try completely erasing and resetting it, but it is suppose to do a join attempt each time upon power-up, and clearly SmartThings is seeing the join attempt … but no … “desc:”.


(John Rucker) #16

I saw this exact thing last week. I’m working on a new ZigBee device and I have logging turned on so I can see what my ZigBee device is receiving from the hub. I made some changes to my custom device type and wanted the device to rematch itself to the new footprint in my device type. So I deleted the device out of my device list and powered the device off and back on knowing it would send a device announce when powered on and trigger the identification process. It did exactly that I saw the device announce packet go out and then the hub respond with asking for a list of supported end points and then it queried each end point for its simple descriptor. But back in the hub’s log I only saw the join log entry like you did above. To get the footprint process to run I told the device to remove itself from the ZigBee network, deleted it out of my devices, and then added it back to hub by hitting the add new device on my phone. This time my device responded the same way as it did before but I saw all the foot printing information in the hub log.

So I bet yours will work if you remove it from the ZigBee network and then add it back.

( co-founder Terry @ActionTiles; GitHub: @cosmicpuppy) #17

Yup… It sure did; though I had a heck of a time resetting it for other reasons (…stuck bootloader… had to force reflash stock firmware… ).

Thanks for confirming the behavior I observed!

When it rejoined, I’m suddenly only getting reports from the other of the two Endpoints, but now I get the “Temperature:…” events instead of the raw “description” to parse().

Hmph… These new ZigBee methods are rather frustrating at the moment because we only have half the documentation and because they don’t cover several essential functions…

(Scott G) #18

Agreed! There’s a lot in flux at the moment. They seem to be letting some new messages get to parse() that never got through before, like a bind response message in the post below and the OTA upgrade message on some bulbs. Hopefully it means they’re working to give us more info and power with zigbee, but it takes a lot of digging to figure it all out.

(Tom Manley) #19

When I tested your device handler I noticed the sensor rejoins the network on basically every button press. I wanted to hold off on further testing until some lower level changes I’m making to the ZigBee join support is released to make sure it would still work correctly. Sorry for not letting you know sooner, just been really busy :grin:

(Kevin Tierney) #20

Good to know. Thanks for the update. I figured you guys were swamped