feat: add PRT3 ASCII serial connection type

[NaanyaBiz]

Summary

This PR adds support for the Paradox PRT3 printer module as a first-class
connection type alongside the existing Serial and IP backends. The PRT3
exposes a documented ASCII serial protocol over a standard DB9/USB-serial cable,
providing a practical integration path for panels where the native binary protocol
and IP module are no longer accessible.

Motivation

Two trends have progressively closed off the existing integration paths for Paradox
panels:

1. Native serial encryption — newer EVO/Spectra firmware encrypts the binary
   serial link, making reverse-engineered integrations unreliable or broken outright
   on updated panels.

2. IP150 lockdown — recent IP150 firmware versions restrict connections from
   third-party software, breaking IP-based integrations on many panels.

The PRT3 module is unaffected by both. Paradox publishes and maintains its ASCII
protocol; it has been stable across firmware generations and works over commodity
USB-to-serial hardware. Making PRT3 a supported PAI backend preserves integration
capability for a meaningful portion of the Paradox install base.

---

Architecture

PRT3 is implemented as a peer connection type, not a wrapper around the existing
native serial path.

• PRT3SerialConnection extends SerialCommunication, overriding only the protocol
  factory to produce a line-oriented ASCII framer instead of binary.
• PRT3Panel extends the same Panel base class as EVO/Spectra panels, implementing
  all required methods via ASCII commands (RA/RZ for status, AL/ZL/UL for
  labels, AA/AQ/AD for arm/disarm, UK for utility keys, PE/PM/PF for
  panic).
• paradox.py selects PRT3 in the existing if/elif/else connection type chain.
• State flows through the same MemoryStorage → MQTT pipeline as other backends.

The only special-casing outside the prt3/ module is:

• 3 connection-selection branches (peer with IP/Serial)
• 3 protocol-gap guards (sync_time, _clean_session, control_utility_key guard)
• 1 event handler registration (PRT3 dispatches dataclass events, not binary Containers)
• 1 optional MQTT feature (utility key button discovery, gated on PRT3_UTILITY_KEYS)

Total: 9 conditionals, all justified by genuine protocol differences.

---

What's included

New files

Path	Purpose
paradox/connections/prt3/connection.py	Serial connection; ASCII line framer
paradox/connections/prt3/protocol.py	asyncio protocol; splits on \r
paradox/hardware/prt3/parser.py	Parses all PRT3 ASCII lines into dataclasses
paradox/hardware/prt3/encoder.py	Builds PRT3 command strings
paradox/hardware/prt3/panel.py	Full Panel implementation
paradox/hardware/prt3/event.py	Maps PRT3 G-group events → PAI Event objects
paradox/hardware/prt3/adapter.py	Normalises PRT3 status replies into PAI storage model
paradox/hardware/prt3/property.py	Property key definitions
paradox/hardware/prt3/runtime.py	(reserved for future PRT3-specific runtime extensions)
paradox/interfaces/mqtt/entities/button.py	UtilityKeyButton HA discovery entity
docs/prt3-usage.md	Setup, configuration, and limitations guide

Modified files

Path	Change
paradox/paradox.py	PRT3 connect path, event dispatch, utility key control, protocol guards
paradox/config.py	PRT3_* config keys, MQTT_UTILITY_KEY_TOPIC
paradox/interfaces/mqtt/entities/factory.py	make_utility_key_button()
paradox/interfaces/mqtt/homeassistant.py	_publish_utility_key_configs()
paradox/interfaces/mqtt/basic.py	Utility key MQTT subscription and handler
paradox/interfaces/mqtt/core.py	Bug fix: fire on_connect for late-registering interfaces
config/pai.conf.example	PRT3 section with annotated options

Tests

File	Coverage
tests/hardware/prt3/test_parser.py	Full parser round-trip, edge cases
tests/hardware/prt3/test_encoder.py	All command types, boundary values
tests/hardware/prt3/test_adapter.py	Area/zone status normalisation
tests/hardware/prt3/test_command_dispatch.py	Command send/echo/fail/timeout paths
tests/hardware/prt3/test_panel.py	initialize_communication, load_labels, request_status
tests/hardware/prt3/test_mqtt_integration.py	HA discovery, utility key buttons, event passthrough
tests/hardware/prt3/fixtures.py	Verified ASCII fixture lines for all message types
tests/connection/prt3/test_protocol.py	Line framing and protocol parsing

---

Configuration

CONNECTION_TYPE = 'PRT3'
PRT3_SERIAL_PORT = '/dev/ttyUSB0'
PRT3_SERIAL_BAUD = 9600
PRT3_USER_CODE = '1234'       # Required for disarm; leave empty for quick-arm only
PRT3_MAX_AREAS = 2
PRT3_MAX_ZONES = 32
PRT3_UTILITY_KEYS = {
    1: 'Lock Front Gate',
    2: 'Garden Lights',
}

Full options documented in config/pai.conf.example and docs/prt3-usage.md.

---

Known limitations (v1)

