Skip to content

feat: family presence ring (who is home, ambient) #5

Description

@Ryan4n6

Idea

The four corners of the matrix dim/glow per family member based on whether their phone is on the home network. Glance at the wall, you know who's home — no app, no notification, no GPS. Wordless ambient awareness.

How it works

  • Source of truth is the home router: when a known device's MAC has an active DHCP lease (or recent ARP entry), that person is "present."
  • Clockwise polls the router (UniFi controller API, or whatever's running) every ~60s for the watched MAC list.
  • Per-person config: name, MAC list (a person may have phone + watch + iPad), corner assignment (TL/TR/BL/BR), color.
  • Render: 4×4-pixel rounded square in each assigned corner, full brightness when present, dim+desaturated when away. Optional 1-pixel name initial inside.

Privacy story

  • No GPS, no location services, no third-party tracking.
  • All polling is LAN-local; no data leaves the house.
  • Watched MACs configured by the device owner.

Architecture sketch

  • New firmware/lib/cw-presence/ module: pluggable backend (UniFi REST, generic ARP-via-router-SSH, OPNsense, etc.) returning {mac → bool present}.
  • Settings UI: per-corner person editor (name, color, list of MACs).
  • Composable with any clockface: presence ring renders as an overlay on the existing face, not a face of its own. (Implementation note: most current clockfaces don't expose an overlay slot — may need to add IClockface::renderOverlay() as an optional virtual.)

Constraints

  • Requires router cooperation. UniFi has a clean API; consumer routers vary. Initial scope: UniFi only, document the backend interface so others can add OPNsense/pfSense/etc.
  • MAC randomization: iOS/Android randomize per-SSID by default. The watched MACs are the home-SSID-specific ones, which are stable. Document this so users know which MAC to grab.

Acceptance

  • UniFi backend reads device-presence list given controller URL + API key.
  • Up to 4 people configurable from the web UI.
  • Corners glow/dim within ~60s of presence change.
  • No noticeable impact on clock-face animation framerate.
  • Failed router poll → corners freeze last-known state, don't all go dark.

Out of scope

  • Geofencing / leaving-the-neighborhood alerts.
  • Per-person history / who-arrived-when log.
  • Multi-network presence (work network, etc.).

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions