Skip to content

presence

diapason.mesh.presence

Which devices are actually reachable, right now.

The one rule this module exists to keep (spec §57): a device that is not there must never be presented as there. So presence is DERIVED from the last heartbeat at read time, never stored as a state someone remembered to set. A stored "ONLINE" survives a crashed app, a closed laptop lid and a dead battery; a timestamp cannot lie about those.

The ladder, from the last time we heard anything:

≤ 45 s   ONLINE      — a heartbeat is due every 15 s, so this tolerates
                       two missed beats before doubting the device
≤ 5 min  IDLE        — the app is alive but nobody is using it
≤ 30 min BACKGROUND  — plausibly suspended (mobile especially), a queued
                       command may still be delivered when it wakes
beyond   OFFLINE     — assume nothing; commands requiring the device
                       online must fail loudly rather than hopefully

is_reachable(device, *, now_ms=None)

True only when a command sent now has a real chance of arriving.

BACKGROUND is deliberately excluded: a suspended phone may accept a queued notification, but promising it will OPEN a screen would be the exact lie §57 forbids. The command policy decides whether to queue.

presence_of(device, *, now_ms=None)

The device's presence, computed from its last heartbeat.

A revoked device is OFFLINE whatever its timestamp says: it is not a device we are willing to reach, so reporting it as available would invite a command that must be refused anyway.