Python SDK: Make Cohn feature backwards compatible (#757)

This PR updates the SDK to support legacy COHN protobuf flows by introducing a unified `ProtobufId` identifier, adding support checks via a `require_supported` decorator, and enhancing the response parser and routing to handle unsupported protobuf responses gracefully.

- Introduce `ProtobufId` type and update all parsers/commands to use it
- Add `require_supported` decorator and `is_supported` checks for features
- Extend `BleRespBuilder` and `_route_response` to identify and route unsupported protobuf errors
- Update tests and mocks to cover new unsupported-CoHN behavior
- Bump third-party dependency versions and enable debug logging for response parsing

<details>
<summary>Show a summary per file</summary>

| File                                                                            | Description                                                     |
| ------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| demos/python/sdk_wireless_camera_control/thirdPartyDependencies.csv            | Bump `packaging` to 25.0 and `protobuf` to 6.31.0               |
| demos/python/sdk_wireless_camera_control/tests/unit/test_wireless_gopro.py      | Add unsupported protobuf operation test; update imports        |
| demos/python/sdk_wireless_camera_control/tests/unit/test_responses.py          | Add and adjust tests for unsupported protobuf responses         |
| demos/python/sdk_wireless_camera_control/tests/unit/test_ble_commands.py       | Import new `ErrorCode` and `FeatureId` for BLE command tests    |
| demos/python/sdk_wireless_camera_control/tests/mocks.py                        | Extend mocks for protobuf and remove legacy BLE send override   |
| demos/python/sdk_wireless_camera_control/open_gopro/util/logger.py             | Enable DEBUG logging for `open_gopro.parsers.response`          |
| demos/python/sdk_wireless_camera_control/open_gopro/parsers/response.py        | Add `validResponseProtobufIds` and handle missing action IDs    |
| demos/python/sdk_wireless_camera_control/open_gopro/models/types.py            | Introduce `ProtobufId` and update `ResponseType`                |
| demos/python/sdk_wireless_camera_control/open_gopro/models/constants/constants.py | Remove deprecated `PROTOBUF_QUERY` enum                         |
| demos/python/sdk_wireless_camera_control/open_gopro/gopro_wireless.py          | Enhance `_route_response` to match unsupported protobuf errors  |
| demos/python/sdk_wireless_camera_control/open_gopro/features/base_feature.py   | Implement `require_supported` decorator and `is_supported` abstract property |
| demos/python/sdk_wireless_camera_control/open_gopro/features/cohn_feature.py   | Add support tracking and guard methods with `require_supported` |
| demos/python/sdk_wireless_camera_control/open_gopro/features/streaming/stream_feature.py | Add `is_supported` property                                    |
| demos/python/sdk_wireless_camera_control/open_gopro/features/access_point_feature.py | Add `is_supported` property                                    |
| demos/python/sdk_wireless_camera_control/open_gopro/api/builders.py            | Update `BleProtoCommand` to use `ProtobufId`                    |
| demos/python/sdk_wireless_camera_control/open_gopro/api/ble_commands.py        | Update protobuf commands to use `ProtobufId` in `additional_matching_ids` |
</details>

Author: tcamise-gpsw

demos/python/sdk_wireless_camera_control/open_gopro/api/ble_commands.py

@@ -49,7 +49,7 @@
     SettingId,
     StatusId,
 )
