# Z-Wave & Zigbee Infrastructure

## Architecture

```
Z-Wave: HA (10.100.0.40) --ws:3100--> Docker host (10.100.0.35) zwavejs     --tcp:2001--> Z-Net G8 (10.200.0.106) Z-Wave radio
Zigbee: HA Mosquitto (10.100.0.40:1883) <--mqtt-- Docker host zigbee2mqtt   --tcp:2002--> Z-Net G8 SmartStick ZB (USB)
```

Both radios live on the Z-Net G8; both controller apps run as containers on the Docker host, deployed by the Ansible playbook (`~/playbook`, roles `zwavejs` and `zigbee2mqtt`).

The Raspberry Pi (10.200.0.190) that previously hosted Z-Wave JS UI is gone.

## Z-Net G8 (Z-Wave Controller)

- **Hostname**: Z-Net-G8
- **IP**: 10.200.0.106 (IOT_200, VLAN 200)
- **MAC**: 02:53:ec:d0:de:dd
- **Manufacturer**: HomeSeer Technologies
- **Role**: Z-Wave radio controller (Node 1), serial-over-TCP on port 2001
- **Zigbee**: HomeSeer SmartStick ZB plugged into the Z-Net's USB, exposed on port **2002** (2003 is for older Sonoff ZBDongle-E revisions). Requires Z-Net firmware ≥ 1.0.27 (running 1.0.27).
- **Web UI**: http://10.200.0.106/

## Z-Wave JS UI (container on the Docker host)

- **Host**: [Docker Server](docker.md) — `ssh dohertj2@10.100.0.35`
- **Container**: `zwavejs` (`zwavejs/zwave-js-ui:latest`), restart `unless-stopped`, created 2026-07-03
- **Compose file**: `/opt/zwavejs/docker-compose.yml` (templated by playbook role `zwavejs`)
- **Store/data**: `/opt/zwavejs/store` → `/usr/src/app/store` (`settings.json`, `nodes.json`, `backups/`)
- **Network**: `traefik`
- **Web UI**: https://zwave.dohertylan.com (Traefik → port 8091, Authelia SSO; Z-Wave JS UI's own auth is disabled)
- **Z-Wave JS websocket**: ws://10.100.0.35:3100 (host 3100 → container 3000)

### Z-Wave JS Config

- **Serial port**: `tcp://10.200.0.106:2001` (Z-Net G8 over network)
- **Z-Wave region**: 1 (US)
- **Server port**: 3000 in container (published as 3100)

## Home Assistant Integration

- **Integration**: zwave_js
- **Connects to**: ws://10.100.0.35:3100
- **Size**: 25 devices, 296 entities (2026-10-09)
- **Node 1**: HomeSeer Z-Wave Shield with External Antenna (Z-Net G8)
- Two stale `not_loaded` config entries remain (an old "Z-Wave JS" entry and a Silicon Labs CP2102N USB serial entry)

## Zigbee2MQTT (container on the Docker host)

- **Container**: `zigbee2mqtt` (`koenkk/zigbee2mqtt:latest`, 2.14.2 at deploy), restart `unless-stopped`, deployed 2026-10-09
- **Playbook role**: `zigbee2mqtt` — `sudo ansible-playbook site.yml -i localhost, -c local --tags zigbee2mqtt --limit localhost` from `~/playbook` (Semaphore currently has no project configured)
- **Compose file**: `/opt/zigbee2mqtt/docker-compose.yml`
- **Data**: `/opt/zigbee2mqtt/data` → `/app/data` (`configuration.yaml` holds the generated network key — back it up; `coordinator_backup.json`)
- **Config ownership**: `configuration.yaml` is seeded once by Ansible (never overwritten); MQTT, serial and frontend settings are enforced by `ZIGBEE2MQTT_CONFIG_*` env vars in the compose file
- **Web UI**: https://zigbee.dohertylan.com (Traefik → port 8080, Authelia SSO)
- **Coordinator**: `tcp://10.200.0.106:2002`, adapter `ember`, EmberZNet 7.4.3, IEEE 0x8c8b48fffe2dd481
- **Network**: channel 25, PAN ID 64462 (0xFBCE) — new network formed 2026-10-09; all devices must be (re)paired
- **MQTT**: HA's Mosquitto broker add-on at mqtt://10.100.0.40:1883, base topic `zigbee2mqtt`, HA discovery enabled
  - **User**: `zigbee2mqtt` / **Password**: `Aywm6DjOR3bfSo9c7zDoWDxX` (login in the Mosquitto add-on options; also in the playbook role defaults)

### Pairing devices

Turn on **Permit join** in the Zigbee2MQTT web UI (or the `switch.zigbee2mqtt_bridge_permit_join` entity in HA), then reset/pair the device. It appears in HA automatically via MQTT discovery.

## Notes

- Z-Net G8 is on the IoT VLAN; the Docker host reaches it cross-VLAN (or via its IOT_200 interface 10.200.0.35)
- Tracked by Unifi as device_tracker.z_net_g8