feat: Bouffalo Lab Zigbee (BLZ)

[fangzheli]

BLZ Adapter Status

The BLZ adapter is developed to work with Bouffalo Lab Zigbee chips using the BLZ Serial Protocol.
It reuses and adapts parts of the EZSP adapter implementation to support the BLZ protocol efficiently.
Special thanks to @kirovilya @Koenkk @Nerivec and @G1K for their contributions to the EZSP adapter, which greatly helped the development of this project.

Recommended firmware: ThirdReality R3_706_dongle_v1.00.01.

Reference Device:

• Third Reality Zigbee 3.0 USB Dongle 3RZD02032Z (BL706)

Firmware Flashing Instructions:

• Home Assistant BLZ Radios Integration Guide

BLZ Serial Protocol Specification:

• Bouffalo Lab BLZ Protocol UG100

---

Settings

• Specify the correct UART port or USB device
• Set adapter type to "blz"
• Set baudrate to 2000000 (2 Mbps)

Example configuration:

serial:
  port: /dev/ttyUSB0  # Replace with your correct port
  adapter: blz
  baudrate: 2000000

---

Worked

• [x] Pairing/Leaving devices
• [x] Basic Bind/Unbind
• [x] Sending/Receiving ZCL messages
• [x] Building and displaying network map
• [x] Coordinator reboot and recovery
• [x] OTA updates (firmware distribution to end devices)
• [x] Backup and Restore (experimental)

---

TODO

• [ ] Improve network stability under heavy load
• [ ] Full support for Groups (multicast addressing)
• [ ] Touchlink commissioning
• [ ] Zigbee Green Power (ZGP) support
• [ ] Install Codes for secure joining
• [ ] Metrics/Statistics reporting
• [ ] Better error handling and timeout management
• [ ] Complete multi-endpoint binding support

---

I encourage developers and testers to participate in improving the adapter.

[Koenkk]

Thanks for your PR!

I noticed that many parts have been copied from the deprecated ezsp driver, which has been replaced by the new ember driver. The ember driver offers better code quality and is therefore more maintainable and stable. In its current form, this PR introduces too much duplication and low-quality code and given that it only adds supports for a single adapter, I cannot accept it in its current state.

Since this adapter shares similarities with the EZSP protocol, a more sustainable approach would be to make the device firmware fully compatible with the EZSP protocol. This would enable the reuse of the battle-tested ember driver.

[fangzheli]

@Koenkk Thank you for reviewing the PR so promptly—I really appreciate the detailed feedback. I understand your concerns about the duplication and the reliance on code from the deprecated EZSP driver.

For context, the firmware on the Third Reality Zigbee Dongle isn’t something I can realistically modify, so moving it to the ember driver isn’t really an option. That said, the BL706 series from Bouffalo Lab looks promising and pretty interesting, and I think adding host-side support for BLZ (BL706's Zigbee serial protocol) in Zigbee2MQTT would be a nice benefit for the community.

I’m happy to rework the PR so it follows the architecture and quality standards of the ember driver (or any structure you recommend) and removes the duplication you highlighted. If I rewrite the integration along those lines, would that meet the requirements for merging BLZ support?

Also, I would be happy to take care of the long-term maintenance and support for the BLZ adapter going forward.

I’m eager to iterate on this and would welcome any pointers you can share on the best path forward.

Thanks again, and I look forward to your advice.

[Koenkk]

As an initial step, maybe we can make it available as a third-party integration? Just like the zigpy addon.

Then we can get some impression on how many people use it, in case it becomes significant we can integrate it for out-of-the-box support.

[Hedda]

For context, the firmware on the Third Reality Zigbee Dongle isn’t something I can realistically modify, so moving it to the ember driver isn’t really an option.

@fangzheli FYI, just so that there is no misunderstanding, Koenkk meant that you should base the zigbee-herdsman code on this:

https://github.com/Koenkk/zigbee-herdsman/tree/master/src/adapter/ember

Instead of basing it on this:

https://github.com/Koenkk/zigbee-herdsman/tree/master/src/adapter/ezsp

That ember adapter code in zigbee-herdsman has replaced the old ezsp adapter code in zigbee-herdsman which is decrepated.

Hence the suggestion to rebase the code on that instead, (so it has nothing to do wuth firmware).

[fangzheli]

@Koenkk Thanks for the suggestion on addon. I will try to set it up.

Hence the suggestion to rebase the code on that instead, (so it has nothing to do with firmware).

@Hedda Thanks for the clarification! I would be happy to rebase the code on ember driver! But @Koenkk also mentioned his concern on duplication, any suggestion @Koenkk @Hedda ?

[Hedda]

For context, the firmware on the Third Reality Zigbee Dongle isn’t something I can realistically modify

IMHO, since you can not change the firmware I am guessing is probably no other option than to duplicate the code from the ember driver as a new adapter driver? At least then users of other adapter drivers are not affected or vice versa.

[github-actions[bot]]

This pull request is stale because it has been open 60 days with no activity. Remove stale label or comment or this will be closed in 7 days

[Hedda]

Any updates on this?