From 5af3c9478b57bc6d85dea03cdedab926f25250cd Mon Sep 17 00:00:00 2001 From: Kaloyan Danchev Date: Sun, 8 Feb 2026 11:30:17 +0200 Subject: [PATCH] Add Home Assistant setup documentation Covers HAOS VM setup, Xiaomi/Gree/Tuya integrations, visionOS theme, Mushroom Cards dashboards (mobile + desktop), and known issues. Co-Authored-By: Claude Opus 4.6 --- docs/wip/HOME-ASSISTANT-SETUP.md | 111 +++++++++++++++++++++++++++++++ docs/wip/README.md | 6 ++ 2 files changed, 117 insertions(+) create mode 100644 docs/wip/HOME-ASSISTANT-SETUP.md diff --git a/docs/wip/HOME-ASSISTANT-SETUP.md b/docs/wip/HOME-ASSISTANT-SETUP.md new file mode 100644 index 0000000..a5c4531 --- /dev/null +++ b/docs/wip/HOME-ASSISTANT-SETUP.md @@ -0,0 +1,111 @@ +# 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) | + +**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 + +### 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. **Radiators** — Living Room, Main Bedroom, Girls Room +4. **Temperatures** — 4 indoor Miaomiaoce BLE sensors + outside temp/humidity +5. **Lights** — Living Room, Dining Room, Bedroom LED strip, Picture Frame lamp +6. **Switches** — Entrance (x2), Bathroom (x2), Kids Bathroom (x2), Boys Lamp +7. **Curtain & Vacuum** — Smart Curtain, Roborock S7, Vacuum battery + +### 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` diff --git a/docs/wip/README.md b/docs/wip/README.md index 7641d38..2c359f0 100644 --- a/docs/wip/README.md +++ b/docs/wip/README.md @@ -30,6 +30,12 @@ Planned changes, evaluations, and ideas not yet implemented. | [CONSOLE-PORT-ETHER5.md](CONSOLE-PORT-ETHER5.md) | EVALUATING | Low | Console/serial port on HAP1 ether5 | | [KVM-SWITCH-MAC-NOBARA.md](KVM-SWITCH-MAC-NOBARA.md) | EVALUATING | Medium | Software KVM for Mac/Nobara switching | +### Smart Home + +| Document | Status | Priority | Description | +|----------|--------|----------|-------------| +| [HOME-ASSISTANT-SETUP.md](HOME-ASSISTANT-SETUP.md) | IN PROGRESS | High | HAOS VM, dashboards, themes, integrations | + ### Applications | Document | Status | Priority | Description |