Occupancy Logic

Last modified by Mark Kohlmann on 2026/05/26 21:36

Occupancy Logic Flow

1. Scene Recall Logic Diagram

flowchart TD
A[Occupancy State change] --> B{Mode: Occupancy or Vacancy}
B -->|No| N1
D -->|No| N1[No scene recall]
B -->|Yes| B2{Occupied?}
C2 -->|Yes| C{Mode: Occupancy &
Occupied Scene set or 
at Intermediate Vacancy Scene}
C -->|No| D{Grace Occupancy
within Threshold}
C -->|Yes| S1[Recall Occupied Scene]

D -->|Yes| E{Grace Occupancy Scene Set}
E -->|No| S1
E -->|Yes| S2[Recall Grace Scene]

B2 -->|No| H{"Extended timeout > 0"}
B2 -->|Yes| C2["Clear Extended Timer
(if active)"]

H -->|No| G 
H -->|Yes| T1[Run Extended Timeout Timer
Stage 1 Occupied State]

T1 --> F{Intermediate Vacant Scene Set}
F -->|No| T2[Wait timer expiry]
F -->|Yes| S4[Recall Intermediate Vacant Scene]
S4 --> T2

T2 --> G{Vacant Scene Set}
G -->|No| N1
G -->|Yes| S5[Recall Vacant Scene]

classDef scnOcc fill:#1E88E5,stroke:#0D47A1,color:#ffffff,stroke-width:2px
classDef scnGrace fill:#8E24AA,stroke:#4A148C,color:#ffffff,stroke-width:2px
classDef scnInt fill:#FB8C00,stroke:#E65100,color:#ffffff,stroke-width:2px
classDef scnVac fill:#E53935,stroke:#B71C1C,color:#ffffff,stroke-width:2px

class S1 scnOcc
class S2 scnGrace
class S4 scnInt
class S5 scnVac

classDef stOcc fill:#43A047,stroke:#1B5E20,color:#ffffff,stroke-width:2px
classDef stStage fill:#FDD835,stroke:#F57F17,color:#000000,stroke-width:2px
classDef stVac fill:#546E7A,stroke:#263238,color:#ffffff,stroke-width:2px

class O1 stOcc
class O2 stStage
class O3 stVac

2. “What Happens When” Sequence

sequenceDiagram
participant S as Sensor
participant L as Occupancy Logic
participant A as Area
participant C as Scene Recall

S->>L: occupied true
L->>A: state occupied
A->>C: recall occupied scene

S->>L: occupied false after timeout
L->>A: state stage1 or stage2
A->>C: recall intermediate vacant scene if configured

L->>A: state vacant
A->>C: recall vacant scene

S->>L: occupied true within grace window
L->>A: state occupied by grace path
A->>C: recall grace scene or occupied scene

3. Mode Behavior Matrix

Mode	Occupied transition	Vacant transition	Notes
Occupancy	Recalls Occupied Scene	No Extended Occupancy Timeout: Recalls Vacant Scene Extended Occupancy Timeout: Recalls Intermediate Vacant Scene / Starts Extended Timer	Standard auto-on and auto-off behavior. Can be augmented with Intermediate Scene. Supports Staged timeout
Occupancy-Ext	Extended Occupancy Timeout [Stage1] Recalls Intermediate Vacancy Scene [If configured]	Recalls Vacant Scene	Extends the hardware timeout of the sensors
Vacancy	Grace path can still recall scene if configured and within window	Recalls Vacant Scene	Often used to reduce auto-on behavior
Disabled	No occupancy-driven recall	No occupancy-driven recall	Manual control only
Use Hardware Logic	Controller-driven	Controller-driven	ShowRunner defers to supported hardware logic and its configured behavior

4. Settings That Most Affect User Experience

Setting	Notes	If too low / disabled	If too high / enabled
Evaluate Occupancy at Mode Change	Forces the Area to recalculate its occupancy state when the Occupancy Mode is changed.	The area state stays the same regardless of current occupied state	The area scenes will recall based on the current occupied state
Extended Occupancy Timeout	Extends the timeout for the area once the hardware occupancy sensors are showing vacant. Allows for an intermediate vacancy scene.	Room may go vacant too quickly	Room may stay “occupied” too long
Grace Occupancy Period	Turns the lights back on if an area is in vacancy mode and the room is re-occupied within a certain timeout.	Re-entry may not restore scene	Re-entry may restore scene longer than desired
Occupancy Scene	Scene recalled when the area goes occupied	Lights aren't bright enough for use	N/A if scene choice is appropriate
Intermediate Vacant Scene	Scene recalled when the area hardware sensors no longer detect occupancy	No warning/step-down feel	N/A if scene choice is appropriate
Vacant Scene	Scene recalled when the area is no longer occupied	Lights may not turn off as expected	N/A, depends on desired policy

5. Commissioning Test Script

Walk in and confirm Occupied Scene is recalled if configured for Occupancy or no change if configured for Vacancy
Leave and wait for sensor timeout.
Confirm Intermediate scene behavior if configured.
Confirm Vacant Scene recall at final vacancy.
Re-enter during grace window and confirm Grace or Occupied scene recall.
Change Occupancy Mode and verify immediate behavior if Evaluate At Mode Change is enabled.