From 259c46e5587cde4cdfa417e8bf13e8325208c690 Mon Sep 17 00:00:00 2001
From: Ryan Malloy <ryan@supported.systems>
Date: Mon, 11 May 2026 13:40:34 -0600
Subject: [PATCH] Release 2026.5.11: v1-over-UDP + HA integration

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.
---
 README.md                                | 19 +++++++++++++++++++
 custom_components/omni_pca/manifest.json |  4 ++--
 pyproject.toml                           |  2 +-
 3 files changed, 22 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index e61271c..46064c5 100644
--- a/README.md
+++ b/README.md
@@ -53,6 +53,25 @@ asyncio.run(main())
 
 For the panel walkthrough — connect, list zones, react to push events — see the [tutorial](https://hai-omni-pro-ii.warehack.ing/tutorials/first-script/).
 
+## Two wire dialects — TCP/v2 vs UDP/v1
+
+The Omni network module is configurable at the panel keypad to listen on **TCP, UDP, or both**. Each transport speaks a different wire dialect — `OmniClient` above handles the TCP path (OmniLink2, the modern wire format used by PC Access ≥ 3); panels configured UDP-only fall back to the legacy v1 protocol with typed `RequestZoneStatus` / `RequestUnitStatus` opcodes, no `RequestProperties`, and streaming name downloads. For those, use [`OmniClientV1`](https://hai-omni-pro-ii.warehack.ing/reference/library-api/#v1-udp-omniclientv1) from the `omni_pca.v1` subpackage:
+
+```python
+from omni_pca.v1 import OmniClientV1
+
+async with OmniClientV1(
+    host="192.168.1.9",
+    controller_key=bytes.fromhex("..."),
+) as panel:
+    info = await panel.get_system_information()      # same dataclass as v2
+    names = await panel.list_all_names()             # streaming UploadNames
+    zones = await panel.get_zone_status(1, 16)       # typed status by range
+    await panel.execute_security_command(area=1, mode=SecurityMode.AWAY, code=1234)
+```
+
+The HA integration picks the right client automatically based on the **Transport** dropdown in the config flow (TCP vs UDP). See [zone & unit numbering](https://hai-omni-pro-ii.warehack.ing/explanation/zone-unit-numbering/) for why v1 panels need the long-form `RequestUnitStatus` for unit indices > 255.
+
 ## Quick start (Home Assistant)
 
 ```bash
diff --git a/custom_components/omni_pca/manifest.json b/custom_components/omni_pca/manifest.json
index 2479998..cb46ec8 100644
--- a/custom_components/omni_pca/manifest.json
+++ b/custom_components/omni_pca/manifest.json
@@ -1,12 +1,12 @@
 {
     "domain": "omni_pca",
     "name": "HAI/Leviton Omni Panel",
-    "version": "2026.5.10",
+    "version": "2026.5.11",
     "iot_class": "local_push",
     "config_flow": true,
     "dependencies": [],
     "codeowners": ["@rsp2k"],
-    "requirements": ["omni-pca==2026.5.10"],
+    "requirements": ["omni-pca==2026.5.11"],
     "documentation": "https://git.supported.systems/warehack.ing/omni-pca",
     "issue_tracker": "https://git.supported.systems/warehack.ing/omni-pca/issues",
     "integration_type": "hub"
diff --git a/pyproject.toml b/pyproject.toml
index cefaa7c..562b11b 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -1,6 +1,6 @@
 [project]
 name = "omni-pca"
-version = "2026.5.10"
+version = "2026.5.11"
 description = "Async Python client for HAI/Leviton Omni-Link II home automation panels (Omni Pro II, Omni IIe, Omni LTe, Lumina)."
 readme = "README.md"
 license = { text = "MIT" }