ZigBee DTH - configure() & refresh() - correct method in 2018?

I am very new to all of this, so please excuse any errors in terminology…

I am trying to improve some community created DTHs for ZigBee devices (various Xiaomi sensors, to be precise) and presently I’m focusing on the configure() and refresh() function code.

I am trying to figure out what is the best / correct code to set up bindings (if necessary), configure attribute reporting, and anything else necessary under configure() and refresh(). Unfortunately, searching the forums and looking at the SmartThings Developer documentation creates a lot of confusion, because in the forums all code methods, past and present, are discussed, and there are gaps, errors, and inconsistencies in the developer documentation pages.

For example, this thread from late 2015 discusses changes in what can be used for configure(), suggesting that xcl global send-me-a-report has been depreciated and that zigbee.configSetup() can be used instead (or even more specific calls for certain cluster/attributes can be used, like onOffConfig()).

But looking at later posts, developer documentation, and the current crop of ZigBee DTHs on the SmartThingsPublic GitHub repository, I see that xcl global send-me-a-report and zigbee.configSetup() seem to have been supplanted by zigbee.configureReporting() paired along with zigbee.readAttribute() - with the readAttribute call needed for configuring reporting on some but not all commonly used device attributes as explained here.

Also, I notice most of the newest revisions of ZigBee DTHs aren’t using zdo bind in configure() or st rattr in refresh() anymore either.

So…. now, in 2018, what is the appropriate (best?) way to set up configure() and refresh() in a ZigBee DTH?

Thanks in advance!

1 Like

Same problem here, the docs are about two years out of date except a few typo fixes and frankly a complete and utter mess for devs without years of ST experience. New features and capabilities trickle out to external developers through snippets of code and random comments in community posts from ST engineers and devs with inside connections. And it’s the worst of both world, closed source so you can’t access it but since you’re not paying you can’t demand structure or timely updates either. Pretty much useless.

My guess is they’re prepping for a new way of writing DTHs and have been for a while(*), and that is why most updates appear undocumented and behind the scenes. Probably tied to the new half-baked APIs for webhooks and the new dev site. Alternatively, they’re just slowly becoming insanely bad at this and if this is the case I see the Mozilla Thing Gateway quickly taking over. It’s at the Helo Worlld stage now, but depending on what Samsung intends to do with the hobby developer crowd going forward that could quickly change.

Random post for you to look at for more info on conf/refresh:

OK

*) https://smartthings.developer.samsung.com/develop/workspace/ide/create-a-new-hub-connected-profile.html
Nice form to fill out btw.

1 Like

The zigbee.configureReporting and zigbee.readAttribute methods are the “correct” way to accomplish those tasks. Having the commands just being strings set in each individual DTH makes it very difficult to control and fix bugs that come up because every DTH is doing it’s own thing. By using those commands, the library controls building the correct commands, and so if there is a mistake it can be fixed in one place for everyone. This page talks about these commands a bit.

That said, some devices (like Xiaomi since you explicitly mention them) do not follow the Zigbee specification and so you may have limited success with these commands. I have played with a couple of Xiaomi devices and from what I remember, they ignored configure reporting commands and simply did their own thing. For example for motion, despite using a standard cluster, they did not use the attributes in the way defined in the specification (e.g. they never report that motion has stopped, they simply stop reporting that motion is happening).

1 Like

The original Xiaomi devices were only intended to be used with their own gateway and are, as they say, idiosyncratic. :wink:

The newer Aqara line is supposed to be using the ZHA (zigbee home automation) profile, but I don’t know if it’s actually certified.

Yes, since I asked this question almost a month ago, I have figured that out.

After the pairing process, Xiaomi sensors only send attribute reports, and only based on how Xiaomi programmed the hardware. Battery reports (on a non-standard cluster) roughly either every 50 or 60 minutes depending on which variety of device, and for environmental sensors, based on amount of change, such as a 0.5 degree C change in temperature.

As far as I’m concerned, besides the non-standard cluster used for reporting battery voltage (which can be accessed by a SmartThings device handler in the hex data: string portion of a catchall: message) the way these devices work is perfectly fine, considering their incredibly reasonable price and that they are powered by a low-cost button cell battery.

The limitation you mention of the motion sensor only sending a motion detected report is easily handled in the device handler as well, and I don’t see it being any more problematic than other fully ZHA certified PIR sensors which send a motion stopped message despite the hardware still being “blind” to motion events for a set period of time to save on battery usage.

What’s really frustrating, however, is that the SmartThings ZigBee hardware abstraction parser removes any source endpoint data from attribute reports. So for some of these Xiaomi devices that send attribute reports from different endpoints on the same cluster/attribute ID, the data I have to work with in the device handler is useless, or only half useful.

I know that the suggested workaround for the lack of endpoint information on attribute report messages is to send a readAttribute command with an endpoint specified. This may work with other devices, but unfortunately not with Xiaomi’s, as they ignore readAttribute.

I have done a lot of reading on the lack of endpoint data delivered with attribute reports, and it’s been a well-known sore spot for some years. If the trend in ZigBee devices is moving from a “call and report” model (aka., polling or readAttribute command) to a “report as needed” model of operation, then this lack of endpoint data really needs to be rectified.

1 Like

Oh, I didn’t realize the original post was so old. Sorry you didn’t get a response sooner. I agree that the Xiaomi sensors are great for their price, and are work with-able. The problem with being non-standard is that we can’t have any generic handling of the device. Also, not being a “Works with SmartThings” device means problems it has don’t get prioritised to be fixed.

I absolutely agree that the endpoint data being removed is a problem. And you’ve probably read the same thing written by me or another dev here on the forums before. Unfortunately due to decisions made in the past, there isn’t a quick fix for this. I don’t know when the work will get prioritized, but if it’s something you want to see and you haven’t contacted support I would recommend doing so. They keep track of requests like this.

1 Like

I have to say I see a real “chicken and egg” paradox in that approach, but understand it’s a business decision at an executive level which development teams must adhere to.

Well with the new SmartThings developer platform moving to AWS and the methods for working with local Z-Wave / ZigBee hardware not being public yet, now is the opportunity for Samsung/SmartThings to address shortcomings like this. I will contact support, as I assume many others have in past, and just hope for the best.

Thank you for your replies.

1 Like