Enhance Protocol handling: add ProtocolType model, update Protocol enum with labels, and implement protocol enum generation script

Author: iMicknl

pyoverkiz/client.py

@@ -61,6 +61,7 @@
     Option,
     OptionParameter,
     Place,
+    ProtocolType,
     ServerConfig,
     Setup,
     State,
@@ -669,9 +670,17 @@ async def search_reference_devices_model(self, payload: JSON) -> JSON:
         return await self.__post("reference/devices/search", payload)
 
     @retry_on_auth_error
-    async def get_reference_protocol_types(self) -> JSON:
-        """Get details about supported protocol types on that server instance."""
-        return await self.__get("reference/protocolTypes")
+    async def get_reference_protocol_types(self) -> list[ProtocolType]:
+        """Get details about supported protocol types on that server instance.
+
+        Returns a list of protocol type definitions, each containing:
+        - id: Numeric protocol identifier
+        - prefix: URL prefix used in device addresses
+        - name: Internal protocol name
+        - label: Human-readable protocol label
+        """
+        response = await self.__get("reference/protocolTypes")
+        return [ProtocolType(**protocol) for protocol in response]
 
     @retry_on_auth_error
     async def get_reference_timezones(self) -> JSON:

pyoverkiz/enums/protocol.py

@@ -1,4 +1,8 @@
-"""Protocol enums describe device URL schemes used by Overkiz."""
+"""Protocol enums describe device URL schemes used by Overkiz.
+
+THIS FILE IS AUTO-GENERATED. DO NOT EDIT MANUALLY.
+Run `uv run utils/generate_enums.py` to regenerate.
+"""
 
 from enum import StrEnum, unique
 
@@ -14,33 +18,33 @@ class Protocol(UnknownEnumMixin, StrEnum):
 
     UNKNOWN = "unknown"
 
-    AUGUST = "august"
-    CAMERA = "camera"
-    ELIOT = "eliot"
-    ENOCEAN = "enocean"
+    AUGUST = "august"  # 59: August Webservices
+    CAMERA = "camera"  # 13: Generic Camera Control Protocol
+    ELIOT = "eliot"  # 45: Eliot Webservices
+    ENOCEAN = "enocean"  # 7: EnOcean
     HLRR_WIFI = "hlrrwifi"
-    HOMEKIT = "homekit"
-    HUE = "hue"
-    INTERNAL = "internal"
-    IO = "io"
-    JSW = "jsw"
-    MODBUS = "modbus"
+    HOMEKIT = "homekit"  # 48: HOMEKIT
+    HUE = "hue"  # 22: Philips HUE - Personal Wireless Lighting
+    INTERNAL = "internal"  # 29: Kizbox Internal Modules
+    IO = "io"  # 1: IO HomeControl©
+    JSW = "jsw"  # 30: JSW Webservices
+    MODBUS = "modbus"  # 20: Modbus
     MODBUSLINK = "modbuslink"
-    MYFOX = "myfox"
-    NETATMO = "netatmo"
-    OGCP = "ogcp"
-    OGP = "ogp"
-    OPENDOORS = "opendoors"
-    OVP = "ovp"
-    PROFALUX_868 = "profalux868"
-    RAMSES = "ramses"
-    RTD = "rtd"
-    RTDS = "rtds"
+    MYFOX = "myfox"  # 25: MyFox Webservices
+    NETATMO = "netatmo"  # 38: Netatmo Webservices
+    OGCP = "ogcp"  # 62: Overkiz Generic Cloud Protocol
+    OGP = "ogp"  # 56: Overkiz Generic Protocol
+    OPENDOORS = "opendoors"  # 35: OpenDoors Webservices
+    OVP = "ovp"  # 14: OVERKIZ Radio Protocol
+    PROFALUX_868 = "profalux868"  # 50: Profalux 868
+    RAMSES = "ramses"  # 6: Ramses II (Honeywell)
+    RTD = "rtd"  # 5: Domis RTD - Actuator
+    RTDS = "rtds"  # 11: Domis RTD - Sensor
     RTN = "rtn"
-    RTS = "rts"
-    SOMFY_THERMOSTAT = "somfythermostat"
-    UPNP_CONTROL = "upnpcontrol"
-    VERISURE = "verisure"
-    WISER = "wiser"
-    ZIGBEE = "zigbee"
-    ZWAVE = "zwave"
+    RTS = "rts"  # 2: Somfy RTS
+    SOMFY_THERMOSTAT = "somfythermostat"  # 39: Somfy Thermostat Webservice
+    UPNP_CONTROL = "upnpcontrol"  # 43: UPnP Control
+    VERISURE = "verisure"  # 23: Verisure Webservices
+    WISER = "wiser"  # 54: Schneider Wiser
+    ZIGBEE = "zigbee"  # 3: Zigbee
+    ZWAVE = "zwave"  # 8: Z-Wave

