From 0d6465dad0e706fc22cb8d629d2c13172a2c98fb Mon Sep 17 00:00:00 2001 From: Ryan Malloy Date: Mon, 11 May 2026 14:51:19 -0600 Subject: [PATCH] docs: cross-reference manuals from SecurityMode, ZoneType, events, commands Sprinkle pca-re/docs/manuals/ citations into the four files that map hardest to user-visible panel behavior, so a reader chasing "why is this byte 0x03 here" lands on the right manual chapter directly from the source. models.SecurityMode Per-value comments summarising what each arming mode means at the keypad (entry/exit delays, which zones it arms, when to use it). Points at the Owner's Manual SECURITY_SYSTEM_OPERATION chapter where these semantics are spelled out for end users. models.ZoneType Class docstring now points at the Installation Manual SETUP ZONES table where each numeric byte value is named -- the byte values and short names we chose match that table one-for-one, so a reader can cross-walk the v1 ZoneStatus byte to "PERIMETER" / "AWAY INT" / etc. by row. events.py Module docstring adds Cross-references to APPENDIX A (Contact ID reporting format) and APPENDIX B (digital communicator code sheet) in the Installation Manual -- the central-station codes a panel transmits for each AlarmKind correspond directly to those tables. commands.py Module docstring points at the Owner's Manual CONTROL, Scene Commands, and SECURITY SYSTEM OPERATION chapters so the reader can tie each enuUnitCommand byte to the user-facing keypad path that triggers it. No code changes; all 387 tests still pass. --- src/omni_pca/commands.py | 13 +++++++++++++ src/omni_pca/events.py | 10 ++++++++++ src/omni_pca/models.py | 34 ++++++++++++++++++++++++---------- 3 files changed, 47 insertions(+), 10 deletions(-) diff --git a/src/omni_pca/commands.py b/src/omni_pca/commands.py index 282ec21..d03e063 100644 --- a/src/omni_pca/commands.py +++ b/src/omni_pca/commands.py @@ -39,6 +39,19 @@ The reply (ExecuteSecurityCommandResponse, opcode 75) carries a single status byte at ``payload[0]`` whose values are listed in ``enuSecurityCommnadResponse.cs`` — :class:`SecurityCommandResponse` mirrors that enum. + +Cross-references (HAI OmniPro II Owner's Manual): + Chapter "CONTROL" (pca-re/docs/owner_manual/05_CONTROL/) documents + the user-facing keypad keys that map to these commands — + e.g. UNIT_ON/OFF + UNIT_LEVEL are what a homeowner triggers via + the "Control → 1 (Unit)" menu, SHOW_MESSAGE_WITH_BEEP is + invoked from "Control → Message → Show". + Chapter "Scene Commands" (06_Scene_Commands/) covers + COMPOSE_SCENE and the per-room scene-recall path. + Chapter "SECURITY SYSTEM OPERATION" (03_SECURITY_SYSTEM_OPERATION/) + documents what each SecurityMode byte (0-6) means at the user + level — the arming menu, entry/exit-delay semantics, and which + zones each mode arms. """ from __future__ import annotations diff --git a/src/omni_pca/events.py b/src/omni_pca/events.py index 34defc3..73daa54 100644 --- a/src/omni_pca/events.py +++ b/src/omni_pca/events.py @@ -29,6 +29,16 @@ References (decompiled C# source): — bit-mask classifier we mirror below clsText.cs:1693-1911 (GetEventText) — per-category sub-field extraction + +Cross-references (HAI OmniPro II Installation Manual): + APPENDIX A — CONTACT ID REPORTING FORMAT (p68): the Contact ID + event codes the panel transmits to a central monitoring station + for each :class:`AlarmKind`. The class names below mirror those + codes one-for-one. (pca-re/docs/manuals/installation_manual/ + 10_APPENDIX_A_CONTACT_ID_REPORTING_FORMAT/) + APPENDIX B — DIGITAL COMMUNICATOR CODE SHEET (p69-73): the 4/2 and + 3/1 reporting-format code tables. Useful when correlating a + SystemEvents word with what a central station would see. (12_…) """ from __future__ import annotations diff --git a/src/omni_pca/models.py b/src/omni_pca/models.py index 7c4c509..4172eaf 100644 --- a/src/omni_pca/models.py +++ b/src/omni_pca/models.py @@ -490,18 +490,25 @@ class ObjectType(IntEnum): class SecurityMode(IntEnum): """Area security mode (enuSecurityMode.cs). - Values 9..14 are the "arming in progress" variants the panel reports - while a delayed-arm timer is running. + The first 7 values are what the user actually picks at the keypad + when arming. Values 9..14 are the "arming in progress" variants the + panel reports while a delayed-arm timer is running. + + Reference: HAI OmniPro II Owner's Manual, *Security System + Operation* chapter (pca-re/docs/owner_manual/ + 03_SECURITY_SYSTEM_OPERATION/) — the user-facing semantics of each + mode (entry/exit delays, which zones are armed, when to use which) + come from there. """ - OFF = 0 - DAY = 1 - NIGHT = 2 - AWAY = 3 - VACATION = 4 - DAY_INSTANT = 5 - NIGHT_DELAYED = 6 - ANY_CHANGE = 7 + OFF = 0 # disarmed; resets fire / emergency alarms, silences sirens + DAY = 1 # perimeter armed, interior motion NOT armed, entry delay + NIGHT = 2 # perimeter + non-sleeping-area motion armed, NO entry delay + AWAY = 3 # everything armed, both exit + entry delays + VACATION = 4 # same as AWAY but for multi-day absences + DAY_INSTANT = 5 # DAY with no entry delay (instant alarm on perimeter) + NIGHT_DELAYED = 6 # NIGHT with entry delay on entry-exit zones + ANY_CHANGE = 7 # programming-condition wildcard, NOT a real arming state ARMING_DAY = 9 ARMING_NIGHT = 10 ARMING_AWAY = 11 @@ -560,6 +567,13 @@ class ZoneType(IntEnum): the temperature/humidity sensors and a handful of utility types. Any raw byte value still round-trips through ``ZoneStatus.zone_type`` — it just won't have a named enum member. + + Reference: HAI OmniPro II Installation Manual, *Installer Setup → + SETUP ZONES → ZONE TYPES* table (pca-re/docs/manuals/ + installation_manual/04_INSTALLER_SETUP/INSTALLER_SETUP.md, p38-39). + The byte values and short names here match the installer-setup + keypad selections one-for-one (e.g. ``PERIMETER = 1`` is the same + "PERIMETER" the installer scrolls to when setting Z1..Z176 types). """ ENTRY_EXIT = 0