====== 🏠 Home Assistant (High-Level Overview) ======

Home Assistant is the central automation and orchestration system inside **TorresVault**, integrating lighting, sensors, network health, FPP lighting control, BLE tracking, and room-level dashboards into one unified platform.

This page provides the architectural overview of how Home Assistant fits into the broader TorresVault ecosystem.

----

===== Role in TorresVault =====

Home Assistant acts as the **automation brain** of the environment:

  * Collects data from sensors (motion, BLE, environmental)
  * Controls lights, switches, media players, and devices
  * Powers dashboards: mobile, wall tablets, control panels
  * Integrates with UniFi, Proxmox, Pi-hole, TrueNAS
  * Automates cross-system routines (lighting, FPP, IoT, network, security)

It ties together hardware from multiple platforms into a single cohesive automation layer.

----

===== System Architecture =====

Home Assistant runs inside a **dedicated Proxmox VM** and integrates with the following systems:

==== Core Systems ====
  * **Proxmox** — VM host for HA
  * **UniFi Network** — device presence, AP states, WAN health
  * **Pi-hole DNS** — local DNS overrides, ad-block data feeds
  * **TrueNAS** — backup storage, snapshots, recordings

==== Show Control ====
  * **FPP (Falcon Player)**  
    * Mega Tree — 192.168.60.55  
    * Matrix — 192.168.60.56  
  * Start/Stop show  
  * Playlist control  
  * WLED notifications (Car, Office, Living Room)

==== Voice + Local AI ====
  * Home Assistant Voice (Piper TTS + Whisper STT)
  * Local voice control (Office prototype)
  * Future: Jarvis-style full-house voice assistant

==== BLE Item & Room Tracking ====
  * Pi Zero 2W running **Room Assistant** (planned)
  * ESPHome BLE devices (Atom Lite / Echo)
  * BLE Tags: keys, wallet, badge, laptop bag
  * Car BLE tracker triggers TTS events

----

===== Dashboard Structure =====

Home Assistant uses a **multi-dashboard, multi-view layout**, optimized for mobile devices and wall-mounted tablets.

==== ✔ Downstairs Dashboard ====
  * Swipeable room views  
  * Rooms: Kitchen, Bar, Foyer, Guest Bath, Living Room  
  * Dynamic tiles (color = room activity)  
  * Compact “Back” button in subviews  
  * Vacuum: Rosie  
  * Thermostat: Foyer climate panel  

==== ✔ Upstairs Dashboard ====
  * Rooms: Office, Master, Guest, Mom’s Room, Hallway  
  * Swipe navigation  
  * Dynamic tiles  
  * Back button template  

==== ✔ Outside Dashboard ====
  * Front Yard / Back Yard / Garage  
  * Smaller camera feeds  
  * WLED + Mega Tree controller  
  * Garage freezer outlet monitoring  

==== ✔ System / Network Dashboard ====
  * UniFi client count + AP health  
  * WAN latency  
  * Pi-hole stats  
  * Proxmox VM summary  
  * UPS / NUT integration (future)

----

===== Automations (High-Level) =====

Home Assistant orchestrates major automation layers across TorresVault:

==== Network & Infrastructure ====
  * AP down alerts  
  * UniFi client-count drop alerts  
  * WAN latency pings  
  * Pi-hole health checks  

==== Lighting & Motion ====
  * Zigbee/PIR motion-based lighting  
  * Living Room motion toggle  
  * Smart LED notifications via WLED  

==== FPP Lighting Show ====
  * Start / Stop show buttons  
  * Playlist selector  
  * Fault notifications (FPP offline, sync errors)  

==== BLE Tracking ====
  * Presence tracking for keys, wallet, badge, laptop  
  * Car BLE → TTS “Good morning” & item reminders  
  * Planned: “Forgot something” automations  

==== Voice Assistant ====
  * Office test-deployment of HA Voice  
  * Goal: Replace all Alexa/Echo devices  
  * Local STT/TTS (Whisper/Piper)  
  * Seamless voice→AI→automation pipeline  

----

===== Integrations =====

High-level list of core integrations Home Assistant uses:

  * UniFi OS (Gateway, Switches, APs)
  * Pi-hole DNS
  * Proxmox VE
  * Prometheus / Grafana
  * Zigbee/Matter (Hue, Aqara, standard ZHA)
  * ESPHome sensors + BLE gateways
  * FPP (Falcon Player)
  * Roku & media players
  * WLED (indicators, car, office)
  * Vivint Security
  * Nest Thermostat

----

===== Current State =====

  * Fully functional, stable automation layer  
  * Dashboards rebuilt with unified templates  
  * All views optimized for mobile + wall tablets  
  * BLE + voice systems expanding  
  * FPP integration used successfully for 2024/2025 seasons  

----

===== Future Enhancements (Roadmap) =====

  * Full room-level BLE tracking via Pi Zero + Room Assistant  
  * Complete migration from Echo → HA Voice  
  * Unified “Jarvis” local AI control  
  * Mini-PC Proxmox nodes + Kubernetes (in-VM)  
  * Add UPS monitoring via NUT  
  * Add garden environmental sensors + irrigation automations  

----

''This page documents the Home Assistant architecture inside the TorresVault ecosystem and evolves as the system expands.''