37 lines
1.6 KiB
Markdown
37 lines
1.6 KiB
Markdown
# presence
|
|
|
|
## Purpose
|
|
|
|
Tracks whether household members are home by ICMP-pinging their phones on the LAN at a fixed interval. Derives an overall household state (EMPTY, OCCUPIED, etc.) from per-member presence and publishes both to MQTT so the rule engine and arm-state FSM can react.
|
|
|
|
## Key files
|
|
|
|
- `vigilar/presence/monitor.py` — `PresenceMonitor`: ping loop, per-member state machine with `departure_delay_m` grace period, publishes per-member and household-level topics
|
|
- `vigilar/presence/models.py` — `MemberPresence` dataclass and `derive_household_state` aggregator
|
|
- `vigilar/presence/__init__.py`
|
|
|
|
## MQTT topics
|
|
|
|
**Subscribes:** none
|
|
**Publishes:**
|
|
- `vigilar/presence/{name}` — per-member status (`HOME` or `AWAY`, plus role)
|
|
- `vigilar/presence/status` — aggregated household state and a `{name: HOME|AWAY}` map
|
|
|
|
## Database tables
|
|
|
|
none — presence state lives only in memory and on the bus.
|
|
|
|
## Depends on
|
|
|
|
- LAN reachability of configured `[presence.members]` IPs
|
|
- `ping` binary on the host
|
|
|
|
## Consumed by
|
|
|
|
- `events` — rules and the arm-state FSM react to household state changes
|
|
- `alerts` — smart alert profile matcher in `vigilar/alerts/profiles.py` branches on `HouseholdState`
|
|
|
|
## Notes
|
|
|
|
A member is marked HOME the moment a ping succeeds, but only marked AWAY after `departure_delay_m` minutes without a successful ping — this prevents a single dropped reply from flipping the household state. The monitor uses `time.monotonic()` for the grace window, so it is immune to wall-clock jumps. Per-member and household topics are republished every poll, not only on transitions, so late subscribers always get current state.
|