[REQUEST] zigpy-blz is a new radio library that adds support for Bouffalo Lab Zigbee (BLZ) radios to zigpy

[Hedda]

FYI, zigpy-blz is a new experimental open-source Python library that adds support for Bouffalo Lab Zigbee (BLZ) radios to zigpy:

• https://github.com/bouffalolab/zigpy-blz

  • https://github.com/fangzheli/zigpy-blz

Update: Packages are published on PyPI as zigpy-blz to enable installation via pip install zigpy-blz

• https://pypi.org/project/zigpy-blz/

Supported hardware includes:

• ThirdReality Zigbee 3.0 USB Dongle (based on the Bouffalo Lab BL706 chip).
• Any other Zigbee Coordinator based on Bouffalo Lab BL702 or Bouffalo Lab BL706 chips.

Developed by @fangzheli but published under the Bouffalo Lab orginazation, so looks official or semi-official?

• https://github.com/bouffalolab/zigpy-blz/blob/main/README.md

Home Assistant BLZ Radios Integration Guide:

• https://github.com/bouffalolab/zigpy-blz/blob/main/docs/Home_Assistant_BLZ_Radios_Integration_Guide_1.0.0.pdf

Reference Device:

• Third Reality USBC-Dongle

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

Radio MCU SoC details:

• Bouffalo Lab BL702.

Recommended firmware for the Third Reality USBC-Dongle:

• ThirdReality R3_706_dongle_v1.00.01.

Firmware Flashing Instructions:

• https://github.com/bouffalolab/zigpy-blz/blob/main/docs/Home_Assistant_BLZ_Radios_Integration_Guide_1.0.0.pdf

Configuration:

• serial baudrate = 2000000

BLZ Serial Protocol Specification:

• Bouffalo Lab BLZ Protocol UG100

For more details on the protocol used by Bouffalo Lab radios, see the Bouffalo Lab Zigbee (BLZ) documentation:

• Bouffalo Lab BLZ Protocol

• BLZ ZHA User Guide

PS: fangzheli has also submitted a PR for adding experimental adapter with BLZ Serial Protocol support to zigbee-herdsman (Zigbee2MQTT):

• feat: Bouffalo Lab Zigbee (BLZ) Koenkk/zigbee-herdsman#1397

[fangzheli]

Thanks @Hedda for taking the time to go through the project and organize the information so clearly.
BLZ is still in its early stages, and we truly welcome contributions and feedback from the open-source community.
We invite anyone interested to contribute.

[pipiche38]

I would be happy to get it validated with the Zigbee for Domoticz plugin
Any chance to get a sample to test+validate the all stack ?

[Hedda]

FYI, if anyone want to test this and other zigpy radio libraries from third-parties with the zha library (which is used by Home Assistant’s native Zigbee Home Automation integration that comes built-in with HA) you should be aware that puddly has begun working on a pull request that will allow users to test third-party radio libraries for zigpy with ZHA. Check out this PR:

• Allow external radio types zha#461

[pipiche38]

@Hedda thanks , but as Domoticz is a C++ program and we are in an embedded python framework, we use only the low level zigpy layers.
As mentioned also by you this is zha related . we cannot rely on that, as we are not launching zigpy and using zigpy the way zha does

[Hedda]

@pipiche38 yeah I know, but this request is not on behalf of Domoticz users but instead befalf of zha users. So my reply was not directed towards the Domoticz tangent, but to projects using zigpy's zha library like Home Assistant's build-in ZHA integration:

• https://github.com/zigpy/zha

  • https://www.home-assistant.io/integrations/zha

[fangzheli]

I would be happy to get it validated with the Zigbee for Domoticz plugin Any chance to get a sample to test+validate the all stack ?

Yeah sure, you can email me detail for shipping to fangzhel@bouffalolab.com. I would ship a Third Reality Zigbee Dongle with BLZ firmware asap.

[pipiche38]

Integration on Z4D undergoing zigbeefordomoticz/Domoticz-Zigbee#1852

[Hedda]

@fangzheli I also like to recommend that you consider donating/transfer ownership of zigpy-blz to the shared zigpy organization:

• https://github.com/zigpy

As such I wwould suggest that you consider asking/discussing the possibility with puddly about maybe giving/tranfering your zigpy-blz code and repository to the Open Home Foundation (which is the non-profit organization that governs all "official" zigpy projects) and moving the mainline zigpy-blz project/repository from https://github.com/fangzheli/zigpy-blz/ (and https://github.com/bouffalolab/zigpy-blz) to the upstream zigpy organization on GitHub @ https://github.com/zigpy/ (which is a "organization" on GitHub for grouping repositories that is maintained the same community) so that the mainstream copy of this repo will stay there become upstream for shared access together by the collective of developers that make up the zigpy organization?

