Pouzor
0acfe3acc3
A Zigbee2MQTT networkmap on a 200+ device mesh takes minutes to build.
Two separate failures fell out of that:
- POST /zigbee/import held the HTTP request open for the whole MQTT
round-trip, so any reverse proxy in front of the API cut it first
(Cloudflare returns a 524 at 120 s) and the browser never saw the map.
It now registers a job, fetches in the background and answers 202; the
client polls GET /zigbee/import/{job_id} until the payload is ready.
Job results are transient and live in memory with a 15 min TTL — the
same single-worker assumption the scheduler already makes. A failed
fetch replays the status the synchronous route used to raise, so a bad
broker is still a 502 and a slow mesh still a 504.
- The networkmap wait was hard-coded at 300 s with no way to raise it.
It now reads ZIGBEE_NETWORKMAP_TIMEOUT, and the shared MQTT round-trip
used by the Z-Wave import reads MQTT_RESPONSE_TIMEOUT. Both default to
300 s, fall back to that if misconfigured to a non-positive value, and
name themselves in the timeout message.
Also corrects the route and doc claims that the wait was 60 s.
The /import tests changed with the contract they cover, not to pass.
Fixes #380
ha-relevant: yes
4.6 KiB
Zigbee2MQTT Network Map Importer
This feature lets you connect Homelable to your MQTT broker, fetch the Zigbee2MQTT network topology, and drop all Zigbee devices onto the canvas as typed nodes with proper hierarchy.
Feature Overview
- Automatic device discovery — Requests the Z2M networkmap via the MQTT bridge API and parses the full device list
- Typed nodes — Devices are mapped to three homelable node types:
zigbee_coordinator— The Zigbee coordinator (hub)zigbee_router— Mains-powered router deviceszigbee_enddevice— Battery-powered end devices (sensors, bulbs, etc.)
- Hierarchy —
parent_idis set automatically: coordinator → routers → end devices - LQI display — Link Quality Indicator is stored as a node property
- IoT edges — Links between devices are added as
IoT / Zigbeeedge type
Prerequisites
- A running MQTT broker (e.g. Mosquitto) accessible from your Homelable host
- Zigbee2MQTT connected to the broker and running
- Z2M must respond to networkmap requests on:
- Request topic:
<base_topic>/bridge/request/networkmap - Response topic:
<base_topic>/bridge/response/networkmap - The default base topic is
zigbee2mqtt
- Request topic:
Step-by-step Usage
1. Open the Zigbee Import dialog
Click Zigbee Import in the left sidebar (below "Scan Network").
2. Configure the MQTT connection
| Field | Default | Description |
|---|---|---|
| Broker Host | — | IP or hostname of your MQTT broker |
| Port | 1883 | MQTT broker port |
| Base Topic | zigbee2mqtt |
Zigbee2MQTT base topic |
| Username | (optional) | MQTT username if authentication is enabled |
| Password | (optional) | MQTT password |
3. Test the connection (optional)
Click Test Connection to verify broker reachability before fetching devices.
A green indicator confirms success; red shows the error message from the broker.
4. Fetch devices
Click Fetch Devices. Homelable will:
- Connect to the broker
- Subscribe to the response topic
- Publish
{"type": "raw", "routes": false}to the request topic - Wait up to
ZIGBEE_NETWORKMAP_TIMEOUTseconds (default 300) for the network map response - Parse and group devices by type
The fetch runs server-side and the browser polls for the result, so a mesh that takes minutes to answer cannot be cut short by a reverse proxy's read timeout.
Large meshes and timeouts
A network of 200+ devices can take several minutes to build its map. Two knobs:
| Variable | Default | What it bounds |
|---|---|---|
ZIGBEE_NETWORKMAP_TIMEOUT |
300 |
Seconds to wait for the Z2M bridge to answer a networkmap request. Raise it if an import fails with Timed out waiting for networkmap response. |
MQTT_RESPONSE_TIMEOUT |
300 |
The same bound for the Z-Wave MQTT round-trip. |
Both apply to manual imports and to auto-sync. If you reverse-proxy the API, these are the only timeouts that matter — the import request itself returns immediately.
5. Select and add to canvas
Devices are grouped by type (Coordinator / Router / End Device).
Use the checkboxes to select which devices to add, then click Add N to Canvas.
Tip: All devices are selected by default. Uncheck any you don't want.
6. Arrange on the canvas
Devices are placed in a grid at the top-right of the canvas.
Use Auto Layout (toolbar) to re-arrange the full canvas, or drag nodes manually.
MQTT Configuration Tips
Mosquitto without authentication
listener 1883
allow_anonymous true
Mosquitto with password file
listener 1883
password_file /etc/mosquitto/passwd
Create a user:
mosquitto_passwd -c /etc/mosquitto/passwd <username>
Zigbee2MQTT configuration.yaml
mqtt:
base_topic: zigbee2mqtt
server: mqtt://localhost:1883
# user: mqtt_user
# password: mqtt_password
Supported Z2M Versions
The networkmap bridge API is available in Zigbee2MQTT 1.x and 2.x.
Tested against Z2M 1.35+ and 2.x.
The importer uses the raw topology format (routes: false) which is the most widely supported mode.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| "Connection refused" | Broker unreachable | Check host/port, firewall rules |
| "Timed out waiting for networkmap" | Z2M not running or wrong base_topic | Verify Z2M is connected, check base_topic setting |
| 0 devices returned | Z2M has no devices paired | Pair at least one device first |
| "Malformed networkmap response" | Z2M returned unexpected format | Check Z2M version; open an issue |
Screenshots
(Screenshots will be added in a future release)