Sanitized mirror from private repository - 2026-04-20 01:32:01 UTC

docs/services/home-assistant/gl-s200-integration.md

@@ -0,0 +1,82 @@
+# GL-S200 Thread Border Router Integration Plan
+
+Planning notes for adding a GL.iNet GL-S200 as a Thread Border Router for Home Assistant on concord NUC.
+
+## Device Overview
+
+**GL-S200** ([product page](https://www.gl-inet.com/products/gl-s200/))
+
+| Spec | Value |
+|------|-------|
+| CPU | QCA9531 @ 650 MHz |
+| RAM / Flash | 128 MB DDR2 / 128 MB NAND |
+| OS | GL.iNet firmware (OpenWrt 21.02, kernel 5.4) |
+| Radios | Thread + BLE 5.0 + Wi-Fi 2.4 GHz b/g/n (150 Mbps) |
+| Ports | 1x WAN, 1x LAN (10/100 Mbps) |
+| Power | USB-C 5V / 2A |
+| Role | Thread Border Router (OTBR) — not a Matter controller; Matter runs on top via python-matter-server already deployed on the NUC |
+
+## Where to Plug It In
+
+**Must land on the same L2 segment as Home Assistant.**
+
+HA runs as a Docker container on `vish-concord-nuc` with `network_mode: host`. The NUC sits on `192.168.68.0/22` (gateway `192.168.68.1`) — **deliberately separated** from the main homelab LAN (`192.168.0.0/24`).
+
+Thread/Matter border router discovery uses mDNS (`_meshcop._udp`), which is link-local. Cross-subnet discovery would require an mDNS reflector (not currently deployed). So:
+
+- ✅ Plug S200 WAN into a switch/AP on `192.168.68.0/22` (same segment as the NUC).
+- ❌ Do not plug into the main 192.168.0.0/24 LAN — HA will not see it.
+
+## Existing Stack on Concord NUC
+
+Compose: `concord_nuc/homeassistant.yaml`
+
+| Service | Purpose | Status |
+|---------|---------|--------|
+| `homeassistant` | HA Core (host networking) | Running |
+| `matter-server` | python-matter-server (host networking) | Running |
+| `piper` | Wyoming TTS (port 10200) | Running |
+| `whisper` | Wyoming STT (port 10300) | Running |
+| `openwakeword` | Wyoming wake word (port 10400) | Running |
+
+The Matter server is already in place — the S200 plugs in as the *radio* layer for Thread. No compose changes needed to add the S200 itself.
+
+## Integration Steps (When Device Arrives)
+
+1. **Physical setup**
+   - Connect S200 WAN to the 192.168.68.0/22 network.
+   - Power via USB-C (5V/2A).
+   - First-boot admin UI reachable at `192.168.8.1` until reconfigured, then at the DHCP-assigned 192.168.68.x address.
+   - Update firmware, set an admin password.
+
+2. **Verify mDNS discovery from the NUC**
+   ```bash
+   # Run on concord NUC (Tailscale: 100.72.55.21)
+   avahi-browse -rt _meshcop._udp
+   ```
+   Should list the S200 as a Thread Border Router with a TXT record containing `rv=1`, `tv=1.3.0`, etc.
+
+3. **Add to Home Assistant**
+   - Settings → Devices & Services → Add Integration → **Thread**
+   - S200 should auto-discover. Add it as an External Thread Border Router.
+   - Settings → Devices & Services → Add Integration → **Matter (BETA)** (already configured to talk to the local matter-server container).
+
+4. **Pair Matter devices**
+   - Use the Home Assistant Companion app (iOS/Android) to pair.
+   - The app hands off Thread commissioning credentials to each device so it joins the S200's mesh.
+
+## Gotchas
+
+- **Firmware lag**: GL.iNet's OTBR implementation trails upstream OpenThread. Check the admin UI for firmware updates before committing to the device.
+- **No Zigbee**: S200 is Thread-only. Existing Zigbee devices (if any) still need a separate coordinator (e.g., a Zigbee stick on the NUC via Zigbee2MQTT or ZHA).
+- **Thread credential backup**: Once the S200 forms an operational dataset (network name, PAN ID, network key), export and back it up — losing it means re-commissioning every Thread device.
+- **HA network_mode: host is load-bearing**: If HA is ever migrated to bridge networking, Matter/Thread discovery breaks. Keep host networking.
+
+## Status
+
+- [ ] S200 acquired
+- [ ] Plugged into 192.168.68.0/22 segment
+- [ ] mDNS discovery verified from NUC
+- [ ] Added to HA Thread integration
+- [ ] First Matter device paired
+- [ ] Thread operational dataset backed up