A Zigbee coordinator stack and Zigbee to MQTT bridge, written in Rust. It runs a Zigbee network through a USB or network coordinator, interviews the devices that join, and publishes their readings to MQTT with Home Assistant discovery. It is one static binary with no runtime: CI holds it under 4 MB, and the stack under 16 MB of memory with 200 devices, so it fits on routers and small gateways as well as on a Raspberry Pi or a server. The same stack is a set of library crates for anyone building their own Zigbee software in Rust.
It exists because the established Zigbee stacks need a Node.js or Python runtime, and there was no complete, embeddable Zigbee coordinator stack in Rust.
Documentation | Quick start | Hardware | MQTT API | Library | Changelog
zigbee-bridge is 0.x and young. Version 0.3.0 is the third release and the first on crates.io. The whole stack is tested in CI against a coordinator simulator, but it has not yet been tested on real hardware. Expect rough edges and breaking changes between 0.x releases, and keep a backup of your network (backup and restore).
| Feature | State |
|---|---|
| Silicon Labs EmberZNet 7.4 and 8.x coordinators (EZSP 13 to 19) | done in 0.1.0 |
| Network formation, resume, and refusal to wipe an unknown network | done in 0.1.0 |
| Zigbee 3.0 trust center: unique link keys, install codes, join policy | done in 0.1.0 |
| Device interview, binding and reporting configuration, IAS zone enrollment | done in 0.1.0 |
| Readings from the standard ZCL clusters (no per-device converters needed) | done in 0.1.0 |
| On/off, brightness and color temperature control | done in 0.1.0 |
| Home Assistant MQTT discovery | done in 0.1.0 |
| Backup and restore in the open coordinator backup format, dongle migration | done in 0.1.0 |
| Network topology, neighbor scans, energy scan | done in 0.1.0 |
Read-only coordinator probe (zigbee-bridge probe) |
done in 0.1.0 |
| Texas Instruments Z-Stack 3 coordinators (ZNP) | done in 0.2.0 |
| dresden elektronik ConBee and RaspBee (deCONZ) | done in 0.2.0 |
| Channel change without re-pairing | done in 0.2.0 |
| Device firmware updates (OTA) from image files you provide | done in 0.2.0 |
| Restore a backup onto a coordinator of another family | done in 0.2.0 |
| Testing on real coordinators and devices | in progress |
| Manufacturer-specific clusters and per-device quirks | planned |
| Groups, scenes and binding requests over MQTT | planned |
| A web frontend | not planned; the bridge is headless by design |
The coordinator is a radio module with network co-processor (NCP) firmware. Expected means the hardware runs firmware the stack implements and is covered by the simulator, but nobody has reported it working yet. If you try one, please tell us how it went.
| Coordinator | Chip | Firmware | State |
|---|---|---|---|
| Home Assistant Connect ZBT-1 (SkyConnect) | EFR32MG21 | EmberZNet 7.4 or newer, NCP | expected |
| Sonoff ZBDongle-E | EFR32MG21 | EmberZNet 7.4 or newer, NCP (ships with 6.x: update it first) | expected |
| SMLIGHT SLZB-06M, SLZB-07 | EFR32MG21 | EmberZNet 7.4 or newer, NCP (SLZB-06M over tcp://) |
expected |
| Any EFR32MG21 or MG24 coordinator | EFR32MG2x | EmberZNet 7.4 to 8.x, NCP | expected |
| Sonoff ZBDongle-P, SMLIGHT SLZB-06 | CC2652P | Z-Stack 3.x.0 | expected |
| ConBee II, ConBee III, RaspBee II | deCONZ | deCONZ firmware 0x26580700 or newer | expected |
| EmberZNet 7.3 and older | EFR32 | EZSP 12 and older | unsupported: refused with "update the firmware" |
| CC2531, CC2530 | CC253x | Z-Stack Home 1.2 | unsupported: refused (probe still identifies it) |
| XBee, ZiGate, Telink, NXP | unsupported, not planned |
Devices: any Zigbee 3.0 or Zigbee HA 1.2 device that uses the standard clusters reports its readings without device-specific code. The hardware page lists what is exposed and how to flash recommended firmware.
From nothing to a sensor in Home Assistant, on 64-bit Linux (x86_64 or aarch64) with a supported coordinator. You need an MQTT broker (for example Mosquitto) that Home Assistant's MQTT integration already uses.
1. Download the release and check its checksum.
VERSION=0.2.0
ARCH=$(uname -m) # x86_64 or aarch64
BASE=https://github.com/pulzar-net/zigbee-bridge/releases/download/v$VERSION
curl -fsSLO "$BASE/zigbee-bridge-v$VERSION-$ARCH-unknown-linux-musl"
curl -fsSLO "$BASE/SHA256SUMS"
sha256sum --check --ignore-missing SHA256SUMS
sudo install -m 0755 "zigbee-bridge-v$VERSION-$ARCH-unknown-linux-musl" /usr/local/bin/zigbee-bridge
zigbee-bridge --version2. Check that the coordinator answers. Use the stable name under
/dev/serial/by-id/ rather than /dev/ttyUSB0, which can change between
boots.
ls /dev/serial/by-id/
sudo zigbee-bridge probe /dev/serial/by-id/usb-...It prints the firmware it found, for example {"kind":"ezsp","firmware":"7.4.4.0",...}.
If it says the firmware is too old, update it.
3. Write a minimal configuration to /etc/zigbee-bridge/config.toml.
Only serial.port is required; everything else has a default.
[serial]
port = "/dev/serial/by-id/usb-..." # the path from step 2
[mqtt]
host = "localhost" # your broker4. Run it. On first start it forms a new network with a random network
key, which it keeps in /var/lib/zigbee-bridge.
sudo zigbee-bridge --config /etc/zigbee-bridge/config.toml5. Pair a device. Open the network for two minutes, then reset the device or hold its pairing button.
mosquitto_pub -h localhost -t zigbee/bridge/request/permit_join -m '{"time": 120}'Within a minute the device appears in Home Assistant under Settings > Devices & services > MQTT. To watch everything the bridge publishes:
mosquitto_sub -h localhost -t 'zigbee/#' -vNo coordinator yet? The getting started guide runs the same steps against the simulator. To run the bridge as a service, see installation.
- Release binaries. Each release
has static Linux binaries for
x86_64,aarch64(Raspberry Pi 3 and newer with a 64-bit OS) andmipsel(MT7621 and MT7628 routers), with aSHA256SUMSfile. They have no runtime dependencies. - From crates.io, with Rust 1.89 or newer:
cargo install --locked zigbee-bridge - systemd: a hardened unit is in
contrib/systemd/. - OpenWrt: a procd init script is in
contrib/openwrt/.
The installation guide covers each one step by step.
The bridge reads one TOML file, /etc/zigbee-bridge/config.toml by default
(--config FILE to change it). It has these tables:
| Table | What it sets |
|---|---|
[serial] |
the coordinator's port (serial device or tcp://host:port), baud rate, flow control, family |
[mqtt] |
broker, credentials (password from a file), client id, base topic |
[homeassistant] |
discovery on or off, discovery prefix, Home Assistant's status topic |
[network] |
channel and transmit power for a new network; whether to replace a foreign one |
[join] |
install-code-only joining, whether pre-Zigbee 3.0 devices may stay |
[data] |
the data directory: network keys, device store, backup |
[ota] |
where device firmware images are kept |
Unknown keys are an error, so a typo stops the bridge at startup. Every key,
its type and default are in the
configuration reference,
which is generated from the code. config.example.toml
shows them all. Log verbosity comes from RUST_LOG (default info).
Everything lives under a base topic, zigbee by default. Payloads are JSON.
| Topic | Direction | What |
|---|---|---|
zigbee/bridge/state |
out, retained | {"state":"online"} or {"state":"offline"} (also the last will) |
zigbee/bridge/info |
out, retained | version, coordinator, channel and PAN ids, join state |
zigbee/bridge/devices |
out, retained | every device with its interview, endpoints and clusters |
zigbee/bridge/event |
out | joins, announces, interviews, leaves, removals, join window, channel and firmware update progress |
zigbee/bridge/request/<name> |
in | permit_join, remove, rename, install_code, interview, backup, topology, scan_neighbors, energy_scan, devices, change_channel, ota_check, ota_update |
zigbee/bridge/response/<name> |
out | {"status":"ok","data":{...}} or {"status":"error","error":"..."} |
zigbee/<device> |
out, retained | the device's state, for example {"temperature":21.5,"humidity":45.2,"linkquality":160} |
zigbee/<device>/set |
in | {"state":"ON"}, {"brightness":128,"transition":1}, {"color_temp":300} |
zigbee/<device>/report |
out | every attribute report, by cluster and attribute name |
zigbee/<device>/action |
out | commands the device sends, such as button presses |
<device> is the name you gave the device with the rename request, or its
IEEE address (0x00124b0001020304). Network keys never appear on MQTT. The
MQTT reference has
every payload with examples.
The bridge is a thin layer over library crates you can use on their own.
| Crate | What it is |
|---|---|
zigbee-host |
the coordinator host: formation, trust center, interview, reporting, device store, backup and restore, topology, probe |
zigbee-zcl |
the Zigbee Cluster Library: data types, frames, global commands, cluster definitions |
zigbee-zdo |
Zigbee Device Object frames: discovery, binding, network management |
zigbee-ezsp |
Silicon Labs EZSP frames and an async client |
zigbee-ash |
the ASHv2 serial link that carries EZSP, as a sans-IO state machine |
zigbee-znp |
Texas Instruments Z-Stack ZNP frames and an async client |
zigbee-deconz |
dresden elektronik deCONZ serial frames and an async client |
zigbee-primitives |
addresses, keys and a bounds-checked wire reader shared by all crates |
zigbee-sim |
a coordinator simulator with simulated devices, for tests without hardware |
zigbee-bridge |
the MQTT bridge, as a binary and a library |
Each is on crates.io with its API on docs.rs. For the example below:
cargo add zigbee-host zigbee-zcl
cargo add tokio --features macros,rt-multi-threadThis example starts a network, lets a device join, and reads its
temperature. It runs here against the simulator; on hardware, open the port
with zigbee_host::port::open("/dev/ttyUSB0", 115_200, FlowControl::None)
instead.
use zigbee_host::probe::NcpKind;
use zigbee_host::{random_network, AnyAdapter, Host, HostConfig, HostEvent, StartMode};
use zigbee_zcl::{attr, cluster_id};
# use zigbee_sim::{SimConfig, SimDevice, Simulator};
# use zigbee_primitives::Ieee;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
# let sim = Simulator::new(SimConfig {
# devices: vec![SimDevice::temperature_humidity_sensor(Ieee(0x00124b0000000001))],
# ..SimConfig::default()
# });
# let (port, ncp) = tokio::io::duplex(4096);
# tokio::spawn(async move { sim.serve(ncp).await });
let (adapter, adapter_events) = AnyAdapter::connect(port, NcpKind::Ezsp).await?;
let mode = StartMode::Normal { settings: random_network(15)?, replace_other: false };
let (host, mut events) = Host::start(adapter, adapter_events, mode, HostConfig::default()).await?;
// Open the network and wait for a device to join and finish its interview.
host.permit_join(60, None).await?;
let device = loop {
match events.recv().await {
Some(HostEvent::InterviewDone { device }) => break device,
Some(_) => continue,
None => return Err("the host stopped".into()),
}
};
println!("{} joined: {:?} {:?}", device.ieee, device.manufacturer, device.model);
// Read its temperature, if it has a thermometer.
let cluster = cluster_id::TEMPERATURE_MEASUREMENT;
if let Some(endpoint) = device.endpoint_with(cluster) {
let value = attr::temperature_measurement::MEASURED_VALUE;
let records = host.read_attributes(device.ieee, endpoint.endpoint, cluster, &[value]).await?;
println!("{records:?}");
}
host.shutdown().await?;
Ok(())
}The library guide covers each crate, and the API docs cover every item.
Home Assistant, Node-RED, scripts
│ MQTT (JSON, Home Assistant discovery)
┌───────────────┴───────────────────────────────────────┐
│ zigbee-bridge topics, requests, discovery, state │
├────────────────────────────────────────────────────────┤
│ zigbee-host formation, trust center, interview, │
│ reporting, device store, backup, │
│ topology, probe │
├──────────────┬──────────────┬──────────────────────────┤
│ zigbee-zcl │ zigbee-zdo │ zigbee-primitives │
├──────────────┴─┬────────────┴─┬────────────────────────┤
│ zigbee-ezsp │ zigbee-znp │ zigbee-deconz │
│ zigbee-ash │ │ │
└────────┬────────┴──────┬───────┴────────┬───────────────┘
│ serial or TCP │
Silicon Labs NCP TI Z-Stack NCP ConBee, RaspBee (or zigbee-sim)
│ │ │
Zigbee mesh: routers, end devices
The coordinator's firmware runs the radio, MAC, network layer and routing.
Everything above it, including the trust center, runs in the host. The
architecture page
explains the layers, the event flow and the design rules (no unsafe, no
panics on radio input, bounded memory).
| zigbee-bridge | Zigbee2MQTT | ZHA | |
|---|---|---|---|
| Language and runtime | Rust, one static binary | Node.js | Python, inside Home Assistant |
| Device support | standard clusters only, so far | over 4,000 devices with per-device converters | thousands, with quirks |
| Coordinators | EmberZNet, Z-Stack, deCONZ | EmberZNet, Z-Stack, deCONZ, ZiGate, others | EmberZNet, Z-Stack, deCONZ, ZiGate, XBee |
| Interface | MQTT and Home Assistant discovery | MQTT, discovery, web frontend | Home Assistant UI |
| Small hardware | runs on 128 MB MIPS routers | needs a Node.js capable host | needs Home Assistant |
| Embeddable library | yes, Rust crates | zigbee-herdsman (TypeScript) | zigpy (Python) |
| Maturity | 0.x, not yet hardware-tested | mature, very widely used | mature, very widely used |
Pick Zigbee2MQTT or ZHA if you want a large and varied device collection to work today, a web frontend, or automatic device firmware updates: they are mature and their device libraries are the work of thousands of contributors. Pick zigbee-bridge if you need Zigbee on hardware too small for Node.js or Python, a single static binary with no runtime, or a Zigbee stack to embed in Rust software, and your devices use the standard clusters. The topic scheme is modeled on Zigbee2MQTT's, so tools written for one need little change for the other, but the two are not interchangeable.
- Next: the first reports from real hardware.
- After that: manufacturer-specific clusters and device quirks, groups and scenes, binding over MQTT.
Questions go in Discussions; bugs and requests in issues.
Contributions are welcome, from hardware reports to code. The whole stack can be developed and tested without hardware, using the simulator. See CONTRIBUTING.md for how to build, test, fuzz and send a change, and the code of conduct.
Please report vulnerabilities privately through GitHub private vulnerability reporting, never in a public issue. See SECURITY.md for what to include and how fast we respond, and the security model for what the bridge protects.
MIT. See LICENSE.
The implementation follows the Zigbee specification and Silicon Labs' and Texas Instruments' public protocol documentation. zigbee-herdsman (MIT) was studied as a reference; no code was copied from any project.
zigbee-bridge is maintained by Pulzar, which uses it in its own gateways. It is developed in the open, for anyone to use.