Zigbee in Home Assistant: coordinator and sensors after HAOS

This article answers one buying question: Zigbee in Home Assistant after HAOS is installed. What to get if you assemble the network from scratch, instead of buying more of the devices already on the walls.

From scratch I would buy this. Zigbee2MQTT, a Sonoff ZBDongle-P coordinator, Aqara H1 switches with no neutral, two smart plugs as repeaters, an Aqara Motion Sensor P1, an Aqara Door and Window Sensor E1, an Aqara Wireless Mini Switch, an Aqara Temperature and Humidity Sensor WSDCGQ11LM, Royal Thermo thermostatic heads and a mains-powered curtain motor from Zemismart or Aqara. An Aqara hub is not required.

The no-neutral switches, Tuya door sensors, Aqara temperature and humidity sensors, two repeater plugs and the stick on a Ugreen hub that are already installed can stay. Sonoff motion sensors, the Tuya button and the battery curtain motor are not in the new set. The list comes first, then the devices left out, then the install.

Passing a USB stick into a virtual machine is covered in Home Assistant on Proxmox. The Aqara G4 doorbell is not part of this Zigbee network: it joins separately, through HomeKit and go2rtc, as described in Aqara G4 in Home Assistant.

Zigbee in Home Assistant from scratch

Software and the Zigbee coordinator first, then the Zigbee sensors and other devices I would put up instead of the ones already installed.

• Software. Zigbee2MQTT and the Mosquitto broker. I started on ZHA and left it: it supported few of the Zigbee devices I wanted. The motion-sensor interval and the switch that is detached from its lamp live on the device card. Those settings are why the set uses a separate app, not the built-in ZHA integration.
• Coordinator. The Zigbee coordinator is a Sonoff ZBDongle-P on a Texas Instruments CC2652P. The case says ZBDongle-P or Dongle Plus, without the letter E. In the Zigbee2MQTT adapter list it is the zstack adapter. My HAOS box is a fanless Intel N5095 mini PC. It has sat on a hallway wardrobe for five years, and the stick is plugged in through a Ugreen USB hub. The case is on the wardrobe, not inside a metal cabinet, so an Ethernet SLZB-06, a ZBDongle-E and a Home Assistant Connect ZBT-2 are not in this set.
• Switches. WS-EUK01 for one rocker and WS-EUK02 for two. These are Aqara H1 models with no neutral. The switch only breaks the live wire, there is no neutral in the box, and the electricians said a neutral switch is unsafe there. These models switch their own lights. Neighbouring sensors do not route through them: the plugs in the next line extend the network.
• Plugs. I extend the network with them. Three bedrooms and a combined kitchen and living room, 78 square metres, needed two: an IKEA TRADFRI smart plug and a Tuya smart plug from HOMMYN. Both are fine as repeaters. I do not use them as smart plugs: I never found a use for the relay. The IKEA page on Zigbee2MQTT says the plug is also a router. The HOMMYN Tuya plug shows up in Zigbee2MQTT as TS011F_plug_1, and after pairing its type should be Router. No-name smart plugs are unsafe: they can catch fire. This set only uses plugs with a clear brand.
• Motion. Aqara Motion Sensor P1, model RTCGQ14LM. Two CR2450 cells. The card exposes occupancy, illuminance, sensitivity and the detection interval. The five-year figure Aqara quotes assumes an interval of at least 30 seconds. A 2-second interval drains the cells faster. The sensor sleeps: press the button on the case before you save a setting.
• Doors. Aqara Door and Window Sensor E1, model MCCGQ14LM. The CC2652 coordinator needs firmware dated 20211114 or newer. A new ZBDongle-P usually already has that. Check the version before you buy a batch.
• Button. Aqara Wireless Mini Switch, model WXKG11LM. Single, double, triple and hold arrive in Zigbee2MQTT as an action.
• Curtains. Zemismart motors are fine in principle. Mine run on a battery pack: after four years it would no longer charge above about 75%. For a new buy I would take a mains-powered drive and look at Zemismart and Aqara curtains.
• Climate. Aqara Temperature and Humidity Sensor, model WSDCGQ11LM. I like these for accuracy, battery life and stable operation. The same sensors feed Better Thermostat as the room temperature.
• Thermostatic heads. Royal Thermo RTE 77.001B on the radiators. I like them. Better Thermostat from HACS takes the room temperature from an Aqara WSDCGQ11LM, plus the outdoor temperature and the window sensor from the same Zigbee2MQTT network.

This set does not need an Aqara hub. Sensors and switches join Zigbee2MQTT, and Home Assistant sees them over MQTT. A vendor cloud account is optional.

