Hardware and firmware
zigbee-bridge drives a Zigbee coordinator: a radio module running network co-processor (NCP) firmware, attached over USB serial, a UART, or TCP. The firmware decides whether it works, more than the hardware does.
No release has been tested on real hardware yet. Everything below “expected” is what the stack implements and the simulator covers. Reports that something works, or does not, are very welcome: open a hardware report.
Coordinators
Section titled “Coordinators”| Coordinator | Chip | Connection | Firmware | State |
|---|---|---|---|---|
| Home Assistant Connect ZBT-1 (SkyConnect) | EFR32MG21 | USB | EmberZNet 7.4 or newer, Zigbee NCP | Expected |
| Sonoff ZBDongle-E | EFR32MG21 | USB | EmberZNet 7.4 or newer (ships with 6.10: update it) | Expected |
| SMLIGHT SLZB-07 | EFR32MG21 | USB | EmberZNet 7.4 or newer | Expected |
| SMLIGHT SLZB-06M | EFR32MG21 | Ethernet, tcp:// |
EmberZNet 7.4 or newer | Expected |
| Other EFR32MG21, MG24 coordinators | EFR32MG2x | USB, UART, TCP | EmberZNet 7.4 to 8.x | Expected |
| Sonoff ZBDongle-P, SMLIGHT SLZB-06 | CC2652P | USB, TCP | Z-Stack 3.x.0 | Expected |
| Other CC2652, CC1352 coordinators | CC26x2, CC13x2 | USB, UART, TCP | Z-Stack 3.x.0 | Expected |
| CC2531 | CC2531 | USB | Z-Stack 3.0.x | expected, not recommended |
| ConBee II, ConBee III, RaspBee II | deCONZ | USB, GPIO UART | deCONZ firmware 0x26580700 or newer | Expected |
| EFR32 with EmberZNet 7.3 or older | EFR32 | EZSP 12 or older | unsupported: refused, update the firmware | |
| CC2530, CC2531 with Z-Stack Home 1.2 | CC253x | Z-Stack 1.2 | unsupported: refused, though probe identifies it |
|
| XBee, ZiGate, Telink, NXP | unsupported, not planned |
The firmware must be the Zigbee NCP build (also called “coordinator” or “ncp-uart”). Router, RCP (multiprotocol) and Thread firmware for the same stick will not work.
Silicon Labs EmberZNet
Section titled “Silicon Labs EmberZNet”The stack speaks EZSP protocol versions 13 to 19, which EmberZNet 7.4.0 to
8.x firmware uses. Older firmware (EZSP 12 and older) is detected and refused
with a message to update it; zigbee-bridge probe still identifies it.
Firmware builds are named for their flow control: ncp-uart-hw builds use
RTS/CTS (flow_control = "hardware"), ncp-uart-sw builds use XON/XOFF
(flow_control = "software"). Most run at 115200 baud; some builds run at
460800 (baud = 460800).
dresden elektronik deCONZ
Section titled “dresden elektronik deCONZ”Since 0.2.0. ConBee II, ConBee III and RaspBee II with dresden elektronik’s deCONZ firmware 0x26580700 or newer, over its serial protocol.
The deCONZ firmware does not report joins or leaves (the bridge learns of a
device from its announce) and keeps one global trust center link key. So
with a ConBee or RaspBee, join.install_code_only is refused, and
join.allow_legacy = false is not enforced.
Texas Instruments Z-Stack
Section titled “Texas Instruments Z-Stack”Since 0.2.0. Z-Stack 3.x.0 (CC2652, CC1352, CC26x2) and Z-Stack 3.0.x (CC2530, CC2531) coordinator firmware, over ZNP. A CC2531 works but is slow and has very little memory; it is fine for a test, not for a house.
Z-Stack does not report signal strength, link key exchanges or ZDO
delivery, so those readings are left out rather than guessed (rssi is
null in topology links), and Z-Stack itself enforces
join.allow_legacy = false. Z-Stack Home 1.2 is refused; probe still
identifies it.
Choosing the family
Section titled “Choosing the family”serial.adapter (since 0.2.0) is auto by default: the bridge probes the
port for EZSP, then ZNP, then deCONZ. Set ezsp, znp or deconz to skip
the probe. zigbee-bridge probe PORT runs the same probe and prints the
kind and product it found.
Check a coordinator
Section titled “Check a coordinator”probe sends one reset and a few read-only queries, prints what it found,
and closes the port. It never writes anything and finishes within a few
seconds:
zigbee-bridge probe /dev/serial/by-id/usb-Nabu_Casa_SkyConnect_v1.0_...{"kind":"ezsp","firmware":"7.4.4.0","protocol":13,"supported":true,"ieee_address":"0x...","manufacturer":"...","board":"..."}supported: false means the firmware is too old. No output and exit status
1 means nothing answered: check the port, --baud, and that the firmware is
an NCP build. Stop anything else using the port (another bridge, ModemManager)
first.
Flashing firmware
Section titled “Flashing firmware”Needs real hardware. Flashing replaces the firmware on the stick and can brick it if interrupted. Follow the vendor’s instructions where they differ from this summary.
EFR32 coordinators
Section titled “EFR32 coordinators”Use Nabu Casa’s
universal-silabs-flasher
(Python), which detects what is running and flashes .gbl images:
pip install universal-silabs-flasheruniversal-silabs-flasher --device /dev/serial/by-id/usb-... probeuniversal-silabs-flasher --device /dev/serial/by-id/usb-... flash --firmware <firmware>.gblFirmware images:
- Home Assistant Connect ZBT-1: Nabu Casa’s silabs-firmware-builder releases (the Zigbee NCP images), or Home Assistant’s own firmware update for the stick.
- Sonoff ZBDongle-E and other EFR32MG21 sticks: the darkxst/silabs-firmware-builder releases, or the vendor’s own.
- SMLIGHT devices: the firmware page of the device’s web interface.
CC2652 coordinators
Section titled “CC2652 coordinators”Use cc2538-bsl with the coordinator images from Koenkk/Z-Stack-firmware:
python3 cc2538-bsl.py -p /dev/ttyUSB0 -evw <firmware>.hexPick the image for your chip and board. Many sticks enter the bootloader by holding a button while plugging in; see the stick’s documentation.
ConBee and RaspBee
Section titled “ConBee and RaspBee”dresden elektronik’s GCFFlasher and the firmware from their download site.
Devices
Section titled “Devices”The bridge has no per-device database. Any device that implements the
standard Zigbee Cluster Library clusters reports through them; the
MQTT API lists which clusters become which fields,
and Home Assistant which entities they
become. Every attribute report is also published raw on
zigbee/<device>/report, so nothing a device sends is lost.
What does not work yet: devices that put their readings in manufacturer-specific clusters or non-standard attributes (common with Tuya and Xiaomi/Aqara devices), and devices that need a manufacturer-specific setup step. Support for those is on the roadmap.
Radio placement
Section titled “Radio placement”Zigbee shares the 2.4 GHz band with Wi-Fi, and USB 3 ports radiate noise in
the same band. Put the coordinator on a USB 2 extension cable, away from the
computer and from USB 3 devices. Choose a channel away from your Wi-Fi: the
energy_scan request measures every channel, and
network.channel sets the channel of a new network. Channels 15, 20 and 25
sit between the common Wi-Fi channels 1, 6 and 11.