4.1 KiB

Raw Blame History

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

Create the area in Home Assistant (or let a device's suggested_area create it).
Use its area_id as room on every kiosk/audio endpoint that lives there.
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.

4.1 KiB Raw Blame History