Initial commit: homelab infrastructure wiki

- Full Obsidian vault content - Host configs (ice, grizzley, ubuntu, proxmox, truenas, panda, hyte) - Media stack documentation - Traefik HA setup - Automation scripts - Bachelor party planning
2026-05-24 16:08:40 -07:00
parent d132442429
commit e4d91aadf9
285 changed files with 30018 additions and 0 deletions
--- a/homelab/concepts/smart-home-handbook.md
+++ b/homelab/concepts/smart-home-handbook.md
@@ -0,0 +1,108 @@
+---
+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