bumble 0.0.203__py3-none-any.whl → 0.0.207__py3-none-any.whl

bumble/gatt.py

@@ -28,23 +28,26 @@ import functools
 import logging
 import struct
 from typing import (
+    Any,
     Callable,
     Dict,
     Iterable,
     List,
     Optional,
     Sequence,
+    SupportsBytes,
+    Type,
     Union,
     TYPE_CHECKING,
 )
 
 from bumble.colors import color
-from bumble.core import BaseBumbleError, UUID
+from bumble.core import BaseBumbleError, InvalidOperationError, UUID
 from bumble.att import Attribute, AttributeValue
+from bumble.utils import ByteSerializable
 
 if TYPE_CHECKING:
     from bumble.gatt_client import AttributeProxy
-    from bumble.device import Connection
 
 
 # -----------------------------------------------------------------------------
@@ -275,6 +278,13 @@ GATT_SOURCE_AUDIO_LOCATION_CHARACTERISTIC       = UUID.from_16_bits(0x2BCC, 'Sou
 GATT_AVAILABLE_AUDIO_CONTEXTS_CHARACTERISTIC    = UUID.from_16_bits(0x2BCD, 'Available Audio Contexts')
 GATT_SUPPORTED_AUDIO_CONTEXTS_CHARACTERISTIC    = UUID.from_16_bits(0x2BCE, 'Supported Audio Contexts')
 
+# Gaming Audio Service (GMAS)
+GATT_GMAP_ROLE_CHARACTERISTIC    = UUID.from_16_bits(0x2C00, 'GMAP Role')
+GATT_UGG_FEATURES_CHARACTERISTIC = UUID.from_16_bits(0x2C01, 'UGG Features')
+GATT_UGT_FEATURES_CHARACTERISTIC = UUID.from_16_bits(0x2C02, 'UGT Features')
+GATT_BGS_FEATURES_CHARACTERISTIC = UUID.from_16_bits(0x2C03, 'BGS Features')
+GATT_BGR_FEATURES_CHARACTERISTIC = UUID.from_16_bits(0x2C04, 'BGR Features')
+
 # Hearing Access Service
 GATT_HEARING_AID_FEATURES_CHARACTERISTIC             = UUID.from_16_bits(0x2BDA, 'Hearing Aid Features')
 GATT_HEARING_AID_PRESET_CONTROL_POINT_CHARACTERISTIC = UUID.from_16_bits(0x2BDB, 'Hearing Aid Preset Control Point')
@@ -304,6 +314,7 @@ GATT_CENTRAL_ADDRESS_RESOLUTION__CHARACTERISTIC                = UUID.from_16_bi
 GATT_CLIENT_SUPPORTED_FEATURES_CHARACTERISTIC                  = UUID.from_16_bits(0x2B29, 'Client Supported Features')
 GATT_DATABASE_HASH_CHARACTERISTIC                              = UUID.from_16_bits(0x2B2A, 'Database Hash')
 GATT_SERVER_SUPPORTED_FEATURES_CHARACTERISTIC                  = UUID.from_16_bits(0x2B3A, 'Server Supported Features')
+GATT_LE_GATT_SECURITY_LEVELS_CHARACTERISTIC                    = UUID.from_16_bits(0x2BF5, 'E GATT Security Levels')
 
 # fmt: on
 # pylint: enable=line-too-long
@@ -312,8 +323,6 @@ GATT_SERVER_SUPPORTED_FEATURES_CHARACTERISTIC                  = UUID.from_16_bi
 # -----------------------------------------------------------------------------
 # Utils
 # -----------------------------------------------------------------------------
-
-
 def show_services(services: Iterable[Service]) -> None:
     for service in services:
         print(color(str(service), 'cyan'))
@@ -343,7 +352,7 @@ class Service(Attribute):
     def __init__(
         self,
         uuid: Union[str, UUID],
-        characteristics: List[Characteristic],
+        characteristics: Iterable[Characteristic],
         primary=True,
         included_services: Iterable[Service] = (),
     ) -> None:
@@ -362,7 +371,7 @@ class Service(Attribute):
         )
         self.uuid = uuid
         self.included_services = list(included_services)
-        self.characteristics = characteristics[:]
+        self.characteristics = list(characteristics)
         self.primary = primary
 
     def get_advertising_data(self) -> Optional[bytes]:
@@ -393,7 +402,7 @@ class TemplateService(Service):
 
     def __init__(
         self,
-        characteristics: List[Characteristic],
+        characteristics: Iterable[Characteristic],
         primary: bool = True,
         included_services: Iterable[Service] = (),
     ) -> None:
@@ -490,7 +499,7 @@ class Characteristic(Attribute):
         uuid: Union[str, bytes, UUID],
         properties: Characteristic.Properties,
         permissions: Union[str, Attribute.Permissions],
-        value: Union[str, bytes, CharacteristicValue] = b'',
+        value: Any = b'',
         descriptors: Sequence[Descriptor] = (),
     ):
         super().__init__(uuid, permissions, value)
@@ -525,7 +534,11 @@ class CharacteristicDeclaration(Attribute):
 
     characteristic: Characteristic
 
