Add support for fetching play capabilities

Author: wlcrs

afsapi/__init__.py

@@ -2,30 +2,30 @@
 
 from importlib.metadata import PackageNotFoundError, version
 
-from afsapi.exceptions import (
+from .api import AFSAPI
+from .exceptions import (
     FSApiError,
     FSConnectionError,
-    FsNotImplementedError,
+    FSNotImplementedError,
     InvalidPinError,
     InvalidSessionError,
     OutOfRangeError,
 )
-from afsapi.models import (
+from .models import (
     Equaliser,
+    PlayCaps,
     PlayControl,
     PlayerMode,
     PlayRepeatMode,
     PlayState,
     Preset,
 )
-from afsapi.nodes import (
+from .nodes import (
     Endpoint,
     ListEndpoint,
     Nodes,
 )
 
-from .api import AFSAPI
-
 try:
     __version__ = version(__name__)
 except PackageNotFoundError:  # pragma: no cover
@@ -40,12 +40,13 @@
     "Equaliser",
     "FSApiError",
     "FSConnectionError",
-    "FsNotImplementedError",
+    "FSNotImplementedError",
     "InvalidPinError",
     "InvalidSessionError",
     "ListEndpoint",
     "Nodes",
     "OutOfRangeError",
+    "PlayCaps",
     "PlayControl",
     "PlayRepeatMode",
     "PlayState",

afsapi/api.py

@@ -16,12 +16,14 @@
 from afsapi.exceptions import (
     FSApiError,
     FSConnectionError,
+    FSNodeBlockedError,
     InvalidPinError,
     InvalidSessionError,
     OutOfRangeError,
 )
 from afsapi.models import (
     Equaliser,
+    PlayCaps,
     PlayControl,
     PlayerMode,
     PlayRepeatMode,
@@ -564,6 +566,13 @@ async def get_play_status(self) -> PlayState | None:
             return PlayState(status)
         return None
 
+    async def get_play_caps(self) -> PlayCaps | None:
+        """Get the supported play control capabilities of the device."""
+        caps = await self.get(Nodes.caps)
+        if caps is not None:
+            return PlayCaps(caps)
+        return None
+
     async def get_play_name(self) -> str | None:
         """Get the name of the played item."""
         return await self.get(Nodes.name)

afsapi/exceptions.py

@@ -5,7 +5,11 @@ class FSApiError(Exception):
     """Base exception for all Frontier Silicon API errors."""
 
 
-class FsNotImplementedError(FSApiError):
+class FSNodeBlockedError(FSApiError):
+    """Exception raised when the device responds with FS_NODE_BLOCKED error."""
+
+
+class FSNotImplementedError(FSApiError):
     """Exception raised when an API operation is not implemented."""
 
 

afsapi/models.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 from dataclasses import dataclass
-from enum import IntEnum
+from enum import IntEnum, IntFlag, auto
 
 
 class PlayState(IntEnum):
@@ -29,6 +29,31 @@ class PlayRepeatMode(IntEnum):
     REPEAT_ONE = 2
 
 
+class PlayCaps(IntFlag):
+    """Bitmask of supported playback control commands.
+
+    Returned by netRemote.play.caps endpoint.
+    """
+
+    Pause = auto()
+    Stop = auto()
+    SkipNext = auto()
+    SkipPrevious = auto()
+    FastForward = auto()
+    Rewind = auto()
+    Shuffle = auto()
+    Repeat = auto()
+    Seek = auto()
+    ApplyFeedback = auto()
+    Scrobbling = auto()
+    AddPreset = auto()
+    ThumbsUp = auto()
+    ThumbsDown = auto()
+    SkipForward = auto()
+    SkipBackward = auto()
+    RepeatOne = auto()
+
+
 class PlayControl(IntEnum):
     """Enumeration of playback control commands."""
 

afsapi/nodes.py

@@ -182,6 +182,7 @@ class Nodes:
     mute: Endpoint[int] = Endpoint("netRemote.sys.audio.mute", "u8")
 
     # --- play --------------------------------------------------------------
+    caps: Endpoint[int] = Endpoint("netRemote.play.caps", "u32")
     status: Endpoint[int] = Endpoint("netRemote.play.status", "u8")
     name: Endpoint[str] = Endpoint("netRemote.play.info.name", "c8_array")
     control: Endpoint[int] = Endpoint("netRemote.play.control", "u8")

afsapi/response.py

@@ -13,9 +13,10 @@
 if t.TYPE_CHECKING:
     from xml.etree import ElementTree as ET
 
-from afsapi.exceptions import (
+from .exceptions import (
     FSApiError,
-    FsNotImplementedError,
+    FSNodeBlockedError,
+    FSNotImplementedError,
     OutOfRangeError,
 )
 
@@ -68,10 +69,10 @@ def to_exception(self) -> FSApiError:
 
         if self == FSAPIStatus.FS_NODE_DOES_NOT_EXIST:
             msg = "FSAPI service not implemented on this device."
-            return FsNotImplementedError(msg)
+            return FSNotImplementedError(msg)
         if self == FSAPIStatus.FS_NODE_BLOCKED:
             msg = "Device is not in the correct mode"
-            return FSApiError(msg)
+            return FSNodeBlockedError(msg)
         if self == FSAPIStatus.FS_FAIL:
             msg = "Command failed. Value is not in range for this command."
             return OutOfRangeError(msg)