feat(events): expand IoX-6 system event taxonomy from UDI's UDEvents.h (#176)

Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>

Author: shbatm

pyisyox/__init__.py

@@ -95,7 +95,9 @@ async def main():
     SecuritySystemAction,
     StatusListener,
     SystemConfigAction,
+    SystemEditorAction,
     SystemEventControl,
+    SystemUpgradeAction,
     TriggerAction,
     Variable,
     VariableTableChangeEvent,
@@ -171,7 +173,9 @@ async def main():
     "SecuritySystemAction",
     "StatusListener",
     "SystemConfigAction",
+    "SystemEditorAction",
     "SystemEventControl",
+    "SystemUpgradeAction",
     "TLSVersionError",
     "TriggerAction",
     "Variable",

pyisyox/runtime/__init__.py

@@ -27,7 +27,9 @@
     ProgressAction,
     SecuritySystemAction,
     SystemConfigAction,
+    SystemEditorAction,
     SystemEventControl,
+    SystemUpgradeAction,
     TriggerAction,
     VariableTableChangeEvent,
     VariableTableChangeListener,
@@ -70,7 +72,9 @@
     "SecuritySystemAction",
     "StatusListener",
     "SystemConfigAction",
+    "SystemEditorAction",
     "SystemEventControl",
+    "SystemUpgradeAction",
     "TriggerAction",
     "Variable",
     "VariableTableChangeEvent",

pyisyox/runtime/events.py

@@ -48,9 +48,11 @@ class SystemEventControl(StrEnum):
     underscore-prefixed codes with an empty ``node_address``.
 
     Codes ``_0``-``_23`` are the full ISY-994 set from the *ISY994
