Phone modes and lifecycle

Source

This page is generated from docs/device-lifecycle.md in the repository.

Status: the server and app parts are built (modes at claim, per-space session length, idle options, remove = wipe) and run on the browser phone (/device/). The firmware has remove = wipe, the factory reset and Lounge phones; choosing the mode on the phone itself at first run is planned.

Modes (set when a phone is claimed)

Mode	Owned by	Signed in as	When idle
Kids	a home space; guardians manage it	always the child	never idle: allow-list, quiet hours, voicemail
Personal / desk	one person	always that person	never idle: it is their own phone (bedside, desk)
Lounge	a space (venue, office, common room)	whoever signs in	dead by default until someone signs in
Left (not chosen)	a space; guardians manage it	nobody	the phone of someone who left: below

The mode is picked when the phone is claimed (POST /api/devices/pair with mode; the phone’s own first-run choice arrives in pair.begin.kind and is preselected, POST /api/devices/pair/preview). Kids and Lounge phones are claimed by the space’s guardians, and kids’ phones only in a home; anyone may claim a phone as their own (personal reuses the phone’s owner: calls to that person ring it, its keys dial as them). The phone learns its mode and owner from config.owner and shows them on the strip.

Idle Lounge phones can optionally be configured per space (PUT /api/lounge/settings, guardians). These are all off by default:

• house-line keys (houseLine: {enabled, keys}): idle keys call as the space (the phone’s name) — a member (rung wherever they are), someone’s personal desk phone in the space, or a group of members where the first to answer takes the call. Kids’ phones, people outside the space and public lines can’t be targets: a public line is called only by someone signed in at the phone (from their own keys); a free phone that tries one shows SIGN IN TO CALL.
• who’s here (whosHere): shows who is signed in at the space’s other Lounge phones and open to chat (config.here); people who aren’t open to chat aren’t listed.
• …and more configurations later

Session length is a per-space setting managed by the space’s guardians (its admins): session: "idle" (after idleMinutes hung up and unused, default 10 — a venue), "end_of_day" (at dayEnd, local time, default 00:00 — hot desks) or "until_logout" (an office desk). Sessions also end on Log out, Leave, a new takeover, or a disconnect after the 60-second grace period. The end of day uses the space’s one alarm, only while a session is open. Nothing stays on the phone.

Lifecycle

1. Out of the box: no owner and no Wi-Fi. The phone generates its own device key on first boot. The display shows “Set me up”, the status light breathes, and lifting the handset plays a spoken prompt.
2. Wi-Fi setup:
   • Universal path (built, firmware 0.3): with no Wi-Fi saved the phone opens a temporary network “OpenLoungePhone-XXXX” (WPA2; its 8-digit password is on the display, so only someone at the phone can join) and a setup page at http://192.168.4.1/ (phones open it as a captive portal) lets you pick your Wi-Fi and type its password; the phone saves it and restarts. It also opens when the saved Wi-Fi has been unreachable for 3 minutes (moved, new password), from MENU → 3 Wi-Fi → 1, or with MENU+BACK held 3 s at power-on.
   • Android: Bluetooth setup from the companion is optional.
   • Later: the QR sticker on the base opens the page directly.
3. Claim: the QR code on the base or the 6-digit code on the display (the minimal board has no NFC). You pick the space and the mode.
4. Daily use: per mode, as above.
5. Updates and health:
   • Signed OTA updates (built, firmware 0.4) install only while the phone is hung up and idle, overnight by default; MENU → 9 updates now.
   • The firmware has two slots, so a bad update rolls back automatically.
   • The owner sees signal, offline alerts and (on phones that report them) battery and reduced-power mode.
6. Remove, reset, retire:
   • Remove in the app: the server forgets the device key, and the phone wipes itself: at once if it’s connected (wipe), otherwise the next time it connects — the server remembers the removed id and key (removed_devices, a year) and sends wipe only after the phone signs the challenge with that key, so nobody else can trigger it. Deleting a space wipes its phones the same way. The browser phone deletes its key from IndexedDB, its id and its first-run choice, and starts over.
   • Someone leaves (leaves the space, is removed from it, or deletes their account): their own phones there stay, as phones of someone who left.
   • Factory reset (MENU+BACK held 10 s at power-on; released after 3 s it opens the Wi-Fi setup network instead; the display says which): wipes Wi-Fi, owner and keys, and generates a new device key.
   • Changing mode or owner: always goes through a wipe. No data ever carries over. The server enforces it: PATCH /api/devices/:id only renames a phone and answers 409 to any owner or mode field.
   • No claim lock. A removed phone holds nothing of value (no contacts, no history, no keys that still work), so anyone can reset it and claim it again. That keeps second-hand and handed-down phones easy.

Phones of someone who left

When someone leaves a space (or is removed from it, or deletes their account), their own phones there stay in the space, owned by nobody and labelled with whose they were: “Dana’s phone (Dana left)” in the app, DANA LEFT on the phone (config.owner {"mode": "left", "person": "Dana"}). Such a phone is not a kids’ phone, and it isn’t anyone’s:

• Nobody can call it. It never rings for anyone (calls to it end “Nobody can call that phone: its owner left”), it has no extension and isn’t in the directory.
• It calls out under the strictest rules, a kids’ phone’s: only the space’s people left on its list (what was the owner’s own goes: their connections, add-ons and lines, rooms, extension and home features), quiet hours apply, no add-ons or public lines, no voicemail from it, and a call with it is never recorded. It doesn’t count as a kids’ phone for the space’s recording rule.
• Guardians and admins manage it under Home → Phones of people who left → Manage: rename it, Set it up again (it wipes itself and shows a new code to pair it with, in any mode, for anyone), or Remove and wipe. Nothing else about it changes until then (the server refuses with “This phone’s owner left. Set it up again (or remove it) before changing what it does.”).

Phones orphaned by older servers (they turned into ownerless household phones) are marked when the server updates (migration 0035): a phone the audit trail says was added as someone’s own phone shows as theirs (“Dana left”); any other ownerless phone in a team or organization, where kids’ phones can’t exist, shows as “its owner left”. In a home without that trail, such a phone can’t be told from a kids’ phone and stays one; its guardians can set it up again.

See security-model.md for the protections and trust signals. It covers what the minimal board’s hardware does and doesn’t guarantee (no hardware mute switch or mic lights), secure boot, and the four-word device fingerprint.