infrastructure/docs/wip/HOME-ASSISTANT-SETUP.md

# Home Assistant Setup

**Status:** IN PROGRESS
**Priority:** High
**Started:** 2026-02-07

## Overview

Home Assistant OS (HAOS) running as a libvirt VM on Unraid, with custom dashboards, themes, and smart home integrations.

## Infrastructure

| Component | Detail |
|-----------|--------|
| VM | HAOS on libvirt (Unraid host) |
| IP | 192.168.10.50 (VLAN 10 — Management) |
| Access | Web UI at `http://192.168.10.50:8123` |
| VM Management | `virsh qemu-agent-command "Home Assistant"` from Unraid |
| Container | `homeassistant` Docker container inside HAOS |

## Completed

### Integrations

| Integration | Type | Devices | Notes |
|-------------|------|---------|-------|
| Gree AC (manual) | Custom component (`gree_manual`) | 1 AC unit | Cross-VLAN via L3 unicast; generic key `a3K8Bx%2r8Y7#xDh` |
| Xiaomi Miot | HACS integration (`xiaomi_miot`) | 11 devices | 2FA verification required; BLE sensors work via cloud |
| Tuya / Smart Life | Built-in | Smart Curtain, switches, lights | Paired via Smart Life QR code |
| Roborock | Via Xiaomi Miot | S7 Pro Ultra | On 192.168.31.x (Xiaomi router subnet) |
| Bosch Home Connect | Built-in (`home_connect`) | Oven, Washing Machine | OAuth2 via developer.home-connect.com |

**Xiaomi devices discovered:**
- 4x Miaomiaoce BLE temp/humidity sensors (Living Room, Kitchen, Boys Room, Bedroom)
- 2x Air Purifiers (Living Room — zhimi.mc1, Boys Room — cpa4)
- 1x Air Purifier 4 Compact (on VLAN 30)
- 1x Humidifier (Living Room — deerma.jsq2w)
- 1x Roborock S7 Pro Ultra
- 1x Xiaomi Router
- 1x Mi Smart Home Hub

**Bosch Home Connect devices:**
- Bosch Oven HRG7784B1 — temperature, door state, programs, child lock, remote control
- Bosch Washing Machine WGB24400BY — programs, progress, spin speed, temperature, remaining time, door state, child lock

### Theme — visionOS

| File | Path (inside HA) | Source |
|------|-------------------|--------|
| visionOS theme | `/config/themes/visionos.yaml` | [homeassistant-visionos-theme](https://github.com/Nezz/homeassistant-visionos-theme) |
| Liquid Glass theme | `/config/themes/liquid_glass.yaml` | Same repo |
| card-mod.js (v4.2.0) | `/config/www/card-mod.js` | Enables backdrop-filter CSS effects |
| Mushroom Cards (v5.0.10) | `/config/www/mushroom.js` | Clean card collection for dashboards |

- Both JS files registered as Lovelace resources via websocket API (`lovelace/resources/create`)
- visionOS set as default theme via startup automation in `automations.yaml`

### Dashboards

Two custom Lovelace dashboards (not the default Overview):

| Dashboard | URL Path | Columns | Optimized For |
|-----------|----------|---------|---------------|
| Mobile | `/dash-mobile` | 2 | Phone screens |
| Desktop | `/dash-desktop` | 4 | Desktop/tablet |

Both use **Sections** view type with **Mushroom Cards**. Created via HA websocket API (`lovelace/dashboards/create` + `lovelace/config/save`).

**Sections on both dashboards:**

1. **Header** — Title card + chips (weather, outside temp, vacuum status, phone battery)
2. **Climate Control** — Living Room thermostat, Kitchen thermostat, Gree AC
3. **Temperatures** — 4 indoor Miaomiaoce BLE sensors + outside temp/humidity
4. **Radiators** — Living Room, Main Bedroom, Girls Room
5. **Bosch Appliances** — Oven (status, temp, door) + Washer (status, time left, progress)
6. **Lights** — Living Room, Dining Room, Bedroom LED strip, Picture Frame lamp
7. **Switches** — Entrance (x2), Bathroom (x2), Kids Bathroom (x2), Boys Lamp
8. **Curtain & Vacuum** — Smart Curtain, Roborock S7, Vacuum battery

Desktop dashboard has expanded Bosch sections with program selectors, child lock, spin speed, wash temperature, and remote control status.

### Startup Automation

```yaml
# /config/automations.yaml
- id: set_visionos_theme
  alias: "Set visionOS Theme on Startup"
  trigger:
    - platform: homeassistant
      event: start
  action:
    - service: frontend.set_theme
      data:
        name: visionos
```

## Known Issues

| Issue | Detail | Workaround |
|-------|--------|------------|
| Xiaomi devices on 192.168.31.x unreachable | Air purifiers, humidifier, Roborock on Xiaomi router subnet | Switch to cloud-only polling in xiaomi_miot config |
| Cross-VLAN broadcast discovery | UDP broadcasts don't cross VLANs | Use manual IP config (e.g., `gree_manual` component) |
| `/config/www/` not served after creation | HA needs full core restart to detect new `www` directory | `ha core restart` from HAOS VM |
| `automations.yaml` syntax | Appending to `[]` creates invalid YAML | Always overwrite file, never append after `[]` |

## Pending Work

- [ ] Switch Xiaomi air purifiers/humidifier to cloud-only mode for reliable polling
- [ ] Add more dashboard sections as new devices are added
- [ ] Evaluate HACS frontend cards (mini-graph-card, apexcharts-card) for richer data display
- [ ] Set up HA mobile app companion for phone notifications and presence detection

## Technical Notes

- **File transfer to HA:** base64 encode → virsh guest-exec → docker exec -i tee (chunk at 50KB for large files)
- **HAOS minimal toolset:** Only `/usr/bin/curl`, `/sbin/ip` available — no wget/nc/python3/which
- **Dashboard URL paths:** Must contain a hyphen (e.g., `dash-mobile`, not `mobile`)
- **Lovelace resources:** Must be registered via websocket API, not by writing storage files directly
- **HA API token:** Generated JWT with HMAC-SHA256 from refresh token's `jwt_key` in `/config/.storage/auth`
- **Home Connect OAuth2:** Register app at developer.home-connect.com, use redirect URI `https://my.home-assistant.io/redirect/oauth`, disable "One Time Token Mode" (breaks HA token refresh)