Switches with no neutral

In this apartment the switch only breaks the live wire. Neutral runs to the lamp and never enters the switch box. The electricians said a neutral switch is unsafe here, so they fit switches with no neutral. The set is therefore WS-EUK01 and WS-EUK02. WS-EUK03 and WS-EUK04 need a neutral in the box, and I do not install them.

There is no neutral in the box, so one would have to be brought in. That is the hazard. If the ground wire is used instead of neutral, current flows on the protective conductor: when that path breaks, the switch body and grounded parts sit at mains voltage. If neutral is borrowed from another circuit, the wire stays live after this circuit’s breaker is off, and an extra joint in a cramped old box runs hot. A no-neutral switch belongs in this box.

The small current through the lamp is enough for the switch to run itself, and not enough to relay other sensors. The card will say EndDevice. That is expected. The smart plugs carry the network through the apartment.

The card setting is operation_mode. control_relay is an ordinary rocker: press it and that rocker’s lamp turns on or off. decoupled means the rocker does not switch its own lamp. The press only reaches Home Assistant, and an automation turns the light on. On the double WS-EUK02 each rocker, left and right, is set on its own.

power_outage_memory is the state after a power cut. When power returns, the switch restores the lamp to the state it had. Pairing WS-EUK01: hold the button for about 10 seconds, until the blue indicator starts blinking and then stops. On WS-EUK02 hold the right button for 5 seconds.

Royal Thermo thermostatic heads

Royal Thermo heads are on my radiators, and I would buy them again from scratch. On the Zigbee2MQTT device page the model is Royal Thermo RTE 77.001B, a variant of Saswell SEA801/SEA802. The setpoint runs from 5 to 30 °C, and the modes are off, heat and auto.

The sensor inside the head sits against the hot pipe, so it is a poor room reading. Better Thermostat from HACS sits on top of Zigbee2MQTT. After HACS is installed, restart Home Assistant and add the integration: Settings → Devices & services → Add integration → Better Thermostat. For a room, pick the head’s climate entity and a separate temperature sensor from Zigbee2MQTT. Mine are Aqara WSDCGQ11LM: I like them for accuracy, battery life and stable operation. Put that sensor in the room, not on the radiator. If the room has several heads, one integration can take several climate entities.

The window and the outdoors are connected there too. A window sensor already in Zigbee2MQTT pauses the heat while the sash is open and resumes it when the sash closes. The delay works both ways, so a short airing does not kick the valve. If the room has several windows, pick a group: one open window is enough. The outdoor sensor on the same network sets the threshold. Better Thermostat takes a three-day mean and checks it every morning at 5:00. Above the threshold, heating turns off. Below it, heating turns on. Leave the weather-forecast field empty once an outdoor sensor is selected.

Pairing depends on the body. Both methods are on the device page. On the SEA801, with the screen on the front, hold AUTO/MANU and “+” until the display shows dashes. On the SEA802, with the dial on the side, turn the temperature down to OF and hold until the display becomes “–“. Permit join in Zigbee2MQTT while you do this.

What is not in the set

These devices already work at home. They explain the list above. There is no need to pull them off the wall to match the list.

• Sonoff SNZB-03. It is in several rooms and stays while it answers. It is not in a new network. Some of them hang, the battery percentage lies, and from time to time they have to be paired again. The same model fails in different rooms, so the sensor is the problem. Replacing the coordinator does not fix it. I would not buy the next Sonoff model, SNZB-03P, instead of the P1 either.
• A no-name Tuya battery presence sensor. I no longer remember the exact name, so there is no shop link. It drains the cell quickly and behaves unreliably. I do not use it. In Zigbee2MQTT it showed up as TS0202_3.
• Tuya TS0203. The sensors on the front door and on the rooms are online. I will not remove them for the brand. I will not buy another batch of TS0203: a new door gets an Aqara E1.
• Tuya ERS-10TZBVK-AA. The battery dies quickly, and a press often arrives after a long delay. I have not seen that delay on the Aqara WXKG11LM. The Aqara coin cell still has to be replaced.
• Zemismart on a battery. Fine in principle: for four years the curtains opened normally. While the pack still takes a charge, the motor can stay. For a new daily window I would buy mains-powered and look at Zemismart and Aqara.

Why Zigbee2MQTT

When I chose between Zigbee2MQTT and ZHA, ZHA was already running. I left it because it supported few Zigbee devices. For Zigbee in Home Assistant from scratch I install Zigbee2MQTT immediately.

