79 lines
4.1 KiB
Markdown
79 lines
4.1 KiB
Markdown
# Rooms, and what is in them
|
|
|
|
One vocabulary for rooms across the whole project, and one answer to "what hardware is
|
|
in this room". Written because three separate features now need it — the floorplan
|
|
presence view, the Pebble app, and anything room-scoped like the workshop assistant —
|
|
and each of them was about to invent its own.
|
|
|
|
## The room id is an HA `area_id`, everywhere
|
|
|
|
`living_room`, `kitchen`, `workshop`. Lowercase, digits, underscores; Home Assistant
|
|
slugifies area names into exactly that shape.
|
|
|
|
That one string is the join key for every part of this project that cares where
|
|
something is:
|
|
|
|
| Where it appears | As what |
|
|
|---|---|
|
|
| Home Assistant | the device's **area** |
|
|
| `CoreSystemConfig.json` | `room` on each kiosk and audio endpoint |
|
|
| Each host's agent config | `<PREFIX>_ROOM`, baked in at build time |
|
|
| MQTT discovery | `suggested_area` on the device object |
|
|
| `identity` | `floorplan_rooms.ha_area_id` — the drawn polygon's tie to reality |
|
|
| `identity`'s `/presence` | the `room` field, read off `AREA_ATTRIBUTE` of a trusted entity |
|
|
|
|
Nothing translates between these. A room named `Living Room` in one file and
|
|
`living_room` in another is two rooms as far as every join above is concerned, which is
|
|
why `tools/validate-config.py` rejects anything that is not already an area_id rather
|
|
than helpfully slugifying it — helpfully slugifying it is how you end up with two.
|
|
|
|
## How a device learns which room it is in
|
|
|
|
```
|
|
CoreSystemConfig.json tools/config-export.py the ISO builder
|
|
kiosks[].room ────────────> CORE_KIOSK_ROOM ───────────> <PREFIX>_ROOM in the
|
|
agent's config file
|
|
│
|
|
HA files the device in that area <───────────┘
|
|
(suggested_area, on first discovery)
|
|
```
|
|
|
|
Declared once, in the same file that already knows every other fact about that device.
|
|
Nobody drags devices into areas in the HA UI, and nobody types a room name twice.
|
|
|
|
**The one real limitation: `suggested_area` is a suggestion, and it is only honoured
|
|
when HA first discovers the device.** Move a panel to another room, rebuild its image,
|
|
and HA keeps it in the old area — the suggestion is not reapplied. Moving a device
|
|
means moving it in HA too, once. This is a property of HA's discovery, not something
|
|
this project can paper over, and it is why the field is named *suggested*.
|
|
|
|
An empty `room` is allowed and is a **warning, not an error**: a household that hasn't
|
|
settled its room names must still be able to build an image. What it loses is automatic
|
|
area assignment, which is a nuisance to fix by hand — not a broken device.
|
|
|
|
## What is not covered by this
|
|
|
|
- **Zigbee devices, cameras, and anything not built by `tools/`.** Their room lives in
|
|
HA only, set when they are paired or added. That is fine — HA is the registry; this
|
|
file is about the devices this repo builds images for, which otherwise had no way to
|
|
say where they were.
|
|
- **Where a *person* is.** That is `identity`'s `/presence`, and it is a different
|
|
problem with a different reliability story — see
|
|
`docs/pebble-presence-watchface.md`'s closing section.
|
|
- **Where an *item* is.** `pantry-vision` locations for food
|
|
(`docs/fridge-item-location.md`); nothing tracks tools or parts yet
|
|
(`docs/workshop-assistant.md`).
|
|
|
|
## Adding a room
|
|
|
|
1. Create the area in Home Assistant (or let a device's `suggested_area` create it).
|
|
2. Use its area_id as `room` on every kiosk/audio endpoint that lives there.
|
|
3. Draw it on the floorplan in `identity`'s admin panel and set its `ha_area_id` to
|
|
the same string. The room editor offers a pick-list from
|
|
`GET /floorplan/areas` — every area HA is currently reporting — so this step is
|
|
choosing from a list rather than retyping an id.
|
|
|
|
Step 3 is optional and independent: presence works without a drawn plan, and a drawn
|
|
plan is useful before presence is wired up. They only need each other for the views
|
|
that show people *on* the plan.
|