-    def __init__(self, characteristic: Characteristic, value_handle: int) -> None:
+    def __init__(
+        self,
+        characteristic: Characteristic,
+        value_handle: int,
+    ) -> None:
         declaration_bytes = (
             struct.pack('<BH', characteristic.properties, value_handle)
             + characteristic.uuid.to_pdu_bytes()
@@ -665,10 +678,14 @@ class DelegatedCharacteristicAdapter(CharacteristicAdapter):
         self.decode = decode
 
     def encode_value(self, value):
-        return self.encode(value) if self.encode else value
+        if self.encode is None:
+            raise InvalidOperationError('delegated adapter does not have an encoder')
+        return self.encode(value)
 
     def decode_value(self, value):
-        return self.decode(value) if self.decode else value
+        if self.decode is None:
+            raise InvalidOperationError('delegate adapter does not have a decoder')
+        return self.decode(value)
 
 
 # -----------------------------------------------------------------------------
@@ -705,7 +722,7 @@ class MappedCharacteristicAdapter(PackedCharacteristicAdapter):
     '''
     Adapter that packs/unpacks characteristic values according to a standard
     Python `struct` format.
-    The adapted `read_value` and `write_value` methods return/accept aa dictionary which
+    The adapted `read_value` and `write_value` methods return/accept a dictionary which
     is packed/unpacked according to format, with the arguments extracted from the
     dictionary by key, in the same order as they occur in the `keys` parameter.
     '''
@@ -735,6 +752,24 @@ class UTF8CharacteristicAdapter(CharacteristicAdapter):
         return value.decode('utf-8')
 
 
+# -----------------------------------------------------------------------------
+class SerializableCharacteristicAdapter(CharacteristicAdapter):
+    '''
+    Adapter that converts any class to/from bytes using the class'
+    `to_bytes` and `__bytes__` methods, respectively.
+    '''
+
+    def __init__(self, characteristic, cls: Type[ByteSerializable]):
+        super().__init__(characteristic)
+        self.cls = cls
+
+    def encode_value(self, value: SupportsBytes) -> bytes:
+        return bytes(value)
+
+    def decode_value(self, value: bytes) -> Any:
+        return self.cls.from_bytes(value)
+
+
 # -----------------------------------------------------------------------------
 class Descriptor(Attribute):
     '''
@@ -769,3 +804,23 @@ class ClientCharacteristicConfigurationBits(enum.IntFlag):
     DEFAULT = 0x0000
     NOTIFICATION = 0x0001
     INDICATION = 0x0002
+
+
+# -----------------------------------------------------------------------------
+class ClientSupportedFeatures(enum.IntFlag):
+    '''
+    See Vol 3, Part G - 7.2 - Table 7.6: Client Supported Features bit assignments.
+    '''
+
+    ROBUST_CACHING = 0x01
+    ENHANCED_ATT_BEARER = 0x02
+    MULTIPLE_HANDLE_VALUE_NOTIFICATIONS = 0x04
+
+
+# -----------------------------------------------------------------------------
+class ServerSupportedFeatures(enum.IntFlag):
+    '''
+    See Vol 3, Part G - 7.4 - Table 7.11: Server Supported Features bit assignments.
+    '''
+
+    EATT_SUPPORTED = 0x01

bumble/gatt_client.py

@@ -78,6 +78,7 @@ from .gatt import (
     GATT_INCLUDE_ATTRIBUTE_TYPE,
     Characteristic,
     ClientCharacteristicConfigurationBits,
+    InvalidServiceError,
     TemplateService,
 )
 
@@ -162,12 +163,23 @@ class ServiceProxy(AttributeProxy):
         self.uuid = uuid
         self.characteristics = []
 
-    async def discover_characteristics(self, uuids=()):
+    async def discover_characteristics(self, uuids=()) -> list[CharacteristicProxy]:
         return await self.client.discover_characteristics(uuids, self)
 
-    def get_characteristics_by_uuid(self, uuid):
+    def get_characteristics_by_uuid(self, uuid: UUID) -> list[CharacteristicProxy]:
+        """Get all the characteristics with a specified UUID."""
         return self.client.get_characteristics_by_uuid(uuid, self)
 
+    def get_required_characteristic_by_uuid(self, uuid: UUID) -> CharacteristicProxy:
+        """
+        Get the first characteristic with a specified UUID.
+
+        If no characteristic with that UUID is found, an InvalidServiceError is raised.
+        """
+        if not (characteristics := self.get_characteristics_by_uuid(uuid)):
+            raise InvalidServiceError(f'{uuid} characteristic not found')
+        return characteristics[0]
+
     def __str__(self) -> str:
         return f'Service(handle=0x{self.handle:04X}, uuid={self.uuid})'
 

bumble/gatt_server.py

@@ -28,7 +28,17 @@ import asyncio
 import logging
 from collections import defaultdict
 import struct
-from typing import List, Tuple, Optional, TypeVar, Type, Dict, Iterable, TYPE_CHECKING
+from typing import (
+    Dict,
+    Iterable,
+    List,
+    Optional,
+    Tuple,
+    TypeVar,
+    Type,
+    Union,
+    TYPE_CHECKING,
+)
 from pyee import EventEmitter
 
 from bumble.colors import color
@@ -68,6 +78,7 @@ from bumble.gatt import (
     GATT_REQUEST_TIMEOUT,
     GATT_SECONDARY_SERVICE_ATTRIBUTE_TYPE,
     Characteristic,
+    CharacteristicAdapter,
     CharacteristicDeclaration,
     CharacteristicValue,
     IncludedServiceDeclaration,