Skip to Content

Wiki source code of Occupancy Logic

Last modified by Mark Kohlmann on 2026/05/26 21:36
Show last authors
1 = Occupancy Logic Flow =
2
3 == 1. Scene Recall Logic Diagram ==
4
5 {{mermaid}}
6 flowchart TD
7 A[Occupancy State change] --> B{Mode: Occupancy or Vacancy}
8 B -->|No| N1
9 D -->|No| N1[No scene recall]
10 B -->|Yes| B2{Occupied?}
11 C2 -->|Yes| C{Mode: Occupancy &
12 Occupied Scene set or
13 at Intermediate Vacancy Scene}
14 C -->|No| D{Grace Occupancy
15 within Threshold}
16 C -->|Yes| S1[Recall Occupied Scene]
17
18 D -->|Yes| E{Grace Occupancy Scene Set}
19 E -->|No| S1
20 E -->|Yes| S2[Recall Grace Scene]
21
22 B2 -->|No| H{"Extended timeout > 0"}
23 B2 -->|Yes| C2["Clear Extended Timer
24 (if active)"]
25
26 H -->|No| G
27 H -->|Yes| T1[Run Extended Timeout Timer
28 Stage 1 Occupied State]
29
30 T1 --> F{Intermediate Vacant Scene Set}
31 F -->|No| T2[Wait timer expiry]
32 F -->|Yes| S4[Recall Intermediate Vacant Scene]
33 S4 --> T2
34
35 T2 --> G{Vacant Scene Set}
36 G -->|No| N1
37 G -->|Yes| S5[Recall Vacant Scene]
38
39 classDef scnOcc fill:#1E88E5,stroke:#0D47A1,color:#ffffff,stroke-width:2px
40 classDef scnGrace fill:#8E24AA,stroke:#4A148C,color:#ffffff,stroke-width:2px
41 classDef scnInt fill:#FB8C00,stroke:#E65100,color:#ffffff,stroke-width:2px
42 classDef scnVac fill:#E53935,stroke:#B71C1C,color:#ffffff,stroke-width:2px
43
44 class S1 scnOcc
45 class S2 scnGrace
46 class S4 scnInt
47 class S5 scnVac
48
49 classDef stOcc fill:#43A047,stroke:#1B5E20,color:#ffffff,stroke-width:2px
50 classDef stStage fill:#FDD835,stroke:#F57F17,color:#000000,stroke-width:2px
51 classDef stVac fill:#546E7A,stroke:#263238,color:#ffffff,stroke-width:2px
52
53 class O1 stOcc
54 class O2 stStage
55 class O3 stVac
56 {{/mermaid}}
57
58 == 2. “What Happens When” Sequence ==
59
60 {{mermaid}}
61 sequenceDiagram
62 participant S as Sensor
63 participant L as Occupancy Logic
64 participant A as Area
65 participant C as Scene Recall
66
67 S->>L: occupied true
68 L->>A: state occupied
69 A->>C: recall occupied scene
70
71 S->>L: occupied false after timeout
72 L->>A: state stage1 or stage2
73 A->>C: recall intermediate vacant scene if configured
74
75 L->>A: state vacant
76 A->>C: recall vacant scene
77
78 S->>L: occupied true within grace window
79 L->>A: state occupied by grace path
80 A->>C: recall grace scene or occupied scene
81
82 {{/mermaid}}
83
84 == 3. Mode Behavior Matrix ==
85
86 |= Mode |= Occupied transition |= Vacant transition |= Notes
87 | Occupancy | Recalls Occupied Scene |(((
88 No Extended Occupancy Timeout: Recalls Vacant Scene
89
90 Extended Occupancy Timeout: Recalls Intermediate Vacant Scene / Starts Extended Timer
91 )))| Standard auto-on and auto-off behavior. Can be augmented with Intermediate Scene.  Supports Staged timeout
92 | Occupancy-Ext|(((
93 Extended Occupancy Timeout [Stage1]
94
95 Recalls Intermediate Vacancy Scene [If configured]
96 )))| Recalls Vacant Scene| Extends the hardware timeout of the sensors
97 | Vacancy | Grace path can still recall scene if configured and within window | Recalls Vacant Scene | Often used to reduce auto-on behavior
98 | Disabled | No occupancy-driven recall | No occupancy-driven recall | Manual control only
99 | Use Hardware Logic | Controller-driven | Controller-driven | ShowRunner defers to supported hardware logic and its configured behavior
100
101 == 4. Settings That Most Affect User Experience ==
102
103 |= Setting |=Notes|= If too low / disabled|= If too high / enabled
104 | 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
105 | 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
106 | 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
107 | Occupancy Scene |Scene recalled when the area goes occupied| Lights aren't bright enough for use | N/A if scene choice is appropriate
108 | 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
109 | Vacant Scene |Scene recalled when the area is no longer occupied| Lights may not turn off as expected | N/A, depends on desired policy
110
111 == 5. Commissioning Test Script ==
112
113 1. Walk in and confirm Occupied Scene is recalled if configured for Occupancy or no change if configured for Vacancy
114 1. Leave and wait for sensor timeout.
115 1. Confirm Intermediate scene behavior if configured.
116 1. Confirm Vacant Scene recall at final vacancy.
117 1. Re-enter during grace window and confirm Grace or Occupied scene recall.
118 1. Change Occupancy Mode and verify immediate behavior if Evaluate At Mode Change is enabled.