zigpy-blz

zigpy-blz is a Python library that adds support for Bouffalo Lab Zigbee (BLZ) radios to zigpy, a Python Zigbee stack project.

It is designed to interface with Bouffalo Lab Zigbee (BLZ) radios, enabling users to communicate with Zigbee devices using zigpy and compatible home automation platforms, such as Home Assistant's ZHA (Zigbee Home Automation) integration component.

Installation

Via the BLZ Custom ZHA Component (Recommended)

The easiest way to use zigpy-blz with Home Assistant is to install the BLZ Custom ZHA Component, which automatically pulls in zigpy-blz as a dependency. See that repository for HACS and manual install instructions.

Python Module

Install the Python module in your virtual environment:

$ python3 -m venv venv                                                     # if you don't already have one
$ source venv/bin/activate
(venv) $ pip install git+https://github.com/bouffalolab/zigpy-blz.git@main # latest commit from Git
(venv) $ pip install zigpy-blz                                             # or, latest stable from PyPI

Home Assistant Core (manual)

Upgrade the package within your virtual environment (requires git):

(venv) $ pip install git+https://github.com/bouffalolab/zigpy-blz.git@main

Hardware Support

zigpy-blz is compatible with Bouffalo Lab's BLZ radios, which use the Bouffalo Zigbee Serial Protocol (BZSP). Ensure your firmware version matches the protocol version supported by this library.

Supported hardware includes:

• Bouffalo Lab BL702
• Bouffalo Lab BL706
• ThirdReality Zigbee 3.0 USB Dongle

Developer References

For more details on the protocol used by Bouffalo Lab radios, see:

• UG100 Bouffalo Lab Zigbee (BLZ) Protocol (included in this repo)

How to Contribute

We welcome contributions! If you'd like to contribute to this project, please follow the steps in the following guides:

• First Contributions
• GitHub Desktop Tutorial

Testing

Unit tests are available to verify the implementation. To run the tests, use:

pytest tests/

Releases via PyPI

Tagged versions of zigpy-blz are released via PyPI. Push a v* tag to trigger the release workflow.

Related Projects

• zigpy: The core Python Zigbee stack project that integrates with ZHA in Home Assistant.
• BLZ Custom ZHA: Custom ZHA component with BLZ radio support for Home Assistant.
• Home Assistant ZHA: Zigbee Home Automation integration component in Home Assistant.