Zigbee

Zigbee devices live in the Zigbee2MQTT (z2m) network. Homer opens the network, shows what's in it, renames devices and binds buttons. By voice — through the speaker: New Zigbee device by voice.

Where it is

	Where
App	Settings → Devices → Zigbee devices → “Add device” or “+” in the plan header → Zigbee
Web	Menu → Home status and event feed → Zigbee

The owner and the support technician manage the network. If the Zigbee2MQTT bridge is not connected to HA over MQTT, the screen says so: “The Zigbee2MQTT bridge was not found in Home Assistant”.

Add a device

1. Open the add screen and tap “Open network” (on the web — “Open network for 2 min”). The “+” itself doesn't open the network: an accidental tap on a wall tablet shouldn't let just anyone into the home.
2. Put the device into pairing mode — usually hold the button for 5–10 seconds or insert the battery. A table by device type is in adding by voice.
3. The device appears in the “Network devices” list marked “new” once the bridge has interviewed it.
4. Tap the row and pick a room — see How a device gets onto the plan.

In the app the network closes by itself when you leave the screen. On the web — after two minutes or with “Close network”.

Network device list

The list shows exactly what the bridge considers its own. At the top is what joined while the screen was open, then what isn't on the plan yet, then what is already placed.

Each row shows the link — linkquality from the bridge:

Label	Meaning
“link 120” and a green dot	Good
Yellow dot	Fair
Red dot	Weak: commands will get lost. Move the device or put a router nearby now, while you're standing there, not a week later when the light starts “sometimes not turning on”
“link not measured”	The device hasn't said anything yet
“silent”	A reading exists but no reports — the worst pairing outcome

If a row can't be tapped, the reason is shown under it:

• “the bridge hasn't interviewed it yet” — wake the device: press and hold its button for a few seconds. Battery buttons fall asleep in the middle of an interview.
• “the bridge doesn't know this device” — Zigbee2MQTT has no converter. Update the bridge or describe the device with an external converter.
• “button or remote: not placed on the plan, presses get bound” — see Buttons.

Device actions

Button	What it does
Re-interview	The bridge gets to know the device again. Wake a battery device with its button
Reconfigure	Sets up the device's bindings and reporting again
Firmware / Check firmware	Whether a newer one exists. An update takes up to half an hour, and the device may not respond all that time. The result goes to the log and the event feed
Rename…	See below
Remove from network…	The bridge asks the device to leave. If it doesn't answer, “Force forget…” appears: the bridge forgets it, but the device itself stays in the old network and has to be reset by hand

All actions are written to the home log.

Rename

“Rename…” on the device row. The name is up to 80 characters, without #, +, /.

The device gets the new name in the bridge, and with it its entities in Home Assistant and the references in home plans. After renaming you get a report:

• which entities were renamed and which were skipped (with the reason);
• which plans were updated;
• “Check by hand: YAML still has the old id” — the file and line;
• which automations, scripts, scenes, zones and groups mention the device.

WARNING

References in Home Assistant YAML packages are not fixed automatically. If the report shows a file, fix it, or the package will silently stop working.

Buttons and their presses

A button or remote is not placed on the plan — its row has “presses” instead of “to plan” (on the web — “Presses…”, owner only).

1. Open the button's presses. Homer asks the home what the button does now.
2. For each press — single, double, long and so on, whatever the button can do — pick a light or relay from the plan. “does nothing” unbinds it.
3. “Save”.

The binding is written to Home Assistant as the automation homer_btn_<button name>. It works on its own: with the tablet off and the app and browser closed. If the home already has a rule for this button that wasn't written in Homer, saving replaces it — you'll be warned.

Clearing all presses means deleting the automation; you'll be asked first.

Such a button works through Home Assistant: press → bridge → HA → light. If HA or the bridge is down, it won't work. To keep the light working even then, you need direct binding.

Direct remote binding

Direct binding (bind) means the remote sends the command to a light or group itself, over Zigbee, bypassing the coordinator and HA. The light switches even when the home doesn't respond.

Where: on the web — Home status → Zigbee → Direct binding, in the app — at the bottom of the Add device screen (through the Homer server, for the owner and the support technician).

1. Pick the remote, and if it has several endpoints — the endpoint.
2. Pick what it controls: a light or a group (for example, the native living room group).
3. Tick the commands: on/off, brightness, color.
4. Press any button on the remote — it runs on a battery and sleeps — and right away “Bind”.

If the bridge says some commands didn't take, wake the remote and try again. Existing bindings are listed above the form, each with “Unbind”.

You can only bind a remote that can send commands to lights: its bridge description has output clusters genOnOff or genLevelCtrl. IKEA RODRET, STYRBAR and similar work. Simple buttons like IH-K663 (TS0041) can't do this and won't appear in the remote list.

Light memory

Light memory rolls back changes that came around HA. The Homer server records lights under direct binding in input_text.homer_bound_lamps, and the rollback leaves them alone. The brightness re-arm for the wall switch still works for them.

Link map on the plan

You can see link quality right on the plan — to work out where to put a repeater.

1. Settings → Debug → Demo and debugging → “Debug mode”. A halo appears around each device: green — good link, red — commands get lost or crawl. The worse the link, the bigger the spot.
2. “Refresh the link map” — the bridge walks the network again. Whoever didn't answer is listed by name in the “didn't answer: …” line.

The score is the worse of two measures: the bridge's linkquality (how loudly the coordinator hears the device) and response delay (the whole path from press to report).

TIP

Right after Zigbee2MQTT restarts nobody has readings, and for a minute the whole home is “silent”. That's not a fault.

Another hint is the “Sensor and Zigbee coverage” button in the plan header: motion sensor cones and weak Zigbee devices with a hint where a router would help.

Availability: a dead device shows as dead

availability is enabled in Zigbee2MQTT. Without it the bridge remembers the last state of a device that left the network: a light that's gone still counts as on.

That's what happened on 10.10.2026: the “Bathroom” light left the network, and z2m still remembered it as “on”. HA thought the whole home was lit, and the “All lights” toggle got stuck. Now such a light is “unavailable”, and the home card names 1–2 lights that are on, so a case like this is visible right away.

If Zigbee2MQTT is down entirely, the “zigbee2mqtt is down” alarm goes off.

Native z2m groups

The “whole home” light is seven separate radio commands: lights go out in a wave, and a dead light slows down the rest. A Zigbee group command is one transmission, and the lights react at once. That's why the light ladder sends the full command to a z2m group.

Group	id	Lights
homer_house_zigbee	902	Five living room lights, hallway, bathroom
homer_living_zigbee	903	Five living room lights

Group membership is described in tools/ha-package/zigbee-groups.json. The groups themselves are kept in z2m by tools/z2m-groups.py:

python tools/z2m-groups.py          # compare and show what's missing
python tools/z2m-groups.py apply    # create groups and add members

The script only adds: it doesn't touch extra members or other groups, it only reports them. Adding a member doesn't change the light.

WARNING

Don't use id 901: z2m has default_bind_group under it, and a group with this id gets published under its name.

To change a group's members, edit zigbee-groups.json and run apply. The script reaches mosquitto on the home server over SSH; the address is set with the HOMER_SSH variable, e.g. HOMER_SSH="ssh root@192.168.1.10".