-    Developer Cookbook* §8.5; ``_28`` is an IoX-6 addition (Matter)
-    not in that document. Newer IoX firmware emits a few more
-    undocumented codes — those aren't enumerated; :meth:`label` passes
+    Developer Cookbook* §8.5; ``_24``-``_28`` are IoX-6 additions
+    (system editors, the modern Z-Wave / ZigBee / Matter drivers,
+    system upgrade) not in that document — tracked from UDI's
+    internal ``UDEvents.h`` taxonomy. Newer IoX firmware may emit
+    further codes; those aren't enumerated, and :meth:`label` passes
     them through verbatim so logs still identify them.
     """
 
@@ -110,24 +112,53 @@ class SystemEventControl(StrEnum):
     UPB_DEVICE_STATUS = "_16"
     #: Gas-meter events — ISY994 only.
     GAS_METER = "_17"
-    #: Zigbee events — ISY994 only.
+    #: Legacy ZigBee events — ISY994-era driver. See :attr:`ZIGBEE_UYB`
+    #: (``_27``) for the IoX-6+ ZigBee driver used on eisy.
     ZIGBEE = "_18"
     #: ELK alarm-panel events — requires the ELK module (see the ELK
     #: Integration Developer's Manual).
     ELK = "_19"
     #: Device-linker events — ``<action>`` 1 (status) / 2 (cleared).
     #: See :class:`DeviceLinkerAction`.
     DEVICE_LINKER = "_20"
-    #: Z-Wave integration events — requires the Z-Wave module (see the
-    #: Z-Wave Integration Developer's Manual).
+    #: Legacy Z-Wave integration events — ISY994-era driver. See
+    #: :attr:`ZMATTER_ZWAVE` (``_25``) for the IoX-6+ ZMatter Z-Wave
+    #: driver used on eisy.
     ZWAVE = "_21"
     #: Billing events — ISY994 ZS-series only.
     BILLING = "_22"
     #: Portal events — portal socket-connection / account-registration
     #: status when a portal module is installed.
     PORTAL = "_23"
-    #: Matter network status — IoX 6+ with the Matter module. Not in
-    #: the ISY994 cookbook.
+    #: System editor changed — fired when a "system editor" (e.g.
+    #: ``_sys_notify_short``) is updated. ``<node>`` carries the editor
+    #: name. ``<action>`` is :class:`SystemEditorAction`. IoX-6 addition.
+    SYSTEM_EDITOR = "_24"
+    #: ZMatter Z-Wave events — IoX-6+ Z-Wave driver on eisy hardware.
+    #: ``<action>`` is dotted (``"{category}.{type}"``); category
+    #: numbers are system-status (1), discovery (2), general-status (3),
+    #: general-error (4), S2 (5), OTA (6), backup/restore (7), device-
+    #: interview (8), button-detect (9), logger (10). Sub-action details
+    #: aren't modelled — the dotted string passes through verbatim.
+    #: Distinct from :attr:`ZWAVE` (``_21``, ISY994-era driver).
+    ZMATTER_ZWAVE = "_25"
+    #: System-upgrade lifecycle — ``<action>`` is :class:`SystemUpgradeAction`
+    #: (active / inactive / available / reboot-required). IoX-6 addition.
+    SYSTEM_UPGRADE = "_26"
+    #: ZigBee events — IoX-6+ ZigBee driver on eisy hardware. Same
+    #: dotted ``"{category}.{type}"`` action shape as :attr:`ZMATTER_ZWAVE`
+    #: (minus the logger sub-category). Distinct from :attr:`ZIGBEE`
+    #: (``_18``, ISY994-era driver).
+    ZIGBEE_UYB = "_27"
+    #: Matter network status — IoX-6+ Matter driver. ``<action>`` is
+    #: dotted; active sub-categories are 1 (system status), 2 (discovery),
+    #: 3 (RX/TX), 8 (device interview). Not in the ISY994 cookbook.
+    #:
+    #: **Note:** ``_28`` is also reserved in UDI's source for Profile
+    #: change events (actions 1-8 — profile/editor/nodedef/linkdef
+    #: updated/deleted) — but no firmware path fires those today
+    #: (placeholders since Dec 2024 per UDI). Don't subscribe expecting
+    #: them.
     MATTER_STATUS = "_28"
 
     @classmethod
@@ -281,6 +312,39 @@ def label(cls, value: str) -> str:
         return _enum_label(cls, value)
 
 
+class SystemUpgradeAction(StrEnum):
+    """Action codes on :attr:`SystemEventControl.SYSTEM_UPGRADE` (``_26``)
+    frames — IoX-6 firmware-upgrade lifecycle."""
+
+    #: Upgrade in progress.
+    ACTIVE = "1"
+    #: Upgrade not active (post-completion or idle).
+    INACTIVE = "2"
+    #: A new upgrade is available to install.
+    AVAILABLE = "3"
+    #: Upgrade applied; reboot required to take effect.
+    REBOOT_REQUIRED = "4"
+
+    @classmethod
+    def label(cls, value: str) -> str:
+        """Friendly lower-case name, or the raw value."""
+        return _enum_label(cls, value)
+
+
+class SystemEditorAction(StrEnum):
+    """Action codes on :attr:`SystemEventControl.SYSTEM_EDITOR` (``_24``)
+    frames. The ``<node>`` slot carries the editor name (e.g.
+    ``_sys_notify_short``)."""
+
+    #: A system editor's contents changed.
+    EDITOR_CHANGED = "1"
+
+    @classmethod
+    def label(cls, value: str) -> str:
+        """Friendly lower-case name, or the raw value."""
+        return _enum_label(cls, value)
+
+
 class DeviceWriteAction(StrEnum):
     """Device-write sub-codes that ride through on ``_7``
     (:attr:`SystemEventControl.PROGRESS`) frames — PyISY 3.x surfaced
@@ -359,6 +423,20 @@ class NodeLifecycleAction(StrEnum):
     #: should discard cached info for the node and rebuild it.
     #: ``<eventInfo>`` carries the full ``<node>`` structure.
     NODE_REVISED = "RV"
+    #: Supported-type info changed — the node's nodedef assignment was
+    #: reassigned (e.g. a node server's ``changeNode``, or a device
+    #: driver detecting new capabilities). The primary signal that a
+    #: cached nodedef → entity mapping is stale. *Not* fired for
+    #: ``/rest/profiles`` definition updates or moves, or at startup
+    #: migration — those rewrite the profile DB without notifying.
+    NODE_TYPE_INFO_CHANGED = "NI"
+    #: All nodes for a single device have been added (bulk). Fired
+    #: after an include / re-pair so consumers can coalesce a single
+    #: refresh per device instead of per child node.
+    ALL_NODES_ADDED = "AA"
+    #: Scene link updated — a link's properties (on-level / ramp rate)
+    #: changed for an existing scene member.
+    LINK_UPDATED = "LU"
     #: Discovering nodes (linking in progress). No node.
     DISCOVERING_NODES = "SN"
     #: Node discovery complete. No node.