The set already makes that choice: Zigbee2MQTT. ZHA is built into Home Assistant and runs in the same process. It finds the stick by itself, and Mosquitto is not required. While Home Assistant restarts, the radio is silent.

Zigbee2MQTT is a separate app and talks to Home Assistant through Mosquitto. Restarting Home Assistant does not stop the app, so the mesh stays up. Restarting the app itself, or the whole mini PC, stops the radio.

One stick serves one program. If Home Assistant has already offered ZHA and ZHA has taken the port, remove that integration, or Zigbee2MQTT cannot open the port. The ZHA documentation says a device from another Zigbee implementation must be factory reset before it joins ZHA. A Zigbee2MQTT backup does not drop into ZHA. I do not tear down a live network just to change the interface.

The device lists differ. A model card in Zigbee2MQTT does not promise the same card in ZHA. The P1 interval is also described in ZHA, in the device quirk. I still build the rest of this set in Zigbee2MQTT.

Over-the-air firmware differs too. Zigbee2MQTT takes images from the Koenkk index by default, when the server has internet. In ZHA, updates are on by default for Ledvance, Sonoff, Inovelli and ThirdReality. Other vendors are off: a firmware update can change how a device behaves.

ZHA remains an option if you do not want Mosquitto. Home Assistant then recommends its own coordinator, Connect ZBT-2. That is a different build, not the set in this article.

Coordinator

A Sonoff ZBDongle-P Zigbee coordinator is enough for a network from scratch. A different coordinator is needed in two cases.

• The stick is an old bare CC2531 board: blue, with no metal case and no external antenna. Zigbee2MQTT recommends leaving it. Moving from a CC2531 (Z-Stack 1.2) to a CC2652 means pairing the devices again. A backup does not bridge that gap.
• The antenna cannot be brought out of a metal cabinet. Then use an SMLIGHT SLZB-06 on the same CC2652P chip, over Ethernet, not Wi-Fi. It does not need USB passthrough. Home Assistant reaches it by IP.

In the Zigbee2MQTT serial block for an SLZB-06 the serial: key is usually already there. Add the two lines below it. Take the address from the coordinator’s web interface. The socket port on this model is usually 6638.

adapter: zstack
port: tcp://192.168.1.50:6638

My case is different. The Intel N5095 mini PC sits on a hallway wardrobe, and the stick is in a Ugreen hub, not in the blue USB 3.0 ports on the front panel. An SLZB-06 is not needed here. If the hub itself is USB 3.0 and the stick is plugged straight into it, a short USB 2.0 cable between them is better: USB 3.0 radiates on the same 2.4 GHz band as Zigbee. In the settings, take the path from /dev/serial/by-id/, not from /dev/ttyUSB0. The tty number changes after a reboot, and a hub makes that more obvious.

adapter: zstack
port: /dev/serial/by-id/usb-ITead_Sonoff_Zigbee_3.0_USB_Dongle_Plus_xxxxxxxx-if00

The Zigbee2MQTT wizard shows the exact string in the list of discovered devices. If the list is empty, run ha hardware info in the Home Assistant console. If the case says ZBDongle-E, the chip is different, a Silicon Labs EFR32. That stick uses the ember driver and firmware 7.4.4 or newer. The E stick is not in this set: moving between zstack and ember is not a supported migration in the migration guide. I do not touch a working network for a new chip. Changing the stick does not fix individual sensors that hang.

How to install Zigbee in Home Assistant on HAOS

To run Zigbee in Home Assistant on HAOS, the broker and Zigbee2MQTT are add-ons. The official add-on instructions cover 64-bit systems, aarch64 and amd64.

1. Settings → Apps → Add-on store. Install Mosquitto broker and start it.
2. In the same store open the menu → Repositories and add https://github.com/zigbee2mqtt/hassio-zigbee2mqtt.
3. Install the Zigbee2MQTT app, not Edge. Edge tracks the development branch.
4. Start the app and open its web interface. A 502 means the process is still starting: wait and refresh. If it stays that way for a couple of minutes, open the log tab.
5. In the wizard, pick the adapter it found. In the nearest Wi-Fi channel field, enter your access point’s channel: Zigbee2MQTT moves the Zigbee network away from it. Which channel number that produces, and what transmit power to leave on the stick, is in the channel and power section. An Ethernet SLZB may not appear in the list. Enter adapter and port by hand.
6. A message that the USB adapter was not found means one of two things: ZHA still holds the port, or the stick was not passed into the virtual machine. Passthrough by vendor and device ID is in the article on Home Assistant on Proxmox.
7. After startup, Home Assistant offers the MQTT integration. Add it: devices from Zigbee2MQTT appear without hand-written sensors in configuration.yaml. Turn permit join off after setup, and turn it on only while pairing.

