ADR: Home Assistant Deployment

Date: 2026-05-11
Status: Accepted
Deciders: Self

Context

Home Assistant (HA) is the central hub for IoT automation in the new house. It needs to integrate with:

• Zigbee devices (switches, sensors, buttons) via USB coordinator
• Tapo cameras (RTSP/Tapo integration)
• Unifi Protect (running on UDM)
• Google Home (TTS announcements)
• Sensi thermostats (cloud API)

The homelab has a defined Prod/Test/Dev architecture with Komodo-managed Docker hosts. Home Assistant must fit into this architecture while meeting its unique requirements.

Requirements

1. USB access — Zigbee coordinator must be physically attached to host
2. Network access — Must reach IoT VLAN (10.0.4.0/24) for cameras, Google Home, etc.
3. Unifi Protect access — Must reach UDM for Protect integration
4. Reliability — Automation failures directly impact daily life
5. Manageability — Should fit into existing GitOps/Komodo workflow where possible
6. Backup/Recovery — Must be recoverable quickly if host fails

Constraints

• IoT VLAN (10.0.4.0/24) is isolated from other VLANs by design
• Zigbee coordinator is USB-bound — cannot easily fail over to another host
• Home Assistant does not support native clustering/HA

Decision

Deploy Home Assistant as a container on LenovoMini 1 (Prod Docker host) with USB passthrough for the Zigbee coordinator.

Phased Approach

Phase 1 — Bootstrap (RPi):

• Run HA on existing Raspberry Pi 4
• Place on Prod VLAN (10.0.1.0/24)
• Configure firewall rules for IoT access
• Validates the setup before full integration

Phase 2 — Production Migration:

• Migrate HA to container on LenovoMini 1
• USB passthrough for Zigbee coordinator
• Komodo-managed deployment
• Automated backups to UnRaid NAS

Options Considered

Option 1: Dedicated Raspberry Pi

Description: Run Home Assistant OS on a dedicated RPi 4.

Pros:

• Simple setup
• Direct USB access (no passthrough complexity)
• Isolated from other workloads

Cons:

• Another device to manage outside Komodo
• SD card reliability concerns
• Limited compute for future expansion (Frigate, etc.)
• No integration with existing backup infrastructure

Verdict: Good for bootstrap, not ideal long-term.

Option 2: Container on Prod Docker Host (LenovoMini 1)

Description: Run HA as a Docker container on the existing Prod host, managed via Komodo.

Pros:

• Better hardware (8th Gen i7, 16GB RAM, NVIDIA GPU)
• Integrated with existing management (Komodo, GitOps)
• Backups to UnRaid NAS
• Network already on Prod VLAN with access to other services
• GPU available for future Frigate integration

Cons:

• USB passthrough required (adds configuration)
• Shares resources with Plex/*arr (mitigated by resource limits)
• Single point of failure (mitigated by backups)

Verdict: Best fit for long-term architecture.

Option 3: VM on ProxMox

Description: Run HA in a dedicated VM on the ProxMox host.

Pros:

• Isolated resources
• ProxMox has snapshot/backup features

Cons:

• ProxMox is on Dev VLAN (10.0.3.0/24) — wrong network segment
• USB passthrough to VM is more complex than Docker
• Not on the Komodo-managed path

Verdict: Network placement is wrong. Rejected.

Option 4: Dedicated Mini Host on Prod VLAN

Description: Purchase a dedicated small device (NUC, mini PC) for HA.

Pros:

• Dedicated to home automation
• Direct USB, proper network placement

Cons:

• Additional hardware cost
• Another device outside existing management
• Overkill given available capacity on LenovoMini 1

Verdict: Unnecessary given existing infrastructure.

Consequences

Positive

• Integrated management: HA deployment is Komodo-managed, follows GitOps patterns
• Better hardware: More headroom for future expansion (Frigate, more integrations)
• Unified backups: HA config/data backed up to UnRaid alongside other Prod data
• Network positioning: Prod VLAN has (or will have) appropriate access to IoT and UDM

Negative

• USB passthrough complexity: Requires privileged container or explicit device mapping
• Shared host: HA competes with Plex/*arr for resources (mitigated with resource limits)
• Single point of failure: If LenovoMini 1 goes down, HA is down (mitigated by backups + quick restore)

Neutral

• No native HA failover: Accepted limitation — most homelabs operate this way
• Zigbee bound to host: Coordinator cannot fail over, but Zigbee direct bindings provide local fallback

Implementation

Phase 1: Bootstrap on RPi

Timeline: Immediate (while homelab is being set up)

1. Install Home Assistant OS on Raspberry Pi 4
2. Connect Zigbee coordinator (Sonoff dongle)
3. Place RPi on Prod VLAN (10.0.1.0/24)
4. Configure firewall rules:
   • Allow Prod → IoT (for cameras, Google Home)
   • Allow Prod → UDM management interface (for Unifi Protect)
5. Set up integrations (Zigbee, Tapo, Protect, Google Cast, Sensi)
6. Configure automations
7. Validate everything works

Backup: Manual snapshots to USB or network share

Phase 2: Migrate to Prod Docker

Timeline: When homelab Prod environment is stable

1. Prepare LenovoMini 1:

   • Identify USB port for Zigbee coordinator
   • Test USB device passthrough (/dev/ttyUSB0 or /dev/ttyACM0)

2. Create HA container configuration:

   # docker-compose.yml (Komodo-managed)
   services:
     homeassistant:
       container_name: homeassistant
       image: ghcr.io/home-assistant/home-assistant:stable
       restart: unless-stopped
       privileged: true  # Required for USB and network discovery
       network_mode: host  # Simplifies discovery protocols
       volumes:
         - /opt/homeassistant/config:/config
         - /etc/localtime:/etc/localtime:ro
       devices:
         - /dev/ttyUSB0:/dev/ttyUSB0  # Zigbee coordinator
       environment:
         - TZ=America/New_York

   Notes:

   • privileged: true or explicit device mapping required for USB
   • network_mode: host recommended for mDNS/SSDP discovery (Google Cast, etc.)
   • Adjust device path based on actual Zigbee dongle

3. Migrate configuration:

   • Create HA snapshot on RPi
   • Restore snapshot to container config volume
   • Verify Zigbee coordinator is detected
   • Verify all integrations reconnect

4. Set up backups:

   • Mount UnRaid NAS share for backup storage
   • Configure HA to snapshot to NAS (daily)
   • Or use Komodo/external script to backup /opt/homeassistant/config

5. Add to Komodo:

   • Create TOML resource for HA container
   • Enable GitOps management
   • Set deploy: false initially (manual approval for HA changes)

6. Decommission RPi:

   • Verify Prod deployment is stable (run parallel for a few days if desired)
   • Power down RPi
   • Keep as cold spare for emergency restore

Network Configuration

Firewall rules needed (on UDM):

Note: IoT VLAN should remain isolated from other VLANs. Only Prod (where HA lives) gets access.

Backup & Recovery

Backup strategy:

• Daily HA snapshots to UnRaid NAS
• Retain 7 daily + 4 weekly snapshots
• Config directory also backed up via standard Prod backup job

Recovery procedure:

1. If LenovoMini 1 fails:
   • Option A: Restore to LenovoMini 2 (Test) temporarily
   • Option B: Boot RPi with latest snapshot
2. Restore latest snapshot
3. Reconnect Zigbee coordinator (may need re-pairing if coordinator changed)
4. Verify automations

RTO target: < 1 hour (acceptable for home automation)

Resilience Notes

What survives HA downtime:

• Zigbee direct bindings (button → switch) work without HA
• Smart switches work manually (physical toggle)
• Cameras continue recording (Protect is independent)
• Thermostats continue on last schedule (Sensi is independent)

What fails:

• Automations (door alerts, scenes, presence-based lighting)
• Voice control via HA (Google Home native commands still work)
• Unified dashboard/control

Acceptable trade-off: Brief outages are tolerable. Critical functions (lights, climate) have manual fallback.

Phase 3: Automated Failover (Stretch Goal)

Status: Future consideration
Complexity: Medium-high
Additional hardware: Second Zigbee coordinator (~$25)

Concept

Implement a warm/cold spare HA instance on the Test environment (LenovoMini 2) with automated failover capability. When the primary (Prod) instance has unfixable issues, a single-click remediation brings up the spare and updates network rules.

Architecture

                     Normal Operation
┌─────────────────────────────────────────────────────────────┐
│                                                             │
│   Prod VLAN (10.0.1.0/24)              IoT VLAN (10.0.4.0/24)
│   ┌─────────────────────┐              ┌─────────────────┐  │
│   │   LenovoMini 1      │   allowed    │  Zigbee devices │  │
│   │   [HA - Active]     │─────────────▶│  Cameras        │  │
│   │   [Zigbee Coord 1]  │              │  Google Home    │  │
│   └─────────────────────┘              └─────────────────┘  │
│                                                 ▲           │
│   Test VLAN (10.0.2.0/24)               blocked │           │
│   ┌─────────────────────┐                       │           │
│   │   LenovoMini 2      │───────────────────────┘           │
│   │   [HA - Standby]    │                                   │
│   │   [Zigbee Coord 2]  │                                   │
│   └─────────────────────┘                                   │
│                                                             │
└─────────────────────────────────────────────────────────────┘

                     Failover State
┌─────────────────────────────────────────────────────────────┐
│                                                             │
│   Prod VLAN (10.0.1.0/24)              IoT VLAN (10.0.4.0/24)
│   ┌─────────────────────┐              ┌─────────────────┐  │
│   │   LenovoMini 1      │   blocked    │  Zigbee devices │  │
│   │   [HA - DOWN]       │──────────X   │  Cameras        │  │
│   │                     │              │  Google Home    │  │
│   └─────────────────────┘              └─────────────────┘  │
│                                                 ▲           │
│   Test VLAN (10.0.2.0/24)               allowed │           │
│   ┌─────────────────────┐                       │           │
│   │   LenovoMini 2      │───────────────────────┘           │
│   │   [HA - Active]     │                                   │
│   │   [Zigbee Coord 2]  │                                   │
│   └─────────────────────┘                                   │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Components

1. Standby HA Instance (LenovoMini 2)

• Home Assistant container (same config as Prod)
• Second Zigbee coordinator (Sonoff dongle)
• Container stopped or running in standby mode

2. Config Synchronization

• Option A: Scheduled rsync of /opt/homeassistant/config from Prod → Test (via NAS or direct)
• Option B: Shared config on NAS mount (both read, only active writes)
• Option C: Git-based config with HA Git integration

3. Zigbee Network Portability

• Use Zigbee2MQTT (not ZHA) — stores network config in coordinator_backup.json
• Backup can be restored to second coordinator
• Devices don’t need re-pairing if network key is preserved
• Caveat: Second coordinator must be same model or compatible

4. Firewall Automation (Ansible/Terraform)

# ansible playbook: failover-to-test.yml
- name: Failover HA to Test environment
  hosts: localhost
  tasks:
    - name: Update UDM firewall - block Prod to IoT
      community.general.udm_firewall_rule:
        name: "Prod-to-IoT"
        state: disabled
      
    - name: Update UDM firewall - allow Test to IoT
      community.general.udm_firewall_rule:
        name: "Test-to-IoT"
        state: enabled
        
    - name: Start HA container on Test
      community.docker.docker_container:
        name: homeassistant
        state: started
      delegate_to: lenovomini2
      
    - name: Stop HA container on Prod (if reachable)
      community.docker.docker_container:
        name: homeassistant
        state: stopped
      delegate_to: lenovomini1
      ignore_errors: yes

5. Failback Procedure

• Reverse the process when Prod is healthy
• Sync any config changes from Test back to Prod
• Re-enable Prod firewall rules, disable Test

Spare Modes

Recommendation: Start with Cold Spare. Warm Spare adds complexity for marginal time savings.

Triggering Failover

Manual (Phase 3a):

• Single-click: Run Ansible playbook from Komodo UI or CLI
• Human detects issue, initiates failover

Automated (Phase 3b, future):

• Health check monitors HA (e.g., /api/ endpoint)
• Consecutive failures trigger alert
• Optional: Auto-failover after N failures (risky, needs tuning)

Prerequisites

Before implementing:

1. Hardware: Second Zigbee coordinator (~$25)
2. Network: Test VLAN firewall rules pre-configured (disabled)
3. Ansible: Playbooks for failover/failback
4. UDM API access: Ansible collection for Unifi or direct API calls
5. Zigbee2MQTT: Migrate from ZHA if using ZHA initially
6. Testing: Validate failover in controlled scenario

Risks & Mitigations

Cost

Decision

Defer to Phase 3. Implement after Phase 2 is stable and proven. The complexity is justified only after experiencing reliability issues or when uptime requirements increase.

References

• Home Assistant Container Installation
• Zigbee2MQTT Docker
• Zigbee2MQTT Coordinator Backup
• Home Assistant Backup/Restore
• Unifi API

Decision: Door Locks

Date: 2026-05-11
Status: Deferred
Decision: No smart locks initially; rely on physical keys + camera detection

Context

Evaluating whether to include smart locks in the initial IoT deployment.

Decision

Defer smart locks. Focus on detection, not prevention.

Rationale

1. Security philosophy: If someone is determined to get in, they will. Detection and evidence (cameras) are more valuable than a smart lock.

2. Existing coverage: Unifi Protect cameras + door sensors provide detection and alerting.

3. Complexity trade-off: Smart locks add battery management, failure modes, and integration points without a clear use case.

4. Physical keys work: No current pain point that a smart lock solves.

Future Considerations

Revisit when one of these use cases becomes valuable:

• Keyless entry for family
• Temporary access codes for guests/contractors
• Auto-lock after X minutes
• Remote verification
• Presence-based auto-unlock

Options to Evaluate Later

Consumer (HA compatible):

• Yale Assure Lock 2 (Zigbee, Z-Wave, Matter)
• Schlage Encode Plus (WiFi, HomeKit)
• August Wi-Fi Smart Lock (retrofit)
• Level Lock+ (invisible, HomeKit/Matter)

Enterprise:

• Unifi Access — NFC/card based, integrates with Protect
• Higher cost (~$300+/lock + hub), more commercial-grade
• Interesting for “set and forget” but overkill for residential

When Adding Locks

1. Prefer Zigbee or Matter (aligns with existing protocol)
2. Integrate via Home Assistant
3. Automate: auto-lock, lock-on-leave, alert if unlocked while away
4. Tie to camera snapshots on unlock events

Decision: Smart Switch Protocol

Date: 2026-05-11
Status: Decided
Decision: Zigbee (Inovelli Blue switches)

Context

Planning IoT lighting for new house. Requirements:

• Work in 3-way configurations with only ONE switch replaced
• Support wireless buttons for remote control
• Prioritize cost savings and upgradeability
• Integrate with self-hosted Home Assistant

Neutral wire is present.

Options Considered

Zigbee — Inovelli Blue Series

Protocol: Zigbee 3.0
Switch Cost: ~$45-50
Coordinator Cost: ~$20-30

Pros:

• Works with existing dumb switch in 3-way config
• Large device ecosystem (sensors, buttons, plugs)
• Cheap wireless buttons ($7-15)
• Direct Zigbee binding (button controls switch without hub)
• Configurable LED notification bar
• Scene/multi-tap support
• Mesh network extends coverage

Cons:

• Higher per-switch cost
• 2.4GHz interference possible (manageable)

Z-Wave — Zooz Switches

Protocol: Z-Wave Plus
Switch Cost: ~$30-35
Coordinator Cost: ~$35-45

Pros:

• Works with existing dumb switch in 3-way config
• Lower per-switch cost
• Dedicated frequency (no WiFi interference)
• Mature, reliable protocol

Cons:

• Smaller device ecosystem
• Wireless buttons limited and expensive ($40+)
• Less feature-rich

Also Considered

Lutron Caseta: Excellent reliability, but requires proprietary bridge. Less flexible ecosystem.

WiFi switches: Cloud dependency or complex local setup. Doesn’t align with self-hosted goals.

Decision

Zigbee with Inovelli Blue switches.

Rationale

1. Accessory ecosystem: Zigbee buttons and sensors are significantly cheaper. $7 IKEA button vs $40+ Z-Wave compounds quickly.

2. Upgradeability: Largest device selection across manufacturers for future expansion.

3. Feature set: LED notifications, direct binding, scene control — useful for automations.

4. 3-way handling: Single switch replacement works cleanly.

Implementation

• Coordinator: Sonoff Zigbee 3.0 USB Dongle Plus
• Integration: ZHA or Zigbee2MQTT (both well-supported)
• Placement: Central location or USB extension to avoid interference

Home Assistant Automations

Workflow definitions for IoT automations. Copy/adapt these for Home Assistant.

Door Sensor Automations

Door Left Open Alert

Announces via Google Home when a door has been open for 5 minutes.

alias: "Alert - Door Left Open"
description: "Announce when a door has been open too long"
trigger:
  - platform: state
    entity_id:
      - binary_sensor.front_door
      - binary_sensor.back_door
      - binary_sensor.office_door
      - binary_sensor.garage_entry_door
    to: "on"
    for:
      minutes: 5
action:
  - service: tts.google_translate_say
    target:
      entity_id: media_player.living_room_speaker
    data:
      message: "{{ trigger.to_state.attributes.friendly_name }} has been open for 5 minutes."
mode: parallel

Door Still Open Reminder

Repeats announcement every 5 minutes while an exterior door remains open.

alias: "Alert - Door Still Open Reminder"
description: "Repeat reminder every 5 minutes while door is open"
trigger:
  - platform: state
    entity_id:
      - binary_sensor.front_door
      - binary_sensor.back_door
    to: "on"
    for:
      minutes: 5
action:
  - repeat:
      while:
        - condition: state
          entity_id: "{{ trigger.entity_id }}"
          state: "on"
      sequence:
        - service: tts.google_translate_say
          target:
            entity_id: media_player.living_room_speaker
          data:
            message: "Reminder: {{ trigger.to_state.attributes.friendly_name }} is still open."
        - delay:
            minutes: 5
mode: parallel

Garage Entry Night Alert

Alerts when garage entry door opens at night, with camera snapshot.

alias: "Alert - Garage Entry Night"
description: "Alert when garage entry opens at night"
trigger:
  - platform: state
    entity_id: binary_sensor.garage_entry_door
    to: "on"
condition:
  - condition: time
    after: "22:00:00"
    before: "06:00:00"
action:
  - service: tts.google_translate_say
    target:
      entity_id: media_player.bedroom_speaker
    data:
      message: "Garage entry door opened."
  - service: camera.snapshot
    target:
      entity_id: camera.tapo_garage
    data:
      filename: "/config/www/snapshots/garage_{{ now().strftime('%Y%m%d_%H%M%S') }}.jpg"
mode: single

Lighting Automations

Garage Light Button

Wireless button in adjacent room toggles garage light.

alias: "Button - Garage Light Toggle"
description: "Wireless button controls garage light"
trigger:
  - platform: event
    event_type: zha_event
    event_data:
      device_id: <zigbee_button_device_id>
      command: "toggle"
action:
  - service: light.toggle
    target:
      entity_id: light.garage
mode: single

Note: Can also use Zigbee direct binding for button-to-switch control without HA in the loop.

Goodnight Scene

Single button or voice command triggers bedtime routine.

alias: "Scene - Goodnight"
description: "Turn off lights, set fan, dim bedroom"
trigger:
  - platform: event
    event_type: zha_event
    event_data:
      device_id: <bedside_button_device_id>
      command: "on"
action:
  - service: light.turn_off
    target:
      entity_id:
        - light.hall_light
        - light.garage
  - service: light.turn_on
    target:
      entity_id: light.bedroom_fan_light
    data:
      brightness_pct: 10
  - service: fan.set_percentage
    target:
      entity_id: fan.bedroom_fan
    data:
      percentage: 50
mode: single

Presence Automations

Arriving Home

Turns on entry lights when arriving home after sunset.

alias: "Presence - Arriving Home"
description: "Turn on lights when someone arrives after sunset"
trigger:
  - platform: state
    entity_id: person.you
    to: "home"
condition:
  - condition: sun
    after: sunset
action:
  - service: light.turn_on
    target:
      entity_id:
        - light.front_porch
        - light.living_room
mode: single

Presence detection options:

• HA Companion app (phone GPS)
• Unifi device tracker (via Unifi integration)
• Bluetooth/BLE presence sensors (future)

Climate Automations (Future)

With Sensi thermostats integrated, potential automations:

Away Mode

alias: "Climate - Away Mode"
description: "Set thermostats to away when everyone leaves"
trigger:
  - platform: state
    entity_id: group.all_people
    to: "not_home"
    for:
      minutes: 30
action:
  - service: climate.set_preset_mode
    target:
      entity_id:
        - climate.sensi_upstairs
        - climate.sensi_downstairs
    data:
      preset_mode: "away"
mode: single

Pre-condition Before Arrival

alias: "Climate - Pre-condition"
description: "Resume normal temps when someone is heading home"
trigger:
  - platform: zone
    entity_id: person.you
    zone: zone.near_home
    event: enter
action:
  - service: climate.set_preset_mode
    target:
      entity_id:
        - climate.sensi_upstairs
        - climate.sensi_downstairs
    data:
      preset_mode: "home"
mode: single

Integration Notes

Google Cast TTS

Uses tts.google_translate_say service. Requires:

• Google Cast integration configured in HA
• Speaker entity IDs (e.g., media_player.living_room_speaker)

Tapo Camera Snapshots

Requires Tapo integration or generic camera with RTSP. Snapshots save to /config/www/ for web access.

Zigbee Events

Button events use zha_event (for ZHA) or mqtt triggers (for Zigbee2MQTT). Device IDs and commands vary by button model — check HA device page after pairing.

Receipt Automation

Receipt Fridge Launch — NFC App Launch

Tap the fridge NFC tag to open the receipt scanner app directly.

alias: "Receipts - NFC App Launch"
description: "Launch receipt scanner app from fridge NFC"
trigger:
  - platform: nfc
    tag_id: <fridge_receipt_nfc_uid>
action:
  - service: notify.mobile_app_<phone>
    data:
      message: "open_receipt_scanner"
      data:
        action: launch_app
        package: com.example.receiptscanner
mode: single

The NFC tag is the entry point. The app handles the actual capture and any per-receipt workflow.

Considerations:

• If the app supports deep links or URL schemes, prefer that over a generic notification.
• If people use different phones/scanner apps, map multiple notify targets or a choose block by person/presence.

Service Check / Router Status NFC

Router Status — NFC Status Page

Opens a locally hosted status page showing service health.

alias: "Status - Router NFC"
description: "Serve local status page for router/service health"
trigger:
  - platform: nfc
    tag_id: <router_status_nfc_uid>
action:
  - service: browser_mod.popup
    data:
      title: "Service Status"
      # Serve from a local/static endpoint; no external CDN deps
      url: "/local/status/index.html"
mode: single

Implementation notes:

• Host status/index.html on the same host that serves HA or a lightweight internal web server.
• Keep the page plain HTML with no external dependencies so it works when the internet is down.
• Display gateway ping, DNS resolution result, Pi-hole stats, and a one-click router reboot if supported.

Consumable Replacement NFC

Consumable Tag — Reorder Trigger

Opens the replacement item’s reorder path.

alias: "Consumables - Replace"
description: "Open consumable replacement action"
trigger:
  - platform: nfc
    tag_id: <consumable_nfc_uid>
action:
  - service: browser_mod.popup
    data:
      title: "Replace Air Filter"
      # Prefer a stable local/HA endpoint; the destination can rotate behind this URL
      url: "/local/consumables/air-filter.html"
mode: single

Instead of encoding a retailer URL directly, use a stable local or Home Assistant destination so the reorder page can change without rewriting the tag.

Pi-hole Temporary Disable NFC

Pi-hole — 30 Minute Disable

Disables Pi-hole time-boxed for 30 minutes.

alias: "Pi-hole - Temp Disable 30m"
description: "Disable Pi-hole for 30 minutes from NFC tap"
trigger:
  - platform: nfc
    tag_id: <pihole_temp_disable_nfc_uid>
action:
  - service: rest_command.pihole_disable_30m
mode: single

Time-box the disable window so ad-blocking is re-enabled automatically. Surface the remaining time on the local status page so the household can see the countdown.