@@ -419,6 +497,9 @@ def label(cls, value: str) -> str:
     NodeLifecycleAction.PENDING_DEVICE_OP: (),
     NodeLifecycleAction.PROGRAMMING_DEVICE: (),
     NodeLifecycleAction.NODE_REVISED: (),  # plus the full <node> structure
+    NodeLifecycleAction.NODE_TYPE_INFO_CHANGED: (),
+    NodeLifecycleAction.ALL_NODES_ADDED: (),
+    NodeLifecycleAction.LINK_UPDATED: (),
     NodeLifecycleAction.DISCOVERING_NODES: (),
     NodeLifecycleAction.NODE_DISCOVERY_COMPLETE: (),
     NodeLifecycleAction.NODE_ERROR: (),
@@ -454,6 +535,8 @@ def label(cls, value: str) -> str:
     SystemEventControl.PROGRESS: ProgressAction,
     SystemEventControl.SECURITY_SYSTEM: SecuritySystemAction,
     SystemEventControl.DEVICE_LINKER: DeviceLinkerAction,
+    SystemEventControl.SYSTEM_EDITOR: SystemEditorAction,
+    SystemEventControl.SYSTEM_UPGRADE: SystemUpgradeAction,
 }
 
 
@@ -472,7 +555,9 @@ def describe_system_event(control: str, action: str) -> str:
     * ``"_0"`` / ``"90"`` → ``"heartbeat = 90"`` (action = seconds to
       the next heartbeat; not enumerated)
     * ``"_28"`` / ``"1.3"`` → ``"matter_status = 1.3"`` (no enum)
