Cal Corum a900f9c744 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>

2026-01-09 10:58:19 -06:00

22 KiB

Raw Blame History

Home Assistant Deployment Guide

Last Updated: January 9, 2026 Deployment Method: Home Assistant OS (HAOS) VM on Proxmox Status: ✅ Deployed and Operational

Current Deployment

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

Identify the old VM in Proxmox web UI

# List all VMs to find the old HA instance
qm list | grep -i home

Check if it has any valuable config (likely not if never fully implemented)

# If VM is running, you could backup config first
# But if it was never completed, skip this

Stop and remove the old VM

# Stop the VM (replace VMID with actual ID)
qm stop <VMID>

# Remove the VM and its disks
qm destroy <VMID> --purge

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:

# Run from Proxmox shell
bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/vm/haos-vm.sh)"

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

Wait for HAOS to boot (2-3 minutes first boot)
Access web UI at http://<VM-IP>:8123
Create admin account
Complete onboarding wizard

Initial Configuration

Step 1: Onboarding

Set location (for sun-based automations, weather)
Create admin user account
Skip or configure any auto-discovered devices
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

Go to Settings → Devices & Services
Hue Bridge should auto-discover
Click Configure → Press button on Hue Bridge
All Hue devices appear immediately
Full local control established

Step 4: Matter/Thread Setup

For Eve and other Matter devices:

Go to Settings → Devices & Services → Add Integration
Search for Matter
Follow pairing instructions for each device
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

# USB device info
Bus 002 Device 003: ID 303a:831a Nabu Casa ZBT-2

# VM config line
usb0: host=303a:831a

Setup Steps

Plug ZBT-2 into Proxmox host (USB 2.0 port preferred to avoid USB 3.0 interference)

Identify device:

ssh proxmox "lsusb | grep -i nabu"
# Expected: 303a:831a Nabu Casa ZBT-2

Stop VM and add USB passthrough:

qm stop 109
qm set 109 -usb0 host=303a:831a
qm start 109

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:

Settings → System → Hardware → Find ZBT-2
Click three dots → Configure → Flash Thread firmware
Wait for flash to complete
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

# 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:

Unifi Controller → Settings → Services
Gateway mDNS Proxy: Custom
VLAN Scope: Select all VLANs that need mDNS (Home Network, Servers)
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

HA on same subnet as IoT devices (10.0.0.x)
Matter Server addon running
OpenThread Border Router addon running
Thread network configured (Apple or HA)
HA Companion app on phone with Bluetooth permission

Commissioning Steps

Factory reset the device (hold button 10+ seconds)
Open HA Companion app on phone
Go to Settings → Devices & Services → Add Integration → Matter
Scan the Matter QR code on the device
Phone uses Bluetooth for initial PASE session
Device receives Thread credentials and joins network
Device appears in HA

Adding HA as Secondary Controller

If device is already in Apple Home:

In Apple Home app, find device → Settings
Look for "Turn On Pairing Mode"
In HA Companion app → Add Matter Device
Enter the temporary pairing code
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

# Example: Weekly full backup
# Settings → System → Backups → Create Backup

Proxmox-Level Backup

Additionally, back up the entire VM via Proxmox:

# Manual backup
vzdump <VMID> --storage local --mode snapshot

# Or configure in Proxmox Backup Server

Migration Strategy

Phase 1: Foundation (Week 1)

✅ Decommission old HA VM
✅ Deploy new HAOS VM with recommended specs
Connect Philips Hue Bridge (native integration)
Test Hue control from HA
Install essential add-ons

Phase 2: Parallel Operation (Weeks 2-3)

Re-pair 2-3 Matter devices (Eve switches) to HA
Keep Apple Home running for remaining devices
Build basic automations in HA
Test reliability and family usability
Install HA mobile app for all household members

Phase 3: Full Migration (Weeks 4-5)

Re-pair remaining Matter devices to HA
Migrate all automations from Apple Home
Optional: Set up HomeKit Controller integration
- Exposes HA devices back to Apple Home
- Maintains Siri voice control for family
Decommission Apple Home as primary controller

Phase 4: Enhancement (Ongoing)

Add HACS for community integrations
Build advanced automations
Consider voice integration (Whisper/Piper add-ons)
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

# Advanced morning routine with conditions
automation:
  - alias: "Smart Morning Routine"
    trigger:
      - platform: time
        at: "06:30:00"
    condition:
      - condition: state
        entity_id: binary_sensor.workday
        state: 'on'
      - condition: state
        entity_id: person.cal
        state: 'home'
    action:
      - service: light.turn_on
        target:
          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-Based Automation

# Welcome home scene
automation:
  - alias: "Arrival Detection"
    trigger:
      - platform: state
        entity_id: person.cal
        to: 'home'
    condition:
      - condition: sun
        after: sunset
    action:
      - service: light.turn_on
        target:
          entity_id: light.living_room
        data:
          brightness_pct: 80
      - service: notify.mobile_app
        data:
          message: "Welcome home!"

Troubleshooting

VM Won't Start

# 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

Check VM console in Proxmox for IP address
Verify network bridge configuration
Ensure firewall allows port 8123
Wait 5 minutes on first boot for full initialization
Try both IPs: http://10.0.0.28:8123 and http://10.10.0.215:8123

Hue Bridge Not Discovered

Verify same subnet as HA VM
Check mDNS/Avahi is working
Manually add: Settings → Integrations → Add → Philips Hue
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:

curl -s http://10.0.0.28:8081/node/state
# Should return: "leader" or "router"

Check Thread diagnostics:

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:

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:

The primary interface (net0) must be on the IoT network

Swap interfaces in Proxmox if needed:

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"

Reconfigure IPs in HAOS after reboot

Resources

Checklist

Pre-Deployment

Identify and document old HA VM ID
Plan IP address for new VM
Verify Proxmox storage has 64GB+ free

Deployment

Decommission old HA VM
Run community helper script
Configure with recommended specs (4 cores, 8GB, 64GB)
Complete onboarding wizard

Post-Deployment

Install File Editor and Terminal add-ons
Connect Philips Hue Bridge
Test light control from HA
Install HA mobile app
Set up first automation

USB Passthrough (ZBT-2)

Plug ZBT-2 into Proxmox host
Add USB passthrough to VM (303a:831a)
Verify device visible in HA
Flash Thread firmware
Configure OpenThread Border Router addon

Network Configuration

Add second NIC to VM (net1 on vmbr0)
Swap interfaces (net0 on home network vmbr1)
Configure IPs in HAOS
Set DHCP reservation for 10.0.0.28
Enable mDNS reflection in Unifi

Matter/Thread Setup

Install Matter Server addon
Install OpenThread Border Router addon
Set Apple network as preferred Thread network
Commission first Matter device (Eve outlet)
Commission remaining Matter devices

Lessons Learned

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

22 KiB Raw Blame History