CLAUDE: Document Home Assistant Matter/Thread setup and network config
- 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
parent
282a2f8a9c
commit
a900f9c744
@ -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?
|
## Current Deployment
|
||||||
- **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
|
|
||||||
|
|
||||||
### 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
|
```bash
|
||||||
# Core Home Assistant container
|
# Run from Proxmox shell
|
||||||
podman run -d --name homeassistant \
|
bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/vm/haos-vm.sh)"
|
||||||
--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
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### 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
|
```yaml
|
||||||
# docker-compose.yml for full stack
|
# Example: Weekly full backup
|
||||||
version: '3.8'
|
# Settings → System → Backups → Create Backup
|
||||||
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
|
|
||||||
```
|
```
|
||||||
|
|
||||||
|
### 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
|
## Migration Strategy
|
||||||
|
|
||||||
### Phase 1: Parallel Setup (Recommended)
|
### Phase 1: Foundation (Week 1)
|
||||||
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 2: Gradual Migration
|
1. ✅ Decommission old HA VM
|
||||||
1. **Re-pair devices in groups** (sensors first, then bulbs, etc.)
|
2. ✅ Deploy new HAOS VM with recommended specs
|
||||||
2. **Migrate automations one by one**
|
3. Connect Philips Hue Bridge (native integration)
|
||||||
3. **Keep Apple Home as backup** until confident
|
4. Test Hue control from HA
|
||||||
|
5. Install essential add-ons
|
||||||
|
|
||||||
### Phase 3: Full Cutover
|
### Phase 2: Parallel Operation (Weeks 2-3)
|
||||||
1. **Remove devices from Apple Home**
|
|
||||||
2. **Decommission Apple TV hub role** (keep as media device)
|
|
||||||
3. **Full automation implementation**
|
|
||||||
|
|
||||||
## 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)
|
### Phase 3: Full Migration (Weeks 4-5)
|
||||||
- **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
|
|
||||||
|
|
||||||
### Philips Hue Bridge
|
1. Re-pair remaining Matter devices to HA
|
||||||
- **Option 1:** Keep bridge, integrate via Hue integration (easier)
|
2. Migrate all automations from Apple Home
|
||||||
- **Option 2:** Direct Zigbee control (requires Zigbee coordinator)
|
3. Optional: Set up HomeKit Controller integration
|
||||||
- **Recommendation:** Keep bridge initially, migrate later if needed
|
- Exposes HA devices back to Apple Home
|
||||||
|
- Maintains Siri voice control for family
|
||||||
|
4. Decommission Apple Home as primary controller
|
||||||
|
|
||||||
### Future Expansion Options
|
### Phase 4: Enhancement (Ongoing)
|
||||||
- **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)
|
|
||||||
|
|
||||||
## 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
|
### Complex Scheduling
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
# Advanced morning routine with conditions
|
# Advanced morning routine with conditions
|
||||||
automation:
|
automation:
|
||||||
@ -129,57 +469,212 @@ automation:
|
|||||||
entity_id: binary_sensor.workday
|
entity_id: binary_sensor.workday
|
||||||
state: 'on'
|
state: 'on'
|
||||||
- condition: state
|
- condition: state
|
||||||
entity_id: person.your_name
|
entity_id: person.cal
|
||||||
state: 'home'
|
state: 'home'
|
||||||
action:
|
action:
|
||||||
- service: light.turn_on
|
- service: light.turn_on
|
||||||
target:
|
target:
|
||||||
entity_id: light.bedroom_lights
|
entity_id: light.bedroom
|
||||||
data:
|
data:
|
||||||
brightness_pct: 30
|
brightness_pct: 30
|
||||||
color_temp: 400
|
color_temp: 400
|
||||||
- delay: "00:15:00"
|
- delay: "00:15:00"
|
||||||
- service: light.turn_on
|
- service: light.turn_on
|
||||||
|
target:
|
||||||
|
entity_id: light.bedroom
|
||||||
data:
|
data:
|
||||||
brightness_pct: 80
|
brightness_pct: 80
|
||||||
```
|
```
|
||||||
|
|
||||||
### Presence Detection
|
### Presence-Based Automation
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
# Multi-factor presence with phone + door sensors
|
# Welcome home scene
|
||||||
automation:
|
automation:
|
||||||
- alias: "Arrival Detection"
|
- alias: "Arrival Detection"
|
||||||
trigger:
|
trigger:
|
||||||
- platform: state
|
- platform: state
|
||||||
entity_id: person.your_name
|
entity_id: person.cal
|
||||||
to: 'home'
|
to: 'home'
|
||||||
- platform: state
|
|
||||||
entity_id: binary_sensor.front_door
|
|
||||||
to: 'on'
|
|
||||||
condition:
|
condition:
|
||||||
- condition: state
|
- condition: sun
|
||||||
entity_id: person.your_name
|
after: sunset
|
||||||
state: 'home'
|
|
||||||
action:
|
action:
|
||||||
- service: scene.turn_on
|
- service: light.turn_on
|
||||||
target:
|
target:
|
||||||
entity_id: scene.arrival_lights
|
entity_id: light.living_room
|
||||||
- service: climate.set_temperature
|
|
||||||
target:
|
|
||||||
entity_id: climate.main_thermostat
|
|
||||||
data:
|
data:
|
||||||
temperature: 72
|
brightness_pct: 80
|
||||||
|
- service: notify.mobile_app
|
||||||
|
data:
|
||||||
|
message: "Welcome home!"
|
||||||
```
|
```
|
||||||
|
|
||||||
## Resource Requirements
|
---
|
||||||
|
|
||||||
### Minimum Specs
|
## Troubleshooting
|
||||||
- **CPU:** 2 cores
|
|
||||||
- **RAM:** 2GB
|
|
||||||
- **Storage:** 20GB
|
|
||||||
- **Network:** Gigabit recommended for media streaming integration
|
|
||||||
|
|
||||||
### Your Proxmox Environment
|
### VM Won't Start
|
||||||
- Should handle HA easily alongside existing containers
|
|
||||||
- Consider dedicating specific resources if running many integrations
|
```bash
|
||||||
- Network mode: host recommended for device discovery
|
# 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*
|
||||||
|
|||||||
@ -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
|
bios: ovmf
|
||||||
boot: order=scsi0;ide2;net0
|
boot: order=scsi0
|
||||||
cores: 4
|
cores: 4
|
||||||
efidisk0: local-lvm:vm-109-disk-1,efitype=4m,size=4M
|
efidisk0: local-lvm:vm-109-disk-0,efitype=4m,pre-enrolled-keys=0,size=4M
|
||||||
ide2: none,media=cdrom
|
machine: q35
|
||||||
memory: 8192
|
memory: 8192
|
||||||
meta: creation-qemu=6.1.0,ctime=1647545631
|
meta: creation-qemu=6.1.0,ctime=1767762202
|
||||||
name: hass-io
|
name: homeassistant
|
||||||
net0: virtio=D6:0D:3B:EC:7D:44,bridge=vmbr1,firewall=1
|
net0: virtio=0E:E0:41:39:CC:95,bridge=vmbr1
|
||||||
numa: 0
|
net1: virtio=6E:16:AB:69:63:89,bridge=vmbr0
|
||||||
onboot: 1
|
|
||||||
ostype: l26
|
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
|
scsihw: virtio-scsi-pci
|
||||||
smbios1: uuid=06361ef8-7954-4211-98cd-061ff047c401
|
serial0: socket
|
||||||
sockets: 1
|
smbios1: uuid=ace611b1-66f3-4d34-8727-9dd9ff29e84e
|
||||||
vmgenid: 62003864-950d-4e6f-a959-67caf08d3d4a
|
usb0: host=303a:831a
|
||||||
|
vmgenid: d2aa05f5-f01f-4944-9fc3-5c4662096d7e
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user