Reset Logic

How the Occupancy Data Engine corrects count drift using inactivity-based and manual resets

Why Resets Are Needed

Entryway sensors are not 100% accurate. Occasionally they miss an entry or exit — for example, when two people walk through a doorway simultaneously. These small errors accumulate over time:

  • Day 1: Misses 1 exit → shows 1 person at night when room is empty
  • Day 2: All counts are off by 1, misses another exit → shows 2 people at night
  • Day 3: Drift continues growing

Resets correct this drift by setting the count back to zero when the engine determines the space is empty.

Reset Types

The Occupancy Data Engine supports two reset mechanisms:

TypeHow it worksConfiguration
Inactivity resetAutomatic reset when no sensor activity is detected for a configurable periodInactivity period in hours, per device group
Manual resetAPI-triggered reset on demandNo configuration — call the API when needed

Inactivity Reset

The inactivity reset triggers automatically when all sensors in a device group have been inactive for the configured period. The exact trigger conditions depend on the sensor composition of the group.

Entryway Only Groups

Reset triggers when all Entryway sensors have been inactive for the configured inactivity period.

Effect: Sets occupantsCount to 0.

Example: A device group with two Entryway sensors and a 10-hour inactivity period. If neither sensor reports any entry or exit for 10 hours (e.g., overnight), the count resets to zero.

Presence Only Groups

Inactivity resets are not triggered. Presence-only groups are naturally self-correcting — when all sensors report not occupied, the group status updates automatically without needing a reset.

Mixed Groups (Entryway + Presence)

Reset triggers when all of these conditions are met:

  • All Presence sensors currently report not occupied
  • All Presence sensors report movementDetections = 0
  • No activity from any sensor for the configured inactivity period

Effect: Sets occupantsCount to 0 and occupancyStatus to not occupied.

Choosing an Inactivity Period

The inactivity period is configured per device group and should match how the space is used. Setting it too short causes false resets during quiet periods (e.g., a long meeting with no doorway traffic). Setting it too long allows count drift to accumulate before correction.

Space typeSuggested periodRationale
Meeting room2–4 hoursEmpties frequently, short gaps between meetings
Open office zone4–8 hoursMay have quiet periods during the day
Floor8–12 hoursActivity varies across zones; avoid resetting during temporary lulls
Building entrance10–14 hoursOnly truly empty overnight; short periods cause false resets during low-traffic hours

Manual Reset

A manual reset can be triggered through the API for any device group at any time. It has the same effect as an inactivity reset:

  • Sets occupantsCount to 0
  • Sets occupancyStatus to not occupied (if not already)

Manual resets are useful for:

  • Correcting a known incorrect count immediately
  • Resetting after maintenance or testing
  • Spaces with unusual schedules where inactivity reset timing doesn’t fit

Reset Behavior Details

Resets Only Affect the Device Group

A reset writes only to the device group’s own measurements. It does not modify any individual sensor’s data — neither per-device is_occupied nor per-device movementDetections are changed. Individual sensor values are managed by the platform’s device connector and self-correct naturally when sensors report new data.

No Duplicate Resets

The engine avoids unnecessary reset operations:

  • If a group is already showing not occupied, a reset does not publish a duplicate status
  • If there has been no activity since the last reset, a duplicate inactivity reset is not triggered
  • New device groups with no activity history wait for the first sensor event before any reset logic applies

Next Steps