That is, make puddly and the other administrators from the zigpy project co-administrators of this repository and then have them move this whole repository from https://github.com/fangzheli/zigpy-blz and https://github.com/bouffalolab/zigpy-blz to https://github.com/zigpy/zigpy-blz

That "organization" is just GitHub's terminology as I understand it is more or less still only an informal collaboration between like-minded ZHA and zigpy developers in order to collect ZHA and zigpy projects ín one place and shared access rights, (noting that the zigpy organization on GitHub has no public members and that you must be a member to see who’s a part of that organization, which I am not myself).

https://github.com/zigpy/

I understand that this would not mean that support for zigpy-blz have to be implemeneted upstream into Home Assistant's ZHA integration right away. This zigpy-blz can still remain listed as experimental. I am however sure that it would gain much more attention from additional third-party developers if this repository belonged to the existing zigpy organization.

Most other ZHA related repositories have sooner or later been moved to the zigpy organization over time as a way for like-minded ZHA and zigpy developers that are members of the zigpy organization with yourself included can have shared ownership and access to your zigpy-blz repository and the other projects for collaboration within that community.

Again, moving this zigpy-blz repository there could potentially also help both new ZHA/zigpy developers and others to take more notice that this zigpy-blz radio library project exist (which is much less likely with it remaining here) and hopefully more developers will then eventually be interested to help and assistant with improving and maintaining.

Perhaps ask if should also do the same with any specific firmware repository with your reference firmware image for testing this?

• https://github.com/fangzheli/zigpy-blz/

  • https://github.com/bouffalolab/zigpy-blz

Hope that you at least will consider this option and if you think it is a good idea then hoping that you all could come to an agreement that will make everyone happy with you continuing this zigpy-blz repository under the zigpy organization together without getting offended by any ownership conflicts.

Anyway, I believe moving zigpy-blz is wanted by the overall zha community and would make so more people notice it:

• [REQUEST] zigpy-blz is a new radio library that adds support for Bouffalo Lab Zigbee (BLZ) radios to zigpy #1595

PS: By the way, the same people who are members of that zigpy organization on GitHub also share another GitHub organization called "zha-ng" (guess it is short for "ZHA next-generation"?) which historically previously contains additional early experimental projects before they became mature and was later moved to the common zigpy organization on GitHub:

• https://github.com/zha-ng

[Hedda]

@fangzheli FYI, zigpy library has added a TX power API for setting the TX power at runtime, and the ZHA implementation uses country code will be pulled from the zigpy config dict at network startup, which ZHA will update with the country code supplied by Home Assistant. Radio libraries implementing this API need to supply _set_tx_power See:

• API for setting the TX power at runtime #1703

  • Implement zigpy TX power API bellows#698

  • Implement zigpy set_tx_power API zigpy-znp#266

[Hedda]

For refernce; fangzheli have been continuously improving the code quality based on the earlier feedback from Zigbee2MQTT devs:

Originally posted by @fangzheli in Koenkk/zigbee-herdsman#1397 (comment)

I’m happy to keep iterating to make it easier to maintain long-term. At the same time, interest is growing: Third Reality is already using BLZ for their Zigbee dongle and has now also launched a new Linux Box dev kit based on BLZ, and PINE64 is also planning to adopt BLZ in their upcoming hardware as well.

I will be at CES 2026 in Las Vegas (Venetian, Booth 52162). If you’re around, you’re very welcome to drop by to discuss how we can move BLZ support forward and eventually merge it.

• https://3reality.com/product/linux-box-dev-edition/

PS: Again, there is also an inexpensive BLZ-based Zigbee Coordinator USB dongle available from Third Reality @ 3reality.com here:

• https://3reality.com/product/3-0-usbc-dongle/

[fangzheli]

Hi all, a quick status update on zigpy-blz:

• PyPI: zigpy-blz v0.1.0 is now available — pip install zigpy-blz
• Zigbee2MQTT: BLZ adapter for zigbee-herdsman is functional (branch feat/blz). Z2M Docker images with BLZ support available at ghcr.io/fangzheli/zigbee2mqtt:latest-dev, and as a Home Assistant add-on via hassio-zigbee2mqtt
• ZHA (HAOS): Custom ZHA component with BLZ support installable via HACS from bouffalolab/haos_custom_zha_blz
• Hardware: Third Reality Zigbee 3.0 USB dongles (BL702) are the primary reference hardware

@Hedda regarding the _set_tx_power API — thanks for the heads-up, it's on our radar.

We're also watching zigpy/zha#461 closely — once external radio types land in ZHA, it would eliminate the need for the custom component path entirely.