---
title: Smart Home Handbook
created: 2026-05-10
updated: 2026-05-10
type: concept
tags: [smart-home, iot, home-assistant, matter, concept, runbook]
confidence: high
---

# Smart Home Handbook

> Operational overview for the homelab smart home. Canonical orientation page linking to all smart home entities and concepts.

## Architecture Summary

The smart home is built around **Home Assistant** on [[panda]] as the central automation hub, with Matter multi-fabric providing cross-ecosystem access to devices.

```
┌─────────────────────────────────────────────────────┐
│                   USER INTERFACES                    │
│   HA UI │ Apple Home │ Google Home │ Alexa │ Voice   │
├─────────────────────────────────────────────────────┤
│              HOME ASSISTANT (panda)                   │
│   Automations │ Scripts │ Scenes │ Dashboards        │
├──────────┬──────────┬──────────┬──────────┬─────────┤
│  ZHA     │  Matter  │  Cloud   │  Local   │ ESPHome │
│ Zigbee   │  Thread  │  APIs    │  LAN     │ BLE/Voice│
├──────────┴──────────┴──────────┴──────────┴─────────┤
│                   DEVICES (~35)                      │
│  Aqara │ Govee │ Shelly │ TP-Link │ IKEA │ Echo     │
│  Apple TV │ LG TV │ Nest │ VeSync │ Aivo            │
└─────────────────────────────────────────────────────┘
```

## Key Entities

| Entity | Role | Page |
|--------|------|------|
| [[panda]] | HA host (RPi, HAOS) | [[panda]] |
| [[home-assistant-connect-zbt-2]] | Zigbee + Thread coordinator | [[home-assistant-connect-zbt-2]] |
| [[aqara-hub-m3]] | Aqara Matter bridge + Zigbee hub | [[aqara-hub-m3]] |

## Key Concepts

| Concept | Description | Page |
|---------|-------------|------|
| Matter Multi-Fabric | Cross-ecosystem device sharing | [[matter-multi-fabric]] |
| IoT Device Inventory | Complete device catalog | [[iot-device-inventory]] |

## Quick Reference

### Accessing Home Assistant
- **Web UI**: `https://ha.tophermayor.com`
- **SSH**: `ssh bear@192.168.30.196` (password auth)
- **API**: `http://192.168.30.196:8123/api/` (requires bearer token)
- **Traefik**: Routed from both [[ubuntu]] and [[grizzley]]

### Adding a New Matter Device
1. Open HA → Settings → Devices & Services → Matter → Add Device
2. Follow pairing flow using QR code or numeric code
3. Once in HA, use multi-admin pairing code to add to Apple/Google/Alexa
4. See [[matter-multi-fabric]] for full commissioning flow

### Adding a Non-Matter Device
1. Add to HA via native integration (Zigbee, Wi-Fi, cloud)
2. If needed in other ecosystems, enable HA Matter Bridge
3. Commission the bridge into target ecosystem
4. See [[matter-multi-fabric]] → Non-Matter Devices section

### Troubleshooting

| Problem | Solution |
|---------|----------|
| Device not responding | Check VLAN 30 connectivity, verify device power |
| Zigbee device offline | Check ZHA → Settings → Network → visualization for mesh health |
| Thread device not connecting | Verify Thread credentials match across all border routers |
| HA SSH access denied | Add SSH key to Advanced SSH add-on config via HA web UI |
| Matter multi-admin fails | Check device's fabric limit (some only support 2-3) |
| Govee lights won't pair | Ensure on same VLAN 30, use govee_light_local integration |

### Voice Pipeline

```
openWakeWord → Whisper (STT) → HA Assist (intent) → Piper (TTS)
```

- **Wake word**: "Hey Jarvis" (configurable via openWakeWord)
- **Hardware**: Home Assistant Voice PE (ESPHome)
- **Fallback**: Echo Dots → Alexa, Apple TV → Siri

### Network Placement

All IoT devices sit on **VLAN 30 (IoT subnet 192.168.30.0/24)**:
- [[panda]] has dual-homed: 192.168.30.196 (IoT) + 192.168.50.196 (Servers)
- Physical path: UGC Ultra Port 2 → TP-Link SG108PE trunk
- Firewall: IoT VLAN is isolated from Server and Family VLANs
- Management: Access HA via Traefik reverse proxy from any VLAN

## Improvement Opportunities

- [ ] Add grizzley SSH key to panda's SSH add-on for agent automation
- [ ] Verify unified Thread credentials across all border routers
- [ ] Set up HA Matter Bridge to expose non-Matter devices to Apple/Google/Alexa
- [ ] Commission Aqara Hub M3 into Apple Home and Google Home fabrics
- [ ] Consider ESP32 Bluetooth proxies for improved BLE coverage
- [ ] Evaluate moving panda's primary IP to VLAN 50 for easier management
- [ ] Add Nest Hub as Google Thread Border Router
- [ ] Document automations and scenes in a dedicated wiki page