Sensor Composition

Overview

The behavior of a device group depends on which sensor types it contains. The Occupancy Data Engine recognizes three composition scenarios, each with its own occupancy logic and reset behavior.

Choose the composition that matches your space and sensors:

Entryway Only

A device group with one or more Entryway sensors and no Presence sensors.

Occupancy logic:

• occupantsCount is the sum of all Entryway sensors’ entries minus exits
• occupancyStatus is occupied when occupantsCount > 0

Inactivity reset: Triggered when all Entryway sensors have been inactive for the configured inactivity period. Resets occupantsCount to 0.

Manual reset: Supported. Same effect as inactivity reset.

Example: A meeting room with two doors, each with an Entryway sensor.

Meeting Room (Device Group)
├── Entryway sensor (Door 1) — tracks entries and exits
└── Entryway sensor (Door 2) — tracks entries and exits
→ Output: occupantsCount = sum of all entries - sum of all exits

Presence Only

A device group with one or more Presence sensors and no Entryway sensors.

Occupancy logic:

• occupancyStatus is occupied if any Presence sensor reports occupied or reports movementDetections > 0
• occupancyStatus is not occupied if all Presence sensors report not occupied and movementDetections = 0

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

Manual reset: Supported. Sets occupancyStatus to not occupied and occupantsCount to 0.

Example: A large open office area covered by multiple PIR sensors.

Open Office Area (Device Group)
├── Presence sensor (Zone A) — detects motion/presence
└── Presence sensor (Zone B) — detects motion/presence
→ Output: occupied if either zone detects presence

Mixed (Entryway + Presence)

A device group containing both Entryway and Presence sensors. This provides the most accurate occupancy data by combining counting with presence verification.

Occupancy logic:

• occupancyStatus is occupied if any Presence sensor reports occupied or movementDetections > 0 or occupantsCount > 0
• occupancyStatus is not occupied if all Presence sensors report not occupied and movementDetections = 0 and occupantsCount ≤ 0

Inactivity reset: Triggered when all Presence sensors report not occupied and movementDetections = 0 and no activity from any sensor for the configured inactivity period. Resets occupantsCount to 0 and occupancyStatus to not occupied.

Manual reset: Supported. Same effect as inactivity reset.

Example: A conference room with doorway counting and interior presence detection.

Conference Room (Device Group)
├── Entryway sensor (Main door) — counts entries/exits
├── Presence sensor (Area 1)    — detects presence
└── Presence sensor (Area 2)    — detects presence
→ Output: occupantsCount from entryway + occupancyStatus validated by presence

Choosing the Right Composition

%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#F6FAFA', 'primaryTextColor': '#143633', 'primaryBorderColor': '#143633', 'lineColor': '#143633', 'secondaryColor': '#C7FDE6', 'tertiaryColor': '#73F9C1', 'clusterBkg': '#ffffff', 'clusterBorder': '#143633', 'edgeLabelBackground': '#ffffff'}}}%%
flowchart TB
    Q1["Do you need to know<br/>how many people?"]
    Q2["Does the space have<br/>defined entry points?"]
    Q3["Do you also want presence<br/>verification for accuracy?"]
    R1["Presence Only"]
    R2["Entryway Only"]
    R3["Mixed"]

    Q1 -->|"No — just occupied<br/>or not"| R1
    Q1 -->|Yes| Q2
    Q2 -->|Yes| Q3
    Q2 -->|"No — open area"| R1
    Q3 -->|"No — count is enough"| R2
    Q3 -->|Yes| R3

    style R1 fill:#C7FDE6,stroke:#143633,color:#143633
    style R2 fill:#C7FDE6,stroke:#143633,color:#143633
    style R3 fill:#C7FDE6,stroke:#143633,color:#143633

Signal Freshness

Presence sensors can report both is_occupied and movementDetections. When evaluating a sensor’s state, the Occupancy Data Engine uses the more recent of the two signals (by timestamp). This prevents a stale value from a previous reporting mode from keeping a group occupied indefinitely.

When a new measurement arrives, the triggering sensor is trusted directly. Other sensors in the group are evaluated from their most recent stored signal.

Negative People Counts

Entryway sensors can occasionally produce negative counts (more exits than entries detected). The Occupancy Data Engine preserves these values for transparency but treats them the same as zero when determining occupancy status.

No Redundant Publications

The Occupancy Data Engine avoids publishing duplicate state:

• Identical repeated occupancy evaluations (occupied → occupied or not occupied → not occupied) are not published
• A reset does not send a duplicate not occupied status if the group is already not occupied
• Duplicate inactivity resets are not triggered if there has been no activity since the last reset
• New device groups with no activity history wait for the first sensor event before producing any output

Changing Composition

When you add or remove sensors from a device group, the behavior changes dynamically based on the new composition. Any temporarily outdated occupancy values self-correct — groups with Entryway sensors correct at the next reset, groups with Presence sensors correct when sensors report new data.

Next Steps

• Occupancy Data Engine — How the engine processes sensor data and produces output measurements
• Reset Logic — How inactivity and manual resets work