# Home Assistant

<overview>
HA OS at `home.thelonglakelodge.com`, proxied via fritzlab sjc001 remote-proxy
to the lodge LAN. Use the public HTTPS/WSS path; direct `172.24.24.50:8123` is
unapproved IPv4 inventory, not an operational path. API token in `~/.env` as
`LODGE_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 Supervisor full-backup schedule. Local recovery backups include
`pre-matter-recommission 2026-07-05` and
`post-matter-recommission-2026-07-15`.

Local control via WebSocket: `wss://home.thelonglakelodge.com/api/websocket`,
auth with `{"type":"auth","access_token":LODGE_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`. Retained as fallback.
- **Matter (local)** — `matter` integration via the `core_matter_server` addon,
  entities `climate.*_nest`. Primary control path.

8 zones: Office, Kitchen, Bunkhouse Kitchen (forced-air "HVAC"); Eat-in Kitchen,
Primary Bathroom, Basement Living Room, Basement Bedroom, Tub Room (in-floor heat).

`script.set_away_temperatures` (HVAC `heat_cool` low/high 55–78 / in-floor 55)
and `script.set_occupied_temperatures` (HVAC `heat_cool` low/high 68–76 /
in-floor 67) set all zones,
targeting Matter device labels `matter_hvac` (3 forced-air) and
`matter_in_floor_heat` (5 in-floor). Both run with no delays and resolve device
labels to climate entities via
`label_devices(..) | map('device_entities') | ... | select('match','climate')`
because labels are on devices. Verified 8/8 for both profiles on 2026-07-15.
Cloud devices retain `google_nest` plus `hvac` / `in_floor_heat` labels; any
cloud fallback script must serialize commands with an 8 s delay to avoid the
Google SDM `ExecuteDeviceCommand` 429 limit.
</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.

The 9.0.0 Python→matter.js migration created fabric 2; the old compressed fabric
`1E5211CA4C7B5275` is gone. Recovery completed 2026-07-15 by recommissioning all
8 thermostats through Nest multi-admin. Cloud Nest remained available throughout.
</matter-outage>

<matter-recommission>
## Matter fabric 2 (complete)

`core_matter_server` 9.1.0 runs matter.js. All nodes are available:

| Node | Device | Climate entity | Category | Child sensor |
|---:|---|---|---|---|
| 16 | Lodge Kitchen Nest | `climate.lodge_kitchen_nest` | `matter_hvac` | Lodge Kitchen Sensor Nest |
| 17 | Lodge Office Nest | `climate.lodge_office_nest` | `matter_hvac` | Lodge Office Sensor Nest |
| 18 | Bunkhouse Kitchen Nest | `climate.bunkhouse_kitchen_nest` | `matter_hvac` | Bunkhouse Kitchen Sensor Nest |
| 19 | Lodge Primary Bathroom Nest | `climate.lodge_primary_bathroom_nest` | `matter_in_floor_heat` | — |
| 20 | Lodge Eat-in Kitchen Nest | `climate.lodge_eat_in_kitchen_nest` | `matter_in_floor_heat` | — |
| 21 | Lodge Basement Bedroom Nest | `climate.lodge_basement_bedroom_nest` | `matter_in_floor_heat` | — |
| 22 | Lodge Tub Room Nest | `climate.lodge_tub_room_nest` | `matter_in_floor_heat` | — |
| 23 | Lodge Basement Living Room Nest | `climate.lodge_basement_living_room_nest` | `matter_in_floor_heat` | — |

Every thermostat also has `matter_nest`. Eight thermostat nodes plus the three
bridged sensors equal 11 HA Matter devices. All stale fabric-1 registry devices
are deleted.

Recommissioning requires a phone on lodge WiFi; Google Home refuses to generate
a Matter code off-network:
1. Google Home app (lodge account) → thermostat → Settings → Linked Matter
   apps & services → Link apps & services → 11-digit code (single-use, ~5 min).
2. WS `{"type":"matter/commission","code":"<code>","network_only":true}`
   (or HA UI Add device).
3. Rename device to "<Zone> Nest", label `matter_nest` + `matter_hvac`
   (Office, Kitchen, Bunkhouse Kitchen) or `matter_in_floor_heat` (the 5
   in-floor zones), rename climate entity to `climate.<zone>_nest`.

GOTCHA — `Address unreachable` / commission timeout after host boot can be a
wedged matter.js socket (`1 of 1 attempt(s) failed, 1 discovered`). Restart
`core_matter_server`, then retry. Do not treat add-on restart as lost-fabric
recovery.

`post-matter-recommission-2026-07-15` (backup id `2e0efde0`) includes HA,
database, and `core_matter_server` data on `hassio.local`. The nightly Git export
does NOT contain Matter fabric storage. Automatic Supervisor backups remain off.
</matter-recommission>

<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).

Overview thermostat cards point at all 8 local Matter `climate.*_nest` entities.
The `Environmentals` page remains cloud-backed: three per-category
vertical-stacks (Lodge HVAC / In-Floor Heat / Bunkhouse), each with Temperature,
Humidity, and Heating/Cooling history graphs (72h). Five in-floor thermostats
have no Matter humidity entity, so cloud humidity remains required there.
</dashboard>