pyoverkiz/models.py

@@ -1030,3 +1030,20 @@ def __init__(
         self.parameters = (
             [OptionParameter(**p) for p in parameters] if parameters else []
         )
+
+
+@define(init=False, kw_only=True)
+class ProtocolType:
+    """Protocol type definition from the reference API."""
+
+    id: int
+    prefix: str
+    name: str
+    label: str
+
+    def __init__(self, id: int, prefix: str, name: str, label: str, **_: Any):
+        """Initialize ProtocolType from API data."""
+        self.id = id
+        self.prefix = prefix
+        self.name = name
+        self.label = label

utils/generate_enums.py

@@ -0,0 +1,101 @@
+"""Generate enum files from the Overkiz API reference data."""
+
+# ruff: noqa: T201
+
+from __future__ import annotations
+
+import asyncio
+import os
+from pathlib import Path
+
+from pyoverkiz.auth.credentials import UsernamePasswordCredentials
+from pyoverkiz.client import OverkizClient
+from pyoverkiz.enums import Server
+
+# Hardcoded protocols that may not be available on all servers
+# Format: (name, prefix)
+ADDITIONAL_PROTOCOLS = [
+    ("HLRR_WIFI", "hlrrwifi"),
+    ("MODBUSLINK", "modbuslink"),
+    ("RTN", "rtn"),
+]
+
+
+async def generate_protocol_enum() -> None:
+    """Generate the Protocol enum from the Overkiz API."""
+    username = os.environ["OVERKIZ_USERNAME"]
+    password = os.environ["OVERKIZ_PASSWORD"]
+
+    async with OverkizClient(
+        server=Server.SOMFY_EUROPE,
+        credentials=UsernamePasswordCredentials(username, password),
+    ) as client:
+        await client.login()
+
+        protocol_types = await client.get_reference_protocol_types()
+
+        # Build list of protocol entries (name, prefix, id, label)
+        protocols: list[tuple[str, str, int | None, str | None]] = [
+            (p.name, p.prefix, p.id, p.label) for p in protocol_types
+        ]
+
+        # Add hardcoded protocols that may not be on all servers (avoid duplicates)
+        fetched_prefixes = {p.prefix for p in protocol_types}
+        for name, prefix in ADDITIONAL_PROTOCOLS:
+            if prefix not in fetched_prefixes:
+                protocols.append((name, prefix, None, None))
+
+        # Sort by name for consistent output
+        protocols.sort(key=lambda p: p[0])
+
+        # Generate the enum file content
+        lines = [
+            '"""Protocol enums describe device URL schemes used by Overkiz.',
+            "",
+            "THIS FILE IS AUTO-GENERATED. DO NOT EDIT MANUALLY.",
+            "Run `uv run utils/generate_enums.py` to regenerate.",
+            '"""',
+            "",
+            "from enum import StrEnum, unique",
+            "",
+            "from pyoverkiz.enums.base import UnknownEnumMixin",
+            "",
+            "",
+            "@unique",
+            "class Protocol(UnknownEnumMixin, StrEnum):",
+            '    """Protocol used by Overkiz.',
+            "",
+            "    Values have been retrieved from /reference/protocolTypes",
+            '    """',
+            "",
+            '    UNKNOWN = "unknown"',
+            "",
+        ]
+
+        # Add each protocol as an enum value with label comment
+        for name, prefix, protocol_id, label in protocols:
+            if protocol_id is not None:
+                lines.append(f'    {name} = "{prefix}"  # {protocol_id}: {label}')
+            else:
+                lines.append(f'    {name} = "{prefix}"')
+
+        lines.append("")  # End with newline
+
+        # Write to the protocol.py file
+        output_path = (
+            Path(__file__).parent.parent / "pyoverkiz" / "enums" / "protocol.py"
+        )
+        output_path.write_text("\n".join(lines))
+
+        fetched_count = len(protocol_types)
+        additional_count = len(
+            [p for p in ADDITIONAL_PROTOCOLS if p[1] not in fetched_prefixes]
+        )
+
+        print(f"✓ Generated {output_path}")
+        print(f"✓ Added {fetched_count} protocols from API")
+        print(f"✓ Added {additional_count} additional hardcoded protocols")
+        print(f"✓ Total: {len(protocols)} protocols")
+
+
+asyncio.run(generate_protocol_enum())