diff --git a/.claude/plans/home-assistant-deployment-guide.md b/.claude/plans/home-assistant-deployment-guide.md index 9e710cb..94ca4ec 100644 --- a/.claude/plans/home-assistant-deployment-guide.md +++ b/.claude/plans/home-assistant-deployment-guide.md @@ -1,122 +1,462 @@ -# Home Assistant Deployment Architecture +# Home Assistant Deployment Guide -## Recommended Deployment: Podman Container on Proxmox +**Last Updated:** January 9, 2026 +**Deployment Method:** Home Assistant OS (HAOS) VM on Proxmox +**Status:** ✅ Deployed and Operational -### Why Podman Container vs Home Assistant OS? -- **Flexibility:** Full control over host system, easier customization -- **Integration:** Better integration with existing Proxmox infrastructure -- **Backup:** Standard container backup/restore workflows -- **Resources:** More efficient resource usage -- **Updates:** Granular update control -- **GPU Support:** Already proven working with your Tdarr setup +## Current Deployment -### Container Architecture +| Setting | Value | +|---------|-------| +| **VM ID** | 109 | +| **VM Name** | homeassistant | +| **Primary IP** | 10.0.0.28 (home network - for Matter/IoT) | +| **Secondary IP** | 10.10.0.215 (server network - management) | +| **Web UI** | http://10.0.0.28:8123 | +| **USB Device** | Nabu Casa ZBT-2 (Thread/Zigbee coordinator) | + +## Deployment Overview + +### Why HAOS VM (Not Container)? + +| Factor | HAOS VM | Container (HA Core) | +|--------|---------|---------------------| +| **Add-on Marketplace** | ✅ Full access | ❌ Not available | +| **Supervisor** | ✅ Included | ❌ Not included | +| **USB Passthrough** | ✅ Reliable | ⚠️ Problematic | +| **Official Support** | ✅ Yes | ⚠️ Limited | +| **Backup/Restore** | ✅ Built-in | Manual | +| **Updates** | ✅ One-click | Manual | + +The Add-on marketplace provides one-click installation of: +- **Mosquitto** (MQTT broker) +- **Node-RED** (visual automation) +- **Zigbee2MQTT** / **ZHA** (Zigbee coordination) +- **ESPHome** (DIY sensors) +- **Piper** / **Whisper** (local voice) +- **File Editor**, **Terminal**, **Samba**, and 1000+ more + +--- + +## Pre-Deployment: Decommission Old HA VM + +An old, unmaintained Home Assistant VM exists and should be removed before deploying the new instance. + +### Decommissioning Steps + +1. **Identify the old VM** in Proxmox web UI + ```bash + # List all VMs to find the old HA instance + qm list | grep -i home + ``` + +2. **Check if it has any valuable config** (likely not if never fully implemented) + ```bash + # If VM is running, you could backup config first + # But if it was never completed, skip this + ``` + +3. **Stop and remove the old VM** + ```bash + # Stop the VM (replace VMID with actual ID) + qm stop + + # Remove the VM and its disks + qm destroy --purge + ``` + +4. **Free up resources** - Note the resources being reclaimed for the new VM + +--- + +## VM Specifications + +### Recommended Configuration + +| Resource | Value | Rationale | +|----------|-------|-----------| +| **CPU** | 4 cores | Headroom for add-ons and integrations | +| **RAM** | 8 GB | Comfortable for MQTT, Node-RED, history | +| **Disk** | 64 GB | Add-ons, recorder database, backups | +| **Network** | Bridge (vmbr0) | Same network as IoT devices | +| **Machine Type** | q35 | Modern, better device support | +| **BIOS** | OVMF (UEFI) | Required for HAOS | + +### Network Considerations + +- Place on same VLAN/subnet as IoT devices for discovery +- Static IP recommended (or DHCP reservation) +- Suggested IP: Document in your network scheme +- Ports: 8123 (web UI), 1883 (MQTT if using add-on) + +--- + +## Installation + +### Method: Community Helper Script (Recommended) + +The community-maintained scripts (originally by tteck) automate the entire process: ```bash -# Core Home Assistant container -podman run -d --name homeassistant \ - --restart=unless-stopped \ - -p 8123:8123 \ - -v /path/to/config:/config \ - -v /etc/localtime:/etc/localtime:ro \ - --device /dev/ttyUSB0:/dev/ttyUSB0 \ # If you add Zigbee/Z-Wave - --network=host \ - ghcr.io/home-assistant/home-assistant:stable +# Run from Proxmox shell +bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/vm/haos-vm.sh)" ``` -### Supporting Services Architecture +### Script Prompts + +When prompted, select **Advanced** to customize specs: + +| Prompt | Recommended Value | +|--------|-------------------| +| Use default settings? | No (select Advanced) | +| HAOS Version | Latest (default) | +| VM ID | Next available or choose | +| Machine Type | q35 | +| Disk Size | 64G | +| CPU Cores | 4 | +| RAM | 8192 | +| Bridge | vmbr0 (or your IoT bridge) | +| MAC Address | Auto or specify | +| VLAN | Your IoT VLAN if applicable | +| Start after creation | Yes | + +### Post-Installation + +1. **Wait for HAOS to boot** (2-3 minutes first boot) +2. **Access web UI** at `http://:8123` +3. **Create admin account** +4. **Complete onboarding wizard** + +--- + +## Initial Configuration + +### Step 1: Onboarding + +1. Set location (for sun-based automations, weather) +2. Create admin user account +3. Skip or configure any auto-discovered devices +4. Install HA mobile app for presence detection + +### Step 2: Essential Add-ons + +Navigate to **Settings → Add-ons → Add-on Store** + +| Add-on | Purpose | Priority | +|--------|---------|----------| +| **File Editor** | Edit YAML configs in browser | Install first | +| **Terminal & SSH** | Shell access | Install first | +| **Samba Share** | Access config from desktop | Recommended | +| **Mosquitto** | MQTT broker for devices | When needed | +| **HACS** | Community integrations | Recommended | + +### Step 3: Philips Hue Integration + +1. Go to **Settings → Devices & Services** +2. Hue Bridge should auto-discover +3. Click **Configure** → Press button on Hue Bridge +4. All Hue devices appear immediately +5. Full local control established + +### Step 4: Matter/Thread Setup + +For Eve and other Matter devices: + +1. Go to **Settings → Devices & Services → Add Integration** +2. Search for **Matter** +3. Follow pairing instructions for each device +4. Use existing Thread network (Apple TV/HomePod as border routers) + +--- + +## USB Passthrough: Nabu Casa ZBT-2 + +The ZBT-2 is a Thread/Zigbee coordinator that provides: +- **Thread Border Router** functionality (for Matter over Thread devices) +- **Zigbee coordinator** capability (for ZHA integration) + +### Current Configuration + +```bash +# USB device info +Bus 002 Device 003: ID 303a:831a Nabu Casa ZBT-2 + +# VM config line +usb0: host=303a:831a +``` + +### Setup Steps + +1. **Plug ZBT-2 into Proxmox host** (USB 2.0 port preferred to avoid USB 3.0 interference) + +2. **Identify device:** + ```bash + ssh proxmox "lsusb | grep -i nabu" + # Expected: 303a:831a Nabu Casa ZBT-2 + ``` + +3. **Stop VM and add USB passthrough:** + ```bash + qm stop 109 + qm set 109 -usb0 host=303a:831a + qm start 109 + ``` + +4. **Verify in HA:** Settings → System → Hardware + - Should show `/dev/ttyACM0` or similar + - Full path: `/dev/serial/by-id/usb-Nabu_Casa_ZBT-2_-if00` + +### Flash Thread Firmware + +If the ZBT-2 needs Thread firmware: +1. Settings → System → Hardware → Find ZBT-2 +2. Click three dots → Configure → Flash Thread firmware +3. Wait for flash to complete +4. Restart OpenThread Border Router addon + +--- + +## CRITICAL: Network Configuration for Matter + +**Matter devices REQUIRE Home Assistant to be on the same subnet as the IoT devices.** This is the most common cause of Matter commissioning failures. + +### The Problem + +If HA is on a server VLAN (10.10.0.x) but IoT devices are on the home network (10.0.0.x): +- mDNS discovery fails across subnets +- Matter commissioning times out with "Discovery timed out" errors +- PASE session establishment fails + +### The Solution: Dual-NIC Configuration + +VM 109 has two network interfaces: + +| Interface | Bridge | Network | Purpose | +|-----------|--------|---------|---------| +| net0 (enp6s18) | vmbr1 | 10.0.0.x (Home) | **Primary** - Matter/IoT communication | +| net1 (enp6s19) | vmbr0 | 10.10.0.x (Server) | Secondary - Management access | + +### Proxmox VM Network Config + +```bash +# Current configuration (qm config 109 | grep net) +net0: virtio=0E:E0:41:39:CC:95,bridge=vmbr1 +net1: virtio=6E:16:AB:69:63:89,bridge=vmbr0 +``` + +### Why This Matters + +- **net0 on vmbr1 (home network)**: Matter Server auto-selects the first interface. By putting the home network on net0, Matter commissioning works. +- **net1 on vmbr0 (server network)**: Provides management access from the server VLAN. + +### HAOS Network Settings + +| Interface | IP | Gateway | Purpose | +|-----------|-----|---------|---------| +| enp6s18 | 10.0.0.28 (DHCP) | 10.0.0.1 | Matter/mDNS/IoT | +| enp6s19 | 10.10.0.215 (DHCP) | 10.10.0.1 | Server management | + +**Important:** Set a DHCP reservation for 10.0.0.28 in your router to prevent IP changes. + +### Unifi mDNS Configuration + +If you have VLANs, enable mDNS reflection: +1. Unifi Controller → Settings → Services +2. **Gateway mDNS Proxy**: Custom +3. **VLAN Scope**: Select all VLANs that need mDNS (Home Network, Servers) +4. **Service Scope**: All + +--- + +## Thread Network Configuration + +### Network Topology + +``` +┌─────────────────────────────────────────────────────────────┐ +│ Home Assistant VM │ +│ (10.0.0.28 on home network) │ +├─────────────────────────────────────────────────────────────┤ +│ ┌─────────────────┐ ┌─────────────────────────────────┐ │ +│ │ Matter Server │ │ OpenThread Border Router │ │ +│ │ (addon) │ │ (ZBT-2 @ /dev/ttyACM0) │ │ +│ └────────┬────────┘ └────────────┬────────────────────┘ │ +└───────────┼──────────────────────────┼──────────────────────┘ + │ │ + │ IPv6/mDNS │ 802.15.4 Radio + │ │ + ▼ ▼ + ┌───────────────┐ ┌───────────────┐ + │ Apple Thread │◄────────►│ Thread │ + │ Border Routers│ Thread │ Devices │ + │ (8x HomePods) │ Mesh │ (Eve, etc.) │ + └───────────────┘ └───────────────┘ +``` + +### Thread Networks + +Two Thread networks exist in this environment: + +| Network | PAN ID | Channel | Border Routers | +|---------|--------|---------|----------------| +| MyHome (Apple) | 0xF672 | 25 | 8 (HomePods/Apple TVs) | +| ha-thread-b072 | 0xB072 | 25 | 1 (ZBT-2) | + +**Current setup:** Apple network is set as "Preferred" in HA → Settings → Thread. This means: +- HA uses Apple's Thread credentials for commissioning +- Devices join Apple's strong mesh (8 border routers) +- HA can still control devices via Matter + +### OTBR Addon Configuration + +Settings → Add-ons → OpenThread Border Router: +- **Device**: `/dev/serial/by-id/usb-Nabu_Casa_ZBT-2_DCB4D90E794C-if00` +- **Baudrate**: 460800 +- **Hardware flow control**: Enabled +- **NAT64**: Enabled +- **OTBR firewall**: Enabled + +### OTBR REST API + +Accessible at `http://10.0.0.28:8081/`: +- `/node/state` - Current state (leader, router, etc.) +- `/node/dataset/active` - Active Thread dataset +- `/diagnostics` - Network diagnostics + +--- + +## Matter Commissioning + +### Prerequisites + +1. HA on same subnet as IoT devices (10.0.0.x) +2. Matter Server addon running +3. OpenThread Border Router addon running +4. Thread network configured (Apple or HA) +5. HA Companion app on phone with Bluetooth permission + +### Commissioning Steps + +1. **Factory reset the device** (hold button 10+ seconds) +2. Open **HA Companion app** on phone +3. Go to **Settings → Devices & Services → Add Integration → Matter** +4. Scan the Matter QR code on the device +5. Phone uses Bluetooth for initial PASE session +6. Device receives Thread credentials and joins network +7. Device appears in HA + +### Adding HA as Secondary Controller + +If device is already in Apple Home: +1. In Apple Home app, find device → Settings +2. Look for **"Turn On Pairing Mode"** +3. In HA Companion app → Add Matter Device +4. Enter the temporary pairing code +5. Device now controlled by both Apple Home and HA + +--- + +## Backup Strategy + +### Built-in Backups + +HAOS includes automated backup to: +- Local storage +- Network shares (Samba/NFS) +- Google Drive (via add-on) + +### Recommended Schedule ```yaml -# docker-compose.yml for full stack -version: '3.8' -services: - homeassistant: - container_name: homeassistant - image: ghcr.io/home-assistant/home-assistant:stable - volumes: - - ./config:/config - - /etc/localtime:/etc/localtime:ro - restart: unless-stopped - privileged: true - network_mode: host - - # Optional: Local database instead of SQLite - postgres: - container_name: ha-postgres - image: postgres:15 - environment: - POSTGRES_DB: homeassistant - POSTGRES_USER: homeassistant - POSTGRES_PASSWORD: your-secure-password - volumes: - - ./postgres-data:/var/lib/postgresql/data - restart: unless-stopped - ports: - - "5432:5432" - - # Optional: MQTT broker for device communication - mosquitto: - container_name: ha-mosquitto - image: eclipse-mosquitto:latest - restart: unless-stopped - ports: - - "1883:1883" - - "9001:9001" - volumes: - - ./mosquitto/config:/mosquitto/config - - ./mosquitto/data:/mosquitto/data - - ./mosquitto/log:/mosquitto/log - - # Optional: Node-RED for visual automation development - node-red: - container_name: ha-node-red - image: nodered/node-red:latest - restart: unless-stopped - ports: - - "1880:1880" - volumes: - - ./node-red-data:/data +# Example: Weekly full backup +# Settings → System → Backups → Create Backup ``` +### Proxmox-Level Backup + +Additionally, back up the entire VM via Proxmox: +```bash +# Manual backup +vzdump --storage local --mode snapshot + +# Or configure in Proxmox Backup Server +``` + +--- + ## Migration Strategy -### Phase 1: Parallel Setup (Recommended) -1. **Deploy HA alongside Apple Home** (don't disturb current setup) -2. **Start with 1-2 test devices** (re-pair a couple of sensors) -3. **Build basic automations** to validate functionality -4. **Test for 1-2 weeks** to ensure stability +### Phase 1: Foundation (Week 1) -### Phase 2: Gradual Migration -1. **Re-pair devices in groups** (sensors first, then bulbs, etc.) -2. **Migrate automations one by one** -3. **Keep Apple Home as backup** until confident +1. ✅ Decommission old HA VM +2. ✅ Deploy new HAOS VM with recommended specs +3. Connect Philips Hue Bridge (native integration) +4. Test Hue control from HA +5. Install essential add-ons -### Phase 3: Full Cutover -1. **Remove devices from Apple Home** -2. **Decommission Apple TV hub role** (keep as media device) -3. **Full automation implementation** +### Phase 2: Parallel Operation (Weeks 2-3) -## Device Integration Strategy +1. Re-pair 2-3 Matter devices (Eve switches) to HA +2. Keep Apple Home running for remaining devices +3. Build basic automations in HA +4. Test reliability and family usability +5. Install HA mobile app for all household members -### Matter Devices (Your Current Setup) -- **Direct Integration:** HA's Matter support is mature as of 2024 -- **No Hub Required:** HA can be the Matter controller -- **Thread Network:** Can share Thread network between platforms during migration +### Phase 3: Full Migration (Weeks 4-5) -### Philips Hue Bridge -- **Option 1:** Keep bridge, integrate via Hue integration (easier) -- **Option 2:** Direct Zigbee control (requires Zigbee coordinator) -- **Recommendation:** Keep bridge initially, migrate later if needed +1. Re-pair remaining Matter devices to HA +2. Migrate all automations from Apple Home +3. Optional: Set up HomeKit Controller integration + - Exposes HA devices back to Apple Home + - Maintains Siri voice control for family +4. Decommission Apple Home as primary controller -### Future Expansion Options -- **Zigbee:** Add Zigbee coordinator for non-Matter devices -- **Z-Wave:** Add Z-Wave stick for legacy devices -- **WiFi Devices:** Direct integration via HA's vast library -- **Custom Integrations:** HACS (Home Assistant Community Store) +### Phase 4: Enhancement (Ongoing) -## Automation Examples You Can Build +1. Add HACS for community integrations +2. Build advanced automations +3. Consider voice integration (Whisper/Piper add-ons) +4. Evaluate Zigbee coordinator if expanding beyond Matter + +--- + +## Device Integration Architecture + +``` +┌─────────────────────────────────────────────────────────────┐ +│ Home Assistant VM │ +│ (HAOS on Proxmox) │ +├─────────────────────────────────────────────────────────────┤ +│ │ +│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │ +│ │ Hue Native │ │ Matter │ │ Future: Zigbee │ │ +│ │ Integration │ │ Integration │ │ (ZBT-2 + Z2M) │ │ +│ └──────┬──────┘ └──────┬──────┘ └──────────┬──────────┘ │ +│ │ │ │ │ +└─────────┼────────────────┼─────────────────────┼─────────────┘ + │ │ │ + ▼ ▼ ▼ + ┌──────────────┐ ┌───────────┐ ┌───────────┐ + │ Hue Bridge │ │ Thread │ │ USB │ + │ (Zigbee) │ │ Border │ │ Coord. │ + └──────┬───────┘ │ Router │ └─────┬─────┘ + │ │(Apple TV) │ │ + ▼ └─────┬─────┘ ▼ + ┌──────────────┐ │ ┌───────────┐ + │ Hue Bulbs │ ▼ │ Zigbee │ + │ Hue Sensors │ ┌───────────┐ │ Devices │ + └──────────────┘ │Eve, etc. │ └───────────┘ + │(Matter/ │ + │ Thread) │ + └───────────┘ +``` + +--- + +## Automation Examples ### Complex Scheduling + ```yaml # Advanced morning routine with conditions automation: @@ -129,57 +469,212 @@ automation: entity_id: binary_sensor.workday state: 'on' - condition: state - entity_id: person.your_name + entity_id: person.cal state: 'home' action: - service: light.turn_on target: - entity_id: light.bedroom_lights + entity_id: light.bedroom data: brightness_pct: 30 color_temp: 400 - delay: "00:15:00" - service: light.turn_on + target: + entity_id: light.bedroom data: brightness_pct: 80 ``` -### Presence Detection +### Presence-Based Automation + ```yaml -# Multi-factor presence with phone + door sensors +# Welcome home scene automation: - alias: "Arrival Detection" trigger: - platform: state - entity_id: person.your_name + entity_id: person.cal to: 'home' - - platform: state - entity_id: binary_sensor.front_door - to: 'on' condition: - - condition: state - entity_id: person.your_name - state: 'home' + - condition: sun + after: sunset action: - - service: scene.turn_on + - service: light.turn_on target: - entity_id: scene.arrival_lights - - service: climate.set_temperature - target: - entity_id: climate.main_thermostat + entity_id: light.living_room data: - temperature: 72 + brightness_pct: 80 + - service: notify.mobile_app + data: + message: "Welcome home!" ``` -## Resource Requirements +--- -### Minimum Specs -- **CPU:** 2 cores -- **RAM:** 2GB -- **Storage:** 20GB -- **Network:** Gigabit recommended for media streaming integration +## Troubleshooting -### Your Proxmox Environment -- Should handle HA easily alongside existing containers -- Consider dedicating specific resources if running many integrations -- Network mode: host recommended for device discovery \ No newline at end of file +### VM Won't Start + +```bash +# Check VM status +qm status 109 + +# Check for errors +journalctl -u pve-guests | grep 109 + +# Verify UEFI boot +qm config 109 | grep bios +``` + +### Can't Access Web UI + +1. Check VM console in Proxmox for IP address +2. Verify network bridge configuration +3. Ensure firewall allows port 8123 +4. Wait 5 minutes on first boot for full initialization +5. Try both IPs: http://10.0.0.28:8123 and http://10.10.0.215:8123 + +### Hue Bridge Not Discovered + +1. Verify same subnet as HA VM +2. Check mDNS/Avahi is working +3. Manually add: Settings → Integrations → Add → Philips Hue +4. Enter bridge IP manually if needed + +### Matter Commissioning Fails + +**Symptom:** "Pairing Failed" or endless spinning in Companion app + +**Check Matter Server logs** (Settings → Add-ons → Matter Server → Logs): + +| Error | Cause | Solution | +|-------|-------|----------| +| `Discovery timed out` | HA can't find device on network | Verify same subnet | +| `PASESession timed out` | Can't establish secure session | Check Bluetooth permissions on phone | +| `Thread credentials don't match` | Wrong Thread network | Set correct preferred network in HA | +| `Msg Retransmission failure` | Network communication issue | Check mDNS reflection, firewall | + +**Most common fix:** Ensure HA is on the same subnet as IoT devices (see Network Configuration section). + +### Thread/OTBR Issues + +**Check OTBR status:** +```bash +curl -s http://10.0.0.28:8081/node/state +# Should return: "leader" or "router" +``` + +**Check Thread diagnostics:** +```bash +curl -s http://10.0.0.28:8081/diagnostics | jq '.[] | {ActiveRouters, ChildTable, IfInUcastPkts}' +``` + +**Common issues:** + +| Symptom | Cause | Solution | +|---------|-------|----------| +| `NoAck` errors in OTBR logs | Radio can't communicate | Check USB passthrough, restart OTBR | +| `IfInUcastPkts: 0` | Not receiving any traffic | Verify channel matches other devices | +| Empty `ChildTable` | No devices joined | Device joining different network | +| Commissioner disabled | Matter not enabling it | Restart Matter Server | + +### ZBT-2 Radio Issues + +**Verify USB passthrough:** +```bash +ssh proxmox "lsusb | grep 303a" +# Should show: 303a:831a Nabu Casa ZBT-2 +``` + +**Check if device visible in HA:** +- Settings → System → Hardware → Search "usb" +- Should show `/dev/ttyACM0` + +**Flash firmware if needed:** +- Settings → System → Hardware → ZBT-2 → Configure → Flash + +### Network Interface Issues + +**Matter Server using wrong interface:** + +Check logs for: `Using 'enp6s18' as primary network interface` + +If using wrong interface: +1. The primary interface (net0) must be on the IoT network +2. Swap interfaces in Proxmox if needed: + ```bash + ssh proxmox "qm set 109 -net0 virtio=,bridge=vmbr1" + ssh proxmox "qm set 109 -net1 virtio=,bridge=vmbr0" + ssh proxmox "qm reboot 109" + ``` +3. Reconfigure IPs in HAOS after reboot + +--- + +## Resources + +- [Home Assistant Documentation](https://www.home-assistant.io/docs/) +- [Community Scripts - HAOS VM](https://community-scripts.github.io/ProxmoxVE/scripts?id=haos-vm) +- [Home Assistant Community Forums](https://community.home-assistant.io/) +- [HACS - Community Store](https://hacs.xyz/) + +--- + +## Checklist + +### Pre-Deployment +- [x] Identify and document old HA VM ID +- [x] Plan IP address for new VM +- [x] Verify Proxmox storage has 64GB+ free + +### Deployment +- [x] Decommission old HA VM +- [x] Run community helper script +- [x] Configure with recommended specs (4 cores, 8GB, 64GB) +- [x] Complete onboarding wizard + +### Post-Deployment +- [x] Install File Editor and Terminal add-ons +- [ ] Connect Philips Hue Bridge +- [ ] Test light control from HA +- [x] Install HA mobile app +- [ ] Set up first automation + +### USB Passthrough (ZBT-2) +- [x] Plug ZBT-2 into Proxmox host +- [x] Add USB passthrough to VM (303a:831a) +- [x] Verify device visible in HA +- [x] Flash Thread firmware +- [x] Configure OpenThread Border Router addon + +### Network Configuration +- [x] Add second NIC to VM (net1 on vmbr0) +- [x] Swap interfaces (net0 on home network vmbr1) +- [x] Configure IPs in HAOS +- [ ] Set DHCP reservation for 10.0.0.28 +- [x] Enable mDNS reflection in Unifi + +### Matter/Thread Setup +- [x] Install Matter Server addon +- [x] Install OpenThread Border Router addon +- [x] Set Apple network as preferred Thread network +- [x] Commission first Matter device (Eve outlet) +- [ ] Commission remaining Matter devices + +--- + +## Lessons Learned + +1. **Matter requires same-subnet connectivity** - The biggest blocker was HA being on a different subnet than IoT devices. mDNS doesn't cross subnets without explicit reflection. + +2. **Matter Server selects the first network interface** - No configuration option exists to change this. The solution is to ensure net0 is on the correct network at the Proxmox level. + +3. **Thread channel matters** - If HA's Thread network is on a different channel than existing devices, they can't communicate. Match channels or use the existing network's credentials. + +4. **Apple Thread network is robust** - With 8 HomePods/Apple TVs as border routers, the Apple Thread mesh is strong. Using it as the preferred network is practical. + +5. **ZBT-2 USB passthrough works reliably** - Using vendor:product ID (303a:831a) passthrough is reliable and survives USB port changes. + +--- +*Last updated: January 9, 2026* diff --git a/server-configs/proxmox/qemu/109.conf b/server-configs/proxmox/qemu/109.conf index 7437694..03637f7 100644 --- a/server-configs/proxmox/qemu/109.conf +++ b/server-configs/proxmox/qemu/109.conf @@ -1,17 +1,27 @@ +# Home Assistant OS VM +# Deployed: January 2026 +# Primary IP: 10.0.0.28 (home network - Matter/IoT) +# Secondary IP: 10.10.0.215 (server network - management) +# Web UI: http://10.0.0.28:8123 +# +# CRITICAL: net0 MUST be on vmbr1 (home network) for Matter to work +# Matter Server auto-selects the first interface for mDNS/commissioning + +agent: 1 bios: ovmf -boot: order=scsi0;ide2;net0 +boot: order=scsi0 cores: 4 -efidisk0: local-lvm:vm-109-disk-1,efitype=4m,size=4M -ide2: none,media=cdrom +efidisk0: local-lvm:vm-109-disk-0,efitype=4m,pre-enrolled-keys=0,size=4M +machine: q35 memory: 8192 -meta: creation-qemu=6.1.0,ctime=1647545631 -name: hass-io -net0: virtio=D6:0D:3B:EC:7D:44,bridge=vmbr1,firewall=1 -numa: 0 -onboot: 1 +meta: creation-qemu=6.1.0,ctime=1767762202 +name: homeassistant +net0: virtio=0E:E0:41:39:CC:95,bridge=vmbr1 +net1: virtio=6E:16:AB:69:63:89,bridge=vmbr0 ostype: l26 -scsi0: local-lvm:vm-109-disk-0,size=32G,ssd=1 +scsi0: local-lvm:vm-109-disk-1,discard=on,size=64G,ssd=1 scsihw: virtio-scsi-pci -smbios1: uuid=06361ef8-7954-4211-98cd-061ff047c401 -sockets: 1 -vmgenid: 62003864-950d-4e6f-a959-67caf08d3d4a +serial0: socket +smbios1: uuid=ace611b1-66f3-4d34-8727-9dd9ff29e84e +usb0: host=303a:831a +vmgenid: d2aa05f5-f01f-4944-9fc3-5c4662096d7e