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