homelab-docs/infrastructure

Home Infrastructure

Comprehensive documentation and configuration management for home network infrastructure, Home Assistant, and smart home automation.

Repository Structure

infrastructure/
├── home-assistant/          # Home Assistant configuration files
│   ├── configuration.yaml
│   ├── automations.yaml
│   ├── scripts.yaml
│   ├── switches.yaml
│   └── secrets.yaml (gitignored)
│
├── esphome/                 # ESPHome device configurations
│   ├── garage-controller.yaml
│   └── README.md
│
├── voice-assistant/         # Local voice assistant system
│   ├── gaming-pc-setup/          # Docker services (GPU-accelerated AI)
│   ├── surface-go-setup/         # Wyoming satellite installation
│   ├── home-assistant-config/    # Voice pipeline HA config (merge with main)
│   ├── docs/                     # Voice system documentation
│   ├── README.md                 # Voice system overview
│   └── QUICK_START.md           # 30-minute voice setup guide
│
├── docs/                    # Infrastructure documentation
│   ├── FURNACE-PROJECT.md            # Furnace control integration project
│   ├── HOME-ASSISTANT-CONFIG-MERGE.md # Guide to merge voice HA config
│   ├── MQTT-SETUP.md                 # MQTT broker configuration
│   ├── DNS-OVER-TLS-SETUP.md         # DNS security setup
│   ├── MONITORING.md                 # System monitoring setup
│   ├── SERVICES.md                   # Services inventory
│   ├── DISASTER-RECOVERY.md          # Backup and recovery procedures
│   ├── RUNBOOK.md                    # Operational procedures
│   └── IMPROVEMENTS.md               # Future improvements tracking
│
├── scripts/                 # Automation and utility scripts
│
└── claude-shared/          # Shared resources with Claude Code assistant

Quick Start

Home Assistant

Configuration files are in /home-assistant/.

Key Files:

• configuration.yaml - Main HA configuration
• automations.yaml - All automations
• scripts.yaml - Reusable scripts
• secrets.yaml - Sensitive data (create from secrets.yaml.example)

Deployment: Copy files to your Home Assistant config directory (typically /config/ in HA OS).

ESPHome Devices

Device configurations are in /esphome/.

Current Devices:

• garage-controller - ESP32 with 8-relay board controlling garage doors, lights, and planned furnace integration

Deployment:

cd esphome
esphome run garage-controller.yaml

Or use Home Assistant ESPHome integration for OTA updates.

Voice Assistant

Local GPU-accelerated voice assistant system with Home Assistant integration.

System Components:

• Gaming PC (RTX 5060): Docker containers for Ollama LLM, Whisper STT, Piper TTS, OpenWakeWord
• Home Assistant: Voice pipeline coordinator
• Surface Go: Wyoming satellite (microphone/speaker interface)

Quick Start:

1. Set up Gaming PC AI services: /voice-assistant/gaming-pc-setup/
2. Set up Surface Go satellite: /voice-assistant/surface-go-setup/
3. Merge voice HA config: See /docs/HOME-ASSISTANT-CONFIG-MERGE.md
4. Full documentation: /voice-assistant/README.md

Current Status: Operational - needs HA config merge for full integration

Active Projects

🔥 Furnace Control Integration

• Status: Planning phase
• Goal: Replace failed furnace board with ESP32-based smart control
• Documentation: docs/FURNACE-PROJECT.md
• Hardware: ESP32-WROOM-32E with relay board, 6x temp/humidity sensors
• Features: Multi-zone monitoring (garage + shed), HA integration, safety interlocks

🎤 Local Voice Assistant

• Status: Operational, pending HA config merge
• Goal: GPU-accelerated local voice control with LLM
• Documentation: voice-assistant/README.md
• Hardware: Gaming PC (RTX 5060), Surface Go (Wyoming satellite)
• Features: Ollama LLM, Whisper STT, Piper TTS, OpenWakeWord, no cloud dependencies
• Integration: See docs/HOME-ASSISTANT-CONFIG-MERGE.md

🌐 Network Infrastructure

• MQTT: Mosquitto broker for device communication
• DNS: DNS-over-TLS with Unbound
• Documentation: See docs/MQTT-SETUP.md and docs/DNS-OVER-TLS-SETUP.md

Documentation

All infrastructure documentation is in the /docs/ directory:

• FURNACE-PROJECT.md - ESP32 furnace control integration
• HOME-ASSISTANT-CONFIG-MERGE.md - Merge voice assistant HA config
• MQTT-SETUP.md - MQTT broker setup and configuration
• DNS-OVER-TLS-SETUP.md - Secure DNS configuration
• MONITORING.md - System monitoring and alerting
• SERVICES.md - Inventory of all services
• DISASTER-RECOVERY.md - Backup and recovery procedures
• RUNBOOK.md - Operational procedures and troubleshooting

Voice assistant documentation is in /voice-assistant/docs/:

• Installation, commands, calendar setup, troubleshooting

Network Information

Current network setup and IP allocations are documented in:

• IP-ALLOCATION.md - IP address assignments
• DHCP exports in repository root

Contributing

This is a personal infrastructure repository. Updates are made through:

1. Local testing and validation
2. Git commits with descriptive messages
3. Push to GitHub for backup and history

Secrets Management

Sensitive information (passwords, API keys, etc.) is stored in secrets.yaml files which are gitignored.

Template files:

• /home-assistant/secrets.yaml.example
• Create your own secrets.yaml from the template

Backup Strategy

See DISASTER-RECOVERY.md for:

• Backup procedures
• Recovery steps
• Critical system information

Support & Notes

• Experience Level: 20+ years low voltage wiring, network infrastructure
• Tools: Home Assistant, ESPHome, MQTT, Unbound DNS
• Approach: Document everything, safety-first, incremental improvements

Recent Updates

• 2025-11-28:
  • Consolidated all smart home projects into monorepo
  • Added ESPHome directory and furnace control project documentation
  • Integrated voice assistant project (Gaming PC AI + Surface Go)
  • Created Home Assistant config merge guide
• 2025-11-27: Home Assistant configuration updates
• 2025-11-18: MQTT and DNS-over-TLS setup documentation

---

Maintained by: Fred N9MRQ Repository: https://github.com/FredN9MRQ/infrastructure