Repository navigation
[REQUEST] zigpy-blz is a new radio library that adds support for Bouffalo Lab Zigbee (BLZ) radios to zigpy #1595
Description
FYI, zigpy-blz is a new experimental open-source Python library that adds support for Bouffalo Lab Zigbee (BLZ) radios to zigpy:
Packages are also published on PyPI as zigpy-blz to enable installation via pip install zigpy-blz
Update: FYI; With this not being in ZHA fangzheli as a workaround to make this easier to test currently maintain a custom ZHA component to patch BLZ radio support into ZHA, (which requires tracking every HA Core release):
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?
Home Assistant BLZ Radios Integration Guide:
Reference Device:
Radio MCU SoC details:
Recommended firmware for the Third Reality USBC-Dongle:
Firmware Flashing Instructions:
Configuration:
- serial baudrate = 2000000
BLZ Serial Protocol Specification:
For more details on the protocol used by Bouffalo Lab radios, see the Bouffalo Lab Zigbee (BLZ) documentation:
PS: fangzheli has also submitted a PR for adding experimental adapter with BLZ Serial Protocol support to zigbee-herdsman (Zigbee2MQTT):
Activity
fangzheli commentedon Jul 15, 2025
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 commentedon Jul 24, 2025
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 commentedon Jul 24, 2025
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:
pipiche38 commentedon Jul 24, 2025
@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 commentedon Jul 24, 2025
@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
fangzheli commentedon Jul 24, 2025
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 commentedon Aug 13, 2025
Integration on Z4D undergoing zigbeefordomoticz/Domoticz-Zigbee#1852
Hedda commentedon Aug 13, 2025
@fangzheli I also like to recommend that you consider donating/transfer ownership of zigpy-blz to the shared zigpy organization:
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/
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:
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:
Hedda commentedon Jan 9, 2026
@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_powerSee:API for setting the TX power at runtime #1703
Implement zigpy TX power API bellows#698
Implement zigpy
set_tx_powerAPI zigpy-znp#266Hedda commentedon Jan 9, 2026
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)
PS: Again, there is also an inexpensive BLZ-based Zigbee Coordinator USB dongle available from Third Reality @ 3reality.com here:
fangzheli commentedon Mar 23, 2026
Hi all, a quick status update on zigpy-blz:
zigpy-blzv0.1.0 is now available —pip install zigpy-blzfeat/blz). Z2M Docker images with BLZ support available atghcr.io/fangzheli/zigbee2mqtt:latest-dev, and as a Home Assistant add-on via hassio-zigbee2mqtt@Hedda regarding the
_set_tx_powerAPI — 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.
Use pypi zigpy-blz instead of a repository clone cf. zigpy/zigpy#1595…
Hedda commentedon Jul 27, 2026
FYI, "PineDio USB-C Zigbee Dongle (from Pine64)" is another ready-made Zigbee Coordinator USB radio adapter on the market using the Bouffalo Labs BL706 chipset:
It looks like it is current being sold for less than $20 and right now they have it sale for less too:
SKU: PINEDIO-ZIGBEE
Based on the Bouffalo Labs BL706 chipset.
Includes a U-shape USB-A to USB-C connector.
Dimension: 75mm x 23.8 mm