Files

Kaloyan Danchev 5af3c9478b 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>

2026-02-08 11:30:17 +02:00

4.8 KiB

Raw Blame History

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
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:

Header — Title card + chips (weather, outside temp, vacuum status, phone battery)
Climate Control — Living Room thermostat, Kitchen thermostat, Gree AC
Radiators — Living Room, Main Bedroom, Girls Room
Temperatures — 4 indoor Miaomiaoce BLE sensors + outside temp/humidity
Lights — Living Room, Dining Room, Bedroom LED strip, Picture Frame lamp
Switches — Entrance (x2), Bathroom (x2), Kids Bathroom (x2), Boys Lamp
Curtain & Vacuum — Smart Curtain, Roborock S7, Vacuum battery

Startup Automation

# /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

4.8 KiB Raw Blame History