- manifest.json: keys reordered to domain, name, then alphabetical
- strings.json + translations/en.json: rephrase user-step description
without backticks/angle-brackets (hassfest rejects HTML in i18n strings)
- __init__.py: add CONFIG_SCHEMA = cv.config_entry_only_config_schema(DOMAIN)
since async_setup exists but the integration is config-entry-only
StateEvaluator decodes AND/OR records against MockState. ProgramEngine
.use_state_evaluator() installs one bound to the engine's panel + clock
+ location. Replaces the stub that always-passes-AND-always-fails-OR.
Traditional (OP=0) decode follows clsConditionLine.Cond synthesis
(clsConditionLine.cs:17-33): disk byte 1 (= and_family) carries the
compact GetConditionalText family byte, disk bytes 3-4 (and_instance
from cond2>>8) carry the object index. Family decoding mirrors
clsText.GetConditionalText (clsText.cs:2224-2274):
family & 0xFC == 0x00 → OTHER (low 4 bits = MiscConditional)
family & 0xFC == 0x04 → ZONE (bit 0x02 = NOT_READY, else SECURE)
family & 0xFC == 0x08 → CTRL (bit 0x02 = ON, else OFF)
family & 0xFC == 0x0C → TIME (no MockState model → False)
family >= 0x10 → SEC (high nibble = mode, low = area)
Structured (OP > 0) decode uses Arg1 OP Arg2 with both sides resolved
via _resolve_arg(argtype, ix, field). MockState-backed resolution:
ZONE → loop / current_state / arming_state / latched_state
UNIT → on/off byte / time_remaining / dim level
THERMOSTAT → temp / setpoints / modes / humidity
AREA → mode
TIME_DATE → (clock-derived) year / month / day / DoW / hour /
minute / time-of-day-in-minutes
CondOP supported: EQ / NE / LT / GT / ODD / EVEN / MULTIPLE / IN /
NOT_IN. Unknown argtypes or fields raise _UnsupportedCondition
internally — the evaluator swallows it and returns False, keeping the
chain *guarded* rather than firing too eagerly.
LIGHT/DARK MiscConditional uses astral via the engine's PanelLocation
when set. When location is missing, returns False either way (don't
fire if we can't determine).
15 new tests covering each evaluator branch (Traditional ZONE secure/
not-ready/undefined, CTRL on/off/dimmed, SEC mode-match, OTHER NEVER/
DARK; Structured Zone.CurrentState EQ/NE, Thermostat.Temp GT/LT,
TimeDate.Hour/DOW EQ, TimeDate-without-clock) plus end-to-end engine
integration showing use_state_evaluator() gates a real WHEN+AND chain
and the OR-alternative path works against real state.
Full suite: 581 passed, 1 skipped (up from 563, 82 engine tests total).
Final phase of the autonomous program-execution engine. Multi-record
clausal programs (firmware ≥3.0.0) now run end-to-end:
* WHEN-headed chains dispatch through emit_event() — same code path as
raw EVENT programs, but with optional AND/OR condition guards.
* AT-headed chains schedule like TIMED (absolute or sun-relative).
* EVERY-headed chains fire on a recurring interval (every_interval
seconds — the unit derivation matches the existing programs.py
decode).
New types:
* ClausalChain dataclass — (head, conditions, actions). Built once at
engine construction; engine.chains exposes the list.
* build_chains(programs) walks a slot-ordered Program tuple,
grouping adjacent multi-record records into chains. Stops at the
next clausal head, a non-clausal record, or an empty slot. Drops
chains with no THEN action (they have no effect).
* evaluate_conditions(cs, is_satisfied=fn) — AND-of-OR-groups
evaluator. Empty conditions tuple is True; OR records start a new
group; within a group all ANDs must satisfy; overall True iff any
group satisfies. The detailed semantic decode of each AND/OR record
(zone-state checks, structured TEMP>70-style ops, …) is deferred
to a follow-up — for now ``is_satisfied`` is the integration hook
callers supply.
ProgramEngine.set_condition_evaluator(fn) lets tests / HA plug in a
state-aware evaluator. The default is a stub that passes ANDs and
fails ORs — a usable smoke-test default, deliberately not a real one.
14 new tests covering chain construction (single chain, with conditions,
with multiple THENs, adjacent chains, missing-THEN drop, non-clausal
boundary), the condition evaluator (empty/all-AND/AND-fail/OR-group
separation), and end-to-end execution (WHEN chain dispatch, condition
blocking, custom evaluator, AT chain schedule, EVERY chain interval).
With this the engine implements every program type the panel firmware
exposes — TIMED / EVENT / YEARLY compact-form plus WHEN / AT / EVERY +
AND / OR / THEN clausal. MockPanel + ProgramEngine + .pca decode +
MockState.from_pca composes into a complete "run any panel's programs
autonomously" sandbox.
Full suite: 563 passed, 1 skipped (up from 549, 64 engine tests total).
EVENT programs (ProgType=2) now fire in response to panel events.
Unlike TIMED/YEARLY there's no per-program asyncio worker — EVENT
programs sit in an {event_id → [Program]} dispatch table built at
engine.start(). External code calls engine.emit_event(id) to dispatch.
Event-ID encoding mirrors clsText.GetEventCategory (clsText.cs:1585-...).
The 16-bit ID's high bits select a category; low bits encode the
specific object number / state. Phase 4 ships helpers for the three
practically-common categories plus the hand-rolled fixed-ID events:
event_id_user_macro_button(b) — 0x0000..0x00FF
event_id_zone_state(z, st) — 0x0400 | (((z-1)*4 + st) & 0x3FF)
event_id_unit_state(u, on) — 0x0800 | (((u-1)*2 + on) & 0x3FF)
EVENT_PHONE_DEAD / _RINGING / _OFF_HOOK / _ON_HOOK = 768..771
EVENT_AC_POWER_OFF / _ON = 772 / 773
emit_event(id) returns the count of programs that fired; convenience
methods emit_user_macro_button / emit_zone_state / emit_unit_state
wrap the encoders. emit_event before start() is a no-op (no event
table built); after stop() the table clears, so another start()
rebuilds from the current panel.state.programs.
13 new tests covering the helpers' bit layouts, range checks, single-
program dispatch, no-match silent no-op, before-start no-op, multiple
programs on the same event, zone-state state-filtering, and a smoke
test against AC_POWER_OFF as a sample fixed-ID event.
Full suite: 549 passed, 1 skipped (up from 539).
YEARLY programs (month/day match at hour:minute, regardless of weekday)
now fire autonomously. Each YEARLY slot gets its own asyncio worker
running sleep-until-next-fire / fire / loop, just like TIMED.
Sunrise/sunset support lands in the same phase. New PanelLocation
dataclass wraps a geographic position; PanelLocation.from_account(acct)
builds one from the .pca's latitude/longitude/time_zone, flipping the
longitude sign to match astral's east-positive convention.
The engine's __init__ accepts an optional location=PanelLocation.
TIMED programs whose hour byte hits the AT_SUNRISE (25) or AT_SUNSET
(26) sentinels resolve against astral's computed sunrise/sunset on
each candidate day, applying the program's signed minute offset
(time_offset_minutes). Without a location supplied, sun-relative
programs are silently skipped — the same effect as an empty Days mask.
_next_yearly_fire validates the (month, day) combination — Feb 30 etc.
return None and the program never fires (matches real-panel range
checks).
12 new tests covering:
* PanelLocation longitude sign-flip and timezone derivation
* _next_yearly_fire for today / next-year rollover / disabled / invalid
* YEARLY worker end-to-end + multi-year loop
* _next_sun_relative_fire AT_SUNSET / sunrise-with-offset / no-days
* engine sun-relative skip without location
* engine sun-relative fires correctly with location
Full suite: 539 passed, 1 skipped (up from 527).
First half of the autonomous program-execution engine. Two phases land
together because Phase 1 was pure scaffolding (Clock + classifier)
and made little sense in isolation.
Phase 1 — engine foundation:
* Clock protocol with RealClock (wall time + asyncio.sleep) and
FakeClock (manual advance, no real waiting; sleepers wake in
chronological order on advance_to).
* classify(programs) splits a Program tuple into timed / event /
yearly / clausal-head buckets, dropping FREE / REMARK / unknown
records and the AND/OR/THEN clausal continuations (those are
reached by walking forward from each WHEN/AT/EVERY head, not by
classification).
* ProgramEngine class with start / stop lifecycle (idempotent +
context-manager), per-program asyncio task list, _EngineMetrics
counters.
Phase 2 — TIMED programs actually run:
* _next_absolute_fire(now, program) computes the next datetime at
which a TIMED program with TimeKind.ABSOLUTE should fire, given
its hour/minute/days mask. Walks forward up to 8 days; returns
None for empty Days mask (program is effectively disabled).
* Each TIMED program gets its own asyncio task running
sleep-until-next-fire / fire / loop. Firing dispatches the
4-byte Command wire payload (cmd / par / pr2) through
MockPanel._handle_command — same code path the v2 Command opcode
uses, so a TIMED program turning on a unit produces identical
state to a client sending the equivalent Command.
* astral added as an [engine] optional dependency, pinned to 2.2
for HA compat (HA itself pins astral==2.2). Library wired up but
not yet consumed — sunrise/sunset support lands in Phase 3.
Tests (28 new):
* RealClock and FakeClock behaviour incl. chronological wake order.
* classify against each ProgramType, unknown values, empty input.
* Engine lifecycle (idempotent start/stop, context manager,
malformed-record tolerance).
* End-to-end: TIMED UNIT_ON program fires at the right Monday 06:00,
loops correctly across weeks, never fires outside its Days mask,
ignores programs with empty Days mask.
Full suite: 527 passed, 1 skipped (up from 499).
Closes out the per-object property triad. These three fields live
deep in the installer section past the zone-area / button-area-group
arrays (clsHAC.cs:3290-3416):
3330..3393: Thermostats[1..64].Areas (area-membership bitmask)
3397..3460: Thermostats[1..64].Type (raw enuThermostatType)
3553..3728: Zones[1..176].ZoneOptions (raw options byte)
Offsets derived from the OMNI_PRO_II CAP constants (numConsoles=16,
numTstats=64, numDCMCodes=16, numMessageGroups=16, numSerialPorts=6,
numSCI+numUART=5) plus its feature set — SuperviseBell +
SuperviseExteriorSounder + ZoneResistors + Addressable + UPB all
present, contributing exactly 9 conditional bytes before
ReportBypassRestore. Verified empirically: ZoneOptions is a clean
176-byte run of the default value 4, bounded by CrossZoneTimer=60
as the canary byte just before it.
New PcaAccount fields: zone_options, thermostat_types,
thermostat_areas. MockZoneState gains `options`, MockThermostatState
gains `thermostat_type` + `areas`. The mock's zone and thermostat
Properties replies now serve the real values instead of the
hardcoded 0 / 1 they used before — so HA discovery against
MockState.from_pca gets the complete per-object property set.
Live fixture: all 176 zones at the default options=4, both named
thermostats type 1, thermostat areas 0xFF (all) → normalised to
area 1 in the mock (consistent with the unit-area handling).
With this the OMNI_PRO_II SetupData decode is functionally complete
for every per-object property a consumer would want — zones, units,
areas, thermostats all carry type + area + options sourced from the
file rather than faked.
Full suite: 499 passed, 1 skipped.
Final SetupData sweep. Everything still walked-but-discarded is now
captured.
Telephony / dialer (user-section head + installer):
telephone_access, answer_outside_call, remote_commands_ok,
rings_before_answer, dial_mode, my_phone_number (PII, repr=False),
callback_number.
Misc panel scalars:
high_security, freeze_alarm, flash_light_num (BE u16 — the X10 unit
flashed on alarm), announce_alarms, house_code, zone_expansions,
num_exp_enc, num_thermostats, exterior_horn_delay, dialout_delay,
verify_fire_alarms, enable_console_emg, time_format, date_format,
ac_power_freq, dead_line_detect, off_hook_detect.
DCM (Digital Communicator Module) — the alarm-dialer block — as a
new DcmConfig dataclass: primary/backup phone numbers (PII,
repr=False) + account IDs, dcm_type, supervisory test schedule +
code, the 176-entry per-zone alarm-code table, and the 8 emergency
event codes (Freeze/Fire/Police/Aux/Duress/BatteryLow/FireZone/Cancel).
The phone-number strings use clsHardwareArray.ReadString — a
fixed-width MaxLength+1 slot whose content runs until the first 0xFF,
with no length prefix (distinct from the String8 used by Names).
New _read_hw_string helper handles that format. "-" is the panel's
blank-number sentinel.
Live fixture decodes coherently: telephone access on, 8 rings before
answer, panel's own number "208-854-7071", HouseCode A, 64
thermostats, fire-alarm verification on. DCM is unconfigured for
central-station monitoring (blank "-" numbers, 0xAAAA default
account IDs) but the per-zone alarm-code table is fully populated.
With this, the OMNI_PRO_II SetupData block is essentially fully
decoded — every field clsHAC._ParseSetupData reads up through the
zone-area / button-area-group arrays is now surfaced on PcaAccount.
Full suite: 499 passed, 1 skipped.
The PCA03 post-Connection extension was previously walked as opaque
bytes — _walk_to_remarks read past AccountRemarks_Extended and the
nine 33-byte-per-slot Description tables only to advance the cursor
to the actual Remarks dict.
This pass keeps the data instead. New PcaAccount fields, all populated
only when FileVersion >= 3:
* account_remarks_extended — free-text installer notes (repr=False)
* zone/unit/button/code/thermostat/area/message/audio_source/audio_zone
_descriptions — per-family {slot: description} dicts
Per-slot format inside each Description block is the same String8(32)
that names use elsewhere: 1 length byte + 32 padded bytes, decoded
to UTF-8 with NUL-strip. The leading u32 count can exceed the family's
actual object count (real panels write the max-slot count regardless
of how many are populated); we read all of them and filter empties.
Live fixture decodes cleanly: every Description table is empty
(homeowner never filled them in — that's reality, not a parser
fault). The hand-built synthetic test in test_pca_file proves the
decode works when the data is actually present (zones 1+2 with
descriptions "FOYER!" and "GARAGE LT").
_walk_to_remarks now returns a _RemarksWalk dataclass aggregating
all of the post-Connection extraction; existing remarks-related
tests updated to use the new return shape.
Full suite: 499 passed, 1 skipped.
Three single-byte scalars sandwiched between the TimeClocks block and
AnnounceAlarms (clsHAC.cs:3064-3066). Raw bytes — no N/S/E/W modifier
at this position (those live in the optional WorldWideLatitude feature
block past DST). TimeZone is hours west of UTC on OMNI_PRO_II.
Live fixture decodes as 44°N / 117°W / TZ 7 (Pacific Daylight) —
matches a real northern-US install on the panel time.
PcaAccount gains latitude / longitude / time_zone (int each).
Walker reads them via the existing _read_scalar_byte helper.
Full suite: 499 passed, 1 skipped.
Three more SetupData fields, plus a refinement that uses one of them:
* HouseCodes.EnableExtCode[1..16] at user-section offset 1917 —
one enuHouseCodeFormat byte per 16-unit X10 group. Live fixture:
HouseCode 1 = HLC (5), HouseCodes 2..16 = Extended (1).
* Six 5-byte clsWhen structs at 1863..1892 — TimeClock 1/2/3 On/Off
schedules. Exposed as a new TimeClock dataclass tuple. Live fixture
TC1 = On 22:30 → Off 06:00 daily (outdoor-lights pattern).
* InstallerCode (BE u16 @ 2995), EnablePCAccess (bool @ 2997),
PCAccessCode (BE u16 @ 2998) — both codes are PII so repr=False.
Refinement: unit_types for X10 units now resolves the specific
sub-type via the HouseCodeFormat table instead of the previous
collapsed Standard. Mapping mirrors clsUnit.CalculateUnitType
(clsUnit.cs:928-999) including the (Number-1)%8==0 split for HLC
(HLCRoom vs HLCLoad) and ZWave (ViziaRoomController vs ViziaLoad).
Live fixture now reports the right thing: unit 1 (ROOM ONE) is
HLCRoom (5), units 2-8 (FRONT PORCH, PENDANT LTS, …) are HLCLoad (6),
unit 9 is HLCRoom again, etc. Units 17-256 under HouseCodes 2..16 are
all Extended (2). Total: 2 HLCRoom + 14 HLCLoad + 240 Extended +
136 Output + 119 Flag = 511 unit slots, matches numUnits exactly.
Full suite: 499 passed, 1 skipped.
Four more SetupData fields landed in one pass. The user-section walk
past the previously-mapped 5 contiguous area flags continues with 70
bytes of intervening config (HighSecurity/FreezeAlarm/FlashLightNum/
HouseCodes flags × 32 / 6 TimeClock When-structs / Latitude/Longitude/
TimeZone/AnnounceAlarms) to reach:
1897..1904: PerimeterChime[1..8] (bool[8])
1905..1912: AudibleExitDelay[1..8] (bool[8])
1913..1916: DSTStartMonth/Week, DSTEndMonth/Week (4 scalar bytes)
Live fixture DST decodes as US-standard (March / 2nd Sunday →
November / 1st Sunday). Area-1 PerimeterChime is OFF (homeowner
disabled), the panel default for unused areas 2-8 is ON.
Unit type + area assignment, derived from CAP index ranges and the
AreaGroups bitmap arrays at installer offsets 3035..3105
(clsHAC.cs:3242-3289):
X10 units (1..256) → enuOL2UnitType.Standard (1),
16 units per AreaGroups byte
ExpEnc (257..384) → Output (13), 4 units per byte
VoltOut (385..392) → Output (13), 1 byte per unit
FlagOut (393..511) → Flag (12), 8 flags per byte
The X10 sub-types (Standard/Extended/HLC/UPB/ZWave/…) collapse to
Standard since deriving them needs the HouseCodes EnableExtCode table
which we don't decode yet. Live fixture all-511-units classify
correctly: 256 X10 + 128 ExpEnc + 8 VoltOut + 119 FlagOut.
Unit areas are 8-bit membership bitmasks. The live fixture has 0xFF
everywhere ("panel default — all 8 areas"); from_pca normalises that
to 0x01 ("area 1 only") so the mock's Properties reply gives HA a
single sensible area instead of bit-set noise.
Code PINs (offset 383, 99 × 14-byte entries). Per-entry layout:
bytes 0..1: PIN (BE u16; plain 4-digit 0..9999)
byte 2: Authority (enuCodeAuthority: 0=Disabled, 1=User,
2=Manager, 3=Installer)
byte 3: Areas bitmask
bytes 4..13: WhenOn + WhenOff (2 × clsWhen)
PINs are PII — ``PcaAccount.code_pins`` is marked ``repr=False`` so
a stray ``print(acct)`` can never leak them into logs. They aren't
auto-threaded to MockState.user_codes either; tests set their own
PINs explicitly. Live-fixture decode is sane: COMPUTER=4932/User,
HOMEOWNER=1234/User, Kevin=3411/User, Debra=0000/Manager, etc.
MockAreaState gains perimeter_chime + audible_exit_delay.
MockUnitState gains unit_type + areas (and the Properties reply
serves the configured values now).
Full suite: 499 passed, 1 skipped.
SetupData side (clsHAC.cs:3020-3038): five contiguous bool[8] arrays
immediately after ExitDelay carry per-area config flags. Offsets:
1787..1794: EntryChime
1795..1802: QuickArm
1803..1810: AutoBypass
1811..1818: AllOnForAlarm
1819..1826: TroubleBeep
Verified against live fixture: area 1 shows real homeowner choices
(QuickArm + AllOnForAlarm enabled, others off), unused areas 2-8 carry
the panel defaults (EntryChime/AutoBypass/TroubleBeep on by default).
PerimeterChime and AudibleExitDelay aren't in this contiguous block —
they live past FlashLightNum, HouseCodes flags, and 6 TimeClock
When-structs. Deferred.
New PcaAccount fields:
area_entry_chime, area_quick_arm, area_auto_bypass,
area_all_on_for_alarm, area_trouble_beep — all dict[int, bool].
MockAreaState gains the same five fields. They aren't carried in the
Properties reply on the wire (the OL2 message format doesn't have
them), so they live on MockState for snapshots and any future
SetupData-aware code, but don't surface through HA discovery yet.
v2 client list_area_names fallback: when the Properties walk turns up
no named areas (common — most homes don't name them), synthesize
"Area 1".."Area 8" so HA's _discover_areas has slots to walk.
Mirrors the v1 adapter behaviour exactly.
Knock-on win in the live-fixture HA test: area 1 now reaches
coordinator.data.areas with its configured 60s/90s delays from
SetupData, end-to-end through .pca → MockState → wire Properties →
HA's AreaProperties parser.
Full suite: 499 passed, 1 skipped.
Three more SetupData fields, varying in difficulty:
* Entry/exit delays per area — in the user section, behind 280 bytes
of Phone[8] config and 1386 bytes of Codes[99]. Derived offsets by
counting fixed-width fields out from Seek(1): EntryDelay[1..8] at
offset 1771, ExitDelay[1..8] at 1779. Verified against live fixture
(area 1: entry=60s, exit=90s; unused areas: 15s/15s panel defaults).
* TempFormat at installer offset 2993 — single byte, enuTempFormat
(1=F, 2=C). Live fixture = 1 (US install).
* NumAreasUsed at installer offset 3034 — count of installer-enabled
security areas. Live fixture = 1 (single-area home).
PcaAccount now carries area_entry_delays, area_exit_delays, temp_format,
num_areas_used. MockAreaState gains entry_delay/exit_delay/enabled
fields; mock _build_area_properties serves the configured values
(was hardcoded 60/30/Enabled).
MockState.from_pca now synthesizes per-area MockAreaState entries
for the union of named areas + (1..num_areas_used), filling in delays
and enabled flag. This means a single-area install with no
user-assigned name still surfaces area 1 with the correct config —
matching what an installer would see in PC Access.
(HA's coordinator only enumerates named areas via list_area_names,
so the area properties don't yet reach the diagnostic surface for
unnamed-but-in-use areas. That's a separate filter to revisit; the
data flow through pca_file → MockState → wire Properties reply is
already correct.)
Full suite: 499 passed, 1 skipped.
Walks the OMNI_PRO_II installer section past ZoneType, DCM stuff,
thermostat config, and the X10/VoltOut/FlagOut/ExpEnc area-group
arrays to land on the 176-byte Zones[].Area block at offset 3106.
The path from instSetupStart (2560) to zone area:
ZoneType[176] → DCM phones/accounts/type/test(5-byte clsWhen) →
DCMAlarmCode[176] → 8 DCM bytes → TempFormat..NumAreasUsed (29 bytes
of misc config including 25-byte CallBackNumber) → X10 area groups
(16) → VoltOut (8) → FlagOut (15) → ExpEnc (32) → Zones[].Area (176).
Total preamble within installer section = 546 bytes. Verified against
the live fixture: 176 zones all assigned to area 1 (single-area
install), matches expectation.
PcaAccount.zone_areas now carries {slot: area_number}; MockState.from_pca
threads it through MockZoneState.area; mock _build_zone_properties already
serves it. End-to-end test verifies the area flows through to
coordinator.data.zones[*].area.
This was the largest single-RE jump in SetupData decoding so far — got
us past the variable-length DCM block by counting fixed-width fields
out from the known ZoneType end. The clsWhen=5-byte struct was the
last unknown; derived from clsHardwareArray.ReadWhen (clsHardwareArray
.cs:456-468).
Full suite: 499 passed, 1 skipped.
SetupData (3840 bytes) holds the panel's per-object property tables.
Layout for OMNI_PRO_II's installer section (Seek to instSetupStart=2560
in clsHAC._ParseSetupData at clsHAC.cs:3156):
offset 2560: HouseCode (1 byte)
offsets 2561..2569: OutputType[0..8] (9 bytes; numVoltOutputs)
offset 2570: ZoneExpansions (1 byte)
offset 2571: NumExpEnc (1 byte)
offsets 2572..2747: ZoneType[1..176] (176 bytes; raw enuZoneType per zone)
Verified against the live fixture: 2 EntryExit + 4 Perimeter + 3 AwayInt
+ 1 Extended_Range_OutdoorTemp + 166 Auxiliary (panel default for
unused slots) — matches the named-zones cross-reference exactly.
PcaAccount gains a zone_types dict (1-based slot → raw byte). The
walker stashes the SetupData blob to a buffer up front and indexes
in by offset rather than chasing the sequential parser through all
of telephony/codes/areas — that's a bigger RE pass for another day.
MockZoneState now carries zone_type and area fields. MockState.from_pca
threads acct.zone_types through, and _build_zone_properties uses the
real value instead of hardcoded 0 (EntryExit). End-to-end against
MockPanel.from_pca: HA's discovery now classifies binary vs. analog
zones correctly straight from the .pca — outdoor temp zone surfaces
as a temperature sensor entity, motion sensors as binary_sensor,
door zones as the right kind of binary_sensor.
Full suite: 499 passed, 1 skipped. RE notes in pca_file.py.
The Names block (between SetupData and Voices) was previously walked
as opaque bytes. It's actually a sequence of seven object-family
tables, each storing N × String8(L) per the
clsAbstractNamedItem.ReadName / clsPcaCryptFileStream.ReadString8(out S, byte L)
pattern. Per-slot layout is [1 byte actual length][L bytes name],
with length 0 meaning "unused".
New PcaAccount fields:
* zone_names, unit_names, button_names, code_names,
thermostat_names, area_names, message_names
— each is {1-based slot: name}, only non-empty slots.
Object *properties* (zone_type, area_membership, etc.) aren't
extracted yet — those live in SetupData, which remains opaque.
Names alone unlock the biggest win: meaningful entity labels in
HA from a .pca snapshot.
MockState.from_pca now seeds zones/units/areas/thermostats/buttons
with MockZoneState/MockUnitState/etc. instances carrying just the
name. Defaults handle everything else. A connected client sees the
real panel's names through normal wire discovery (UploadNames
streams them back, properties synth fills the rest).
New end-to-end test verifies the HA integration discovers all 16
zones, 44 units, 16 buttons, 2 thermostats from the live fixture
when the MockPanel is built via MockState.from_pca — proving the
full file → mock → wire → HA pipeline.
Live fixture: 16 zones, 44 units, 16 buttons, 8 codes, 2 thermostats,
0 areas, 8 messages, 330 programs. (Areas in this v1 install have
no user-assigned names — expected.)
Full suite: 499 passed, 1 skipped (fixture-gated).
Convenience constructor that runs parse_pca_file and seeds:
* model_byte + firmware_major/minor/revision from the .pca header,
so SystemInformation replies match the panel the file came from
* programs dict from every non-empty Program record in the 1500-slot
table, encoded back to wire bytes for direct UploadProgram /
UploadPrograms service
Per-object name/state (zones/units/areas/thermostats) isn't in the
pca_file extraction yet — those default to empty unless the caller
overrides. Easy to extend later when pca_file grows zone/unit name
parsing.
Net effect: anyone can now point a MockPanel at any .pca file and
get a hermetic replay of that install's programs over both v1 and
v2 wire dialects:
state = MockState.from_pca("My_House.pca", key=KEY_EXPORT)
panel = MockPanel(controller_key=k, state=state)
New e2e test materialises the live fixture, builds the mock from it,
streams all 330 programs back through OmniClient.iter_programs, and
asserts the slot indexes match.
Adds CONF_PCA_PATH + CONF_PCA_KEY config-flow fields. When set, the
coordinator parses programs from the .pca file at that path instead
of streaming them over the wire on every entry refresh. Useful for:
* deployments where wire enumeration is slow (1500-slot iteration)
* offline snapshots when the panel is unreachable
* deterministic test setups against a known fixture
The config-flow validates the file is readable and decrypts cleanly,
surfacing pca_not_found / pca_decode_failed errors via the strings/
en.json translations.
The .pca path is checked first in _discover_programs; if absent the
wire path runs as before. So existing deployments are unaffected.
Tests cover the success path (live fixture, 330 programs) and the
two validation failures (missing file, garbage bytes).
Coordinator's _discover_programs is no longer a placeholder. It now
drives client.iter_programs() (v2 path) or the v1 adapter's forward
to OmniClientV1.iter_programs (v1 path), populating OmniData.programs
with decoded Program records keyed by slot. Errors are logged and
swallowed so partial enumeration doesn't break entry setup —
programs are non-critical telemetry.
OmniData.programs is now dict[int, Program] rather than the
ProgramProperties dict that was an empty placeholder. The
ProgramProperties dataclass remains in models.py for the Properties
opcode reply path; only the coordinator's value type changed.
New OmniProgramsSensor on the sensor platform: a single diagnostic
entity per panel whose state is the count of defined programs and
whose 'programs' attribute lists each program's slot, type name,
and schedule fields. Easy to consume from automations and the
developer-states UI.
Mock fixture seeds three programs (TIMED+TIMED+EVENT at slots 12 /
42 / 99). New integration test verifies the sensor enumerates them
in slot-ascending order with the expected per-record fields.
Full suite: 494 passed, 1 skipped (fixture-gated).
v2 path adds an iterator over UploadProgram with request_reason=1
("next defined after slot"), mirroring the C# ReadConfig loop at
clsHAC.cs:4985 (seed call) and 5331 (per-reply re-issue). The mock
panel now honours reason=1: walks state.programs for the next
slot strictly greater than the requested one, returns EOD when none.
v1 path wraps OmniConnectionV1.iter_streaming(UploadPrograms) and
decodes each ProgramData reply into a Program. The panel already
streams in slot-ascending order from the previous commit, so the
client just decodes-and-yields.
Both methods return AsyncIterator[Program] for HA-side consumption.
Tests cover populated and empty states for both dialects, plus the
raw v2 reason=1 semantics on a single request.
MockPanel only handled the v2 (single-slot, request/reply)
UploadProgram path. v1 panels use a streaming variant:
client sends UploadPrograms (bare), panel emits one ProgramData
per defined slot, ack-walked by the client, terminated by EOD.
Wire layout is byte-identical to v2 — only the envelope opcode
and stream pattern differ (clsHAC.OL1ReadConfig at clsHAC.cs:4403,
4538-4540, 4642-4651). The mock now mirrors the UploadNames
streaming pattern with its own cursor.
Tests cover both the populated-state stream-then-EOD case and
the empty-state immediate-EOD case, alongside the existing v2
single-slot round-trip tests.
Final RE pass on the multi-record AND record extension. Authored
"AND IF DATE IS EQUAL TO 12/31" (block 12, slot 13) and resolved
the disk encoding model for the structured-OP case:
byte 0 : ProgType = 8 (AND)
byte 1 : (high byte of LE cond) = OP (enuCondOP)
byte 2 : (low byte of LE cond) = Arg1_ArgType (enuCondArgType)
bytes 3-4 : (cond2 LE) = Arg1_IX
byte 5 : (cmd byte) = Arg1_Field
byte 6 : (par byte) = Arg2_ArgType
bytes 7-8 : (pr2 LE) = Arg2_IX
byte 9 : (month byte) = Arg2_Field
bytes 10-11: (day, days bytes) = CompConst
The C# clsConditionLine.Cond property at clsConditionLine.cs:17-33
bridges the two views: for Traditional case (OP=0), the compact-form
cond u16 is SYNTHESIZED from Arg1_ArgType and Arg1_IX. The byte at
offset 2 (= Arg1_ArgType) holds the ProgramCond family code (ZONE=4,
CTRL=8, ...) when OP=0, or the enuCondArgType value (Zone=2, Unit=3,
Thermostat=4, TimeDate=7, ...) when OP > 0. Same byte, different
semantic interpretation based on OP.
New Program properties:
and_op - byte 1, enuCondOP (0 = Traditional, 1-9 = structured)
and_arg1_argtype - byte 2, family code (Trad) or CondArgType (Struct)
and_arg1_ix - bytes 3-4 raw u16 (= cond2; Python LE decode
happens to equal C# in-memory BE Arg1_IX)
and_arg1_field - byte 5
and_arg2_argtype - byte 6
and_arg2_ix - bytes 7-8 raw u16 (= pr2)
and_arg2_field - byte 9
and_compconst - bytes 10-11
The and_instance property is now smart-branched on and_op:
- Traditional: returns Arg1_IX >> 8 (instance in high byte per
clsConditionLine.Cond setter)
- Structured: returns Arg1_IX directly (raw object index)
Also fixed every_interval: per clsProgram.Interval at
clsProgram.cs:338-348, it reads (Data[2] << 8) | Data[3] which spans
the Cond and Cond2 byte ranges. The correct Python formula is
((cond & 0xFF) << 8) | ((cond2 >> 8) & 0xFF). The earlier byte-swap-of-
cond2 formula happened to work for Interval=5 but would break for
Interval > 255.
2 new tests:
test_and_structured_date_eq_1231 - the captured Date case
test_and_traditional_zone_5_secure_via_structured_view
- same vector via structured accessors
475 tests passing (up from 473).
The 6 multi-record ProgType values (WHEN/AT/EVERY/AND/OR/THEN) now have
typed accessors on the Program dataclass:
is_multi_record() - classifier for ProgTypes 5-10
event_id - WHEN trigger event-id (same property as EVENT, no
Mon/Day swap, BE wire form)
and_family - AND record byte-1 family + operand bits (mirrors
compact-form cond's high byte: ZONE=0x04, CTRL+ON=0x0A,
OTHER=0x00, etc.)
and_instance - AND record bytes 3-4 BE u16 (zone#, unit#,
MiscConditional value, ...)
every_interval - EVERY record bytes 3-4 BE u16 (recurrence interval)
AT records reuse the existing month/day/days/hour/minute fields (same
byte layout as compact-form TIMED, just with cmd/par/pr2 zero).
OR records carry no payload — only the ProgType byte distinguishes
them. THEN records reuse cmd/par/pr2 (same layout and LE byte order
as compact-form action fields).
10 new tests cover the empirical captures from pca-re/clausal-re:
- is_multi_record() classifier
- WHEN event_id for Zone 5 Secure and Zone 1 Secure
- EVERY 5 SECONDS interval decoding
- AND IF UNIT 1 ON, AND IF ZONE 5 SECURE, AND IF NEVER family+instance
- AT record month/day/days/hour/minute
- OR record all-zero invariants
- THEN record cmd/par/pr2 (UNIT 1 ON)
All byte vectors in the tests come from real PC Access captures in
pca-re/clausal-re/06-10.pca with firmware override at 3.0+.
The and_family and and_instance properties derive from the existing
cond and cond2 fields via byte-swap — disk bytes 1-4 of AND records
use BE u16 order, but Program's cond/cond2 fields are LE-decoded
(per compact-form convention). The byte-swap formula
((cond2 & 0xFF) << 8) | ((cond2 >> 8) & 0xFF) yields the BE
interpretation without re-reading raw bytes.
473 tests passing (up from 463).
Authored a controlled "AND IF ZONE 5 SECURE" condition in PC Access
and diffed against an "AND IF NEVER" capture at the same record
position:
NEVER: 08 00 00 00 01 00 00 00 ...
ZONE 5 SECURE: 08 04 00 00 05 00 00 00 ...
The zone number "5" lands in byte 4 (high-offset of the u16 at
positions 3-4). If disk were little-endian, the 5 would land at
byte 3. So Arg1_IX, Arg2_IX, and CompConst in AND records are
big-endian on disk — opposite of the compact-form cond/cond2/pr2,
which are LE. Different record families use different byte orders;
the C# encoder writes AND records' u16s directly in BE matching
in-memory Data[] layout, while compact-form fields go through the
Cond/Cond2/Pr2 setters that produce LE on the wire.
Update the AND-record comment block to reflect the resolved byte
order. The byte-1 semantic role (OP vs family code) remains open
and is noted as a future single-experiment follow-up.
No code changes — still no AndRecord decoder exposed since byte 1's
meaning is one open question away from being settled.
Multi-record AND records (ProgType=8, firmware >=3.0.0) carry a
structured condition with the byte layout from clsProgram.cs:326-436:
byte 1: OP (enuCondOP)
byte 2: Arg1_ArgType (enuCondArgType)
bytes 3-4: Arg1_IX (u16)
byte 5: Arg1_Field
byte 6: Arg2_ArgType
bytes 7-8: Arg2_IX (u16)
byte 9: Arg2_Field
bytes 10-11: CompConst (u16)
The two companion enums (CondOP, CondArgType) are exported so callers
can pattern-match on operator + arg type without re-deriving from the
C# source.
Special case noted: when OP == Arg1_Traditional (=0), the AND record's
condition is rendered from the Cond u16 (bytes 1-2) using the same
per-family scheme as compact-form cond, per clsText.cs:2281-2284. The
Arg1_*/Arg2_*/CompConst fields are only meaningful when OP > 0.
Open question logged in comments: disk byte order for the three u16
fields. clsProgram.Read reads them little-endian but the accessors
index Data[] big-endian. Our single captured example is symmetric and
doesn't disambiguate; resolution deferred until we have an authored
AND IF ZONE 5 SECURE (or similar asymmetric Arg1_IX) sample.
No decoder methods added yet — the raw 14-byte body is sufficient for
the current downstream code, and exposing partial-decode methods would
risk shipping a wrong byte-order interpretation.
The 14-byte program record's three u16 fields are little-endian, not
big-endian as the original plan assumed. Empirically confirmed by
authoring known programs in PC Access (running in a Windows XP VM)
and byte-diffing the resulting .pca file:
- UNIT 1 ON → bytes 7,8 = 01 00 → LE 0x0001 (correct), not 0x0100
- AND IF ZONE 2 SECURE → cond bytes [02, 04] → LE 0x0402 (kind=4 ZONE,
inst=2) matches the ProgramCond.ZONE family from the C# source
- Cross-check Our_House.pca's 209 TIMED records: pr2 low-byte is
almost always zero (textbook LE small-value distribution)
Also annotate the multi-record ProgType values (WHEN/AT/EVERY/AND/OR/THEN,
values 5-10) with the firmware ≥3.0.0 requirement from
clsCapOMNI_PRO_II.cs:290 — the user's 2.16A panel can't produce them,
which is why Our_House.pca contains zero such records.
New constants:
- MIN_FIRMWARE_MULTILINE_PROGRAMS (= 196608, packed 3.0.0)
- MIN_FIRMWARE_DOUBLE_PROGRAM_CONDITIONAL (= 0, always)
- pack_firmware_version() helper
Full RE notes in pca-re/clausal-re/FINDINGS.md (separate repo).
Tests: 463 passing, 1 skipped (gitignored fixture).
The 16-bit cond/cond2 fields of a program record pack a 5-family
discriminator + a per-family selector + a per-family operand. The high
byte's bits 2-7 (i.e. (cond >> 8) & 0xFC) pick the family; the rest is
family-specific:
OTHER → bits 0-3 = MiscConditional value (DARK, AC_POWER_OFF, …)
ZONE → bits 0-7 = zone #; bit 9 = NOT_READY (1) / SECURE (0)
CTRL → bits 0-8 = unit #; bit 9 = ON (1) / OFF (0)
TIME → bits 0-7 = clock#; bit 9 = ENABLED (1) / DISABLED(0)
SEC → bits 8-11 = area #; bits 12-14 = SecurityMode;
bit 15 = arming-transition flag
(only when mode != 0)
The Sec family is the catch-all default (per clsText.cs:2226-2273 the
switch falls through to it from anything not Other/Zone/Ctrl/Time).
omni_pca.programs:
* New ConditionFamily IntEnum and MiscConditional IntEnum.
* New Condition frozen dataclass with decode classmethod, is_empty,
describe (renders with index-based labels for offline use).
* New Program.condition() and Program.condition2() helpers.
omni_pca top-level: re-exports Condition, ConditionFamily, MiscConditional.
Verified against the live fixture (330 defined programs):
cond family distribution: SEC=156, TIME=8, ZONE=4, CTRL=3, OTHER=3
cond2 family distribution: SEC=21, TIME=10
tests/test_programs.py (+24 cases):
* Parametrised per-family decode with worked examples from the docs.
* Arming-transition flag asserts (mode=Off + bit 15 is NOT arming).
* Program.condition()/condition2() integration.
* OTHER ignores high bits (PC Access sometimes leaves them set).
* u16 range validation.
* MiscConditional enum values match enuMiscConditional.cs.
Full suite: 463 passed, 1 skipped (was 439 / 1).
Source: clsText.GetConditionalText (clsText.cs:2224-2273) for the
decode logic; frmAutomationEditCondition.cs:615-2550 for the encoder.
The hour byte of a TIMED program is overloaded as a 1-of-3 discriminator:
0..23 means absolute wall-clock time, 25 means sunrise-relative, 26 means
sunset-relative. For the relative forms, the minute byte is signed
(sbyte) -- positive = after, negative = before, zero = at. Source:
frmPopUpEditTime.cs:186-217 (decode) + :241-263 (encode).
This was the canary that tripped our earlier sanity test: slots 182/183
in the live fixture have hour=26 minute=246 and hour=25 minute=10 --
nominally invalid as clock times, but they're "10 min before sunset"
and "10 min after sunrise" respectively. With this commit those decode
cleanly via TimeKind.SUNSET / SUNRISE.
omni_pca.programs:
* New TimeKind IntEnum: ABSOLUTE / SUNRISE / SUNSET.
* New Program.time_kind property (classifies via hour-byte discriminator).
* New Program.time_offset_minutes property (signed minutes-offset for
sunrise/sunset; 0 for absolute).
* New Program.format_time() -> str: "07:15" | "at sunrise" | "30 min
before sunset" etc.
* Module-level _classify_time helper + sentinel constants
_HR_SUNRISE_SENTINEL=25 / _HR_SUNSET_SENTINEL=26.
omni_pca top-level: re-exports TimeKind.
tests/test_programs.py (+13 cases):
* Parametrised TimeKind classification across absolute / sunrise /
sunset including boundary cases (sbyte ±128, ±1, 0).
* Wire-bytes round-trip preserves TimeKind + offset.
tests/test_pca_file.py: tightened the previously-loosened sanity
invariant. ABSOLUTE-time TIMED programs must hit valid wall-clock
ranges (0-23 / 0-59); relative-time programs must have a valid sbyte
offset (-128..127). Both pass cleanly on the 209 TIMED programs in
the live fixture (207 absolute, 1 sunrise, 1 sunset).
Full suite: 439 passed, 1 skipped (was 426 / 1).
Decodes the remark-text dict that Remark-typed program records refer to
via their 32-bit BE RemarkID. The table lives after the Connection
block in PCA03 files; getting to it means walking past ModemBaud +
PCModemInit flags + AccountRemarks_Extended + nine 33-byte-per-entry
Description blocks (Zones, Units, Buttons, Codes, Thermostats, Areas,
Messages, AudioSources, AudioZones).
Format reverse-engineered from clsPrograms.ReadRemarks (clsPrograms.cs:
148-168) and the file-body walker in clsHAC.cs:8055-8079. Each entry is
[u32 LE remark_id][u16 LE text_length][N bytes UTF-8], preceded by a
[u32 LE _RemarksNextID][u32 LE count] header.
pca_file changes:
* PcaAccount.remarks: dict[int, str] (default {}).
* New _walk_to_remarks helper called from parse_pca_file when
file_version >= 3. Best-effort: any read failure leaves remarks={}.
* New _DESCRIPTION_SLOT_BYTES (= 33) constant.
tests/test_pca_file.py (4 new cases):
* Walker on an empty Remarks table (decode count=0 cleanly).
* Walker decodes three hand-built entries, including a UTF-8 string
with non-ASCII characters.
* Truncated input returns {} rather than raising.
* Live fixture (Our_House.pca.plain): walker consumes the prelude +
nine description blocks + zero-count remarks block without raising.
This panel has no Remark-typed programs, so {} is the expected
result -- and the *coarse* walker validation here is what proves
the description-block sizes (counts up to 511) are correct.
Full suite: 426 passed, 1 skipped (was 422 / 1).
First reverse-engineering pass on the panel's built-in automation
engine. Adds a typed Python Program dataclass that decodes/encodes the
14-byte program record used both on the wire (clsOLMsgProgramData) and
on disk (the 21,000-byte Programs block in a .pca file).
Coverage:
* enums: ProgramType, ProgramCond, Days bitmask
* Program dataclass with from_wire_bytes / from_file_record /
encode_wire_bytes / encode_file_record (Mon/Day swap for EVENT-typed
records applied on the file form only -- mirrors clsProgram.Read at
clsProgram.cs:471, while clsProgram.ToByteArray omits the swap)
* Remark variant (bytes 1-4 = BE u32 RemarkID instead of cond/cond2)
* unknown ProgType / Cmd bytes pass through as raw ints with a
once-per-process warning
* decode_program_table for the full 1500-slot .pca block
* pca_file.parse_pca_file populates PcaAccount.programs (backward-
compatible: defaults to ())
* mock_panel.MockState.programs + _reply_program_data so OmniLink2
UploadProgram (opcode 9) round-trips through the test fixture
Verification (422 passed, 1 skipped — was 400):
* 15 unit tests in test_programs.py: golden bytes for each ProgramType,
Mon/Day swap proven distinct between wire and file layouts, Remark
round-trip, 500 random-input wire+file round-trips, unknown-enum
tolerance
* 4 fixture-gated live-data tests in test_pca_file.py: all 1500 slots
decode cleanly, 330 non-empty (matches Phase 1 recon distribution
209 TIMED / 105 EVENT / 16 YEARLY), 21,000-byte byte-for-byte
round-trip against the live decrypted fixture, YEARLY month/day in
valid calendar ranges
* 3 wire-echo tests in test_e2e_program_echo.py: client drives
UploadProgram (opcode 9) through the mock, server replies with
ProgramData (opcode 10) wrapping [number_hi, number_lo, body];
full Program round-trips field-by-field, empty slots return zero
bodies, EVENT bytes are emitted in wire order (no swap)
What this pass deliberately leaves open (documented in the docs page):
* cond / cond2 internal bit split (selector vs operand)
* multi-record clausal encoding (When/At/Every/And/Or/Then)
* RemarkID -> RemarkText lookup table layout
* DPC capability flag location for non-OPII models
* TIMED time-of-day vs sunrise/sunset-relative offset flag
References:
* clsProgram.cs (entire) — field accessors, Read/Write, Evt u16
* enuProgramType.cs / enuProgramCond.cs / enuDays.cs
* Owner's Manual SETUP chapter — user-facing programming-line model
* Installation Manual SETUP MISC — installer-facing setup screen
Adds OmniLinkMessage (0x10) outer-packet handling to the mock so the
v1 path no longer requires a real panel for testing. Exercised over
UDP because OmniClientV1 is UDP-only by design, but the dispatcher
itself is transport-agnostic and the TCP _handle_client routes
OmniLinkMessage packets through the same _dispatch_v1 method too.
Coverage today:
* RequestSystemInformation (17) -> SystemInformation (18)
* RequestSystemStatus (19) -> SystemStatus (20), 8 area mode bytes
* RequestZoneStatus (21) -> ZoneStatus (22), short + long form
* RequestUnitStatus (23) -> UnitStatus (24), short + long form
(long form auto-selected for indices > 255)
* RequestThermostatStatus (30) -> ThermostatStatus (31)
* RequestAuxiliaryStatus (25) -> AuxiliaryStatus (26) (zero records)
* UploadNames (12) -> NameData (11) streaming, lock-step
Ack-driven across Zone/Unit/Button/
Area/Thermostat, terminated by EOD (3)
* Command (15) -> Ack (5) / Nak (6), reuses v2 state
mutator so light-on/off, set-level,
bypass-zone, restore-zone all work
* ExecuteSecurityCommand (102) -> Ack (5) / ExecuteSecurityCommandResponse
(103) on bad code, with structured
status byte preserved
* MessageCrcError -> v1 Nak (opcode 6)
The dispatcher writes replies wrapped in OmniLinkMessage (16) outer
packets (vs OmniLink2Message (32) used by v2) so OmniClientV1 routes
them correctly. The 4-step handshake is shared with v2 -- it's
protocol-version-agnostic at the outer-packet layer.
UploadNames state is panel-instance scoped via _upload_names_cursor
(int | None) -- there is only one active session at a time on the
mock so a single cursor suffices.
tests/test_e2e_v1_mock.py: 13 cases driving OmniClientV1 through the
mock's UDP socket, covering the full read API + UploadNames streaming
+ write methods + structured-failure path on a wrong security code.
Full suite: 400 passed, 1 skipped (was 387 / 1).
Final cross-reference round, covering the remaining files where wire
bytes have a user- or installer-facing counterpart:
v1/messages.py
New Cross-references block: SETUP ZONES + SETUP TEMPERATURES for the
fields the parsers' raw bytes ultimately come from, and APPENDIX C
for what each synthesized index means on hardware (unit 257+ =
expansion-enclosure outputs, 393+ = panel flags).
models.ZoneStatus
Status-byte bit-layout doc now also points at the Owner's Manual
CONTROL chapter's "View Zone Status" keypad screen -- same Secure /
Not Ready / Trouble / Tamper labels.
models.UnitStatus
State-byte semantics doc references the Owner's Manual CONTROL
chapter for the user-side actions (All On/All Off/Scene/Bright/Dim)
that drive units into each of these states.
mock_panel.py
Notes that the mock's plausible-but-arbitrary RequestProperties /
RequestStatus responses correspond on real hardware to what an
installer typed into INSTALLER SETUP. Production fixtures should
pre-seed MockPanel state to match a known SETUP configuration.
uv.lock
Catches up the project's own entry to omni-pca 2026.5.11 (was
pinned to 2026.5.10 from the previous lock generation).
No code changes; 387 tests still pass.
Follow-up to 0d6465d, sprinkling pca-re/docs/manuals/ citations into
three more files that map to user-visible or installer-visible panel
behavior:
models.HvacMode / FanMode / HoldMode
Docstrings now explain which values correspond to keypad menu picks
vs. programmatic-only states, and point at the Owner's Manual
*Scene Commands* chapter where each menu is laid out.
pca_file.py
Module docstring adds Cross-references to the Installation Manual's
*INSTALLER SETUP* chapter (SETUP CONTROL/ZONES/AREAS/MISC/EXPANSION)
-- those are the keypad screens that produce the very SetupData /
Names / Programs blocks the parser walks. Also points at APPENDIX C
(zone and unit mapping) for where the _CAP_OMNI_PRO_II numbers come
from on the panel side.
v1/connection.py
Module docstring adds cross-references to the docs-site pages that
explain (a) the non-public handshake quirks the v1 connection relies
on for crypto and (b) why subsequent RequestUnitStatus calls need
the long-form BE u16 payload (Appendix C zone/unit mapping again).
No code changes, doc-only; 387 tests still pass.
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.
First PyPI release of the v1 wire path. Wheel published from local
source 2026-05-11 with omni_pca/v1/ subpackage included.
What's in 2026.5.11 vs 2026.5.10 (already on PyPI):
* New omni_pca.v1 subpackage -- OmniConnectionV1, OmniClientV1,
OmniClientV1Adapter -- for panels that listen on UDP only and
speak the legacy OmniLink (not OmniLink2) wire dialect.
* HA integration wires the adapter into the coordinator when
Transport=UDP is selected at config-flow time; v2/TCP path is
unchanged.
* Streaming UploadNames discovery (bare opcode + lock-step
Acknowledge until EOD/NAK).
* Long-form RequestUnitStatus for unit indices > 255 (sprinklers,
named flags, expansion-enclosure outputs).
* Chunked status polls -- firmware 2.12 NAKs at ~63 records per
request, so we batch in groups of 40.
* OmniConnection.close() now sends ClientSessionTerminated so the
panel frees our session slot immediately on disconnect.
Verified end-to-end against a firmware 2.12 OmniPro II panel at
192.168.1.9: discovery (16 zones, 44 units, 16 buttons, 8 codes,
2 thermostats, 8 messages) + status polling + execute_command
round-trip all working under HA, side-by-side with the existing
TCP mock-panel path in the dev stack.
README: new "Two wire dialects" section explaining when to pick
TCP/OmniClient vs UDP/OmniClientV1.
manifest.json: requirements bump to omni-pca==2026.5.11.
After HA finishes its first-run wizard the /api/onboarding endpoint
returns 404 plain-text instead of a JSON step list. The previous
screenshot run blew up trying to json-parse "404: Not Found".
Both call sites (_onboard and _complete_onboarding) now check the
status code first and treat anything non-200 as "already complete --
skip and go to the login path".
Adds the homeassistant service to the external caddy network with
labels for juliet.warehack.ing so caddy-docker-proxy issues a public
cert and proxies traffic to port 8123. Uses the same streaming-
friendly transport tuning the docs-site service uses, because HA's
frontend keeps long-lived WebSockets open for lovelace state pushes
and config flows -- without stream_timeout: 24h etc., caddy closes
the socket every ~15s and the UI churns reconnects.
Keeps the 8123 host-port mapping intact for direct localhost dev
access; public traffic flows over the caddy bridge.
dev/ha-config/configuration.yaml (not tracked here -- root-owned in
the HA container) was updated separately to add:
http:
use_x_forwarded_for: true
trusted_proxies:
- 10.10.16.0/20 # caddy bridge subnet
Without that block HA rejects the OAuth redirect_uri at login because
the auth check sees the internal docker IP instead of the public host.
Replace the brittle bind-mount-over-site-packages trick with a proper
``pip install --no-deps /opt/omni-pca-src`` in the HA container's
entrypoint. This gives HA a real ``omni_pca-2026.5.10.dist-info`` so
the manifest's requirement check passes, plus the v1 subpackage that's
not in the published wheel yet (omni-pca==2026.5.10 isn't on PyPI).
Before: ``--force-recreate`` broke the dev stack because the bind mount
overlaid the package contents but left no dist-info, and HA's uv-based
installer can't fetch omni-pca from PyPI.
After: container recreate just works. ``docker compose restart
homeassistant`` re-installs from the latest local source on every
start, so HA + library are always in sync with the working tree.
Header comments updated to mention the real-panel (UDP/v1) config-flow
fields alongside the existing mock-panel ones.
OmniClientV1Adapter (src/omni_pca/v1/adapter.py)
V2-shape facade over OmniClientV1. Exposes the OmniClient surface the
HA coordinator was written against — get_system_information,
list_*_names, get_object_properties (synthesized from streamed names),
get_extended_status (chunked, routed to v1 typed status opcodes),
get_object_status(AREA, ...) (derived from SystemStatus.area_alarms),
events() (EventStream on v1 SystemEvents opcode 35), plus all the
write-method shims.
Chunks unit/zone/thermostat/aux polls per-type because firmware 2.12
NAKs Request*Status with >~62 records in one shot (verified live).
Falls back to "Area 1".."Area 8" when the UploadNames stream returns
zero areas — common on panels where the installer didn't name them.
custom_components/omni_pca/coordinator.py
_ensure_connected picks OmniClientV1Adapter for transport=udp. New
_walk_properties_v1 replaces the v2 RequestProperties walk with a
name-stream + synthesized-Properties pass.
custom_components/omni_pca/config_flow.py
_probe routes to OmniClientV1Adapter for transport=udp instead of
trying to drive v2 OmniClient over UDP (which silently dropped after
handshake, per the earlier diagnosis).
src/omni_pca/events.py
parse_events / _ensure_system_events / EventStream now take an
expected_opcode arg (default v2 SystemEvents=55, v1 callers pass 35).
Word format is byte-identical between v1 and v2, so the typed-event
decoder is unchanged.
src/omni_pca/v1/client.py
_range_status supports the long-form RequestUnitStatus (BE u16
start/end) so panels with unit indices > 255 (sprinklers, flags) work.
Verified end-to-end against firmware 2.12 panel at 192.168.1.9:
config entries:
state=loaded Omni Pro II (host.docker.internal) (mock)
state=loaded Omni Pro II (192.168.1.9) (real, v1+UDP)
real-panel entities created in HA: 96 (30 binary_sensor, 26 light,
15 switch, 13 button, 9 sensor, 3 climate)
cross-check: light.omni_pro_ii_front_porch_2 = on (matches live
probe: unit #2 'FRONT PORCH' state=0x01 brightness=100)
dev/probe_v1_coordinator.py
Coordinator-shaped end-to-end smoke test against the real panel
without HA — drives the full discovery + poll cycle through the
adapter. Useful for regression-checking the v1 wire path.
dev/add_real_panel.py
Programmatically adds the real-panel config entry to the dev HA
stack via the REST config-flow endpoints. Idempotent.
Some Omni network modules are configured for UDP, in which case PC Access
falls back to the v1 wire protocol (OmniLinkMessage outer = 0x10, inner
StartChar 0x5A, typed Request*Status opcodes) instead of v2's TCP path
(OmniLink2Message + StartChar 0x21 + parameterised RequestProperties).
This adds a parallel implementation rather than overloading the v2 path.
omni_pca/v1/
connection.py UDP-only OmniConnectionV1; reuses crypto + handshake,
routes post-handshake messages through OmniLinkMessage
(0x10) wrapping v1 inner format. Adds iter_streaming
for the lock-step UploadNames/Acknowledge/EOD pattern.
messages.py Block parsers for the typed v1 status replies (zone,
unit, thermostat, aux), v1 SystemStatus, and NameData
(handles both one-byte and two-byte NameNumber forms).
client.py OmniClientV1: read API (get_system_information,
get_*_status), discovery (iter_names + list_*_names),
write API (execute_command, execute_security_command,
turn_unit_*, set_unit_level, bypass/restore_zone,
execute_button, set_thermostat_*). acknowledge_alerts
is a no-op (v1 has no equivalent opcode).
Discovery uses bare UploadNames; panel streams every defined name across
all types in a fixed order with per-record Acknowledge. Verified against
firmware 2.12 — pulled 16 zones, 44 units, 16 buttons, 8 codes,
2 thermostats, 8 messages in one stream.
src/omni_pca/message.py
Fix flipped START_CHAR_V1_* constants. enuOmniLinkMessageFormat says
Addressable=0x41 and NonAddressable=0x5A; our names had them swapped.
Wire bytes were unchanged, so existing tests kept passing — but
encode_v1() with no serial_address now correctly emits 0x5A, which
is what UDP needs.
tests/
test_v1_messages.py 22 cases; payloads are real wire captures
from a firmware-2.12 panel via probe_v1_recon.
test_v1_client_commands.py 20 cases; payload-packing for the Command
and ExecuteSecurityCommand opcodes,
including BE u16 parameter2 and the
digit-by-digit security code form.
dev/
probe_v1.py Phase-1 smoke: handshake + RequestSystemInformation.
probe_v1_recon.py Raw opcode dump for protocol reconnaissance.
probe_v1_stream.py Streaming UploadNames flow exploration.
probe_v1_client.py Full read-path smoke test via OmniClientV1.
probe_v1_write.py Live no-op execute_command round-trip.
.gitignore: ignore dev/.omni_key (probe scripts read controller key from
this file as one fallback option).
Discovery on firmware 2.12: Request*ExtendedStatus opcodes (63/65/69)
NAK on this firmware — only the basic Request*Status opcodes are
implemented, so OmniClientV1 uses those (3 bytes/unit, 7 bytes/tstat,
4 bytes/aux records). HA still gets enough signal for polling; full
properties discovery uses streaming UploadNames instead.
Test totals: 387 passed, 1 skipped (existing fixture skip).
Found via live testing against the user's Omni Pro II (firmware 2.12)
on UDP. Without this, the panel holds the session slot (it's
single-client by design) and rejects new sessions from us with
ControllerCannotStartNewSession (packet type 0x07) until its idle
timeout fires (60s+ in our testing).
src/omni_pca/connection.py:
close() now sends Packet(type=ClientSessionTerminated) before
tearing down the socket, but only if we got past CONNECTING (no
point sending termination if we never had a session). For TCP we
drain the writer briefly so the byte hits the wire before FIN.
For UDP the sendto is fire-and-forget. Wrapped in try/except so
close() stays idempotent.
Live-validation findings (real Omni Pro II, firmware 2.12):
✓ UDP handshake works end-to-end. The four-packet exchange
(NewSession ack / SecureSession ack) round-trips cleanly,
confirming the two non-public protocol quirks (session key
XOR mix + per-block whitening) are correctly implemented.
✗ Post-handshake encrypted messages get no reply from this
firmware (tried v1 OmniLinkMessage and v2 OmniLink2Message;
both arrive at the panel — verified via tcpdump — and the
panel sends nothing back). Suspected: firmware 2.12 either
requires an explicit Login first or has a different opcode
set than PC Access 3.17 documents. Needs more RE work.
The handshake-quirks validation is the headline win — we've now
proven that part of the protocol against real hardware, which no
public Omni-Link client has done. Post-handshake message dispatch
is the next investigation.
357 tests still pass.
custom_components/omni_pca/const.py:
+ CONF_TRANSPORT, TRANSPORT_TCP, TRANSPORT_UDP, DEFAULT_TRANSPORT='tcp'
custom_components/omni_pca/config_flow.py:
+ 'transport' field in _USER_SCHEMA with vol.In([tcp, udp]),
default tcp (so existing flows are unchanged)
+ transport stored in entry.data on create
+ reauth carries the existing transport over from entry.data
+ _probe() takes transport=, propagates to OmniClient
custom_components/omni_pca/coordinator.py:
+ transport= constructor arg, defaults to 'tcp'
+ _ensure_connected passes transport= through to OmniClient
custom_components/omni_pca/__init__.py:
+ reads transport from entry.data (default tcp), passes to coordinator
Backward-compat: existing config entries without a transport key fall
through to 'tcp', identical to current behavior. New entries get the
choice at the config-flow form. The reauth step preserves the existing
transport so users don't have to re-pick it.
357 tests pass; ruff clean across src/ tests/ custom_components/.
HA integration tests don't need updating because they don't pass
transport= explicitly (default tcp matches the mock's default).
The C# decompile shows enuOmniLinkConnectionType has both Network_TCP=4
and Network_UDP=3 (clsOmniLinkConnection.cs uses udpSend/tcpSend
parallel paths), and clsHAC carries an enuPreferredNetworkProtocol
{TCP, UDP} per-installation byte. User reports their panel is
configured for UDP. The TCP-only assumption was too narrow.
Wire format is identical: same Packet/Message framing, same handshake,
same per-block whitening, same opcodes, same port. Only differences:
* UDP is connectionless; each datagram = one Packet (no stream framing)
* UDP needs explicit retry-on-timeout for reliability
src/omni_pca/connection.py:
- New constructor args: transport: Literal['tcp','udp']='tcp',
udp_retry_count: int = 3
- connect()/close() branch on transport — TCP keeps the existing
asyncio.open_connection + StreamReader/Writer + reader_task path;
UDP uses asyncio.get_running_loop().create_datagram_endpoint with
remote_addr= so transport.sendto(data) works without per-datagram
addrs. The reader_task is TCP-only.
- _write_packet branches between writer.write and udp_transport.sendto
- request() loops up to (1 + udp_retry_count) attempts on UDP, retrying
on RequestTimeoutError; TCP gets a single attempt (existing behavior)
- New _OmniDatagramProtocol that decodes each datagram into a Packet
and delegates to the shared _dispatch (which already knows how to
route handshake / solicited / unsolicited)
src/omni_pca/mock_panel.py:
- serve(transport='tcp'|'udp') public arg; defaults preserve existing
TCP behavior. Internally splits into _serve_tcp / _serve_udp.
- New _MockServerDatagramProtocol that mirrors _handle_client for UDP.
Tracks one active client by addr (single-session, matches Omni's
single-client constraint). Reuses the panel's existing _dispatch_v2,
_reply_*, _build_* helpers — the dispatch logic is unchanged, only
the transport framing differs.
- New _schedule_udp_push for synthesized SystemEvents (seq=0) push
to the active client's addr after state mutations.
src/omni_pca/client.py:
- OmniClient gains transport= and udp_retry_count= kwargs that pass
through to OmniConnection. Default is 'tcp' so existing callers
are unaffected.
tests/test_e2e_udp.py — 6 e2e tests:
- handshake roundtrip
- get_system_information
- arm area with right code
- arm with wrong code -> CommandFailedError
- turn unit on -> push UnitStateChanged event
- wrong ControllerKey -> HandshakeError
All run under 0.2s. Combined with the existing TCP suite: 357 tests
pass (was 351), ruff clean across src/ tests/.
The HA integration's config_flow still defaults to TCP; users on UDP
panels can manually set transport= via the OmniClient init path. A
follow-up commit will add transport to the HA config flow as a
dropdown option.
- Move install instructions from PyPI-only to Gitea-release-first
(pip from git+https or direct wheel URL); note PyPI as 'pending'
- Add Project home + Documentation links at top
- Fix quick-start API name (get_system_info -> get_system_information,
matching the actual library)
- Replace HA quick-start with the manual-clone path that works today
(HACS support pending PyPI publish)
- Cross-link tutorials (first-script, dev-stack) and how-tos
(install-in-home-assistant) from hai-omni-pro-ii.warehack.ing
- Add Tests section showing how to run the suite
- Add License + JOURNEY link in acknowledgements
Project moved to a self-hosted Gitea at git.supported.systems under the
warehack.ing org. Updated:
pyproject.toml project.urls.Repository
custom_components/omni_pca/manifest.json documentation, issue_tracker
custom_components/omni_pca/README.md every link
CHANGELOG.md release tag URL
Tests still 351 + 1 skip. No code changed.
docs/JOURNEY.md — replaced the placeholder 'What's next' section with
seven new chronological entries covering everything that happened after
the panel-search comedy:
- HA rebuild Phase A: poll-vs-push decision, pure-function helpers
extraction, 61 unit tests with no HA imports
- HA Phase B: the six new entity platforms, the Omni state-byte
overload, security-mode-to-alarm-state mapping, the scene-platform
skip decision
- HA Phase C: services + diagnostics + repairs flow
- 'wait, did we mock enough?' — catching the missing Thermostat
(6) and Button (3) RequestProperties handlers BEFORE the HA
harness ever touched the mock
- HA test harness rough patches: requires-python conflict, pytest_socket
fight, the CONF_ENTRY_ID-doesn't-exist-in-HA find, teardown hang
fixed by converting configured_panel into a generator
- Docker dev stack: mounting only src/ to dodge the read-only-venv
problem with uv
- Automated onboarding + screenshots: the auth_code OAuth dance, the
template-endpoint device-id trick, playwright auto-injection of
hassTokens, the discovery-during-onboarding nice surprise
Plus appended five new entries to 'Things worth remembering':
- Pure functions are the cheapest thing in test suites
- Mocking the entire protocol counterpart catches whole categories
- pytest_socket + real network can coexist
- The 'build without a real device' loop is unreasonably effective
- (existing entries kept verbatim)
Final length: ~6800 words, 27 dated sections plus the lessons list.
CHANGELOG.md — new file. Single 2026.5.10 entry under Keep-a-Changelog-
ish format, broken into seven sections matching the project layers:
Protocol layer (RE findings), Library, Home Assistant integration,
Tests, Developer tooling, Documentation, Known gaps. Cites the source
line numbers for the two non-public protocol quirks. Lists every
public module + every entity platform. Linked to git tag template at
the bottom (release not pushed yet).
Tests still 351 + 1 skip. No code changed.
