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 <noreply@anthropic.com>
This commit is contained in:
Kaloyan Danchev
111
docs/wip/HOME-ASSISTANT-SETUP.md
Normal file
111
docs/wip/HOME-ASSISTANT-SETUP.md
Normal file
@@ -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`
|
||||
@@ -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 |
|
||||
|
||||
Reference in New Issue
Block a user