Wiki source code of Occupancy Logic

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

version	line-number	content
1.1	1	= Occupancy Logic Flow =
	2
1.21	3	== 1. Scene Recall Logic Diagram ==
1.1	4
	5	{{mermaid}}
	6	flowchart TD
1.25	7	A[Occupancy State change] --> B{Mode: Occupancy or Vacancy}
	8	B -->\|No\| N1
1.28	9	D -->\|No\| N1[No scene recall]
1.25	10	B -->\|Yes\| B2{Occupied?}
1.22	11	C2 -->\|Yes\| C{Mode: Occupancy &
1.33	12	Occupied Scene set or
	13	at Intermediate Vacancy Scene}
1.34	14	C -->\|No\| D{Grace Occupancy
1.5	15	within Threshold}
1.30	16	C -->\|Yes\| S1[Recall Occupied Scene]
1.1	17
1.6	18	D -->\|Yes\| E{Grace Occupancy Scene Set}
1.29	19	E -->\|No\| S1
1.1	20	E -->\|Yes\| S2[Recall Grace Scene]
	21
1.26	22	B2 -->\|No\| H{"Extended timeout > 0"}
1.31	23	B2 -->\|Yes\| C2["Clear Extended Timer
	24	(if active)"]
1.30	25
	26	H -->\|No\| G
1.22	27	H -->\|Yes\| T1[Run Extended Timeout Timer
1.8	28	Stage 1 Occupied State]
1.1	29
1.8	30	T1 --> F{Intermediate Vacant Scene Set}
1.29	31	F -->\|No\| T2[Wait timer expiry]
1.1	32	F -->\|Yes\| S4[Recall Intermediate Vacant Scene]
	33	S4 --> T2
	34
1.34	35	T2 --> G{Vacant Scene Set}
1.29	36	G -->\|No\| N1
1.1	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.