Skip to content

Conversation

@fangzheli
Copy link

@fangzheli fangzheli commented Apr 26, 2025

BLZ Adapter Status

Status Contributions

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:

Firmware Flashing Instructions:

BLZ Serial Protocol Specification:


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

  • Pairing/Leaving devices
  • Basic Bind/Unbind
  • Sending/Receiving ZCL messages
  • Building and displaying network map
  • Coordinator reboot and recovery
  • OTA updates (firmware distribution to end devices)
  • 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
Copy link
Owner

Koenkk commented Apr 27, 2025

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
Copy link
Author

@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
Copy link
Owner

Koenkk commented Apr 28, 2025

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
Copy link
Contributor

Hedda commented May 6, 2025

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
Copy link
Author

@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
Copy link
Contributor

Hedda commented May 6, 2025

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
Copy link
Contributor

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

@github-actions github-actions bot added the stale label Nov 18, 2025
@Hedda
Copy link
Contributor

Hedda commented Nov 18, 2025

Any updates on this?

@github-actions github-actions bot removed the stale label Nov 19, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants