Presence Detection

Last updated: April 11, 2026

UniFi Presence Detection

The unifi package provides a localized presence detection system by monitoring active MAC addresses on the local network.

The Mechanism

Rather than relying on GPS or app-based tracking, the system uses network-level telemetry to determine if a user is physically at home or in the office.

1. Polling

The system polls the UniFi OS API periodically to retrieve a list of all currently connected clients (both Wi-Fi and wired).

2. MAC Address Matching

The retrieved list is checked against a configuration of known MAC addresses corresponding to user devices (e.g., smartphones).

3. State Transition & Debouncing

To handle transient Wi-Fi drops (e.g., a phone going to sleep), the system employs a debounce mechanism.

  • A device must be unseen for several consecutive polling cycles before it is marked as "Away".
  • When a device reappears, it triggers a state transition to "Home".

Wakeup Trigger Integration

When a user transitions to the "Home" state, the unifi package sends an HTTP POST request to the assistant module's Wakeup API (/api/wakeup).

This triggers a "Welcome Home" routine:

  1. The assistant wakes up the user's preferred agent.
  2. The agent reviews recent missed notifications, summarized emails, or pending tasks.
  3. The agent sends a proactive welcome message via WhatsApp or smart speakers.

Mermaid Diagram: Presence Flow

graph TD
    U[UniFi Controller] --> Poll[unifi.go Poller]
    Poll --> List[Active MAC Addresses]
    List --> Check{Match User Device?}
    
    Check -- Yes --> Trans{State Transition?}
    Trans -- Away -> Home --> API[POST /api/wakeup]
    
    API --> Ass[assistant/wakeup.go]
    Ass --> Agent[Trigger Welcome Routine]

Guidance for AI Agents

  • Proactive Assistance: If a user has just triggered a "Welcome Home" event, prioritize summarizing information they missed while they were away.
  • Network Health: The UniFi module also provides network health scores. If a user complains about slow internet, you can query this module to check AP loads and interference.

Cross-References