Warning
This project is incomplete and is not ready for use.
It is under active development and will have bugs, missing features, breaking changes, and may cause instability in your Home Assistant instance or Zigbee network. There is no support provided at this stage.
Do not install this on any Home Assistant instance you rely on.
The reliable Zigbee integration for Home Assistant — powered by zigbee-herdsman. No MQTT required.
| Feature | ZHA | Zigbee2MQTT | Zigbee2HASS |
|---|---|---|---|
| No MQTT broker needed | ✅ | ❌ | ✅ |
| Process isolated from HA | ❌ | ✅ | ✅ |
| Command confirmation + retry | ❌ | ❌ | ✅ |
| State reconciliation on reconnect | ❌ | ❌ | ✅ |
| Coordinator watchdog | ❌ | ❌ | ✅ |
| Smart availability (ping mains, timeout battery) | ❌ | Partial | ✅ |
| Auto NVRam backup | ❌ | Manual | ✅ |
| Native HA entities (not MQTT sensors) | ✅ | Partial | ✅ |
| 4000+ devices (zigbee-herdsman-converters) | Partial | ✅ | ✅ |
[Zigbee USB Stick]
↓
[HA Add-on: Node.js + zigbee-herdsman] ← process isolated, survives HA restarts
↓ WebSocket (localhost:8756)
[HA Custom Integration: Python] ← native entities, proper HA platform
↓
[Home Assistant Entities]
- In HA, go to Settings → Add-ons → Add-on Store
- Click the three-dot menu → Repositories
- Add:
https://github.com/bushrangerlabs/zigbee2hass
- Find Zigbee2HASS in the add-on store and install it
- Configure your serial port and adapter type in the add-on configuration tab
- Start the add-on
- Copy the
custom_components/zigbee2hassfolder to your HAcustom_componentsdirectory - Restart Home Assistant
- Go to Settings → Integrations → Add Integration → Zigbee2HASS
- The add-on will be auto-discovered if running on the same machine
You can import your existing Z2M devices — no re-pairing needed.
Call the service in HA Developer Tools:
service: zigbee2hass.migrate_from_z2m
data:
z2m_data_dir: /share/zigbee2mqttThis imports:
coordinator_backup.json— your entire paired device networkdatabase.db— device records and interview data- Device friendly names from
configuration.yaml
| Chip | Adapter | Status |
|---|---|---|
| CC2652P / CC2652R (Sonoff Dongle Plus, SZBT-7) | zstack | ✅ Recommended |
| CC2652RB (Tube's CC2652RB) | zstack | ✅ Recommended |
| CC1352P | zstack | ✅ Supported |
| ConBee II / RaspBee II | deconz | ✅ Supported |
| EZSP / EFR32 (Sonoff Dongle Plus-E, HUSBZB-1) | ezsp / ember | |
| ZiGate | zigate | |
| nRF (ZBOSS) | zboss | |
| CC2531 | zstack | ❌ Not recommended (old, limited) |
Set serial_port to a URI instead of a device path — no extra drivers or software needed.
| Device | serial_port example |
|---|---|
| SLZB-06 / SLZB-06M | tcp://192.168.1.100:6638 |
| Tube's Zigbee Gateway | tcp://192.168.1.100:6638 |
| UZG-01 | tcp://192.168.1.100:6638 |
| ZigStar | tcp://192.168.1.100:6638 |
| Any mDNS/Zeroconf adapter | mdns://hostname |
| Service | Description |
|---|---|
zigbee2hass.permit_join |
Open/close network for new device pairing |
zigbee2hass.ping_device |
Ping a device, returns latency in ms |
zigbee2hass.backup |
Trigger immediate NVRam backup |
zigbee2hass.migrate_from_z2m |
Import from a Z2M data directory |
zigbee2hass.restart_addon |
Restart the Zigbee controller |
Command confirmation — every command sent to a device waits for a state report confirmation before resolving. If no confirmation arrives within the timeout, the command is retried (configurable, default 3 attempts).
State reconciliation — when the HA integration (re)connects to the add-on, it receives a full device state snapshot. Any state drift is immediately corrected — no silent desync.
Coordinator watchdog — if no messages are received from the coordinator for 2 minutes, the watchdog attempts an automatic reconnect. After 3 consecutive failures, HA is alerted and a coordinator_failed event is fired.
Smart availability — mains-powered devices are actively pinged on a configurable interval. Battery-powered end devices use silence detection respecting their sleep cycles.
NVRam backup — the coordinator NVRam (which stores your paired device network) is automatically backed up every hour by default. This lets you swap coordinator hardware without re-pairing all devices.
| Option | Default | Description |
|---|---|---|
serial_port |
/dev/ttyUSB0 |
Coordinator path or URI — see below |
adapter |
auto |
Adapter type: auto, zstack, deconz, ezsp, ember, zigate, zboss |
baudrate |
115200 |
Serial baud rate (USB only — ignored for TCP/mDNS) |
rtscts |
false |
Hardware flow control (USB only — ConBee II requires true) |
disable_led |
false |
Disable the coordinator LED (SLZB-06, some CC2652P sticks) |
channel |
11 |
Zigbee channel (11-26) |
log_level |
info |
Log level: debug, info, warning, error |
availability_timeout |
300 |
Seconds before battery device marked unavailable |
availability_ping_interval |
60 |
Seconds between mains device pings |
command_timeout |
5000 |
Milliseconds to wait for command confirmation |
command_retries |
3 |
Number of command retry attempts |
nvram_backup |
true |
Enable automatic NVRam backups |
nvram_backup_interval |
3600 |
Seconds between automatic backups |
/dev/ttyUSB0 # USB serial (also /dev/serial/by-id/...)
tcp://192.168.1.100:6638 # Network coordinator over TCP
mdns://slzb-06 # Network coordinator via mDNS/Zeroconf
MIT © 2026