homelable/docs/zigbee-import.md

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 devices
  • zigbee_enddevice — Battery-powered end devices (sensors, bulbs, etc.)
• Hierarchy — parent_id is 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 / Zigbee edge type

---

Prerequisites

1. A running MQTT broker (e.g. Mosquitto) accessible from your Homelable host
2. Zigbee2MQTT connected to the broker and running
3. 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

---

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:

1. Connect to the broker
2. Subscribe to the response topic
3. Publish {"type": "raw", "routes": false} to the request topic
4. Wait up to 60 seconds for the network map response (large meshes can take 30 s+)
5. Parse and group devices by type

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)