-from open_gopro.models.types import CameraState
+from open_gopro.models.types import CameraState, ProtobufId
 from open_gopro.parsers.bytes import (
     ConstructByteParserBuilder,
     DateTimeByteParserBuilder,
@@ -306,9 +306,7 @@ async def get_date_time_tz_dst(self) -> GoProResp[TzDstDateTime]:
     @ble_write_command(
         uuid=GoProUUID.CQ_COMMAND,
         cmd=CmdId.REBOOT,
-        rules=MessageRules(
-            fastpass_analyzer=lambda **_: True,
-        ),
+        rules=MessageRules(fastpass_analyzer=lambda **_: True),
     )
     async def reboot(self) -> GoProResp[None]:
         """Reboot the camera (approximating a battery pull)
@@ -430,7 +428,7 @@ async def set_turbo_mode(self, *, mode: constants.Toggle) -> GoProResp[None]:
         response_action_id=ActionId.GET_PRESET_STATUS_RSP,
         request_proto=proto.RequestGetPresetStatus,
         response_proto=proto.NotifyPresetStatus,
-        additional_matching_ids={ActionId.PRESET_MODIFIED_NOTIFICATION},
+        additional_matching_ids={ProtobufId(FeatureId.QUERY, ActionId.PRESET_MODIFIED_NOTIFICATION)},
     )
     async def get_preset_status(
         self,
@@ -559,7 +557,7 @@ async def get_ap_entries(
         response_action_id=ActionId.REQUEST_WIFI_CONNECT_RSP,
         request_proto=proto.RequestConnect,
         response_proto=proto.ResponseConnect,
-        additional_matching_ids={ActionId.REQUEST_WIFI_CONNECT_RSP},
+        additional_matching_ids={ProtobufId(FeatureId.NETWORK_MANAGEMENT, ActionId.REQUEST_WIFI_CONNECT_RSP)},
     )
     async def request_wifi_connect(self, *, ssid: str) -> GoProResp[proto.ResponseConnect]:
         """Request the camera to connect to a WiFi network that is already provisioned.
@@ -580,7 +578,7 @@ async def request_wifi_connect(self, *, ssid: str) -> GoProResp[proto.ResponseCo
         response_action_id=ActionId.REQUEST_WIFI_CONNECT_NEW_RSP,
         request_proto=proto.RequestConnectNew,
         response_proto=proto.ResponseConnectNew,
-        additional_matching_ids={ActionId.REQUEST_WIFI_CONNECT_NEW_RSP},
+        additional_matching_ids={ProtobufId(FeatureId.NETWORK_MANAGEMENT, ActionId.REQUEST_WIFI_CONNECT_NEW_RSP)},
     )
     async def request_wifi_connect_new(self, *, ssid: str, password: str) -> GoProResp[proto.ResponseConnectNew]:
         """Request the camera to connect to a WiFi network that is not already provisioned.
@@ -666,7 +664,7 @@ async def set_livestream_mode(
         response_action_id=ActionId.LIVESTREAM_STATUS_RSP,
         request_proto=proto.RequestGetLiveStreamStatus,
         response_proto=proto.NotifyLiveStreamStatus,
-        additional_matching_ids={ActionId.LIVESTREAM_STATUS_NOTIF},
+        additional_matching_ids={ProtobufId(FeatureId.QUERY, ActionId.LIVESTREAM_STATUS_NOTIF)},
     )
     async def register_livestream_status(
         self,
@@ -694,6 +692,7 @@ async def register_livestream_status(
         response_action_id=ActionId.RELEASE_NETWORK_RSP,
         request_proto=proto.RequestReleaseNetwork,
         response_proto=proto.ResponseGeneric,
+        rules=MessageRules(fastpass_analyzer=lambda **_: True),
     )
     async def release_network(self) -> GoProResp[None]:
         """Disconnect the camera Wifi network in STA mode so that it returns to AP mode.
@@ -819,5 +818,5 @@ class BleAsyncResponses:
     def add_parsers(cls) -> None:
         """Add all of the defined asynchronous responses to the global parser map"""
         for response in cls.responses:
-            GlobalParsers.add(response.action_id, response.parser)
+            GlobalParsers.add(ProtobufId(response.feature_id, response.action_id), response.parser)
             GlobalParsers.add_feature_action_id_mapping(response.feature_id, response.action_id)

demos/python/sdk_wireless_camera_control/open_gopro/api/builders.py

@@ -44,7 +44,7 @@
     SettingId,
     StatusId,
 )
