zigbee-herdsman migration

[hobbyquaker]

Hi Koenkk! First of all: Thanks for your awesome work! I have questions about the herdsman:

• will you move functionality like handling reporting, configure, deviceAvailability (and other stuff that is currently implemented in zigbee2mqtt as extension) to zigbee-herdsman?
• I'm already using zigbee-herdsman@0.1.17 in node-red-contrib-zigbee, worked flawlessly as a drop-in replacement for the shepherd. As far as I saw you introduced some breaking changes in the higher versions of the herdsman - will you create a little "migration guide" pointing out the API changes?

Regards, Sebastian

Ref: https://github.com/hobbyquaker/node-red-contrib-zigbee/issues/44

[Koenkk]

Hey Sebastian!

• In the future some of this functionally might be moved (indeed sounds very vague -> don't expect this on a short term)
• I don't plan to create a migration guide (due to limited time/priorities), however I think the zigbee-herdsman api is quite straightforward, only things you should care about are:
  • public methods from https://github.com/Koenkk/zigbee-herdsman/blob/master/src/controller/controller.ts
  • device methods: https://github.com/Koenkk/zigbee-herdsman/blob/master/src/controller/model/device.ts#L378
  • endpoint methods: https://github.com/Koenkk/zigbee-herdsman/blob/master/src/controller/model/endpoint.ts#L111
  • group methods: https://github.com/Koenkk/zigbee-herdsman/blob/master/src/controller/model/group.ts#L93
  • all events that are emitted from the controller can be found here: https://github.com/Koenkk/zigbee-herdsman/blob/master/src/controller/events.ts
  • as a reference you can use https://github.com/Koenkk/zigbee2mqtt/blob/zigbee-herdsman-controller/lib/zigbee.js

[hobbyquaker]

Thanks for the answer and the API hints! Will try to move my project to 0.6 asap ;)

[Koenkk]

Great, feel free to ask any questions here.

[hobbyquaker]

@Koenkk I would like to offer my help with documentation: adding jsdoc comments in the source, configure jsdoc&jsdoc2markdown to create an API.md file documenting all methods/properties/events. What do you think about that? Would you accept PRs?

[Koenkk]

Yes definitely! Let me know if something is unclear.

I would recommend starting with the things I mentioned here: https://github.com/Koenkk/zigbee-herdsman/issues/23#issuecomment-528857240

[hobbyquaker]

• https://github.com/hobbyquaker/zigbee-herdsman/blob/master/docs/api.md
• https://github.com/hobbyquaker/zigbee-herdsman/commit/9ead960b050d8b9fd95e8f15260827935d4bd11c#diff-45602f0d151fb5f17a4630ef922b95fc

Have to get some more jsdoc(2md) knowledge, this is the first time I'm using it on Typescript and with Async/Await/Promises... This is just a first example so you get some impression on how this could look like ;-)

[Koenkk]

That looks like a good start :smile:

[hobbyquaker]

Hi @Koenkk
I managed it to adapt node-red-contrib-zigbee to zigbee-herdsman@0.7.0 and on my test system everything runs fine. I'm very excited about the herdsman, pairing works much better, until now everything works stable and consuming the api is much more pleasant than working with the shepherd :-) Thank you so much for your work!

Now i tried to upgrade my production system, but I was facing a problem. There are no messages incoming from my sensors, trying to control bulbs always ends in no network route (205). Do I see that right that this migration should just work (starting with already paired devices and a device db that was created by the shepherd)?

[hobbyquaker]

ah, nevermind, got it working 🎉 Made a little mistake leading to another panID: https://github.com/hobbyquaker/node-red-contrib-zigbee/commit/85883110ecc6ac0e67e3e43db9cd30fd1a6d52f7 :-)

[Koenkk]

Good to hear :smile:

[hobbyquaker]

Another Question: I'm keeping track of binds in the device.meta to offer a nice ui for binding: What do you think about the suggestion to integrate that mechanism in the herdsman? Right now binds made by the configure extensions aren't tracked because it seemed to complicated to hook oh these, that's something I'd like to have in future... If you want I could try to prepare a PR, but most likely I will need some hands-holding and pushes into the right direction ;-)

[hobbyquaker]

And one more question: I also have a ui to select which devices should report: But I have no clue how to "un-report". Removing the bind isn't enough I guess, can I remove them completely by some special configuration on endpoint.configureReporting(cluster, configuration)?

[Koenkk]

• Keeping track of the binds is a good idea; if you can prepare a pr we can continue from there:
  • Take a look at how the members in groups are implemented, I think this should be similar
• To un-report, provide 0xffff as the maximum reporting value (see 2.5.7.1.6 of https://github.com/Koenkk/zigbee-herdsman/blob/master/docs/07-5123-06-zigbee-cluster-library-specification.pdf)

[bohtho]

This is exemplary complementary development! And with such quality! I’m ditching my current zigbee system and migrating it all to zigbee-herdsman/node-red-contrib-node-zigbee based on reputation, documentation and what I see here alone.