Stick channel and transmit power

The default Zigbee channel in Zigbee2MQTT is 11. It shares the 2.4 GHz band with Wi-Fi channel 1, and a home router is often on channel 1. The documentation asks for a channel from 11, 15, 20 or 25. 15 and 20 sit nearer Wi-Fi channels 6 and 11. 25 is above those three. For a new network I start at 25, unless the router has already taken the top of the band.

The wizard field for the nearest Wi-Fi channel is the same idea: Zigbee2MQTT moves the network away from the access point. After startup, open the settings and check the channel number. If it is still 11 and the router is on Wi-Fi 1, change the channel before you pair sensors. On an empty network that is one edit. On a network that is already built, a channel change is supported for zstack and ember adapters, as described in the channel change documentation. On startup Zigbee2MQTT broadcasts the change, and the log says the configured channel does not match the stick. Battery sensors are asleep and miss the broadcast, so wake them with the button. Some devices do not support a channel change: if a sensor is still silent a few minutes after you wake it, pair it again. I do not touch a network that already reaches the rooms through two plugs just to change the number.

Stick transmit power is the transmit_power setting, in dBm. The adapter documentation starts at 5. A ZBDongle-P uses a CC2652P, and the ceiling listed there is 20 dBm: the setting will not go higher, and the firmware may cap it further. Restart Zigbee2MQTT after the change.

In configuration.yaml both values sit in the advanced block. 25 and 5 in the example are not a rule: 25 is a channel above typical Wi-Fi, and 5 is the documented starting power.

advanced:
  channel: 25
  transmit_power: 5

Raise the power when a stick in the hallway still cannot reach the first plug. After that, the plugs hold the network. If only the coordinator is louder, the command reaches the sensor and the weak battery reply does not come back. On 78 square metres I start with two plugs and 5 dBm. I turn on 20 dBm only if a far room is still silent after the plugs are in place.

How to pair a device

1. In the Zigbee2MQTT web interface, turn on permit join. Do not leave it on: a stranger’s device can join an open network.
2. Put the device into pairing mode. Hold a battery sensor near the coordinator, or near a device whose type is Router, while the interview runs, and only then take it to its place. WS-EUK01 and WS-EUK02 do not work for that: they do not extend the network. On the P1, the WXKG11LM button and the E1 sensor, hold the reset button for about 5 seconds until the indicator blinks. If the interview stalls, press the button briefly about once a second until Zigbee2MQTT finishes.
3. Wait until the list shows a model, not only an address.
4. Give it a clear name. Home Assistant names entities from it. The Zigbee2MQTT name and the Home Assistant area are separate: set the area in Home Assistant.
5. Turn permit join off.

Two different cases follow. The device has to join the network again, or it has just appeared and the card still needs a check.

Again. Deleting the row in Zigbee2MQTT is not enough: the sensor stays on the radio and gets in the way of a second join. Turn on permit join and reset the device with its own button. When the list shows the model again, turn permit join off.

The card. Check the one property that matters for the device you just paired.

• Switches. WS-EUK01 and WS-EUK02 should show type EndDevice. That is correct: they switch their own lights, and neighbouring sensors do not route through them.
• Plugs. The IKEA TRADFRI smart plug and the Tuya smart plug from HOMMYN. Both should show type Router. These plugs cover the apartment. On 78 square metres, three bedrooms and a combined kitchen and living room, two were enough for me. If a whole far room is silent, it needs one of these plugs nearby.
• P1 sensor. Set the interval to at least 30 seconds. Wake the sensor with its button before you save, or the value does not stick. An Aqara battery percentage can take a day to appear. Zigbee2MQTT also shows the voltage in millivolts. Do not trust the percentage in the first hour.
• Sonoff SNZB-03. Do not use its battery percentage in an automation, and do not buy a cell because of that number. If the row is in the list and motion has stopped, pair that sensor again with the button, as in the paragraph above. The new set uses an Aqara P1 motion sensor instead.

A batch of devices. Right after several pairings the network rebuilds routes for a few hours, and some sensors stay quiet. That is not a failure yet. Wait until the next day. Pair again only the sensor that never woke up, and only with its button while permit join is on.

Common questions

See also

• Home Assistant on Proxmox: HAOS install and USB adapter passthrough
• Aqara G4 in Home Assistant: a doorbell that is not on the Zigbee network
• Home Assistant backups to Google Drive
• CloudPub: Home Assistant access without a public IP