-from open_gopro.models.types import CameraState, JsonDict, Protobuf
+from open_gopro.models.types import CameraState, JsonDict, Protobuf, ProtobufId
 from open_gopro.network.ble import BleUUID
 from open_gopro.parsers.bytes import (
     ConstructByteParserBuilder,
@@ -193,7 +193,7 @@ class BleProtoCommand(BleMessage):
         request_proto (type[Protobuf]): the action ID that will be in the response
         response_proto (type[Protobuf]): protobuf used to parse received bytestream
         parser (Parser | None): Optional response parser. Defaults to None.
-        additional_matching_ids (set[ActionId | CmdId] | None): Other action ID's to share this parser. This is used, for
+        additional_matching_ids (set[ProtobufId | CmdId] | None): Other action ID's to share this parser. This is used, for
             example, if a notification shares the same ID as the synchronous response. Defaults to None. Defaults to None.
     """
 
@@ -206,19 +206,19 @@ def __init__(
         request_proto: type[Protobuf],
         response_proto: type[Protobuf],
         parser: Parser | None,
-        additional_matching_ids: set[ActionId | CmdId] | None = None,
+        additional_matching_ids: set[ProtobufId | CmdId] | None = None,
     ) -> None:
         p = parser or Parser()
         p.byte_json_adapter = ProtobufByteParser(response_proto)
-        super().__init__(uuid=uuid, parser=p, identifier=response_action_id)
+        super().__init__(uuid=uuid, parser=p, identifier=ProtobufId(feature_id, response_action_id))
         self.feature_id = feature_id
         self.action_id = action_id
         self.response_action_id = response_action_id
         self.request_proto = request_proto
         self.response_proto = response_proto
-        self.additional_matching_ids: set[ActionId | CmdId] = additional_matching_ids or set()
+        self.additional_matching_ids: set[ProtobufId | CmdId] = additional_matching_ids or set()
         assert self._parser
-        for matching_id in [*self.additional_matching_ids, response_action_id]:
+        for matching_id in [*self.additional_matching_ids, ProtobufId(feature_id, response_action_id)]:
             GlobalParsers.add(matching_id, self._parser)
         GlobalParsers.add_feature_action_id_mapping(self.feature_id, self.response_action_id)
 
@@ -366,7 +366,8 @@ def ble_proto_command(
     request_proto: type[Protobuf],
     response_proto: type[Protobuf],
     parser: Parser | None = None,
-    additional_matching_ids: set[ActionId | CmdId] | None = None,
+    additional_matching_ids: set[ProtobufId | CmdId] | None = None,
+    rules: MessageRules = MessageRules(),
 ) -> Callable:
     """Decorator to build a BLE Protobuf command and wrapper to execute it
 
@@ -378,8 +379,9 @@ def ble_proto_command(
         request_proto (type[Protobuf]): the action ID that will be in the response
         response_proto (type[Protobuf]): protobuf used to parse received bytestream
         parser (Parser | None): Response parser to transform received Protobuf bytes. Defaults to None.
-        additional_matching_ids (set[ActionId | CmdId] | None): Other action ID's to share this parser. This is used,
+        additional_matching_ids (set[ProtobufId | CmdId] | None): Other action ID's to share this parser. This is used,
             for example, if a notification shares the same ID as the synchronous response. Defaults to None.
+        rules (MessageRules): rules that describe sending / receiving the message. Defaults to MessageRules() (no rules).
 
     Returns:
         Callable: Generated method to perform command
@@ -397,7 +399,7 @@ def ble_proto_command(
 
     @wrapt.decorator
     async def wrapper(wrapped: Callable, instance: BleMessages, _: Any, kwargs: Any) -> GoProResp:
-        return await instance._communicator._send_ble_message(message, **(await wrapped(**kwargs) or kwargs))
+        return await instance._communicator._send_ble_message(message, rules, **(await wrapped(**kwargs) or kwargs))
 
     return wrapper
 
@@ -888,6 +890,7 @@ def build_url(self, **kwargs: Any) -> str:
         Returns:
             str: built URL
         """
+        assert not isinstance(self._identifier, ProtobufId)  # needed to satisfy typing
         return self._endpoint.format(setting=int(self._identifier), option=int(kwargs["value"]))
 
     async def set(self, value: T) -> GoProResp:

demos/python/sdk_wireless_camera_control/open_gopro/demos/gui/livestream.py

@@ -42,15 +42,19 @@ async def main(args: argparse.Namespace) -> None:
         )
         assert gopro.streaming.url
         console.print(
-            f"[yellow]Livestream to {gopro.streaming.url} is now streaming and should be available for viewing at."
+            f"[yellow]Livestream to {gopro.streaming.url} is now streaming and should be available for viewing."
         )
         await ainput("Press enter to stop livestreaming...\n")
 
+        console.print("[yellow]Stopping livestream...")
         await gopro.streaming.stop_active_stream()
 
         # TODO merge this into access point feature
+        console.print("[yellow]Disconnecting GoPro from network...")
         await gopro.ble_command.release_network()
 
+        console.print(" [yellow]Exiting...")
+
 
 def parse_arguments() -> argparse.Namespace:
     parser = argparse.ArgumentParser(

demos/python/sdk_wireless_camera_control/open_gopro/features/access_point_feature.py

@@ -14,6 +14,7 @@
 from open_gopro.features.base_feature import BaseFeature
 from open_gopro.models import proto
 from open_gopro.models.constants import ActionId
+from open_gopro.models.constants.constants import FeatureId
 from open_gopro.models.proto import (
     EnumProvisioning,
     EnumResultGeneric,
@@ -25,6 +26,7 @@
     ResponseConnectNew,
     ResponseStartScanning,
 )
+from open_gopro.models.types import ProtobufId
 
 logger = logging.getLogger(__name__)
 
@@ -33,13 +35,10 @@ class AccessPointFeature(BaseFeature):
     """Access Point (AP) feature abstraction"""
 
     @property
-    def is_ready(self) -> bool:  # noqa: D102
-        # It's ready upon initialization
+    def is_supported(self) -> bool:  # noqa: D102
+        # All Open GoPro cameras support access point
         return True
 
-    async def wait_for_ready(self) -> None:  # noqa: D102
-        return
-
     async def close(self) -> None:  # noqa: D102
         return
 
@@ -54,18 +53,20 @@ async def scan_wifi_networks(self, timeout: int = 60) -> Result[proto.ResponseGe
             Result[proto.ResponseGetApEntries, GoProError]: Discovered AP entries on success or error
         """
         # Wait to receive scanning success
-        logger.info("Scanning for Wifi networks")
+        logger.info("Scanning for Wifi networks...")
 
         async with GoproObserverDistinctInitial[ResponseStartScanning, NotifStartScanning](
             gopro=self._gopro,
-            update=ActionId.NOTIF_START_SCAN,
+            update=ProtobufId(FeatureId.NETWORK_MANAGEMENT, ActionId.NOTIF_START_SCAN),
             register_command=self._gopro.ble_command.scan_wifi_networks(),
         ) as observable, asyncio.timeout(timeout):
             if observable.initial_response.result != EnumResultGeneric.RESULT_SUCCESS:
                 return Result.from_failure(GoProError("Failed to start scanning."))
 
+            logger.info("Waiting for scanning to complete...")
             result = await observable.observe().first(lambda s: s.scanning_state == EnumScanning.SCANNING_SUCCESS)
             entries = await self._gopro.ble_command.get_ap_entries(scan_id=result.scan_id)
+            logger.info(f"Scan complete. Found {len(entries.data.entries)} networks.")
             return Result.from_value(entries.data)
 
     async def connect(
@@ -99,7 +100,7 @@ async def connect(
                         NotifProvisioningState,
                     ](
                         gopro=self._gopro,
-                        update=ActionId.NOTIF_PROVIS_STATE,
+                        update=ProtobufId(FeatureId.NETWORK_MANAGEMENT, ActionId.NOTIF_PROVIS_STATE),
                         register_command=command,
                     ) as observable:
                         if observable.initial_response.result != EnumResultGeneric.RESULT_SUCCESS:

demos/python/sdk_wireless_camera_control/open_gopro/features/base_feature.py

@@ -2,44 +2,86 @@
 # This copyright was auto-generated on Mon May 12 23:03:50 UTC 2025
 
 """Functionality common to all features."""
+from __future__ import annotations
 
 import asyncio
 from abc import ABC, abstractmethod
+from typing import Any, Callable
+
+import wrapt
 
-from open_gopro.api.api import WirelessApi
 from open_gopro.gopro_base import GoProBase
 
 
-class BaseFeature(ABC):
-    """Base Feature definition / interface
+@wrapt.decorator
+def require_supported(wrapped: Callable, instance: BaseFeature, args: Any, kwargs: Any) -> Any:
+    """Ensure the feature is supported before allowing access.
 
     Args:
-        gopro (GoProBase[WirelessApi]): camera to operate on
-        loop (asyncio.AbstractEventLoop): asyncio loop to use for this feature
+        wrapped (Callable): The wrapped function or property
+        instance (BaseFeature): The class instance (or None if accessing a property getter)
+        args (Any): Positional arguments
+        kwargs (Any): Keyword arguments
+
+    Returns:
+        Any: Result of the wrapped function
+
+    Raises:
+        RuntimeError: If feature is not supported
     """
+    # Handle the case where instance might be None (property access)
+    # In this case, the instance is actually the first argument in args
+    actual_instance = instance if instance is not None else args[0]
 
-    def __init__(
-        self,
-        gopro: GoProBase[WirelessApi],
-        loop: asyncio.AbstractEventLoop,
-    ) -> None:
-        self._gopro = gopro
-        self._loop = loop
+    if not actual_instance.is_supported:
+        raise RuntimeError(f"{actual_instance.__class__.__name__} feature is not supported on this camera")
+
+    if instance is None:
+        # Property getter case - call it with the rest of args (skipping the first one which is the instance)
+        if len(args) > 1:
+            return wrapped(args[0], *args[1:], **kwargs)
+        return wrapped(args[0])
+
+    # Normal method call
+    return wrapped(*args, **kwargs)
+
+
+class BaseFeature(ABC):
+    """Base Feature definition / interface"""
+
+    def __init__(self) -> None:
+        self._loop: asyncio.AbstractEventLoop
+        self._gopro: GoProBase[Any]
 
     @property
     @abstractmethod
-    def is_ready(self) -> bool:
-        """Is the feature ready to use?
-
-        No other methods (besides wait_for_ready) should be used until the feature is ready
+    def is_supported(self) -> bool:
+        """Is the feature supported on the  current camera?
 
         Returns:
             bool: True if ready, False otherwise
         """
 
-    @abstractmethod
-    async def wait_for_ready(self) -> None:
-        """Wait until the feature is ready to use"""
+    async def open(  # pylint: disable=unused-argument
+        self,
+        loop: asyncio.AbstractEventLoop,
+        gopro: GoProBase[Any],
+        *args: Any,
+        **kwargs: Any,
+    ) -> None:
+        """Open the feature for use.
+
+        This should be called before using any other methods in the feature. It must be called for each
+        GoProBase instance that is used with the feature.
+
+        Args:
+            loop (asyncio.AbstractEventLoop): asyncio loop to use for this feature
+            gopro (GoProBase[Any]): camera to operate on
+            *args (Any): additional arguments for subclasses
+            **kwargs (Any): additional keyword arguments for subclasses
+        """
+        self._loop = loop
+        self._gopro = gopro
 
     @abstractmethod
     async def close(self) -> None: