CasaSmart guide
Local pairing through Zigbee2MQTT or ZHA.
CasaSmart
Zigbee is a low-power, mesh radio protocol built for the sensors, bulbs, plugs and relay modules that need reliable communication without draining batteries. Instead of depending on a manufacturer's cloud, Zigbee devices can be controlled locally by Home Assistant, the open-source automation server that runs in your own home on a mini-PC, a NAS or a Raspberry Pi. The benefit is real: commands stay fast, they keep working even without internet, and your data never leaves the house. To speak Zigbee, Home Assistant needs a coordinator — a small USB radio, for example from the SMLight or Sonoff family — that creates and manages its own mesh network.
There are two software paths for using that coordinator. ZHA (Zigbee Home Automation) is an integration built directly into Home Assistant: you start it in a few minutes and it needs no extra components. Zigbee2MQTT is a separate add-on that translates Zigbee messages into MQTT, supports a very wide range of devices and offers a dedicated web interface, but it also requires an MQTT broker such as Mosquitto. Neither is "better" in absolute terms; the choice depends on your devices and how much fine control you want. The key rule is to use only one path on a given dongle, never both in parallel, to avoid conflicts.
In this guide we walk through adding a Zigbee device to Home Assistant step by step, valid for both ZHA and Zigbee2MQTT. We prepare the coordinator, note the channel and PAN ID for safety, put the device into pairing mode with a factory reset, open the "permit join" window, confirm and re-interview the entities, then rename the device and assign it an area. Finally we deal with routers, signal strength and OTA firmware updates. The procedure is the same whether you are installing your first sensor or expanding a whole house. If you would rather have everything configured and verified professionally, the CasaSmart team in Moldova installs and maintains such systems turnkey.
TL;DR
Connect a Zigbee coordinator (SMLight or Sonoff) to Home Assistant, choose ZHA or Zigbee2MQTT, note the channel and PAN ID, factory-reset the device, open "permit join", confirm the entities, rename and assign an area, then build the mesh with routers and apply OTA firmware.
Step 1
The Zigbee coordinator is the radio that creates the network: a USB dongle such as those in the SMLight or Sonoff family, connected to your Home Assistant server. If you run a virtual machine or a container, make sure the USB device is passed through to Home Assistant, otherwise it will not be detected. Place the coordinator on a USB extension cable, away from the metal case, hard drives and any USB 3.0 port, which generates radio noise on the 2.4 GHz band. Check in Settings → System → Hardware, or in the add-on log, that the serial port appears (for example /dev/ttyUSB0 or /dev/serial/by-id). Decide now whether you will use the ZHA integration or the Zigbee2MQTT add-on; never run both on the same dongle in parallel.
Step 2
Before adding any devices, open the network configuration and write down the parameters: the radio channel, the network identifier (PAN ID), the extended PAN ID and the network key. In ZHA you find these under Settings → Devices & Services → ZHA → configure; in Zigbee2MQTT, in the configuration.yaml file and the startup log. Why it matters: if you ever reinstall Home Assistant or move the dongle, re-entering the same values keeps your network alive without re-pairing dozens of devices. The channel also matters for Wi-Fi coexistence: Zigbee and Wi-Fi share the 2.4 GHz band, so pick a Zigbee channel that does not overlap your Wi-Fi network. Store these values somewhere safe, off the server itself.
Step 3
Every Zigbee device enters pairing mode through a factory reset. The procedure varies: on many bulbs and plugs you hold the button for five to ten seconds until it blinks, on Aqara sensors you press the small reset button, and on some MOES or Sonoff modules you use a sequence of presses. Always check your specific model's manual. An LED blinking slowly or quickly confirms the device is searching for a network. Keep the device close to the coordinator during the first pairing, even if it will sit far away later. If the device was previously paired with another network or its own hub, it must be reset beforehand, otherwise it will not appear. Only prepare the device after you open the pairing window described in the next steps.
Step 4
In ZHA, go to Settings → Devices & Services → ZHA and press Add Device, or, from the coordinator page, "Add devices via this device". This opens the permit join window, usually for sixty seconds, during which you trigger the device reset. ZHA shows the device "interview" in real time: manufacturer, model and the discovered clusters. If you want a weak device to join through a specific repeater, start pairing directly from that router's page rather than the coordinator. Leave the page open until the card with the created entities appears. If the window expires with no result, repeat the device reset and reopen Add Device; there is no need to restart the whole integration. A device that appears only partially needs a re-interview, covered below.
Step 5
In Zigbee2MQTT, open the web interface (Zigbee2MQTT UI) and press "Permit join", optionally choosing a specific router for the new device to join through. Then trigger the device reset; the UI log will show "Interviewing" and then "Successfully interviewed". Unlike ZHA, Zigbee2MQTT exposes a database file (database.db) and an MQTT layer, so make sure the Mosquitto broker is running and the MQTT integration in Home Assistant is connected, otherwise the entities will not appear. If the model is recognised, you immediately see the sensors and switches exposed through MQTT discovery. Disable "Permit join" once you are done so the network does not stay open. For unknown devices, Zigbee2MQTT may need an external converter, which you add to the configuration.
Step 6
Sometimes the device pairs but the entities are missing or incomplete, because the first interview was cut short by a weak signal. The fix is the re-interview (reconfigure). In ZHA, open the device page, the three-dot menu and choose "Reconfigure device"; in Zigbee2MQTT, press "Reconfigure" on the device card. First wake battery-powered devices with a button press, since they sleep to save energy and do not answer the query while asleep. After the re-interview, check that all expected entities appear: state, battery, temperature, button actions. If a device stays "unavailable", move it closer to the coordinator or a router and try again. Do not delete and re-pair right away; re-interviewing solves most cases without losing history.
Step 7
Right after pairing, the device has a technical name, for example "lumi.sensor_motion" or a model code. Rename it clearly — "Hallway motion sensor" — and rename the entities too, so automations are easy to read. In Home Assistant, open the device page, click the settings icon and fill in the name; then assign an area, for example Kitchen or Bedroom. Areas allow group commands and per-room statistics. Set a consistent naming convention from the start: type, location, function. If you use Zigbee2MQTT you can set the "friendly name" in its interface, but remember that changing it also changes the MQTT topic, so adjust any automations that use it. A well-named system spares you confusion once you reach dozens of devices.
Step 8
Mains-powered devices (bulbs, plugs, modules such as Shelly in its Zigbee variants) act as routers and extend the mesh; battery sensors are only end devices and do not relay. Build the router "backbone" first, then add the sensors, so each one finds a nearby repeater. In both ZHA and Zigbee2MQTT you can view the network map and the LQI indicator to spot weak nodes. If a device drops often, move a router closer or add an intermediate one. Also check OTA firmware updates: both platforms offer them for compatible devices, useful for stability and new features. Do not update everything at once and never cut power during the process. Document the final map so you can diagnose quickly in the future.
The most common mistakes: running ZHA and Zigbee2MQTT on the same dongle at once, pairing a device without a prior factory reset, placing the coordinator right against the NAS server or a USB 3.0 port that drowns the signal, and adding battery sensors before building the router network. Many people forget to note the channel and PAN ID, losing the whole network on a reinstall.
ZHA is built into Home Assistant, easy to start and enough for most homes in Moldova. Zigbee2MQTT supports more devices, offers fine control and a dedicated interface, but adds an MQTT broker. Beginners can start with ZHA; if an exotic device is not recognised, Zigbee2MQTT is the alternative. The CasaSmart team configures either option on request.
Most often the device was not factory-reset or is still paired with another hub. Reset it, move it close to the coordinator and reopen the pairing window. Also check that "permit join" is on. Battery devices must be woken with a button press. If it still does not appear, the signal may be too weak — add an intermediate router.
Some multiprotocol dongles can run Zigbee and Thread at once, but the setup is more fragile and we do not recommend it for a primary network. For reliability, use a dedicated Zigbee coordinator and a separate Thread border router for Matter. In Moldova, where local support matters, a simple, separated architecture is easier to maintain.
A Zigbee network can in theory support hundreds of devices, but the practical limit depends on the coordinator, the number of routers and the mesh quality. For an ordinary home in Moldova, dozens of devices work fine if you have enough mains-powered routers. It is not the count but the radio coverage and stable firmware that determine reliability.
If you noted the channel, PAN ID, extended PAN ID and network key, you re-enter them when configuring ZHA or Zigbee2MQTT and the network returns without re-pairing devices. In Zigbee2MQTT, also keep the database.db file. That is why we recommend regular backups of the Home Assistant configuration; CasaSmart can set up automatic backups at installation.
● CasaSmart · Chișinău
CasaSmart can configure the Home Assistant automation and test it on real devices.