cal/claude-home
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

CLAUDE: Document Home Assistant Matter/Thread setup and network config

Browse Source 
- Update deployment guide with operational status (VM 109)
- Add ZBT-2 USB passthrough documentation (303a:831a)
- Document critical dual-NIC network config for Matter
  - net0 must be on home network (vmbr1) for Matter Server
  - net1 on server network (vmbr0) for management
- Add Thread network configuration details
- Add Matter commissioning steps and troubleshooting
- Update VM config with current settings and comments
- Add lessons learned from Matter commissioning debugging

Key insight: Matter requires HA to be on same subnet as IoT devices
for mDNS discovery. This was root cause of commissioning failures.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Cal Corum 2026-01-09 10:58:19 -06:00
parent 282a2f8a9c
commit a900f9c744
2 changed files with 641 additions and 136 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

743
.claude/plans/home-assistant-deployment-guide.md
View File

@ -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 <VMID>
# Remove the VM and its disks
qm destroy <VMID> --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://<VM-IP>: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_<SERIAL>-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 <VMID> --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
### 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=<MAC>,bridge=vmbr1"
ssh proxmox "qm set 109 -net1 virtio=<MAC>,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*

34
server-configs/proxmox/qemu/109.conf
View File

@ -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