• Zone bypass/force not supported (no PRT3 command exists)
• Virtual PGM outputs parsed but not controllable
• No SetTimeDate command — SYNC_TIME is a no-op
• Area count must be set in config (panel does not report enrolled count)
• Status established by polling on connect; brief gap on reconnect is possible
• Utility keys are not idempotent — PAI deliberately sends no retries

---

Testing

pytest tests/hardware/prt3/ tests/connection/prt3/ -v

All tests use synchronous or asyncio-mocked transports; no hardware required.

[Copilot]

Pull request overview

Adds a new first-class PRT3 ASCII serial backend (Paradox PRT3 printer module) alongside existing Serial/IP paths, including parsing/encoding, panel implementation, event mapping, and MQTT/HA utility-key button support.

Changes:

• Add PRT3 connection/protocol framing and a full PRT3Panel implementation (parser, encoder, adapter, event mapping).
• Integrate PRT3 into runtime selection (paradox.py) and add protocol-gap guards plus PRT3 event dispatch.
• Extend MQTT + Home Assistant discovery with Utility Key button entities and handling; add comprehensive PRT3-focused tests and docs.

Reviewed changes

Copilot reviewed 31 out of 33 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
paradox/paradox.py	Adds PRT3 connection selection, connect path, utility-key control API, and PRT3 event dispatch integration.
paradox/config.py	Adds PRT3_* config keys and MQTT_UTILITY_KEY_TOPIC.
paradox/connections/prt3/connection.py	Introduces PRT3SerialConnection using ASCII protocol framing.
paradox/connections/prt3/protocol.py	Implements CR-delimited ASCII line framer for PRT3.
paradox/connections/prt3/__init__.py	Declares PRT3 connection package.
paradox/hardware/prt3/parser.py	Parses PRT3 ASCII lines into typed dataclasses.
paradox/hardware/prt3/encoder.py	Encodes PRT3 ASCII commands (status/labels/arm/disarm/panic/utility key).
paradox/hardware/prt3/adapter.py	Normalizes PRT3 status/labels into PAI’s storage/status formats.
paradox/hardware/prt3/event.py	Maps PRT3 G-group events into PAI Event objects.
paradox/hardware/prt3/panel.py	Implements Panel API over PRT3 polling + control + async events.
paradox/hardware/prt3/property.py	Re-exports existing property map for consistency with other panels.
paradox/hardware/prt3/__init__.py	Declares PRT3 hardware package.
paradox/lib/async_message_manager.py	Guards event/error handlers so non-binary (PRT3) messages don’t assert/crash.
paradox/lib/handlers.py	Makes “No handler” logging robust for non-Container message types.
paradox/interfaces/mqtt/core.py	Replays on_connect to late-registered interfaces (fix for missed subscriptions).
paradox/interfaces/mqtt/basic.py	Subscribes + handles PRT3 utility-key MQTT commands.
paradox/interfaces/mqtt/homeassistant.py	Publishes HA discovery configs for PRT3 utility-key buttons.
paradox/interfaces/mqtt/entities/factory.py	Adds factory method to build utility-key button entities.
paradox/interfaces/mqtt/entities/button.py	Adds UtilityKeyButton HA discovery entity for PRT3 utility keys.
paradox/interfaces/mqtt/entities/abstract_entity.py	Fixes entity prefix formatting (format_map) used in HA discovery serialization.
tests/connection/prt3/test_protocol.py	Tests PRT3 protocol framing, buffering, and send behavior.
tests/connection/prt3/__init__.py	Declares test package for PRT3 connection.
tests/hardware/prt3/fixtures.py	Adds verified PRT3 ASCII fixture lines for deterministic tests.
tests/hardware/prt3/test_parser.py	Extensive coverage of PRT3 parser behavior and edge cases.
tests/hardware/prt3/test_encoder.py	Validates command encoding, echo prefixes, ASCII, and boundaries.
tests/hardware/prt3/test_adapter.py	Tests normalization into PAI storage/status formats.
tests/hardware/prt3/test_panel.py	Tests request/reply cycles and retry behavior for panel methods.
tests/hardware/prt3/test_command_dispatch.py	Tests Paradox control dispatch for partitions and utility keys.
tests/hardware/prt3/test_mqtt_integration.py	Tests panel_detected emission, HA discovery JSON, and event passthrough.
tests/hardware/prt3/__init__.py	Declares test package for PRT3 hardware.
docs/prt3-usage.md	Documents setup, configuration, HA behavior, and limitations.
docs/prt3-architecture.md	Documents PRT3 layering, runtime wiring points, and v1 scope.
config/pai.conf.example	Adds example PRT3 configuration and MQTT utility-key topic.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[NaanyaBiz]

