thelonglakelodge/reference/home-assistant.md

# Home Assistant

<overview>
HA OS at `home.thelonglakelodge.com`, proxied via fritzlab sjc001 remote-proxy
to `172.24.24.50:8123` (also directly reachable on the lab network). Supervisor
Observer on `:4357` (read-only health, no auth). API token in `~/.env` as
`HA_TOKEN` (long-lived admin token — core API + service calls + Supervisor:
WS `{"type":"supervisor/api","endpoint":...}` for JSON endpoints, REST
`/api/hassio/addons/<slug>/logs` for text logs; `/api/error_log` is 404 —
use WS `system_log/list`). No SSH (`:22` closed, no terminal addon).
No automatic backups configured (`backup/info` → 0 backups).

Local control via WebSocket: `wss://home.thelonglakelodge.com/api/websocket`,
auth with `{"type":"auth","access_token":HA_TOKEN}`. Useful WS cmds:
`config_entries/get`, `config/device_registry/list`, `config/entity_registry/list`,
`matter/node_diagnostics{device_id}`, `lovelace/config{url_path:null}` /
`lovelace/config/save`. Addon control via REST service:
`POST /api/services/hassio/addon_restart {"addon":"core_matter_server"}`.
</overview>

<thermostats>
## Nest thermostats are integrated TWICE

The 8 Nest thermostats appear via two independent paths:
- **Cloud (Google Nest)** — `nest` integration, entities `climate.*_google_nest`
  (+ `climate.lodge_basement` = Basement Living Room) and per-zone
  `sensor.*_temperature` / `sensor.*_humidity`. Reliable; cloud-dependent.
- **Matter (local)** — `matter` integration via the `core_matter_server` addon,
  entities `climate.*_nest`. Local control, but see incident below.

8 zones: Office, Kitchen, Bunkhouse Kitchen (forced-air "HVAC"); Eat-in Kitchen,
Primary Bathroom, Basement Living Room, Basement Bedroom, Tub Room (in-floor heat).
Matter fabric id `1E5211CA4C7B5275`, node ids 1–5,7,8,9 (temp sensors are bridged
endpoint-101 sub-devices of their thermostat node).

`script.set_away_temperatures` (HVAC 55–78 / in-floor 55) and
`script.set_occupied_temperatures` (HVAC 68–76 / in-floor 67) set all zones,
targeting by **label**: `hvac` (3 forced-air) and `in_floor_heat` (5 in-floor),
both applied to the cloud `*_google_nest` devices (resolved in-script via
`label_devices(..) | map('device_entities') | ... | select('match','climate')`
since the labels are on devices, not entities). Commands are **serialized one
zone at a time with an 8 s delay** — firing all 8 at once trips the Google Nest
SDM per-user `ExecuteDeviceCommand` rate limit (429 RESOURCE_EXHAUSTED). (Matter copies carry parallel
`matter_hvac` / `matter_in_floor_heat` labels — used by the scripts before the
2026-06-15 repoint to cloud.) `google_nest` labels all 8 cloud devices.
</thermostats>

<matter-outage>
## Matter fabric loss (2026-06-15)

At 2026-06-15 13:53 UTC an HA Core/Supervisor restart (Supervisor → 2026.06.1)
left the `core_matter_server` addon (v8.5.0) with an **empty fabric** — all 11
Matter devices report `node_not_found`, all 59 `climate.*_nest` etc. entities
`unavailable`. Integration reconnects fine (config entry `loaded`); the server
simply has zero nodes. Addon restart + config-entry reload do NOT restore them
(storage lost, not transient), and there is no backup to restore from.

Cloud Nest is unaffected → thermostat control intact via `*_google_nest`.

Recovery = re-commission each thermostat on-site (non-destructive, no factory
reset needed — Nest supports Matter multi-admin):
1. On lodge WiFi, Google Home app (lodge account) → tap thermostat → Settings →
   "Linked Matter apps & services" → "Link apps & services" → generate a Matter
   setup code (11-digit / QR). Code is single-use, ~5 min TTL.
2. HA → Settings → Devices & Services → Matter → Add device → enter the code.
   Wait ~1–2 min; node appears (bridged temp sensor comes with it).
3. Repeat per thermostat (one code at a time). Rename to match.
4. Delete the stale unavailable Matter devices afterward.
Then re-point dashboard climate tiles back to `climate.*_nest` if local control
is wanted (see dashboard note).
</matter-outage>

<matter-commissioning-blocked>
## Matter re-commissioning blocked (2026-07-05)

Addon `core_matter_server` is now 9.0.4 = matter.js server (`matter-server/1.1.7`,
schema 11) — the 9.0.0 update REPLACED the Python Matter Server; the migration
left an EMPTY fabric (now `fabric_id: 2`, new compressed id — the pre-June
fabric `1E5211CA4C7B5275` is gone for good; nodes must be re-commissioned).

Re-commissioning FAILS: server discovers the Nest via mDNS but PASE dials only
ONE candidate — the Nest's IPv6 link-local (`fe80::…%enp6s18`) — which is
"Address unreachable"; 3-min timeout, then
`Commission failed: … (1 of 1 started attempt(s) failed, 1 discovered)`.
NOT a pairing-code problem (wrong-pin tests fail identically at the same spot).

Facts: HA VM `enp6s18` = 172.24.24.50/24, IPv6 fe80-only (no RA/GUA on vino).
Nests are WIRELESS on the SAME `vino` network (172.24.24.80-99); UniFi SSID has
l2_isolation/mcastenhance/proxy_arp all OFF. So either fe80→wireless NDP fails,
the advertised fe80 belongs to a non-WiFi Nest interface (Thread/BLE MAC
EUI-64), or matter.js ignores an IPv4 A record candidate.
matterjs-server has NO documented IPv4/interface knob (only --primary-interface);
addon passthroughs exist: `matter_server_args`, `matter_server_env_vars`,
`matter_server_version` (npm pin), `beta`.

Addon `log_level: debug` is SET (revert to info when solved). Next attempt will
log the full discovery record (all A/AAAA candidates) — that discriminates the
root cause. A Matter setup code can be generated REMOTELY (Google Home app →
thermostat → Linked Matter apps & services), then drive
WS `{"type":"matter/commission","code":"<11-digit>"}` and read
`/api/hassio/addons/core_matter_server/logs`.
</matter-commissioning-blocked>

<dashboard>
## Main Lovelace (`lovelace` / "Overview", storage mode)

Views: `main` (single grid card, columns:1, headed sections: locks/lights,
Helpful Scripts, Water Sensors, then climate as three 2-col thermostat-card
grids — **Lodge HVAC** (office, kitchen), **In-Floor Heat** (5 in-floor zones),
**Bunkhouse** (bunkhouse kitchen)),
`Environmentals` (history page), and `Lock Management`. Edit via
`lovelace/config` / `lovelace/config/save` (WS).

HVAC climate tiles point at the **cloud** `*_google_nest` entities (repointed
off the dead Matter `*_nest` during the 2026-06-15 outage). The `Environmentals`
page is three per-category vertical-stacks (Lodge HVAC / In-Floor Heat /
Bunkhouse), each with Temperature, Humidity, and Heating/Cooling history-graphs
(72h) scoped to that category's entities.
If Matter is re-commissioned and local control is preferred, repoint these back.
</dashboard>