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 `ZIGBEE_NETWORKMAP_TIMEOUT` seconds (default 300) for the network map response
5. 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:
```bash
mosquitto_passwd -c /etc/mosquitto/passwd <username>
```

### Zigbee2MQTT `configuration.yaml`

```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)_