Thanks for the structured review (recorded in #597) — the multi-agent framing surfaced several things worth fixing. Before acting on the findings I traced each one against the code so we'd target the right things. Below is what I plan to act on, where I'd push back, and what I'd defer.

Findings I'll act on

#	Finding	Action
Bug #3	PRT3BufferFull not in _prt3_send_wait predicates	Add a PRT3BufferFull predicate and fast-fail/retry on !
Bug #4	Invalid PRT3_USER_CODE raises ValueError at arm time	Validate format (^\d{1,6}$) at config load, not first use
Arch #3	Empty runtime.py placeholder	Delete
Minor #1	PRT3_SERIAL_BAUD accepts non-hardware values	Set validator [9600, 19200] (matches CONNECTION_TYPE pattern)
Minor #2	G065 per-N overrides bypass EVENT_MAP	Surface them as a "number_overrides" nested dict in EVENT_MAP
Minor #4	Bare except Exception in handle_prt3_event_message	Catch expected (KeyError/AttributeError) explicitly with warning
Minor #5	User code visible if byte-level serial trace is enabled	Doc note + mask in retry warning path
Minor #6	Missing tests: reconnect, buffer-full, bad config at arm time	Add coverage

Findings whose impact I read differently

Bug #1 — assert → return False in async_message_manager.py

For binary users only Container objects ever flow into these handlers, so neither the assert nor the guard ever fires — there's no behaviour change for them. For PRT3 users, EventMessageHandler and ErrorMessageHandler are registered alongside the PRT3 handler in paradox.py _register_connection_handlers. Without the guard, every PRT3 dataclass would trigger AssertionError on the first line of can_handle, making PRT3 mode unusable.

The architectural critique is solid though, and I'd happily take it further: register EventMessageHandler/ErrorMessageHandler only for binary connection types and a dedicated PRT3 handler only for PRT3, so the guard isn't needed at all. That fits naturally into the Arch #2 polymorphism cleanup if/when we tackle it.

Bug #2 — on_connect fallback args

The synthetic-None fallback exists to cover a microsecond race between self.state = CONNECTED (core.py:222) and self._last_connect_args = (...) (line 223) — the callback runs on the MQTT thread, so a registrar reading self.connected between those two assignments could see True with _last_connect_args still None. Both current on_connect overrides (basic.py:120, homeassistant.py:59) ignore reason_code, so the AttributeError path has no live target today.

That said, the suggested fix (skip replay when _last_connect_args is None) is strictly better — defensive against any future handler that does inspect reason_code. I'll change it. Fair point on the separate commit too; we can't unscramble it now but I'll keep that discipline going forward.

Bug #3 — severity scoping

Real defect, agreed on the fix. The n × IO_TIMEOUT freeze claim doesn't hold up against the code: _prt3_send_wait runs under core.request_lock and each call carries its own IO_TIMEOUT. A single buffer overflow costs one timeout (plus its retry) on the affected command, not a multi-minute cascade across load_labels. Worth fixing for clean retry semantics, not because startup will hang.

Bug #4 — severity scoping

Real defect, agreed on the fix. The "crashing the run loop" framing isn't quite right: the MQTT path is wrapped by mqtt_handle_decorator (basic.py:31-35) which catches Exception and logs; the text path runs under asyncio task supervision. The user-visible symptom is silent failure of every arm/disarm with stack traces in the log — bad UX, not a process crash. Validating at config load is still the right answer.

Minor #3 — control_zones / control_outputs raise instead of returning False

The orchestrator catches it: paradox.py:497-516 (control_zone) and paradox.py:630-647 (control_output) both except NotImplementedError and return False. The MQTT handler never sees the exception, so the Panel interface contract is honoured at the call site even though the panel-level method raises. I'd leave this as-is unless I'm misreading the path.

Deferring

Arch #1 (LSP) and Arch #2 (string guards) — agreed in principle, both worth doing. The concrete behaviour issues they cite are mitigated by Minor #3 above, so I'd fold the cleanup into a follow-up rather than the v1 merge: extract BinaryPanel, replace the 5 candidate guards with Panel methods, and (per Bug #1 above) wire handler registration through Panel.register_protocol_handlers(connection) so the Container guard becomes unnecessary.

Heads-up

While integration-testing on a live EVO192 panel over the last day, three orthogonal arm/disarm state bugs surfaced and are fixed in 3fe0b14e on the branch:

• G014 with area=0 (global keypad disarm) was silently dropped because get_container_object("partition", 0) returns None. Now broadcast to all partitions.
• G013 was mapped as "auto-armed" (arm=True); per PRT3 spec page 18 it's "Disarm with Master". When a master code disarmed, _update_partition_states fell through to the armed_away else branch.
• HA showed a transient armed_stay state for 4-7 s after disarm-during-exit-delay because RA polls return stale armed_stay for ~hundreds of ms after AD&OK while the panel internally settles. Now applies disarmed state optimistically on &OK echo and freezes arm-key updates from RA for 3 s.

Architecture notes on the three-source state model (RA polling, G-events, command echo) added to docs/prt3-architecture.md. None of it overlaps with this review's findings, but flagging in case it changes how you'd want to sequence the merge.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.8% Duplication on New Code

See analysis details on SonarQube Cloud