-    * ``"_26"`` / ``"2"`` → ``"_26 = 2"`` (control we don't recognise —
+    * ``"_26"`` / ``"2"`` → ``"system_upgrade = inactive"``
+    * ``"_24"`` / ``"1"`` → ``"system_editor = editor_changed"``
+    * ``"_99"`` / ``"x"`` → ``"_99 = x"`` (control we don't recognise —
       both halves pass through verbatim)
 
     Intended for the debug logging consumers do over raw event frames
@@ -623,20 +708,27 @@ def requires_reload(self) -> bool:
         Reload-worthy: ``ND`` / ``NR`` / ``NN`` (node added/removed/renamed
         — the registry's set or display names are stale), ``EN``
         (enabled/disabled — the entity's property shape may change),
-        ``RV`` (revised — discard and rebuild this node), ``RG`` (removed
-        from scene — membership changed), ``SC`` (node-discovery complete
-        — new nodes may have appeared), and the folder/scene tree verbs
+        ``RV`` (revised — discard and rebuild this node), ``NI``
+        (supported-type info changed — the node's nodedef assignment was
+        reassigned, so the cached nodedef→entity mapping is stale; per
+        UDI's notification taxonomy this is *the* primary signal for
+        profile-related node changes), ``AA`` (all-nodes-added bulk
+        signal after a device include), ``RG`` (removed from scene —
+        membership changed), ``SC`` (node-discovery complete — new
+        nodes may have appeared), and the folder/scene tree verbs
         ``FD`` / ``FR`` / ``FN`` / ``GD`` / ``GR`` / ``GN`` (the
         ``groups`` / ``folders`` registries are stale).
 
         Softer signals — informational, don't trigger reload UX:
         ``MV`` (added to scene), ``CL`` (link changed — not supported),
-        ``PC`` (parent changed), ``PI`` (power info), ``DI`` (device id —
-        not implemented), ``DP`` (UPB property), ``WH`` (pending op),
-        ``WD`` (programming device — a property-update event follows),
-        ``SN`` (discovering nodes — wait for ``SC``), ``CE`` / ``NE``
-        (comm error/cleared — no shape change), ``WR`` (a networking
-        resource was renamed — doesn't touch nodes).
+        ``LU`` (scene link's on-level/ramp updated — property change,
+        not shape change), ``PC`` (parent changed), ``PI`` (power
+        info), ``DI`` (device id — not implemented), ``DP`` (UPB
+        property), ``WH`` (pending op), ``WD`` (programming device — a
+        property-update event follows), ``SN`` (discovering nodes —
+        wait for ``SC``), ``CE`` / ``NE`` (comm error/cleared — no
+        shape change), ``WR`` (a networking resource was renamed —
+        doesn't touch nodes).
         """
         return self.action in {
             NodeLifecycleAction.NODE_ADDED,
@@ -645,6 +737,8 @@ def requires_reload(self) -> bool:
             NodeLifecycleAction.NODE_REMOVED_FROM_GROUP,
             NodeLifecycleAction.NODE_ENABLED,
             NodeLifecycleAction.NODE_REVISED,
+            NodeLifecycleAction.NODE_TYPE_INFO_CHANGED,
+            NodeLifecycleAction.ALL_NODES_ADDED,
             NodeLifecycleAction.NODE_DISCOVERY_COMPLETE,
             NodeLifecycleAction.FOLDER_ADDED,
             NodeLifecycleAction.FOLDER_REMOVED,

tests/test_runtime/test_events_internal.py

@@ -28,7 +28,9 @@
     ProgressAction,
     SecuritySystemAction,
     SystemConfigAction,
+    SystemEditorAction,
     SystemEventControl,
+    SystemUpgradeAction,
     TriggerAction,
     VariableTableChangeEvent,
     _compact_event_info,
@@ -55,6 +57,11 @@
         (SecuritySystemAction, SecuritySystemAction.DISARMED),
         (DeviceLinkerAction, DeviceLinkerAction.STATUS),
         (NodeLifecycleAction, NodeLifecycleAction.NODE_ENABLED),
+        (NodeLifecycleAction, NodeLifecycleAction.NODE_TYPE_INFO_CHANGED),
+        (NodeLifecycleAction, NodeLifecycleAction.ALL_NODES_ADDED),
+        (NodeLifecycleAction, NodeLifecycleAction.LINK_UPDATED),
+        (SystemEditorAction, SystemEditorAction.EDITOR_CHANGED),
+        (SystemUpgradeAction, SystemUpgradeAction.AVAILABLE),
     ],
 )
 def test_enum_label_known_returns_friendly_name(enum_cls: type, known_value: str) -> None:
@@ -78,6 +85,8 @@ def test_enum_label_known_returns_friendly_name(enum_cls: type, known_value: str
         SecuritySystemAction,
         DeviceLinkerAction,
         NodeLifecycleAction,
+        SystemEditorAction,
+        SystemUpgradeAction,
     ],
 )
 def test_enum_label_unknown_passes_through_raw_value(enum_cls: type) -> None:

tests/test_runtime/test_lifecycle.py

@@ -42,7 +42,18 @@
         ("_0", "90", "heartbeat = 90"),  # action = seconds; not enumerated
         ("_23", "1", "portal = 1"),  # control known, no action enum
         ("_28", "1.3", "matter_status = 1.3"),  # no enum for matter status
-        ("_26", "2", "_26 = 2"),  # unknown control — both halves verbatim
+        ("_24", "1", "system_editor = editor_changed"),
+        ("_25", "1.3", "zmatter_zwave = 1.3"),  # dotted action passes through
+        ("_26", "1", "system_upgrade = active"),
+        ("_26", "2", "system_upgrade = inactive"),
+        ("_26", "3", "system_upgrade = available"),
+        ("_26", "4", "system_upgrade = reboot_required"),
+        ("_27", "2.5", "zigbee_uyb = 2.5"),  # dotted action passes through
+        ("_99", "x", "_99 = x"),  # unknown control — both halves verbatim
+        # _3 lifecycle additions
+        ("_3", "NI", "node_lifecycle = node_type_info_changed"),
+        ("_3", "AA", "node_lifecycle = all_nodes_added"),
+        ("_3", "LU", "node_lifecycle = link_updated"),
     ],
 )
 def test_describe_system_event(control: str, action: str, expected: str) -> None:
@@ -141,6 +152,61 @@ def test_lifecycle_listener_unwraps_action_to_typed_enum() -> None:
     assert received[0].node_xml is None  # no <eventInfo><node> on removes
 
 
+def test_lifecycle_listener_fires_on_node_type_info_changed() -> None:
+    """``NI`` is the primary signal that a node's nodedef assignment
+    changed (the cached nodedef→entity mapping is stale). Per UDI's
+    notification taxonomy it should fan through the lifecycle channel
+    with ``requires_reload=True``."""
+    frame = (
+        '<Event seqnum="55"><control>_3</control><action>NI</action>'
+        "<node>n009_harmonyctrl</node><eventInfo/></Event>"
+    )
+    dispatcher = EventDispatcher({})
+    received: list[NodeLifecycleEvent] = []
+    dispatcher.add_lifecycle_listener(received.append)
+
+    dispatcher.feed(frame)
+
+    assert len(received) == 1
+    assert received[0].action is NodeLifecycleAction.NODE_TYPE_INFO_CHANGED
+    assert received[0].node_address == "n009_harmonyctrl"
+    assert received[0].requires_reload is True
+
+
+def test_lifecycle_listener_fires_on_all_nodes_added() -> None:
+    """``AA`` is the bulk include-complete signal — reload-worthy so
+    consumers can coalesce one refresh per device instead of per child."""
+    frame = (
+        '<Event seqnum="56"><control>_3</control><action>AA</action>'
+        "<node>n009_harmonyctrl</node><eventInfo/></Event>"
+    )
+    dispatcher = EventDispatcher({})
+    received: list[NodeLifecycleEvent] = []
+    dispatcher.add_lifecycle_listener(received.append)
+
+    dispatcher.feed(frame)
+
+    assert received[0].action is NodeLifecycleAction.ALL_NODES_ADDED
+    assert received[0].requires_reload is True
+
+
+def test_link_updated_is_not_reload_worthy() -> None:
+    """``LU`` is a scene-link property update (on-level / ramp rate) —
+    softer signal, no shape change; should not flip ``requires_reload``."""
+    frame = (
+        '<Event seqnum="57"><control>_3</control><action>LU</action>'
+        "<node>3D 7D 87 1</node><eventInfo/></Event>"
+    )
+    dispatcher = EventDispatcher({})
+    received: list[NodeLifecycleEvent] = []
+    dispatcher.add_lifecycle_listener(received.append)
+
+    dispatcher.feed(frame)
+
+    assert received[0].action is NodeLifecycleAction.LINK_UPDATED
+    assert received[0].requires_reload is False
+
+
 def test_lifecycle_listener_passes_through_unknown_actions_as_strings() -> None:
     """A future control-3 verb that isn't in NodeLifecycleAction comes
     through with action=raw_string so consumers can still react."""
@@ -233,6 +299,8 @@ def test_lifecycle_requires_reload_taxonomy() -> None:
         NodeLifecycleAction.NODE_REMOVED_FROM_GROUP,  # RG (scene-edit)
         NodeLifecycleAction.NODE_ENABLED,  # EN — covers both directions
         NodeLifecycleAction.NODE_REVISED,  # RV
+        NodeLifecycleAction.NODE_TYPE_INFO_CHANGED,  # NI — nodedef reassigned
+        NodeLifecycleAction.ALL_NODES_ADDED,  # AA — bulk include-complete
         NodeLifecycleAction.NODE_DISCOVERY_COMPLETE,  # SC — new nodes may have appeared
         NodeLifecycleAction.FOLDER_ADDED,  # FD
         NodeLifecycleAction.FOLDER_REMOVED,  # FR
@@ -244,6 +312,7 @@ def test_lifecycle_requires_reload_taxonomy() -> None:
     soft_actions = {
         NodeLifecycleAction.NODE_MOVED,  # MV (added to scene)
         NodeLifecycleAction.LINK_CHANGED,  # CL — not supported
+        NodeLifecycleAction.LINK_UPDATED,  # LU — scene link on-level/ramp change
         NodeLifecycleAction.PARENT_CHANGED,  # PC
         NodeLifecycleAction.POWER_INFO_CHANGED,  # PI
         NodeLifecycleAction.DEVICE_ID_CHANGED,  # DI — not implemented