Merge pull request #663 from google/gbg/ancs

Initial support for ANCS client functionality

.github/workflows/python-avatar.yml

@@ -44,7 +44,7 @@ jobs:
         run: cat rootcanal.log
       - name: Upload Mobly logs
         if: always()
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         with:
-          name: mobly-logs
+          name: mobly-logs-${{ strategy.job-index }}
           path: /tmp/logs/mobly/bumble.bumbles/

.vscode/settings.json

@@ -14,9 +14,12 @@
         "ASHA",
         "asyncio",
         "ATRAC",
+        "auracast",
         "avctp",
         "avdtp",
         "avrcp",
+        "biginfo",
+        "bigs",
         "bitpool",
         "bitstruct",
         "BSCP",
@@ -36,6 +39,7 @@
         "deregistration",
         "dhkey",
         "diversifier",
+        "ediv",
         "endianness",
         "ESCO",
         "Fitbit",
@@ -47,6 +51,7 @@
         "libc",
         "liblc",
         "libusb",
+        "maxs",
         "MITM",
         "MSBC",
         "NDIS",
@@ -54,8 +59,10 @@
         "NONBLOCK",
         "NONCONN",
         "OXIMETER",
+        "PDUS",
         "popleft",
         "PRAND",
+        "prefs",
         "protobuf",
         "psms",
         "pyee",

apps/auracast.py

@@ -1,4 +1,4 @@
-# Copyright 2024 Google LLC
+# Copyright 2025 Google LLC
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -16,29 +16,49 @@
 # Imports
 # -----------------------------------------------------------------------------
 from __future__ import annotations
+
 import asyncio
+import asyncio.subprocess
+import collections
 import contextlib
 import dataclasses
+import functools
 import logging
 import os
-from typing import cast, Any, AsyncGenerator, Coroutine, Dict, Optional, Tuple
+import struct
+from typing import (
+    Any,
+    AsyncGenerator,
+    Coroutine,
+    Deque,
+    Optional,
+    Tuple,
+)
 
 import click
 import pyee
 
+try:
+    import lc3  # type: ignore  # pylint: disable=E0401
+except ImportError as e:
+    raise ImportError(
+        "Try `python -m pip install \"git+https://github.com/google/liblc3.git\"`."
+    ) from e
+
+from bumble.audio import io as audio_io
 from bumble.colors import color
-import bumble.company_ids
-import bumble.core
+from bumble import company_ids
+from bumble import core
+from bumble import gatt
+from bumble import hci
+from bumble.profiles import bap
+from bumble.profiles import le_audio
+from bumble.profiles import pbp
+from bumble.profiles import bass
 import bumble.device
-import bumble.gatt
-import bumble.hci
-import bumble.profiles.bap
-import bumble.profiles.bass
-import bumble.profiles.pbp
 import bumble.transport
 import bumble.utils
 
-
 # -----------------------------------------------------------------------------
 # Logging
 # -----------------------------------------------------------------------------
@@ -49,9 +69,34 @@ logger = logging.getLogger(__name__)
 # Constants
 # -----------------------------------------------------------------------------
 AURACAST_DEFAULT_DEVICE_NAME = 'Bumble Auracast'
-AURACAST_DEFAULT_DEVICE_ADDRESS = bumble.hci.Address('F0:F1:F2:F3:F4:F5')
+AURACAST_DEFAULT_DEVICE_ADDRESS = hci.Address('F0:F1:F2:F3:F4:F5')
 AURACAST_DEFAULT_SYNC_TIMEOUT = 5.0
 AURACAST_DEFAULT_ATT_MTU = 256
+AURACAST_DEFAULT_FRAME_DURATION = 10000
+AURACAST_DEFAULT_SAMPLE_RATE = 48000
+AURACAST_DEFAULT_TRANSMIT_BITRATE = 80000
+
+
+# -----------------------------------------------------------------------------
+# Utils
+# -----------------------------------------------------------------------------
+def codec_config_string(
+    codec_config: bap.CodecSpecificConfiguration, indent: str
+) -> str:
+    lines = []
+    if codec_config.sampling_frequency is not None:
+        lines.append(f'Sampling Frequency: {codec_config.sampling_frequency.hz} hz')
+    if codec_config.frame_duration is not None:
+        lines.append(f'Frame Duration:     {codec_config.frame_duration.us} µs')
+    if codec_config.octets_per_codec_frame is not None:
+        lines.append(f'Frame Size:         {codec_config.octets_per_codec_frame} bytes')
+    if codec_config.codec_frames_per_sdu is not None:
+        lines.append(f'Frames Per SDU:     {codec_config.codec_frames_per_sdu}')
+    if codec_config.audio_channel_allocation is not None:
+        lines.append(
+            f'Audio Location:     {codec_config.audio_channel_allocation.name}'
+        )
+    return '\n'.join(indent + line for line in lines)
 
 
 # -----------------------------------------------------------------------------
@@ -62,17 +107,12 @@ class BroadcastScanner(pyee.EventEmitter):
     class Broadcast(pyee.EventEmitter):
         name: str | None
         sync: bumble.device.PeriodicAdvertisingSync
+        broadcast_id: int
         rssi: int = 0
-        public_broadcast_announcement: Optional[
-            bumble.profiles.pbp.PublicBroadcastAnnouncement
-        ] = None
-        broadcast_audio_announcement: Optional[
-            bumble.profiles.bap.BroadcastAudioAnnouncement
-        ] = None
-        basic_audio_announcement: Optional[
-            bumble.profiles.bap.BasicAudioAnnouncement
-        ] = None
-        appearance: Optional[bumble.core.Appearance] = None
+        public_broadcast_announcement: Optional[pbp.PublicBroadcastAnnouncement] = None
+        broadcast_audio_announcement: Optional[bap.BroadcastAudioAnnouncement] = None
+        basic_audio_announcement: Optional[bap.BasicAudioAnnouncement] = None
+        appearance: Optional[core.Appearance] = None
         biginfo: Optional[bumble.device.BIGInfoAdvertisement] = None
         manufacturer_data: Optional[Tuple[str, bytes]] = None
 
@@ -86,42 +126,32 @@ class BroadcastScanner(pyee.EventEmitter):
         def update(self, advertisement: bumble.device.Advertisement) -> None:
             self.rssi = advertisement.rssi
             for service_data in advertisement.data.get_all(
-                bumble.core.AdvertisingData.SERVICE_DATA
+                core.AdvertisingData.Type.SERVICE_DATA_16_BIT_UUID
             ):
-                assert isinstance(service_data, tuple)
                 service_uuid, data = service_data
-                assert isinstance(data, bytes)
 
-                if (
-                    service_uuid
-                    == bumble.gatt.GATT_PUBLIC_BROADCAST_ANNOUNCEMENT_SERVICE
-                ):
+                if service_uuid == gatt.GATT_PUBLIC_BROADCAST_ANNOUNCEMENT_SERVICE:
                     self.public_broadcast_announcement = (
-                        bumble.profiles.pbp.PublicBroadcastAnnouncement.from_bytes(data)
+                        pbp.PublicBroadcastAnnouncement.from_bytes(data)
                     )
                     continue
 
-                if (
-                    service_uuid
-                    == bumble.gatt.GATT_BROADCAST_AUDIO_ANNOUNCEMENT_SERVICE
-                ):
+                if service_uuid == gatt.GATT_BROADCAST_AUDIO_ANNOUNCEMENT_SERVICE:
                     self.broadcast_audio_announcement = (
-                        bumble.profiles.bap.BroadcastAudioAnnouncement.from_bytes(data)
+                        bap.BroadcastAudioAnnouncement.from_bytes(data)
                     )
                     continue
 
-            self.appearance = advertisement.data.get(  # type: ignore[assignment]
-                bumble.core.AdvertisingData.APPEARANCE
+            self.appearance = advertisement.data.get(
+                core.AdvertisingData.Type.APPEARANCE
             )
 
             if manufacturer_data := advertisement.data.get(
-                bumble.core.AdvertisingData.MANUFACTURER_SPECIFIC_DATA
+                core.AdvertisingData.Type.MANUFACTURER_SPECIFIC_DATA
             ):
-                assert isinstance(manufacturer_data, tuple)
-                company_id = cast(int, manufacturer_data[0])
-                data = cast(bytes, manufacturer_data[1])
+                company_id, data = manufacturer_data
                 self.manufacturer_data = (
-                    bumble.company_ids.COMPANY_IDENTIFIERS.get(
+                    company_ids.COMPANY_IDENTIFIERS.get(
                         company_id, f'0x{company_id:04X}'
                     ),
                     data,
@@ -157,18 +187,17 @@ class BroadcastScanner(pyee.EventEmitter):
             if self.public_broadcast_announcement:
                 print(
                     f'  {color("Features", "cyan")}:     '
-                    f'{self.public_broadcast_announcement.features}'
-                )
-                print(
-                    f'  {color("Metadata", "cyan")}:     '
-                    f'{self.public_broadcast_announcement.metadata}'
+                    f'{self.public_broadcast_announcement.features.name}'
                 )
+                print(f'  {color("Metadata", "cyan")}:')
+                print(self.public_broadcast_announcement.metadata.pretty_print('    '))
 
             if self.basic_audio_announcement:
                 print(color('  Audio:', 'cyan'))
                 print(
                     color('    Presentation Delay:', 'magenta'),
                     self.basic_audio_announcement.presentation_delay,
+                    "µs",
                 )
                 for subgroup in self.basic_audio_announcement.subgroups:
                     print(color('    Subgroup:', 'magenta'))
@@ -185,17 +214,22 @@ class BroadcastScanner(pyee.EventEmitter):
                         color('        Vendor Specific Codec ID:', 'green'),
                         subgroup.codec_id.vendor_specific_codec_id,
                     )
+                    print(color('      Codec Config:', 'yellow'))
                     print(
-                        color('      Codec Config:', 'yellow'),
-                        subgroup.codec_specific_configuration,
+                        codec_config_string(
+                            subgroup.codec_specific_configuration, '        '
+                        ),
                     )
-                    print(color('      Metadata:    ', 'yellow'), subgroup.metadata)
+                    print(color('      Metadata:    ', 'yellow'))
+                    print(subgroup.metadata.pretty_print('        '))
 
                     for bis in subgroup.bis:
                         print(color(f'      BIS [{bis.index}]:', 'yellow'))
+                        print(color('       Codec Config:', 'green'))
                         print(
-                            color('       Codec Config:', 'green'),
-                            bis.codec_specific_configuration,
+                            codec_config_string(
+                                bis.codec_specific_configuration, '         '
+                            ),
                         )
 
             if self.biginfo:
@@ -232,15 +266,13 @@ class BroadcastScanner(pyee.EventEmitter):
                 return
 
             for service_data in advertisement.data.get_all(
-                bumble.core.AdvertisingData.SERVICE_DATA
+                core.AdvertisingData.Type.SERVICE_DATA_16_BIT_UUID
             ):
-                assert isinstance(service_data, tuple)
                 service_uuid, data = service_data
-                assert isinstance(data, bytes)
 
-                if service_uuid == bumble.gatt.GATT_BASIC_AUDIO_ANNOUNCEMENT_SERVICE:
+                if service_uuid == gatt.GATT_BASIC_AUDIO_ANNOUNCEMENT_SERVICE:
                     self.basic_audio_announcement = (
-                        bumble.profiles.bap.BasicAudioAnnouncement.from_bytes(data)
+                        bap.BasicAudioAnnouncement.from_bytes(data)
                     )
                     break
 
@@ -262,7 +294,7 @@ class BroadcastScanner(pyee.EventEmitter):
         self.device = device
         self.filter_duplicates = filter_duplicates
         self.sync_timeout = sync_timeout
-        self.broadcasts: Dict[bumble.hci.Address, BroadcastScanner.Broadcast] = {}
+        self.broadcasts = dict[hci.Address, BroadcastScanner.Broadcast]()
         device.on('advertisement', self.on_advertisement)
 
     async def start(self) -> None:
@@ -277,33 +309,43 @@ class BroadcastScanner(pyee.EventEmitter):
     def on_advertisement(self, advertisement: bumble.device.Advertisement) -> None:
         if not (
             ads := advertisement.data.get_all(
-                bumble.core.AdvertisingData.SERVICE_DATA_16_BIT_UUID
+                core.AdvertisingData.Type.SERVICE_DATA_16_BIT_UUID
             )
         ) or not (
-            any(
-                ad
-                for ad in ads
-                if isinstance(ad, tuple)
-                and ad[0] == bumble.gatt.GATT_BROADCAST_AUDIO_ANNOUNCEMENT_SERVICE
+            broadcast_audio_announcement := next(
+                (
+                    ad
+                    for ad in ads
+                    if ad[0] == gatt.GATT_BROADCAST_AUDIO_ANNOUNCEMENT_SERVICE
+                ),
+                None,
             )
         ):
             return
 
-        broadcast_name = advertisement.data.get(
-            bumble.core.AdvertisingData.BROADCAST_NAME
+        broadcast_name = advertisement.data.get_all(
+            core.AdvertisingData.Type.BROADCAST_NAME
         )
-        assert isinstance(broadcast_name, str) or broadcast_name is None
 
         if broadcast := self.broadcasts.get(advertisement.address):
             broadcast.update(advertisement)
             return
 
         bumble.utils.AsyncRunner.spawn(
-            self.on_new_broadcast(broadcast_name, advertisement)
+            self.on_new_broadcast(
+                broadcast_name[0] if broadcast_name else None,
+                advertisement,
+                bap.BroadcastAudioAnnouncement.from_bytes(
+                    broadcast_audio_announcement[1]
+                ).broadcast_id,
+            )
         )
 
     async def on_new_broadcast(
-        self, name: str | None, advertisement: bumble.device.Advertisement
+        self,
+        name: str | None,
+        advertisement: bumble.device.Advertisement,
+        broadcast_id: int,
     ) -> None:
         periodic_advertising_sync = await self.device.create_periodic_advertising_sync(
             advertiser_address=advertisement.address,
@@ -311,7 +353,7 @@ class BroadcastScanner(pyee.EventEmitter):
             sync_timeout=self.sync_timeout,
             filter_duplicates=self.filter_duplicates,
         )
-        broadcast = self.Broadcast(name, periodic_advertising_sync)
+        broadcast = self.Broadcast(name, periodic_advertising_sync, broadcast_id)
         broadcast.update(advertisement)
         self.broadcasts[advertisement.address] = broadcast
         periodic_advertising_sync.on('loss', lambda: self.on_broadcast_loss(broadcast))
@@ -323,10 +365,11 @@ class BroadcastScanner(pyee.EventEmitter):
         self.emit('broadcast_loss', broadcast)
 
 
-class PrintingBroadcastScanner:
+class PrintingBroadcastScanner(pyee.EventEmitter):
     def __init__(
         self, device: bumble.device.Device, filter_duplicates: bool, sync_timeout: float
     ) -> None:
+        super().__init__()
         self.scanner = BroadcastScanner(device, filter_duplicates, sync_timeout)
         self.scanner.on('new_broadcast', self.on_new_broadcast)
         self.scanner.on('broadcast_loss', self.on_broadcast_loss)
@@ -461,27 +504,34 @@ async def run_assist(
         await peer.request_mtu(mtu)
 
         # Get the BASS service
-        bass = await peer.discover_service_and_create_proxy(
-            bumble.profiles.bass.BroadcastAudioScanServiceProxy
+        bass_client = await peer.discover_service_and_create_proxy(
+            bass.BroadcastAudioScanServiceProxy
         )
 
         # Check that the service was found
-        if not bass:
+        if not bass_client:
             print(color('!!! Broadcast Audio Scan Service not found', 'red'))
             return
 
         # Subscribe to and read the broadcast receive state characteristics
-        for i, broadcast_receive_state in enumerate(bass.broadcast_receive_states):
+        def on_broadcast_receive_state_update(
+            value: bass.BroadcastReceiveState, index: int
+        ) -> None:
+            print(
+                f"{color(f'Broadcast Receive State Update [{index}]:', 'green')} {value}"
+            )
+
+        for i, broadcast_receive_state in enumerate(
+            bass_client.broadcast_receive_states
+        ):
             try:
                 await broadcast_receive_state.subscribe(
-                    lambda value, i=i: print(
-                        f"{color(f'Broadcast Receive State Update [{i}]:', 'green')} {value}"
-                    )
+                    functools.partial(on_broadcast_receive_state_update, index=i)
                 )
-            except bumble.core.ProtocolError as error:
+            except core.ProtocolError as error:
                 print(
                     color(
-                        f'!!! Failed to subscribe to Broadcast Receive State characteristic:',
+                        '!!! Failed to subscribe to Broadcast Receive State characteristic',
                         'red',
                     ),
                     error,
@@ -497,7 +547,7 @@ async def run_assist(
 
         if command == 'add-source':
             # Find the requested broadcast
-            await bass.remote_scan_started()
+            await bass_client.remote_scan_started()
             if broadcast_name:
                 print(color('Scanning for broadcast:', 'cyan'), broadcast_name)
             else:
@@ -517,15 +567,15 @@ async def run_assist(
 
             # Add the source
             print(color('Adding source:', 'blue'), broadcast.sync.advertiser_address)
-            await bass.add_source(
+            await bass_client.add_source(
                 broadcast.sync.advertiser_address,
                 broadcast.sync.sid,
                 broadcast.broadcast_audio_announcement.broadcast_id,
-                bumble.profiles.bass.PeriodicAdvertisingSyncParams.SYNCHRONIZE_TO_PA_PAST_AVAILABLE,
+                bass.PeriodicAdvertisingSyncParams.SYNCHRONIZE_TO_PA_PAST_AVAILABLE,
                 0xFFFF,
                 [
-                    bumble.profiles.bass.SubgroupInfo(
-                        bumble.profiles.bass.SubgroupInfo.ANY_BIS,
+                    bass.SubgroupInfo(
+                        bass.SubgroupInfo.ANY_BIS,
                         bytes(broadcast.basic_audio_announcement.subgroups[0].metadata),
                     )
                 ],
@@ -535,7 +585,7 @@ async def run_assist(
             await broadcast.sync.transfer(peer.connection)
 
             # Notify the sink that we're done scanning.
-            await bass.remote_scan_stopped()
+            await bass_client.remote_scan_stopped()
 
             await peer.sustain()
             return
@@ -546,7 +596,7 @@ async def run_assist(
                 return
 
             # Find the requested broadcast
-            await bass.remote_scan_started()
+            await bass_client.remote_scan_started()
             if broadcast_name:
                 print(color('Scanning for broadcast:', 'cyan'), broadcast_name)
             else:
@@ -569,13 +619,13 @@ async def run_assist(
                 color('Modifying source:', 'blue'),
                 source_id,
             )
-            await bass.modify_source(
+            await bass_client.modify_source(
                 source_id,
-                bumble.profiles.bass.PeriodicAdvertisingSyncParams.SYNCHRONIZE_TO_PA_PAST_NOT_AVAILABLE,
+                bass.PeriodicAdvertisingSyncParams.SYNCHRONIZE_TO_PA_PAST_NOT_AVAILABLE,
                 0xFFFF,
                 [
-                    bumble.profiles.bass.SubgroupInfo(
-                        bumble.profiles.bass.SubgroupInfo.ANY_BIS,
+                    bass.SubgroupInfo(
+                        bass.SubgroupInfo.ANY_BIS,
                         bytes(broadcast.basic_audio_announcement.subgroups[0].metadata),
                     )
                 ],
@@ -590,7 +640,7 @@ async def run_assist(
 
             # Remove the source
             print(color('Removing source:', 'blue'), source_id)
-            await bass.remove_source(source_id)
+            await bass_client.remove_source(source_id)
             await peer.sustain()
             return
 
@@ -610,14 +660,339 @@ async def run_pair(transport: str, address: str) -> None:
             print("+++ Paired")
 
 
+async def run_receive(
+    transport: str,
+    broadcast_id: Optional[int],
+    output: str,
+    broadcast_code: str | None,
+    sync_timeout: float,
+    subgroup_index: int,
+) -> None:
+    # Run a pre-flight check for the output.
+    try:
+        if not audio_io.check_audio_output(output):
+            return
+    except ValueError as error:
+        print(error)
+        return
+
+    async with create_device(transport) as device:
+        if not device.supports_le_periodic_advertising:
+            print(color('Periodic advertising not supported', 'red'))
+            return
+
+        scanner = BroadcastScanner(device, False, sync_timeout)
+        scan_result: asyncio.Future[BroadcastScanner.Broadcast] = (
+            asyncio.get_running_loop().create_future()
+        )
+
+        def on_new_broadcast(broadcast: BroadcastScanner.Broadcast) -> None:
+            if scan_result.done():
+                return
+            if broadcast_id is None or broadcast.broadcast_id == broadcast_id:
+                scan_result.set_result(broadcast)
+
+        scanner.on('new_broadcast', on_new_broadcast)
+        await scanner.start()
+        print('Start scanning...')
+        broadcast = await scan_result
+        print('Advertisement found:')
+        broadcast.print()
+        basic_audio_announcement_scanned = asyncio.Event()
+
+        def on_change() -> None:
+            if (
+                broadcast.basic_audio_announcement
+                and not basic_audio_announcement_scanned.is_set()
+            ):
+                basic_audio_announcement_scanned.set()
+
+        broadcast.on('change', on_change)
+        if not broadcast.basic_audio_announcement:
+            print('Wait for Basic Audio Announcement...')
+            await basic_audio_announcement_scanned.wait()
+        print('Basic Audio Announcement found')
+        broadcast.print()
+        print('Stop scanning')
+        await scanner.stop()
+        print('Start sync to BIG')
+
+        assert broadcast.basic_audio_announcement
+        subgroup = broadcast.basic_audio_announcement.subgroups[subgroup_index]
+        configuration = subgroup.codec_specific_configuration
+        assert configuration
+        assert (sampling_frequency := configuration.sampling_frequency)
+        assert (frame_duration := configuration.frame_duration)
+
+        big_sync = await device.create_big_sync(
+            broadcast.sync,
+            bumble.device.BigSyncParameters(
+                big_sync_timeout=0x4000,
+                bis=[bis.index for bis in subgroup.bis],
+                broadcast_code=(
+                    bytes.fromhex(broadcast_code) if broadcast_code else None
+                ),
+            ),
+        )
+        num_bis = len(big_sync.bis_links)
+        decoder = lc3.Decoder(
+            frame_duration_us=frame_duration.us,
+            sample_rate_hz=sampling_frequency.hz,
+            num_channels=num_bis,
+        )
+        lc3_queues: list[Deque[bytes]] = [collections.deque() for i in range(num_bis)]
+        packet_stats = [0, 0]
+
+        audio_output = await audio_io.create_audio_output(output)
+        # This try should be replaced with contextlib.aclosing() when python 3.9 is no
+        # longer needed.
+        try:
+            await audio_output.open(
+                audio_io.PcmFormat(
+                    audio_io.PcmFormat.Endianness.LITTLE,
+                    audio_io.PcmFormat.SampleType.FLOAT32,
+                    sampling_frequency.hz,
+                    num_bis,
+                )
+            )
+
+            def sink(queue: Deque[bytes], packet: hci.HCI_IsoDataPacket):
+                # TODO: re-assemble fragments and detect errors
+                queue.append(packet.iso_sdu_fragment)
+
+                while all(lc3_queues):
+                    # This assumes SDUs contain one LC3 frame each, which may not
+                    # be correct for all cases. TODO: revisit this assumption.
+                    frame = b''.join([lc3_queue.popleft() for lc3_queue in lc3_queues])
+                    if not frame:
+                        print(color('!!! received empty frame', 'red'))
+                        continue
+
+                    packet_stats[0] += len(frame)
+                    packet_stats[1] += 1
+                    print(
+                        f'\rRECEIVED: {packet_stats[0]} bytes in '
+                        f'{packet_stats[1]} packets',
+                        end='',
+                    )
+
+                    try:
+                        pcm = decoder.decode(frame).tobytes()
+                    except lc3.BaseError as error:
+                        print(color(f'!!! LC3 decoding error: {error}'))
+                        continue
+
+                    audio_output.write(pcm)
+
+            for i, bis_link in enumerate(big_sync.bis_links):
+                print(f'Setup ISO for BIS {bis_link.handle}')
+                bis_link.sink = functools.partial(sink, lc3_queues[i])
+                await bis_link.setup_data_path(
+                    direction=bis_link.Direction.CONTROLLER_TO_HOST
+                )
+
+            terminated = asyncio.Event()
+            big_sync.on(big_sync.Event.TERMINATION, lambda _: terminated.set())
+            await terminated.wait()
+        finally:
+            await audio_output.aclose()
+
+
+async def run_transmit(
+    transport: str,
+    broadcast_id: int,
+    broadcast_code: str | None,
+    broadcast_name: str,
+    bitrate: int,
+    manufacturer_data: tuple[int, bytes] | None,
+    input: str,
+    input_format: str,
+) -> None:
+    # Run a pre-flight check for the input.
+    try:
+        if not audio_io.check_audio_input(input):
+            return
+    except ValueError as error:
+        print(error)
+        return
+
+    async with create_device(transport) as device:
+        if not device.supports_le_periodic_advertising:
+            print(color('Periodic advertising not supported', 'red'))
+            return
+
+        basic_audio_announcement = bap.BasicAudioAnnouncement(
+            presentation_delay=40000,
+            subgroups=[
+                bap.BasicAudioAnnouncement.Subgroup(
+                    codec_id=hci.CodingFormat(codec_id=hci.CodecID.LC3),
+                    codec_specific_configuration=bap.CodecSpecificConfiguration(
+                        sampling_frequency=bap.SamplingFrequency.FREQ_48000,
+                        frame_duration=bap.FrameDuration.DURATION_10000_US,
+                        octets_per_codec_frame=100,
+                    ),
+                    metadata=le_audio.Metadata(
+                        [
+                            le_audio.Metadata.Entry(
+                                tag=le_audio.Metadata.Tag.LANGUAGE, data=b'eng'
+                            ),
+                            le_audio.Metadata.Entry(
+                                tag=le_audio.Metadata.Tag.PROGRAM_INFO, data=b'Disco'
+                            ),
+                        ]
+                    ),
+                    bis=[
+                        bap.BasicAudioAnnouncement.BIS(
+                            index=1,
+                            codec_specific_configuration=bap.CodecSpecificConfiguration(
+                                audio_channel_allocation=bap.AudioLocation.FRONT_LEFT
+                            ),
+                        ),
+                        bap.BasicAudioAnnouncement.BIS(
+                            index=2,
+                            codec_specific_configuration=bap.CodecSpecificConfiguration(
+                                audio_channel_allocation=bap.AudioLocation.FRONT_RIGHT
+                            ),
+                        ),
+                    ],
+                )
+            ],
+        )
+        broadcast_audio_announcement = bap.BroadcastAudioAnnouncement(broadcast_id)
+
+        advertising_manufacturer_data = (
+            b''
+            if manufacturer_data is None
+            else bytes(
+                core.AdvertisingData(
+                    [
+                        (
+                            core.AdvertisingData.MANUFACTURER_SPECIFIC_DATA,
+                            struct.pack('<H', manufacturer_data[0])
+                            + manufacturer_data[1],
+                        )
+                    ]
+                )
+            )
+        )
+
+        advertising_set = await device.create_advertising_set(
+            advertising_parameters=bumble.device.AdvertisingParameters(
+                advertising_event_properties=bumble.device.AdvertisingEventProperties(
+                    is_connectable=False
+                ),
+                primary_advertising_interval_min=100,
+                primary_advertising_interval_max=200,
+            ),
+            advertising_data=(
+                broadcast_audio_announcement.get_advertising_data()
+                + bytes(
+                    core.AdvertisingData(
+                        [(core.AdvertisingData.BROADCAST_NAME, broadcast_name.encode())]
+                    )
+                )
+                + advertising_manufacturer_data
+            ),
+            periodic_advertising_parameters=bumble.device.PeriodicAdvertisingParameters(
+                periodic_advertising_interval_min=80,
+                periodic_advertising_interval_max=160,
+            ),
+            periodic_advertising_data=basic_audio_announcement.get_advertising_data(),
+            auto_restart=True,
+            auto_start=True,
+        )
+
+        print('Start Periodic Advertising')
+        await advertising_set.start_periodic()
+
+        audio_input = await audio_io.create_audio_input(input, input_format)
+        pcm_format = await audio_input.open()
+        # This try should be replaced with contextlib.aclosing() when python 3.9 is no
+        # longer needed.
+        try:
+            if pcm_format.channels != 2:
+                print("Only 2 channels PCM configurations are supported")
+                return
+            if pcm_format.sample_type == audio_io.PcmFormat.SampleType.INT16:
+                pcm_bit_depth = 16
+            elif pcm_format.sample_type == audio_io.PcmFormat.SampleType.FLOAT32:
+                pcm_bit_depth = None
+            else:
+                print("Only INT16 and FLOAT32 sample types are supported")
+                return
+
+            encoder = lc3.Encoder(
+                frame_duration_us=AURACAST_DEFAULT_FRAME_DURATION,
+                sample_rate_hz=AURACAST_DEFAULT_SAMPLE_RATE,
+                num_channels=pcm_format.channels,
+                input_sample_rate_hz=pcm_format.sample_rate,
+            )
+            lc3_frame_samples = encoder.get_frame_samples()
+            lc3_frame_size = encoder.get_frame_bytes(bitrate)
+            print(
+                f'Encoding with {lc3_frame_samples} '
+                f'PCM samples per {lc3_frame_size} byte frame'
+            )
+
+            print('Setup BIG')
+            big = await device.create_big(
+                advertising_set,
+                parameters=bumble.device.BigParameters(
+                    num_bis=pcm_format.channels,
+                    sdu_interval=AURACAST_DEFAULT_FRAME_DURATION,
+                    max_sdu=lc3_frame_size,
+                    max_transport_latency=65,
+                    rtn=4,
+                    broadcast_code=(
+                        bytes.fromhex(broadcast_code) if broadcast_code else None
+                    ),
+                ),
+            )
+            for bis_link in big.bis_links:
+                print(f'Setup ISO for BIS {bis_link.handle}')
+                await bis_link.setup_data_path(
+                    direction=bis_link.Direction.HOST_TO_CONTROLLER
+                )
+
+            iso_queues = [
+                bumble.device.IsoPacketStream(bis_link, 64)
+                for bis_link in big.bis_links
+            ]
+
+            def on_flow():
+                data_packet_queue = iso_queues[0].data_packet_queue
+                print(
+                    f'\rPACKETS: pending={data_packet_queue.pending}, '
+                    f'queued={data_packet_queue.queued}, '
+                    f'completed={data_packet_queue.completed}',
+                    end='',
+                )
+
+            iso_queues[0].data_packet_queue.on('flow', on_flow)
+
+            frame_count = 0
+            async for pcm_frame in audio_input.frames(lc3_frame_samples):
+                lc3_frame = encoder.encode(
+                    pcm_frame, num_bytes=2 * lc3_frame_size, bit_depth=pcm_bit_depth
+                )
+
+                mid = len(lc3_frame) // 2
+                await iso_queues[0].write(lc3_frame[:mid])
+                await iso_queues[1].write(lc3_frame[mid:])
+
+                frame_count += 1
+        finally:
+            await audio_input.aclose()
+
+
 def run_async(async_command: Coroutine) -> None:
     try:
         asyncio.run(async_command)
-    except bumble.core.ProtocolError as error:
+    except core.ProtocolError as error:
         if error.error_namespace == 'att' and error.error_code in list(
-            bumble.profiles.bass.ApplicationError
+            bass.ApplicationError
         ):
-            message = bumble.profiles.bass.ApplicationError(error.error_code).name
+            message = bass.ApplicationError(error.error_code).name
         else:
             message = str(error)
 
@@ -631,9 +1006,7 @@ def run_async(async_command: Coroutine) -> None:
 # -----------------------------------------------------------------------------
 @click.group()
 @click.pass_context
-def auracast(
-    ctx,
-):
+def auracast(ctx):
     ctx.ensure_object(dict)
 
 
@@ -678,7 +1051,7 @@ def scan(ctx, filter_duplicates, sync_timeout, transport):
 @click.argument('address')
 @click.pass_context
 def assist(ctx, broadcast_name, source_id, command, transport, address):
-    """Scan for broadcasts on behalf of a audio server"""
+    """Scan for broadcasts on behalf of an audio server"""
     run_async(run_assist(broadcast_name, source_id, command, transport, address))
 
 
@@ -691,6 +1064,166 @@ def pair(ctx, transport, address):
     run_async(run_pair(transport, address))
 
 
+@auracast.command('receive')
+@click.argument('transport')
+@click.argument(
+    'broadcast_id',
+    type=int,
+    required=False,
+)
+@click.option(
+    '--output',
+    default='device',
+    help=(
+        "Audio output. "
+        "'device' -> use the host's default sound output device, "
+        "'device:<DEVICE_ID>' -> use one of the  host's sound output device "
+        "(specify 'device:?' to get a list of available sound output devices), "
+        "'stdout' -> send audio to stdout, "
+        "'file:<filename> -> write audio to a raw float32 PCM file, "
+        "'ffplay' -> pipe the audio to ffplay"
+    ),
+)
+@click.option(
+    '--broadcast-code',
+    metavar='BROADCAST_CODE',
+    type=str,
+    help='Broadcast encryption code in hex format',
+)
+@click.option(
+    '--sync-timeout',
+    metavar='SYNC_TIMEOUT',
+    type=float,
+    default=AURACAST_DEFAULT_SYNC_TIMEOUT,
+    help='Sync timeout (in seconds)',
+)
+@click.option(
+    '--subgroup',
+    metavar='SUBGROUP',
+    type=int,
+    default=0,
+    help='Index of Subgroup',
+)
+@click.pass_context
+def receive(
+    ctx,
+    transport,
+    broadcast_id,
+    output,
+    broadcast_code,
+    sync_timeout,
+    subgroup,
+):
+    """Receive a broadcast source"""
+    run_async(
+        run_receive(
+            transport,
+            broadcast_id,
+            output,
+            broadcast_code,
+            sync_timeout,
+            subgroup,
+        )
+    )
+
+
+@auracast.command('transmit')
+@click.argument('transport')
+@click.option(
+    '--input',
+    required=True,
+    help=(
+        "Audio input. "
+        "'device' -> use the host's default sound input device, "
+        "'device:<DEVICE_ID>' -> use one of the host's sound input devices "
+        "(specify 'device:?' to get a list of available sound input devices), "
+        "'stdin' -> receive audio from stdin as int16 PCM, "
+        "'file:<filename> -> read audio from a .wav or raw int16 PCM file. "
+        "(The file: prefix may be omitted if the file path does not start with "
+        "the substring 'device:' or 'file:' and is not 'stdin')"
+    ),
+)
+@click.option(
+    '--input-format',
+    metavar="FORMAT",
+    default='auto',
+    help=(
+        "Audio input format. "
+        "Use 'auto' for .wav files, or for the default setting with the devices. "
+        "For other inputs, the format is specified as "
+        "<sample-type>,<sample-rate>,<channels> (supported <sample-type>: 'int16le' "
+        "for 16-bit signed integers with little-endian byte order or 'float32le' for "
+        "32-bit floating point with little-endian byte order)"
+    ),
+)
+@click.option(
+    '--broadcast-id',
+    metavar='BROADCAST_ID',
+    type=int,
+    default=123456,
+    help='Broadcast ID',
+)
+@click.option(
+    '--broadcast-code',
+    metavar='BROADCAST_CODE',
+    help='Broadcast encryption code in hex format',
+)
+@click.option(
+    '--broadcast-name',
+    metavar='BROADCAST_NAME',
+    default='Bumble Auracast',
+    help='Broadcast name',
+)
+@click.option(
+    '--bitrate',
+    type=int,
+    default=AURACAST_DEFAULT_TRANSMIT_BITRATE,
+    help='Bitrate, per channel, in bps',
+)
+@click.option(
+    '--manufacturer-data',
+    metavar='VENDOR-ID:DATA-HEX',
+    help='Manufacturer data (specify as <vendor-id>:<data-hex>)',
+)
+@click.pass_context
+def transmit(
+    ctx,
+    transport,
+    broadcast_id,
+    broadcast_code,
+    manufacturer_data,
+    broadcast_name,
+    bitrate,
+    input,
+    input_format,
+):
+    """Transmit a broadcast source"""
+    if manufacturer_data:
+        vendor_id_str, data_hex = manufacturer_data.split(':')
+        vendor_id = int(vendor_id_str)
+        data = bytes.fromhex(data_hex)
+        manufacturer_data_tuple = (vendor_id, data)
+    else:
+        manufacturer_data_tuple = None
+
+    if (input == 'device' or input.startswith('device:')) and input_format == 'auto':
+        # Use a default format for device inputs
+        input_format = 'int16le,48000,1'
+
+    run_async(
+        run_transmit(
+            transport=transport,
+            broadcast_id=broadcast_id,
+            broadcast_code=broadcast_code,
+            broadcast_name=broadcast_name,
+            bitrate=bitrate,
+            manufacturer_data=manufacturer_data_tuple,
+            input=input,
+            input_format=input_format,
+        )
+    )
+
+
 def main():
     logging.basicConfig(level=os.environ.get('BUMBLE_LOGLEVEL', 'INFO').upper())
     auracast()

apps/bench.py

@@ -16,6 +16,7 @@
 # Imports
 # -----------------------------------------------------------------------------
 import asyncio
+import dataclasses
 import enum
 import logging
 import os
@@ -97,49 +98,22 @@ DEFAULT_RFCOMM_MTU = 2048
 # -----------------------------------------------------------------------------
 # Utils
 # -----------------------------------------------------------------------------
-def parse_packet(packet):
-    if len(packet) < 1:
-        logging.info(
-            color(f'!!! Packet too short (got {len(packet)} bytes, need >= 1)', 'red')
-        )
-        raise ValueError('packet too short')
-
-    try:
-        packet_type = PacketType(packet[0])
-    except ValueError:
-        logging.info(color(f'!!! Invalid packet type 0x{packet[0]:02X}', 'red'))
-        raise
-
-    return (packet_type, packet[1:])
-
-
-def parse_packet_sequence(packet_data):
-    if len(packet_data) < 5:
-        logging.info(
-            color(
-                f'!!!Packet too short (got {len(packet_data)} bytes, need >= 5)',
-                'red',
-            )
-        )
-        raise ValueError('packet too short')
-    return struct.unpack_from('>bI', packet_data, 0)
-
-
 def le_phy_name(phy_id):
     return {HCI_LE_1M_PHY: '1M', HCI_LE_2M_PHY: '2M', HCI_LE_CODED_PHY: 'CODED'}.get(
         phy_id, HCI_Constant.le_phy_name(phy_id)
     )
 
 
+def print_connection_phy(phy):
+    logging.info(
+        color('@@@ PHY: ', 'yellow') + f'TX:{le_phy_name(phy.tx_phy)}/'
+        f'RX:{le_phy_name(phy.rx_phy)}'
+    )
+
+
 def print_connection(connection):
     params = []
     if connection.transport == BT_LE_TRANSPORT:
-        params.append(
-            'PHY='
-            f'TX:{le_phy_name(connection.phy.tx_phy)}/'
-            f'RX:{le_phy_name(connection.phy.rx_phy)}'
-        )
-
         params.append(
             'DL=('
             f'TX:{connection.data_length[0]}/{connection.data_length[1]},'
@@ -225,13 +199,135 @@ async def switch_roles(connection, role):
             logging.info(f'{color("### Role switch failed:", "red")} {error}')
 
 
-class PacketType(enum.IntEnum):
-    RESET = 0
-    SEQUENCE = 1
-    ACK = 2
+# -----------------------------------------------------------------------------
+# Packet
+# -----------------------------------------------------------------------------
+@dataclasses.dataclass
+class Packet:
+    class PacketType(enum.IntEnum):
+        RESET = 0
+        SEQUENCE = 1
+        ACK = 2
+
+    class PacketFlags(enum.IntFlag):
+        LAST = 1
+
+    packet_type: PacketType
+    flags: PacketFlags = PacketFlags(0)
+    sequence: int = 0
+    timestamp: int = 0
+    payload: bytes = b""
+
+    @classmethod
+    def from_bytes(cls, data: bytes):
+        if len(data) < 1:
+            logging.warning(
+                color(f'!!! Packet too short (got {len(data)} bytes, need >= 1)', 'red')
+            )
+            raise ValueError('packet too short')
+
+        try:
+            packet_type = cls.PacketType(data[0])
+        except ValueError:
+            logging.warning(color(f'!!! Invalid packet type 0x{data[0]:02X}', 'red'))
+            raise
+
+        if packet_type == cls.PacketType.RESET:
+            return cls(packet_type)
+
+        flags = cls.PacketFlags(data[1])
+        (sequence,) = struct.unpack_from("<I", data, 2)
+
+        if packet_type == cls.PacketType.ACK:
+            if len(data) < 6:
+                logging.warning(
+                    color(
+                        f'!!! Packet too short (got {len(data)} bytes, need >= 6)',
+                        'red',
+                    )
+                )
+            return cls(packet_type, flags, sequence)
+
+        if len(data) < 10:
+            logging.warning(
+                color(
+                    f'!!! Packet too short (got {len(data)} bytes, need >= 10)', 'red'
+                )
+            )
+            raise ValueError('packet too short')
+
+        (timestamp,) = struct.unpack_from("<I", data, 6)
+        return cls(packet_type, flags, sequence, timestamp, data[10:])
+
+    def __bytes__(self):
+        if self.packet_type == self.PacketType.RESET:
+            return bytes([self.packet_type])
+
+        if self.packet_type == self.PacketType.ACK:
+            return struct.pack("<BBI", self.packet_type, self.flags, self.sequence)
+
+        return (
+            struct.pack(
+                "<BBII", self.packet_type, self.flags, self.sequence, self.timestamp
+            )
+            + self.payload
+        )
 
 
-PACKET_FLAG_LAST = 1
+# -----------------------------------------------------------------------------
+# Jitter Stats
+# -----------------------------------------------------------------------------
+class JitterStats:
+    def __init__(self):
+        self.reset()
+
+    def reset(self):
+        self.packets = []
+        self.receive_times = []
+        self.jitter = []
+
+    def on_packet_received(self, packet):
+        now = time.time()
+        self.packets.append(packet)
+        self.receive_times.append(now)
+
+        if packet.timestamp and len(self.packets) > 1:
+            expected_time = (
+                self.receive_times[0]
+                + (packet.timestamp - self.packets[0].timestamp) / 1000000
+            )
+            jitter = now - expected_time
+        else:
+            jitter = 0.0
+
+        self.jitter.append(jitter)
+        return jitter
+
+    def show_stats(self):
+        if len(self.jitter) < 3:
+            return
+        average = sum(self.jitter) / len(self.jitter)
+        adjusted = [jitter - average for jitter in self.jitter]
+
+        log_stats('Jitter (signed)', adjusted, 3)
+        log_stats('Jitter (absolute)', [abs(jitter) for jitter in adjusted], 3)
+
+        # Show a histogram
+        bin_count = 20
+        bins = [0] * bin_count
+        interval_min = min(adjusted)
+        interval_max = max(adjusted)
+        interval_range = interval_max - interval_min
+        bin_thresholds = [
+            interval_min + i * (interval_range / bin_count) for i in range(bin_count)
+        ]
+        for jitter in adjusted:
+            for i in reversed(range(bin_count)):
+                if jitter >= bin_thresholds[i]:
+                    bins[i] += 1
+                    break
+        for i in range(bin_count):
+            logging.info(f'@@@ >= {bin_thresholds[i]:.4f}: {bins[i]}')
 
 
 # -----------------------------------------------------------------------------
@@ -281,19 +377,37 @@ class Sender:
                 await asyncio.sleep(self.tx_start_delay)
 
             logging.info(color('=== Sending RESET', 'magenta'))
-            await self.packet_io.send_packet(bytes([PacketType.RESET]))
+            await self.packet_io.send_packet(
+                bytes(Packet(packet_type=Packet.PacketType.RESET))
+            )
+
             self.start_time = time.time()
             self.bytes_sent = 0
             for tx_i in range(self.tx_packet_count):
-                packet_flags = (
-                    PACKET_FLAG_LAST if tx_i == self.tx_packet_count - 1 else 0
+                if self.pace > 0:
+                    # Wait until it is time to send the next packet
+                    target_time = self.start_time + (tx_i * self.pace / 1000)
+                    now = time.time()
+                    if now < target_time:
+                        await asyncio.sleep(target_time - now)
+                else:
+                    await self.packet_io.drain()
+
+                packet = bytes(
+                    Packet(
+                        packet_type=Packet.PacketType.SEQUENCE,
+                        flags=(
+                            Packet.PacketFlags.LAST
+                            if tx_i == self.tx_packet_count - 1
+                            else 0
+                        ),
+                        sequence=tx_i,
+                        timestamp=int((time.time() - self.start_time) * 1000000),
+                        payload=bytes(
+                            self.tx_packet_size - 10 - self.packet_io.overhead_size
+                        ),
+                    )
                 )
-                packet = struct.pack(
-                    '>bbI',
-                    PacketType.SEQUENCE,
-                    packet_flags,
-                    tx_i,
-                ) + bytes(self.tx_packet_size - 6 - self.packet_io.overhead_size)
                 logging.info(
                     color(
                         f'Sending packet {tx_i}: {self.tx_packet_size} bytes', 'yellow'
@@ -302,14 +416,6 @@ class Sender:
                 self.bytes_sent += len(packet)
                 await self.packet_io.send_packet(packet)
 
-                if self.pace is None:
-                    continue
-
-                if self.pace > 0:
-                    await asyncio.sleep(self.pace / 1000)
-                else:
-                    await self.packet_io.drain()
-
             await self.done.wait()
 
             run_counter = f'[{run + 1} of {self.repeat + 1}]' if self.repeat else ''
@@ -321,13 +427,13 @@ class Sender:
         if self.repeat:
             logging.info(color('--- End of runs', 'blue'))
 
-    def on_packet_received(self, packet):
+    def on_packet_received(self, data):
         try:
-            packet_type, _ = parse_packet(packet)
+            packet = Packet.from_bytes(data)
         except ValueError:
             return
 
-        if packet_type == PacketType.ACK:
+        if packet.packet_type == Packet.PacketType.ACK:
             elapsed = time.time() - self.start_time
             average_tx_speed = self.bytes_sent / elapsed
             self.stats.append(average_tx_speed)
@@ -350,52 +456,53 @@ class Receiver:
     last_timestamp: float
 
     def __init__(self, packet_io, linger):
-        self.reset()
+        self.jitter_stats = JitterStats()
         self.packet_io = packet_io
         self.packet_io.packet_listener = self
         self.linger = linger
         self.done = asyncio.Event()
+        self.reset()
 
     def reset(self):
         self.expected_packet_index = 0
         self.measurements = [(time.time(), 0)]
         self.total_bytes_received = 0
+        self.jitter_stats.reset()
 
-    def on_packet_received(self, packet):
+    def on_packet_received(self, data):
         try:
-            packet_type, packet_data = parse_packet(packet)
+            packet = Packet.from_bytes(data)
         except ValueError:
+            logging.exception("invalid packet")
             return
 
-        if packet_type == PacketType.RESET:
+        if packet.packet_type == Packet.PacketType.RESET:
             logging.info(color('=== Received RESET', 'magenta'))
             self.reset()
             return
 
-        try:
-            packet_flags, packet_index = parse_packet_sequence(packet_data)
-        except ValueError:
-            return
+        jitter = self.jitter_stats.on_packet_received(packet)
         logging.info(
-            f'<<< Received packet {packet_index}: '
-            f'flags=0x{packet_flags:02X}, '
-            f'{len(packet) + self.packet_io.overhead_size} bytes'
+            f'<<< Received packet {packet.sequence}: '
+            f'flags={packet.flags}, '
+            f'jitter={jitter:.4f}, '
+            f'{len(data) + self.packet_io.overhead_size} bytes',
         )
 
-        if packet_index != self.expected_packet_index:
+        if packet.sequence != self.expected_packet_index:
             logging.info(
                 color(
                     f'!!! Unexpected packet, expected {self.expected_packet_index} '
-                    f'but received {packet_index}'
+                    f'but received {packet.sequence}'
                 )
             )
 
         now = time.time()
         elapsed_since_start = now - self.measurements[0][0]
         elapsed_since_last = now - self.measurements[-1][0]
-        self.measurements.append((now, len(packet)))
-        self.total_bytes_received += len(packet)
-        instant_rx_speed = len(packet) / elapsed_since_last
+        self.measurements.append((now, len(data)))
+        self.total_bytes_received += len(data)
+        instant_rx_speed = len(data) / elapsed_since_last
         average_rx_speed = self.total_bytes_received / elapsed_since_start
         window = self.measurements[-64:]
         windowed_rx_speed = sum(measurement[1] for measurement in window[1:]) / (
@@ -411,15 +518,17 @@ class Receiver:
             )
         )
 
-        self.expected_packet_index = packet_index + 1
+        self.expected_packet_index = packet.sequence + 1
 
-        if packet_flags & PACKET_FLAG_LAST:
+        if packet.flags & Packet.PacketFlags.LAST:
             AsyncRunner.spawn(
                 self.packet_io.send_packet(
-                    struct.pack('>bbI', PacketType.ACK, packet_flags, packet_index)
+                    bytes(Packet(Packet.PacketType.ACK, packet.flags, packet.sequence))
                 )
             )
             logging.info(color('@@@ Received last packet', 'green'))
+            self.jitter_stats.show_stats()
+
             if not self.linger:
                 self.done.set()
 
@@ -479,25 +588,32 @@ class Ping:
                 await asyncio.sleep(self.tx_start_delay)
 
             logging.info(color('=== Sending RESET', 'magenta'))
-            await self.packet_io.send_packet(bytes([PacketType.RESET]))
+            await self.packet_io.send_packet(bytes(Packet(Packet.PacketType.RESET)))
 
-            packet_interval = self.pace / 1000
             start_time = time.time()
             self.next_expected_packet_index = 0
             for i in range(self.tx_packet_count):
-                target_time = start_time + (i * packet_interval)
+                target_time = start_time + (i * self.pace / 1000)
                 now = time.time()
                 if now < target_time:
                     await asyncio.sleep(target_time - now)
+                    now = time.time()
 
-                packet = struct.pack(
-                    '>bbI',
-                    PacketType.SEQUENCE,
-                    (PACKET_FLAG_LAST if i == self.tx_packet_count - 1 else 0),
-                    i,
-                ) + bytes(self.tx_packet_size - 6)
+                packet = bytes(
+                    Packet(
+                        packet_type=Packet.PacketType.SEQUENCE,
+                        flags=(
+                            Packet.PacketFlags.LAST
+                            if i == self.tx_packet_count - 1
+                            else 0
+                        ),
+                        sequence=i,
+                        timestamp=int((now - start_time) * 1000000),
+                        payload=bytes(self.tx_packet_size - 10),
+                    )
+                )
                 logging.info(color(f'Sending packet {i}', 'yellow'))
-                self.ping_times.append(time.time())
+                self.ping_times.append(now)
                 await self.packet_io.send_packet(packet)
 
             await self.done.wait()
@@ -531,40 +647,35 @@ class Ping:
         if self.repeat:
             logging.info(color('--- End of runs', 'blue'))
 
-    def on_packet_received(self, packet):
+    def on_packet_received(self, data):
         try:
-            packet_type, packet_data = parse_packet(packet)
+            packet = Packet.from_bytes(data)
         except ValueError:
             return
 
-        try:
-            packet_flags, packet_index = parse_packet_sequence(packet_data)
-        except ValueError:
-            return
-
-        if packet_type == PacketType.ACK:
-            elapsed = time.time() - self.ping_times[packet_index]
+        if packet.packet_type == Packet.PacketType.ACK:
+            elapsed = time.time() - self.ping_times[packet.sequence]
             rtt = elapsed * 1000
             self.rtts.append(rtt)
             logging.info(
                 color(
-                    f'<<< Received ACK [{packet_index}], RTT={rtt:.2f}ms',
+                    f'<<< Received ACK [{packet.sequence}], RTT={rtt:.2f}ms',
                     'green',
                 )
             )
 
-            if packet_index == self.next_expected_packet_index:
+            if packet.sequence == self.next_expected_packet_index:
                 self.next_expected_packet_index += 1
             else:
                 logging.info(
                     color(
                         f'!!! Unexpected packet, '
                         f'expected {self.next_expected_packet_index} '
-                        f'but received {packet_index}'
+                        f'but received {packet.sequence}'
                     )
                 )
 
-        if packet_flags & PACKET_FLAG_LAST:
+        if packet.flags & Packet.PacketFlags.LAST:
             self.done.set()
             return
 
@@ -576,89 +687,56 @@ class Pong:
     expected_packet_index: int
 
     def __init__(self, packet_io, linger):
-        self.reset()
+        self.jitter_stats = JitterStats()
         self.packet_io = packet_io
         self.packet_io.packet_listener = self
         self.linger = linger
         self.done = asyncio.Event()
+        self.reset()
 
     def reset(self):
         self.expected_packet_index = 0
-        self.receive_times = []
-
-    def on_packet_received(self, packet):
-        self.receive_times.append(time.time())
+        self.jitter_stats.reset()
 
+    def on_packet_received(self, data):
         try:
-            packet_type, packet_data = parse_packet(packet)
+            packet = Packet.from_bytes(data)
         except ValueError:
             return
 
-        if packet_type == PacketType.RESET:
+        if packet.packet_type == Packet.PacketType.RESET:
             logging.info(color('=== Received RESET', 'magenta'))
             self.reset()
             return
 
-        try:
-            packet_flags, packet_index = parse_packet_sequence(packet_data)
-        except ValueError:
-            return
-        interval = (
-            self.receive_times[-1] - self.receive_times[-2]
-            if len(self.receive_times) >= 2
-            else 0
-        )
+        jitter = self.jitter_stats.on_packet_received(packet)
         logging.info(
             color(
-                f'<<< Received packet {packet_index}: '
-                f'flags=0x{packet_flags:02X}, {len(packet)} bytes, '
-                f'interval={interval:.4f}',
+                f'<<< Received packet {packet.sequence}: '
+                f'flags={packet.flags}, {len(data)} bytes, '
+                f'jitter={jitter:.4f}',
                 'green',
             )
         )
 
-        if packet_index != self.expected_packet_index:
+        if packet.sequence != self.expected_packet_index:
             logging.info(
                 color(
                     f'!!! Unexpected packet, expected {self.expected_packet_index} '
-                    f'but received {packet_index}'
+                    f'but received {packet.sequence}'
                 )
             )
 
-        self.expected_packet_index = packet_index + 1
+        self.expected_packet_index = packet.sequence + 1
 
         AsyncRunner.spawn(
             self.packet_io.send_packet(
-                struct.pack('>bbI', PacketType.ACK, packet_flags, packet_index)
+                bytes(Packet(Packet.PacketType.ACK, packet.flags, packet.sequence))
             )
         )
 
-        if packet_flags & PACKET_FLAG_LAST:
-            if len(self.receive_times) >= 3:
-                # Show basic stats
-                intervals = [
-                    self.receive_times[i + 1] - self.receive_times[i]
-                    for i in range(len(self.receive_times) - 1)
-                ]
-                log_stats('Packet intervals', intervals, 3)
-
-                # Show a histogram
-                bin_count = 20
-                bins = [0] * bin_count
-                interval_min = min(intervals)
-                interval_max = max(intervals)
-                interval_range = interval_max - interval_min
-                bin_thresholds = [
-                    interval_min + i * (interval_range / bin_count)
-                    for i in range(bin_count)
-                ]
-                for interval in intervals:
-                    for i in reversed(range(bin_count)):
-                        if interval >= bin_thresholds[i]:
-                            bins[i] += 1
-                            break
-                for i in range(bin_count):
-                    logging.info(f'@@@ >= {bin_thresholds[i]:.4f}: {bins[i]}')
+        if packet.flags & Packet.PacketFlags.LAST:
+            self.jitter_stats.show_stats()
 
             if not self.linger:
                 self.done.set()
@@ -1211,6 +1289,8 @@ class Central(Connection.Listener):
             logging.info(color('### Connected', 'cyan'))
             self.connection.listener = self
             print_connection(self.connection)
+            phy = await self.connection.get_phy()
+            print_connection_phy(phy)
 
             # Switch roles if needed.
             if self.role_switch:
@@ -1268,8 +1348,8 @@ class Central(Connection.Listener):
     def on_connection_parameters_update(self):
         print_connection(self.connection)
 
-    def on_connection_phy_update(self):
-        print_connection(self.connection)
+    def on_connection_phy_update(self, phy):
+        print_connection_phy(phy)
 
     def on_connection_att_mtu_update(self):
         print_connection(self.connection)
@@ -1395,8 +1475,8 @@ class Peripheral(Device.Listener, Connection.Listener):
     def on_connection_parameters_update(self):
         print_connection(self.connection)
 
-    def on_connection_phy_update(self):
-        print_connection(self.connection)
+    def on_connection_phy_update(self, phy):
+        print_connection_phy(phy)
 
     def on_connection_att_mtu_update(self):
         print_connection(self.connection)
@@ -1471,7 +1551,7 @@ def create_mode_factory(ctx, default_mode):
 def create_scenario_factory(ctx, default_scenario):
     scenario = ctx.obj['scenario']
     if scenario is None:
-        scenarion = default_scenario
+        scenario = default_scenario
 
     def create_scenario(packet_io):
         if scenario == 'send':
@@ -1530,6 +1610,7 @@ def create_scenario_factory(ctx, default_scenario):
     '--att-mtu',
     metavar='MTU',
     type=click.IntRange(23, 517),
+    default=517,
     help='GATT MTU (gatt-client mode)',
 )
 @click.option(
@@ -1605,7 +1686,7 @@ def create_scenario_factory(ctx, default_scenario):
     '--packet-size',
     '-s',
     metavar='SIZE',
-    type=click.IntRange(8, 8192),
+    type=click.IntRange(10, 8192),
     default=500,
     help='Packet size (send or ping scenario)',
 )

apps/console.py

@@ -22,7 +22,6 @@
 import asyncio
 import logging
 import os
-import random
 import re
 import humanize
 from typing import Optional, Union
@@ -57,7 +56,13 @@ from bumble import __version__
 import bumble.core
 from bumble import colors
 from bumble.core import UUID, AdvertisingData, BT_LE_TRANSPORT
-from bumble.device import ConnectionParametersPreferences, Device, Connection, Peer
+from bumble.device import (
+    ConnectionParametersPreferences,
+    ConnectionPHY,
+    Device,
+    Connection,
+    Peer,
+)
 from bumble.utils import AsyncRunner
 from bumble.transport import open_transport_or_link
 from bumble.gatt import Characteristic, Service, CharacteristicDeclaration, Descriptor
@@ -125,6 +130,7 @@ def parse_phys(phys):
 # -----------------------------------------------------------------------------
 class ConsoleApp:
     connected_peer: Optional[Peer]
+    connection_phy: Optional[ConnectionPHY]
 
     def __init__(self):
         self.known_addresses = set()
@@ -132,6 +138,7 @@ class ConsoleApp:
         self.known_local_attributes = []
         self.device = None
         self.connected_peer = None
+        self.connection_phy = None
         self.top_tab = 'device'
         self.monitor_rssi = False
         self.connection_rssi = None
@@ -332,10 +339,10 @@ class ConsoleApp:
                     f'{connection.parameters.peripheral_latency}/'
                     f'{connection.parameters.supervision_timeout}'
                 )
-                if connection.transport == BT_LE_TRANSPORT:
+                if self.connection_phy is not None:
                     phy_state = (
-                        f' RX={le_phy_name(connection.phy.rx_phy)}/'
-                        f'TX={le_phy_name(connection.phy.tx_phy)}'
+                        f' RX={le_phy_name(self.connection_phy.rx_phy)}/'
+                        f'TX={le_phy_name(self.connection_phy.tx_phy)}'
                     )
                 else:
                     phy_state = ''
@@ -654,11 +661,12 @@ class ConsoleApp:
         self.append_to_output('connecting...')
 
         try:
-            await self.device.connect(
+            connection = await self.device.connect(
                 params[0],
                 connection_parameters_preferences=connection_parameters_preferences,
                 timeout=DEFAULT_CONNECTION_TIMEOUT,
             )
+            self.connection_phy = await connection.get_phy()
             self.top_tab = 'services'
         except bumble.core.TimeoutError:
             self.show_error('connection timed out')
@@ -838,8 +846,8 @@ class ConsoleApp:
 
         phy = await self.connected_peer.connection.get_phy()
         self.append_to_output(
-            f'PHY: RX={HCI_Constant.le_phy_name(phy[0])}, '
-            f'TX={HCI_Constant.le_phy_name(phy[1])}'
+            f'PHY: RX={HCI_Constant.le_phy_name(phy.rx_phy)}, '
+            f'TX={HCI_Constant.le_phy_name(phy.tx_phy)}'
         )
 
     async def do_request_mtu(self, params):
@@ -1076,10 +1084,9 @@ class DeviceListener(Device.Listener, Connection.Listener):
             f'{self.app.connected_peer.connection.parameters}'
         )
 
-    def on_connection_phy_update(self):
-        self.app.append_to_output(
-            f'connection phy update: {self.app.connected_peer.connection.phy}'
-        )
+    def on_connection_phy_update(self, phy):
+        self.app.connection_phy = phy
+        self.app.append_to_output(f'connection phy update: {phy}')
 
     def on_connection_att_mtu_update(self):
         self.app.append_to_output(

apps/controller_info.py

@@ -37,6 +37,8 @@ from bumble.hci import (
     HCI_Command_Status_Event,
     HCI_READ_BUFFER_SIZE_COMMAND,
     HCI_Read_Buffer_Size_Command,
+    HCI_LE_READ_BUFFER_SIZE_V2_COMMAND,
+    HCI_LE_Read_Buffer_Size_V2_Command,
     HCI_READ_BD_ADDR_COMMAND,
     HCI_Read_BD_ADDR_Command,
     HCI_READ_LOCAL_NAME_COMMAND,
@@ -147,7 +149,7 @@ async def get_le_info(host: Host) -> None:
 
 
 # -----------------------------------------------------------------------------
-async def get_acl_flow_control_info(host: Host) -> None:
+async def get_flow_control_info(host: Host) -> None:
     print()
 
     if host.supports_command(HCI_READ_BUFFER_SIZE_COMMAND):
@@ -160,14 +162,28 @@ async def get_acl_flow_control_info(host: Host) -> None:
             f'packets of size {response.return_parameters.hc_acl_data_packet_length}',
         )
 
-    if host.supports_command(HCI_LE_READ_BUFFER_SIZE_COMMAND):
+    if host.supports_command(HCI_LE_READ_BUFFER_SIZE_V2_COMMAND):
+        response = await host.send_command(
+            HCI_LE_Read_Buffer_Size_V2_Command(), check_result=True
+        )
+        print(
+            color('LE ACL Flow Control:', 'yellow'),
+            f'{response.return_parameters.total_num_le_acl_data_packets} '
+            f'packets of size {response.return_parameters.le_acl_data_packet_length}',
+        )
+        print(
+            color('LE ISO Flow Control:', 'yellow'),
+            f'{response.return_parameters.total_num_iso_data_packets} '
+            f'packets of size {response.return_parameters.iso_data_packet_length}',
+        )
+    elif host.supports_command(HCI_LE_READ_BUFFER_SIZE_COMMAND):
         response = await host.send_command(
             HCI_LE_Read_Buffer_Size_Command(), check_result=True
         )
         print(
             color('LE ACL Flow Control:', 'yellow'),
-            f'{response.return_parameters.hc_total_num_le_acl_data_packets} '
-            f'packets of size {response.return_parameters.hc_le_acl_data_packet_length}',
+            f'{response.return_parameters.total_num_le_acl_data_packets} '
+            f'packets of size {response.return_parameters.le_acl_data_packet_length}',
         )
 
 
@@ -274,8 +290,8 @@ async def async_main(latency_probes, transport):
         # Get the LE info
         await get_le_info(host)
 
-        # Print the ACL flow control info
-        await get_acl_flow_control_info(host)
+        # Print the flow control info
+        await get_flow_control_info(host)
 
         # Get codec info
         await get_codecs_info(host)

apps/device_info.py

@@ -29,7 +29,9 @@ from bumble.gatt import Service
 from bumble.profiles.device_information_service import DeviceInformationServiceProxy
 from bumble.profiles.battery_service import BatteryServiceProxy
 from bumble.profiles.gap import GenericAccessServiceProxy
+from bumble.profiles.pacs import PublishedAudioCapabilitiesServiceProxy
 from bumble.profiles.tmap import TelephonyAndMediaAudioServiceProxy
+from bumble.profiles.vcs import VolumeControlServiceProxy
 from bumble.transport import open_transport_or_link
 
 
@@ -126,14 +128,52 @@ async def show_tmas(
     print(color('### Telephony And Media Audio Service', 'yellow'))
 
     if tmas.role:
-        print(
-            color('  Role:', 'green'),
-            await tmas.role.read_value(),
-        )
+        role = await tmas.role.read_value()
+        print(color('  Role:', 'green'), role)
 
     print()
 
 
+# -----------------------------------------------------------------------------
+async def show_pacs(pacs: PublishedAudioCapabilitiesServiceProxy) -> None:
+    print(color('### Published Audio Capabilities Service', 'yellow'))
+
+    contexts = await pacs.available_audio_contexts.read_value()
+    print(color('  Available Audio Contexts:', 'green'), contexts)
+
+    contexts = await pacs.supported_audio_contexts.read_value()
+    print(color('  Supported Audio Contexts:', 'green'), contexts)
+
+    if pacs.sink_pac:
+        pac = await pacs.sink_pac.read_value()
+        print(color('  Sink PAC:                ', 'green'), pac)
+
+    if pacs.sink_audio_locations:
+        audio_locations = await pacs.sink_audio_locations.read_value()
+        print(color('  Sink Audio Locations:    ', 'green'), audio_locations)
+
+    if pacs.source_pac:
+        pac = await pacs.source_pac.read_value()
+        print(color('  Source PAC:              ', 'green'), pac)
+
+    if pacs.source_audio_locations:
+        audio_locations = await pacs.source_audio_locations.read_value()
+        print(color('  Source Audio Locations:  ', 'green'), audio_locations)
+
+    print()
+
+
+# -----------------------------------------------------------------------------
+async def show_vcs(vcs: VolumeControlServiceProxy) -> None:
+    print(color('### Volume Control Service', 'yellow'))
+
+    volume_state = await vcs.volume_state.read_value()
+    print(color('  Volume State:', 'green'), volume_state)
+
+    volume_flags = await vcs.volume_flags.read_value()
+    print(color('  Volume Flags:', 'green'), volume_flags)
+
+
 # -----------------------------------------------------------------------------
 async def show_device_info(peer, done: Optional[asyncio.Future]) -> None:
     try:
@@ -161,6 +201,12 @@ async def show_device_info(peer, done: Optional[asyncio.Future]) -> None:
         if tmas := peer.create_service_proxy(TelephonyAndMediaAudioServiceProxy):
             await try_show(show_tmas, tmas)
 
+        if pacs := peer.create_service_proxy(PublishedAudioCapabilitiesServiceProxy):
+            await try_show(show_pacs, pacs)
+
+        if vcs := peer.create_service_proxy(VolumeControlServiceProxy):
+            await try_show(show_vcs, vcs)
+
         if done is not None:
             done.set_result(None)
     except asyncio.CancelledError:

apps/gg_bridge.py

@@ -234,7 +234,7 @@ class GattlinkNodeBridge(GattlinkL2capEndpoint, Device.Listener):
             Characteristic.WRITEABLE,
             CharacteristicValue(write=self.on_rx_write),
         )
-        self.tx_characteristic = Characteristic(
+        self.tx_characteristic: Characteristic[bytes] = Characteristic(
             GG_GATTLINK_TX_CHARACTERISTIC_UUID,
             Characteristic.Properties.NOTIFY,
             Characteristic.READABLE,

apps/lea_unicast/app.py

@@ -39,7 +39,7 @@ import aiohttp.web
 import bumble
 from bumble.core import AdvertisingData
 from bumble.colors import color
-from bumble.device import Device, DeviceConfiguration, AdvertisingParameters
+from bumble.device import Device, DeviceConfiguration, AdvertisingParameters, CisLink
 from bumble.transport import open_transport
 from bumble.profiles import ascs, bap, pacs
 from bumble.hci import Address, CodecID, CodingFormat, HCI_IsoDataPacket
@@ -110,7 +110,7 @@ async def lc3_source_task(
     sdu_length: int,
     frame_duration_us: int,
     device: Device,
-    cis_handle: int,
+    cis_link: CisLink,
 ) -> None:
     logger.info(
         "lc3_source_task filename=%s, sdu_length=%d, frame_duration=%.1f",
@@ -120,7 +120,6 @@ async def lc3_source_task(
     )
     with wave.open(filename, 'rb') as wav:
         bits_per_sample = wav.getsampwidth() * 8
-        packet_sequence_number = 0
 
         encoder: lc3.Encoder | None = None
 
@@ -150,18 +149,8 @@ async def lc3_source_task(
                     num_bytes=sdu_length,
                     bit_depth=bits_per_sample,
                 )
+                cis_link.write(sdu)
 
-                iso_packet = HCI_IsoDataPacket(
-                    connection_handle=cis_handle,
-                    data_total_length=sdu_length + 4,
-                    packet_sequence_number=packet_sequence_number,
-                    pb_flag=0b10,
-                    packet_status_flag=0,
-                    iso_sdu_length=sdu_length,
-                    iso_sdu_fragment=sdu,
-                )
-                device.host.send_hci_packet(iso_packet)
-                packet_sequence_number += 1
             sleep_time = next_round - datetime.datetime.now()
             await asyncio.sleep(sleep_time.total_seconds() * 0.9)
 
@@ -309,6 +298,7 @@ class Speaker:
                     advertising_interval_min=25,
                     advertising_interval_max=25,
                     address=Address('F1:F2:F3:F4:F5:F6'),
+                    identity_address_type=Address.RANDOM_DEVICE_ADDRESS,
                 )
 
             device_config.le_enabled = True
@@ -393,7 +383,7 @@ class Speaker:
                                 ),
                                 frame_duration_us=codec_config.frame_duration.us,
                                 device=self.device,
-                                cis_handle=ase.cis_link.handle,
+                                cis_link=ase.cis_link,
                             ),
                         )
                     else:

bumble/att.py

@@ -29,13 +29,14 @@ import functools
 import inspect
 import struct
 from typing import (
-    Any,
     Awaitable,
     Callable,
+    Generic,
     Dict,
     List,
     Optional,
     Type,
+    TypeVar,
     Union,
     TYPE_CHECKING,
 )
@@ -43,13 +44,18 @@ from typing import (
 from pyee import EventEmitter
 
 from bumble import utils
-from bumble.core import UUID, name_or_number, ProtocolError
+from bumble.core import UUID, name_or_number, InvalidOperationError, ProtocolError
 from bumble.hci import HCI_Object, key_with_value
 from bumble.colors import color
 
+# -----------------------------------------------------------------------------
+# Typing
+# -----------------------------------------------------------------------------
 if TYPE_CHECKING:
     from bumble.device import Connection
 
+_T = TypeVar('_T')
+
 # -----------------------------------------------------------------------------
 # Constants
 # -----------------------------------------------------------------------------
@@ -217,7 +223,12 @@ UUID_2_FIELD_SPEC    = lambda x, y: UUID.parse_uuid_2(x, y)  # noqa: E731
 # Exceptions
 # -----------------------------------------------------------------------------
 class ATT_Error(ProtocolError):
-    def __init__(self, error_code, att_handle=0x0000, message=''):
+    error_code: int
+    att_handle: int
+
+    def __init__(
+        self, error_code: int, att_handle: int = 0x0000, message: str = ''
+    ) -> None:
         super().__init__(
             error_code,
             error_namespace='att',
@@ -227,7 +238,10 @@ class ATT_Error(ProtocolError):
         self.message = message
 
     def __str__(self):
-        return f'ATT_Error(error={self.error_name}, handle={self.att_handle:04X}): {self.message}'
+        return (
+            f'ATT_Error(error={self.error_name}, '
+            f'handle={self.att_handle:04X}): {self.message}'
+        )
 
 
 # -----------------------------------------------------------------------------
@@ -748,7 +762,7 @@ class ATT_Handle_Value_Confirmation(ATT_PDU):
 
 
 # -----------------------------------------------------------------------------
-class AttributeValue:
+class AttributeValue(Generic[_T]):
     '''
     Attribute value where reading and/or writing is delegated to functions
     passed as arguments to the constructor.
@@ -757,33 +771,34 @@ class AttributeValue:
     def __init__(
         self,
         read: Union[
-            Callable[[Optional[Connection]], Any],
-            Callable[[Optional[Connection]], Awaitable[Any]],
+            Callable[[Optional[Connection]], _T],
+            Callable[[Optional[Connection]], Awaitable[_T]],
             None,
         ] = None,
         write: Union[
-            Callable[[Optional[Connection], Any], None],
-            Callable[[Optional[Connection], Any], Awaitable[None]],
+            Callable[[Optional[Connection], _T], None],
+            Callable[[Optional[Connection], _T], Awaitable[None]],
             None,
         ] = None,
     ):
         self._read = read
         self._write = write
 
-    def read(self, connection: Optional[Connection]) -> Union[bytes, Awaitable[bytes]]:
-        return self._read(connection) if self._read else b''
+    def read(self, connection: Optional[Connection]) -> Union[_T, Awaitable[_T]]:
+        if self._read is None:
+            raise InvalidOperationError('AttributeValue has no read function')
+        return self._read(connection)
 
     def write(
-        self, connection: Optional[Connection], value: bytes
+        self, connection: Optional[Connection], value: _T
     ) -> Union[Awaitable[None], None]:
-        if self._write:
-            return self._write(connection, value)
-
-        return None
+        if self._write is None:
+            raise InvalidOperationError('AttributeValue has no write function')
+        return self._write(connection, value)
 
 
 # -----------------------------------------------------------------------------
-class Attribute(EventEmitter):
+class Attribute(EventEmitter, Generic[_T]):
     class Permissions(enum.IntFlag):
         READABLE = 0x01
         WRITEABLE = 0x02
@@ -822,13 +837,13 @@ class Attribute(EventEmitter):
     READ_REQUIRES_AUTHORIZATION = Permissions.READ_REQUIRES_AUTHORIZATION
     WRITE_REQUIRES_AUTHORIZATION = Permissions.WRITE_REQUIRES_AUTHORIZATION
 
-    value: Any
+    value: Union[AttributeValue[_T], _T, None]
 
     def __init__(
         self,
         attribute_type: Union[str, bytes, UUID],
         permissions: Union[str, Attribute.Permissions],
-        value: Any = b'',
+        value: Union[AttributeValue[_T], _T, None] = None,
     ) -> None:
         EventEmitter.__init__(self)
         self.handle = 0
@@ -848,11 +863,11 @@ class Attribute(EventEmitter):
 
         self.value = value
 
-    def encode_value(self, value: Any) -> bytes:
-        return value
+    def encode_value(self, value: _T) -> bytes:
+        return value  # type: ignore
 
-    def decode_value(self, value_bytes: bytes) -> Any:
-        return value_bytes
+    def decode_value(self, value: bytes) -> _T:
+        return value  # type: ignore
 
     async def read_value(self, connection: Optional[Connection]) -> bytes:
         if (
@@ -877,11 +892,14 @@ class Attribute(EventEmitter):
                 error_code=ATT_INSUFFICIENT_AUTHORIZATION_ERROR, att_handle=self.handle
             )
 
-        if hasattr(self.value, 'read'):
+        value: Union[_T, None]
+        if isinstance(self.value, AttributeValue):
             try:
-                value = self.value.read(connection)
-                if inspect.isawaitable(value):
-                    value = await value
+                read_value = self.value.read(connection)
+                if inspect.isawaitable(read_value):
+                    value = await read_value
+                else:
+                    value = read_value
             except ATT_Error as error:
                 raise ATT_Error(
                     error_code=error.error_code, att_handle=self.handle
@@ -889,20 +907,24 @@ class Attribute(EventEmitter):
         else:
             value = self.value
 
-        self.emit('read', connection, value)
+        self.emit('read', connection, b'' if value is None else value)
 
-        return self.encode_value(value)
+        return b'' if value is None else self.encode_value(value)
 
-    async def write_value(self, connection: Connection, value_bytes: bytes) -> None:
+    async def write_value(self, connection: Optional[Connection], value: bytes) -> None:
         if (
-            self.permissions & self.WRITE_REQUIRES_ENCRYPTION
-        ) and not connection.encryption:
+            (self.permissions & self.WRITE_REQUIRES_ENCRYPTION)
+            and connection is not None
+            and not connection.encryption
+        ):
             raise ATT_Error(
                 error_code=ATT_INSUFFICIENT_ENCRYPTION_ERROR, att_handle=self.handle
             )
         if (
-            self.permissions & self.WRITE_REQUIRES_AUTHENTICATION
-        ) and not connection.authenticated:
+            (self.permissions & self.WRITE_REQUIRES_AUTHENTICATION)
+            and connection is not None
+            and not connection.authenticated
+        ):
             raise ATT_Error(
                 error_code=ATT_INSUFFICIENT_AUTHENTICATION_ERROR, att_handle=self.handle
             )
@@ -912,11 +934,11 @@ class Attribute(EventEmitter):
                 error_code=ATT_INSUFFICIENT_AUTHORIZATION_ERROR, att_handle=self.handle
             )
 
-        value = self.decode_value(value_bytes)
+        decoded_value = self.decode_value(value)
 
-        if hasattr(self.value, 'write'):
+        if isinstance(self.value, AttributeValue):
             try:
-                result = self.value.write(connection, value)
+                result = self.value.write(connection, decoded_value)
                 if inspect.isawaitable(result):
                     await result
             except ATT_Error as error:
@@ -924,9 +946,9 @@ class Attribute(EventEmitter):
                     error_code=error.error_code, att_handle=self.handle
                 ) from error
         else:
-            self.value = value
+            self.value = decoded_value
 
-        self.emit('write', connection, value)
+        self.emit('write', connection, decoded_value)
 
     def __repr__(self):
         if isinstance(self.value, bytes):

bumble/audio/__init__.py

@@ -0,0 +1,17 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# -----------------------------------------------------------------------------
+# Imports
+# -----------------------------------------------------------------------------

bumble/audio/io.py

@@ -0,0 +1,553 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# -----------------------------------------------------------------------------
+# Imports
+# -----------------------------------------------------------------------------
+from __future__ import annotations
+
+import asyncio
+import abc
+from concurrent.futures import ThreadPoolExecutor
+import dataclasses
+import enum
+import logging
+import pathlib
+from typing import (
+    AsyncGenerator,
+    BinaryIO,
+    TYPE_CHECKING,
+)
+import sys
+import wave
+
+from bumble.colors import color
+
+if TYPE_CHECKING:
+    import sounddevice  # type: ignore[import-untyped]
+
+
+# -----------------------------------------------------------------------------
+# Logging
+# -----------------------------------------------------------------------------
+logger = logging.getLogger(__name__)
+
+
+# -----------------------------------------------------------------------------
+# Classes
+# -----------------------------------------------------------------------------
+@dataclasses.dataclass
+class PcmFormat:
+    class Endianness(enum.Enum):
+        LITTLE = 0
+        BIG = 1
+
+    class SampleType(enum.Enum):
+        FLOAT32 = 0
+        INT16 = 1
+
+    endianness: Endianness
+    sample_type: SampleType
+    sample_rate: int
+    channels: int
+
+    @classmethod
+    def from_str(cls, format_str: str) -> PcmFormat:
+        endianness = cls.Endianness.LITTLE  # Others not yet supported.
+        sample_type_str, sample_rate_str, channels_str = format_str.split(',')
+        if sample_type_str == 'int16le':
+            sample_type = cls.SampleType.INT16
+        elif sample_type_str == 'float32le':
+            sample_type = cls.SampleType.FLOAT32
+        else:
+            raise ValueError(f'sample type {sample_type_str} not supported')
+        sample_rate = int(sample_rate_str)
+        channels = int(channels_str)
+
+        return cls(endianness, sample_type, sample_rate, channels)
+
+    @property
+    def bytes_per_sample(self) -> int:
+        return 2 if self.sample_type == self.SampleType.INT16 else 4
+
+
+def check_audio_output(output: str) -> bool:
+    if output == 'device' or output.startswith('device:'):
+        try:
+            import sounddevice
+        except ImportError as exc:
+            raise ValueError(
+                'audio output not available (sounddevice python module not installed)'
+            ) from exc
+        except OSError as exc:
+            raise ValueError(
+                'audio output not available '
+                '(sounddevice python module failed to load: '
+                f'{exc})'
+            ) from exc
+
+        if output == 'device':
+            # Default device
+            return True
+
+        # Specific device
+        device = output[7:]
+        if device == '?':
+            print(color('Audio Devices:', 'yellow'))
+            for device_info in [
+                device_info
+                for device_info in sounddevice.query_devices()
+                if device_info['max_output_channels'] > 0
+            ]:
+                device_index = device_info['index']
+                is_default = (
+                    color(' [default]', 'green')
+                    if sounddevice.default.device[1] == device_index
+                    else ''
+                )
+                print(
+                    f'{color(device_index, "cyan")}: {device_info["name"]}{is_default}'
+                )
+            return False
+
+        try:
+            device_info = sounddevice.query_devices(int(device))
+        except sounddevice.PortAudioError as exc:
+            raise ValueError('No such audio device') from exc
+
+        if device_info['max_output_channels'] < 1:
+            raise ValueError(
+                f'Device {device} ({device_info["name"]}) does not have an output'
+            )
+
+    return True
+
+
+async def create_audio_output(output: str) -> AudioOutput:
+    if output == 'stdout':
+        return StreamAudioOutput(sys.stdout.buffer)
+
+    if output == 'device' or output.startswith('device:'):
+        device_name = '' if output == 'device' else output[7:]
+        return SoundDeviceAudioOutput(device_name)
+
+    if output == 'ffplay':
+        return SubprocessAudioOutput(
+            command=(
+                'ffplay -probesize 32 -fflags nobuffer -analyzeduration 0 '
+                '-ar {sample_rate} '
+                '-ch_layout {channel_layout} '
+                '-f f32le pipe:0'
+            )
+        )
+
+    if output.startswith('file:'):
+        return FileAudioOutput(output[5:])
+
+    raise ValueError('unsupported audio output')
+
+
+class AudioOutput(abc.ABC):
+    """Audio output to which PCM samples can be written."""
+
+    async def open(self, pcm_format: PcmFormat) -> None:
+        """Start the output."""
+
+    @abc.abstractmethod
+    def write(self, pcm_samples: bytes) -> None:
+        """Write PCM samples. Must not block."""
+
+    async def aclose(self) -> None:
+        """Close the output."""
+
+
+class ThreadedAudioOutput(AudioOutput):
+    """Base class for AudioOutput classes that may need to call blocking functions.
+
+    The actual writing is performed in a thread, so as to ensure that calling write()
+    does not block the caller.
+    """
+
+    def __init__(self) -> None:
+        self._thread_pool = ThreadPoolExecutor(1)
+        self._pcm_samples: asyncio.Queue[bytes] = asyncio.Queue()
+        self._write_task = asyncio.create_task(self._write_loop())
+
+    async def _write_loop(self) -> None:
+        while True:
+            pcm_samples = await self._pcm_samples.get()
+            await asyncio.get_running_loop().run_in_executor(
+                self._thread_pool, self._write, pcm_samples
+            )
+
+    @abc.abstractmethod
+    def _write(self, pcm_samples: bytes) -> None:
+        """This method does the actual writing and can block."""
+
+    def write(self, pcm_samples: bytes) -> None:
+        self._pcm_samples.put_nowait(pcm_samples)
+
+    def _close(self) -> None:
+        """This method does the actual closing and can block."""
+
+    async def aclose(self) -> None:
+        await asyncio.get_running_loop().run_in_executor(self._thread_pool, self._close)
+        self._write_task.cancel()
+        self._thread_pool.shutdown()
+
+
+class SoundDeviceAudioOutput(ThreadedAudioOutput):
+    def __init__(self, device_name: str) -> None:
+        super().__init__()
+        self._device = int(device_name) if device_name else None
+        self._stream: sounddevice.RawOutputStream | None = None
+
+    async def open(self, pcm_format: PcmFormat) -> None:
+        import sounddevice  # pylint: disable=import-error
+
+        self._stream = sounddevice.RawOutputStream(
+            samplerate=pcm_format.sample_rate,
+            device=self._device,
+            channels=pcm_format.channels,
+            dtype='float32',
+        )
+        self._stream.start()
+
+    def _write(self, pcm_samples: bytes) -> None:
+        if self._stream is None:
+            return
+
+        try:
+            self._stream.write(pcm_samples)
+        except Exception as error:
+            print(f'Sound device error: {error}')
+            raise
+
+    def _close(self):
+        self._stream.stop()
+        self._stream = None
+
+
+class StreamAudioOutput(ThreadedAudioOutput):
+    """AudioOutput where PCM samples are written to a stream that may block."""
+
+    def __init__(self, stream: BinaryIO) -> None:
+        super().__init__()
+        self._stream = stream
+
+    def _write(self, pcm_samples: bytes) -> None:
+        self._stream.write(pcm_samples)
+        self._stream.flush()
+
+
+class FileAudioOutput(StreamAudioOutput):
+    """AudioOutput where PCM samples are written to a file."""
+
+    def __init__(self, filename: str) -> None:
+        self._file = open(filename, "wb")
+        super().__init__(self._file)
+
+    async def shutdown(self):
+        self._file.close()
+        return await super().shutdown()
+
+
+class SubprocessAudioOutput(AudioOutput):
+    """AudioOutput where audio samples are written to a subprocess via stdin."""
+
+    def __init__(self, command: str) -> None:
+        self._command = command
+        self._subprocess: asyncio.subprocess.Process | None
+
+    async def open(self, pcm_format: PcmFormat) -> None:
+        if pcm_format.channels == 1:
+            channel_layout = 'mono'
+        elif pcm_format.channels == 2:
+            channel_layout = 'stereo'
+        else:
+            raise ValueError(f'{pcm_format.channels} channels not supported')
+
+        command = self._command.format(
+            sample_rate=pcm_format.sample_rate, channel_layout=channel_layout
+        )
+        self._subprocess = await asyncio.create_subprocess_shell(
+            command,
+            stdin=asyncio.subprocess.PIPE,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+        )
+
+    def write(self, pcm_samples: bytes) -> None:
+        if self._subprocess is None or self._subprocess.stdin is None:
+            return
+
+        self._subprocess.stdin.write(pcm_samples)
+
+    async def aclose(self):
+        if self._subprocess:
+            self._subprocess.terminate()
+
+
+def check_audio_input(input: str) -> bool:
+    if input == 'device' or input.startswith('device:'):
+        try:
+            import sounddevice  # pylint: disable=import-error
+        except ImportError as exc:
+            raise ValueError(
+                'audio input not available (sounddevice python module not installed)'
+            ) from exc
+        except OSError as exc:
+            raise ValueError(
+                'audio input not available '
+                '(sounddevice python module failed to load: '
+                f'{exc})'
+            ) from exc
+
+        if input == 'device':
+            # Default device
+            return True
+
+        # Specific device
+        device = input[7:]
+        if device == '?':
+            print(color('Audio Devices:', 'yellow'))
+            for device_info in [
+                device_info
+                for device_info in sounddevice.query_devices()
+                if device_info['max_input_channels'] > 0
+            ]:
+                device_index = device_info["index"]
+                is_mono = device_info['max_input_channels'] == 1
+                max_channels = color(f'[{"mono" if is_mono else "stereo"}]', 'cyan')
+                is_default = (
+                    color(' [default]', 'green')
+                    if sounddevice.default.device[0] == device_index
+                    else ''
+                )
+                print(
+                    f'{color(device_index, "cyan")}: {device_info["name"]}'
+                    f' {max_channels}{is_default}'
+                )
+            return False
+
+        try:
+            device_info = sounddevice.query_devices(int(device))
+        except sounddevice.PortAudioError as exc:
+            raise ValueError('No such audio device') from exc
+
+        if device_info['max_input_channels'] < 1:
+            raise ValueError(
+                f'Device {device} ({device_info["name"]}) does not have an input'
+            )
+
+    return True
+
+
+async def create_audio_input(input: str, input_format: str) -> AudioInput:
+    pcm_format: PcmFormat | None
+    if input_format == 'auto':
+        pcm_format = None
+    else:
+        pcm_format = PcmFormat.from_str(input_format)
+
+    if input == 'stdin':
+        if not pcm_format:
+            raise ValueError('input format details required for stdin')
+        return StreamAudioInput(sys.stdin.buffer, pcm_format)
+
+    if input == 'device' or input.startswith('device:'):
+        if not pcm_format:
+            raise ValueError('input format details required for device')
+        device_name = '' if input == 'device' else input[7:]
+        return SoundDeviceAudioInput(device_name, pcm_format)
+
+    # If there's no file: prefix, check if we can assume it is a file.
+    if pathlib.Path(input).is_file():
+        input = 'file:' + input
+
+    if input.startswith('file:'):
+        filename = input[5:]
+        if filename.endswith('.wav'):
+            if input_format != 'auto':
+                raise ValueError(".wav file only supported with 'auto' format")
+            return WaveAudioInput(filename)
+
+        if pcm_format is None:
+            raise ValueError('input format details required for raw PCM files')
+        return FileAudioInput(filename, pcm_format)
+
+    raise ValueError('input not supported')
+
+
+class AudioInput(abc.ABC):
+    """Audio input that produces PCM samples."""
+
+    @abc.abstractmethod
+    async def open(self) -> PcmFormat:
+        """Open the input."""
+
+    @abc.abstractmethod
+    def frames(self, frame_size: int) -> AsyncGenerator[bytes]:
+        """Generate one frame of PCM samples. Must not block."""
+
+    async def aclose(self) -> None:
+        """Close the input."""
+
+
+class ThreadedAudioInput(AudioInput):
+    """Base class for AudioInput implementation where reading samples may block."""
+
+    def __init__(self) -> None:
+        self._thread_pool = ThreadPoolExecutor(1)
+        self._pcm_samples: asyncio.Queue[bytes] = asyncio.Queue()
+
+    @abc.abstractmethod
+    def _read(self, frame_size: int) -> bytes:
+        pass
+
+    @abc.abstractmethod
+    def _open(self) -> PcmFormat:
+        pass
+
+    def _close(self) -> None:
+        pass
+
+    async def open(self) -> PcmFormat:
+        return await asyncio.get_running_loop().run_in_executor(
+            self._thread_pool, self._open
+        )
+
+    async def frames(self, frame_size: int) -> AsyncGenerator[bytes]:
+        while pcm_sample := await asyncio.get_running_loop().run_in_executor(
+            self._thread_pool, self._read, frame_size
+        ):
+            yield pcm_sample
+
+    async def aclose(self) -> None:
+        await asyncio.get_running_loop().run_in_executor(self._thread_pool, self._close)
+        self._thread_pool.shutdown()
+
+
+class WaveAudioInput(ThreadedAudioInput):
+    """Audio input that reads PCM samples from a .wav file."""
+
+    def __init__(self, filename: str) -> None:
+        super().__init__()
+        self._filename = filename
+        self._wav: wave.Wave_read | None = None
+        self._bytes_read = 0
+
+    def _open(self) -> PcmFormat:
+        self._wav = wave.open(self._filename, 'rb')
+        if self._wav.getsampwidth() != 2:
+            raise ValueError('sample width not supported')
+        return PcmFormat(
+            PcmFormat.Endianness.LITTLE,
+            PcmFormat.SampleType.INT16,
+            self._wav.getframerate(),
+            self._wav.getnchannels(),
+        )
+
+    def _read(self, frame_size: int) -> bytes:
+        if not self._wav:
+            return b''
+
+        pcm_samples = self._wav.readframes(frame_size)
+        if not pcm_samples and self._bytes_read:
+            # Loop around.
+            self._wav.rewind()
+            self._bytes_read = 0
+            pcm_samples = self._wav.readframes(frame_size)
+
+        self._bytes_read += len(pcm_samples)
+        return pcm_samples
+
+    def _close(self) -> None:
+        if self._wav:
+            self._wav.close()
+
+
+class StreamAudioInput(ThreadedAudioInput):
+    """AudioInput where samples are read from a raw PCM stream that may block."""
+
+    def __init__(self, stream: BinaryIO, pcm_format: PcmFormat) -> None:
+        super().__init__()
+        self._stream = stream
+        self._pcm_format = pcm_format
+
+    def _open(self) -> PcmFormat:
+        return self._pcm_format
+
+    def _read(self, frame_size: int) -> bytes:
+        return self._stream.read(
+            frame_size * self._pcm_format.channels * self._pcm_format.bytes_per_sample
+        )
+
+
+class FileAudioInput(StreamAudioInput):
+    """AudioInput where PCM samples are read from a raw PCM file."""
+
+    def __init__(self, filename: str, pcm_format: PcmFormat) -> None:
+        self._stream = open(filename, "rb")
+        super().__init__(self._stream, pcm_format)
+
+    def _close(self) -> None:
+        self._stream.close()
+
+
+class SoundDeviceAudioInput(ThreadedAudioInput):
+    def __init__(self, device_name: str, pcm_format: PcmFormat) -> None:
+        super().__init__()
+        self._device = int(device_name) if device_name else None
+        self._pcm_format = pcm_format
+        self._stream: sounddevice.RawInputStream | None = None
+
+    def _open(self) -> PcmFormat:
+        import sounddevice  # pylint: disable=import-error
+
+        self._stream = sounddevice.RawInputStream(
+            samplerate=self._pcm_format.sample_rate,
+            device=self._device,
+            channels=self._pcm_format.channels,
+            dtype='int16',
+        )
+        self._stream.start()
+
+        return PcmFormat(
+            PcmFormat.Endianness.LITTLE,
+            PcmFormat.SampleType.INT16,
+            self._pcm_format.sample_rate,
+            2,
+        )
+
+    def _read(self, frame_size: int) -> bytes:
+        if not self._stream:
+            return b''
+        pcm_buffer, overflowed = self._stream.read(frame_size)
+        if overflowed:
+            logger.warning("input overflow")
+
+        # Convert the buffer to stereo if needed
+        if self._pcm_format.channels == 1:
+            stereo_buffer = bytearray()
+            for i in range(frame_size):
+                sample = pcm_buffer[i * 2 : i * 2 + 2]
+                stereo_buffer += sample + sample
+            return stereo_buffer
+
+        return bytes(pcm_buffer)
+
+    def _close(self):
+        self._stream.stop()
+        self._stream = None

bumble/controller.py

@@ -25,8 +25,6 @@ import random
 import struct
 from bumble.colors import color
 from bumble.core import (
-    BT_CENTRAL_ROLE,
-    BT_PERIPHERAL_ROLE,
     BT_LE_TRANSPORT,
     BT_BR_EDR_TRANSPORT,
 )
@@ -47,6 +45,7 @@ from bumble.hci import (
     HCI_REMOTE_USER_TERMINATED_CONNECTION_ERROR,
     HCI_VERSION_BLUETOOTH_CORE_5_0,
     Address,
+    Role,
     HCI_AclDataPacket,
     HCI_AclDataPacketAssembler,
     HCI_Command_Complete_Event,
@@ -98,7 +97,7 @@ class CisLink:
 class Connection:
     controller: Controller
     handle: int
-    role: int
+    role: Role
     peer_address: Address
     link: Any
     transport: int
@@ -154,15 +153,17 @@ class Controller:
             '0000000060000000'
         )  # BR/EDR Not Supported, LE Supported (Controller)
         self.manufacturer_name = 0xFFFF
-        self.hc_data_packet_length = 27
-        self.hc_total_num_data_packets = 64
-        self.hc_le_data_packet_length = 27
-        self.hc_total_num_le_data_packets = 64
+        self.acl_data_packet_length = 27
+        self.total_num_acl_data_packets = 64
+        self.le_acl_data_packet_length = 27
+        self.total_num_le_acl_data_packets = 64
+        self.iso_data_packet_length = 960
+        self.total_num_iso_data_packets = 64
         self.event_mask = 0
         self.event_mask_page_2 = 0
         self.supported_commands = bytes.fromhex(
             '2000800000c000000000e4000000a822000000000000040000f7ffff7f000000'
-            '30f0f9ff01008004000000000000000000000000000000000000000000000000'
+            '30f0f9ff01008004002000000000000000000000000000000000000000000000'
         )
         self.le_event_mask = 0
         self.advertising_parameters = None
@@ -388,7 +389,7 @@ class Controller:
             connection = Connection(
                 controller=self,
                 handle=connection_handle,
-                role=BT_PERIPHERAL_ROLE,
+                role=Role.PERIPHERAL,
                 peer_address=peer_address,
                 link=self.link,
                 transport=BT_LE_TRANSPORT,
@@ -448,7 +449,7 @@ class Controller:
                 connection = Connection(
                     controller=self,
                     handle=connection_handle,
-                    role=BT_CENTRAL_ROLE,
+                    role=Role.CENTRAL,
                     peer_address=peer_address,
                     link=self.link,
                     transport=BT_LE_TRANSPORT,
@@ -467,7 +468,7 @@ class Controller:
             HCI_LE_Connection_Complete_Event(
                 status=status,
                 connection_handle=connection.handle if connection else 0,
-                role=BT_CENTRAL_ROLE,
+                role=Role.CENTRAL,
                 peer_address_type=le_create_connection_command.peer_address_type,
                 peer_address=le_create_connection_command.peer_address,
                 connection_interval=le_create_connection_command.connection_interval_min,
@@ -691,7 +692,7 @@ class Controller:
                     controller=self,
                     handle=connection_handle,
                     # Role doesn't matter in Classic because they are managed by HCI_Role_Change and HCI_Role_Discovery
-                    role=BT_CENTRAL_ROLE,
+                    role=Role.CENTRAL,
                     peer_address=peer_address,
                     link=self.link,
                     transport=BT_BR_EDR_TRANSPORT,
@@ -759,7 +760,7 @@ class Controller:
                 controller=self,
                 handle=connection_handle,
                 # Role doesn't matter in SCO.
-                role=BT_CENTRAL_ROLE,
+                role=Role.CENTRAL,
                 peer_address=peer_address,
                 link=self.link,
                 transport=BT_BR_EDR_TRANSPORT,
@@ -1181,9 +1182,9 @@ class Controller:
         return struct.pack(
             '<BHBHH',
             HCI_SUCCESS,
-            self.hc_data_packet_length,
+            self.acl_data_packet_length,
             0,
-            self.hc_total_num_data_packets,
+            self.total_num_acl_data_packets,
             0,
         )
 
@@ -1212,8 +1213,21 @@ class Controller:
         return struct.pack(
             '<BHB',
             HCI_SUCCESS,
-            self.hc_le_data_packet_length,
-            self.hc_total_num_le_data_packets,
+            self.le_acl_data_packet_length,
+            self.total_num_le_acl_data_packets,
+        )
+
+    def on_hci_le_read_buffer_size_v2_command(self, _command):
+        '''
+        See Bluetooth spec Vol 4, Part E - 7.8.2 LE Read Buffer Size Command
+        '''
+        return struct.pack(
+            '<BHBHB',
+            HCI_SUCCESS,
+            self.le_acl_data_packet_length,
+            self.total_num_le_acl_data_packets,
+            self.iso_data_packet_length,
+            self.total_num_iso_data_packets,
         )
 
     def on_hci_le_read_local_supported_features_command(self, _command):

bumble/core.py

@@ -1,4 +1,4 @@
-# Copyright 2021-2022 Google LLC
+# Copyright 2021-2025 Google LLC
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -16,10 +16,10 @@
 # Imports
 # -----------------------------------------------------------------------------
 from __future__ import annotations
-import dataclasses
+
 import enum
 import struct
-from typing import List, Optional, Tuple, Union, cast, Dict
+from typing import cast, overload, Literal, Union, Optional
 from typing_extensions import Self
 
 from bumble.company_ids import COMPANY_IDENTIFIERS
@@ -31,11 +31,12 @@ from bumble.utils import OpenIntEnum
 # -----------------------------------------------------------------------------
 # fmt: off
 
-BT_CENTRAL_ROLE    = 0
-BT_PERIPHERAL_ROLE = 1
+class PhysicalTransport(enum.IntEnum):
+    BR_EDR = 0
+    LE     = 1
 
-BT_BR_EDR_TRANSPORT = 0
-BT_LE_TRANSPORT     = 1
+BT_BR_EDR_TRANSPORT = PhysicalTransport.BR_EDR
+BT_LE_TRANSPORT     = PhysicalTransport.LE
 
 
 # fmt: on
@@ -57,7 +58,7 @@ def bit_flags_to_strings(bits, bit_flag_names):
     return names
 
 
-def name_or_number(dictionary: Dict[int, str], number: int, width: int = 2) -> str:
+def name_or_number(dictionary: dict[int, str], number: int, width: int = 2) -> str:
     name = dictionary.get(number)
     if name is not None:
         return name
@@ -200,7 +201,7 @@ class UUID:
     '''
 
     BASE_UUID = bytes.fromhex('00001000800000805F9B34FB')[::-1]  # little-endian
-    UUIDS: List[UUID] = []  # Registry of all instances created
+    UUIDS: list[UUID] = []  # Registry of all instances created
 
     uuid_bytes: bytes
     name: Optional[str]
@@ -259,11 +260,11 @@ class UUID:
         return cls.from_bytes(struct.pack('<I', uuid_32), name)
 
     @classmethod
-    def parse_uuid(cls, uuid_as_bytes: bytes, offset: int) -> Tuple[int, UUID]:
+    def parse_uuid(cls, uuid_as_bytes: bytes, offset: int) -> tuple[int, UUID]:
         return len(uuid_as_bytes), cls.from_bytes(uuid_as_bytes[offset:])
 
     @classmethod
-    def parse_uuid_2(cls, uuid_as_bytes: bytes, offset: int) -> Tuple[int, UUID]:
+    def parse_uuid_2(cls, uuid_as_bytes: bytes, offset: int) -> tuple[int, UUID]:
         return offset + 2, cls.from_bytes(uuid_as_bytes[offset : offset + 2])
 
     def to_bytes(self, force_128: bool = False) -> bytes:
@@ -1280,13 +1281,13 @@ class Appearance:
 # Advertising Data
 # -----------------------------------------------------------------------------
 AdvertisingDataObject = Union[
-    List[UUID],
-    Tuple[UUID, bytes],
+    list[UUID],
+    tuple[UUID, bytes],
     bytes,
     str,
     int,
-    Tuple[int, int],
-    Tuple[int, bytes],
+    tuple[int, int],
+    tuple[int, bytes],
     Appearance,
 ]
 
@@ -1295,116 +1296,116 @@ class AdvertisingData:
     # fmt: off
     # pylint: disable=line-too-long
 
-    FLAGS                                            = 0x01
-    INCOMPLETE_LIST_OF_16_BIT_SERVICE_CLASS_UUIDS    = 0x02
-    COMPLETE_LIST_OF_16_BIT_SERVICE_CLASS_UUIDS      = 0x03
-    INCOMPLETE_LIST_OF_32_BIT_SERVICE_CLASS_UUIDS    = 0x04
-    COMPLETE_LIST_OF_32_BIT_SERVICE_CLASS_UUIDS      = 0x05
-    INCOMPLETE_LIST_OF_128_BIT_SERVICE_CLASS_UUIDS   = 0x06
-    COMPLETE_LIST_OF_128_BIT_SERVICE_CLASS_UUIDS     = 0x07
-    SHORTENED_LOCAL_NAME                             = 0x08
-    COMPLETE_LOCAL_NAME                              = 0x09
-    TX_POWER_LEVEL                                   = 0x0A
-    CLASS_OF_DEVICE                                  = 0x0D
-    SIMPLE_PAIRING_HASH_C                            = 0x0E
-    SIMPLE_PAIRING_HASH_C_192                        = 0x0E
-    SIMPLE_PAIRING_RANDOMIZER_R                      = 0x0F
-    SIMPLE_PAIRING_RANDOMIZER_R_192                  = 0x0F
-    DEVICE_ID                                        = 0x10
-    SECURITY_MANAGER_TK_VALUE                        = 0x10
-    SECURITY_MANAGER_OUT_OF_BAND_FLAGS               = 0x11
-    PERIPHERAL_CONNECTION_INTERVAL_RANGE             = 0x12
-    LIST_OF_16_BIT_SERVICE_SOLICITATION_UUIDS        = 0x14
-    LIST_OF_128_BIT_SERVICE_SOLICITATION_UUIDS       = 0x15
-    SERVICE_DATA                                     = 0x16
-    SERVICE_DATA_16_BIT_UUID                         = 0x16
-    PUBLIC_TARGET_ADDRESS                            = 0x17
-    RANDOM_TARGET_ADDRESS                            = 0x18
-    APPEARANCE                                       = 0x19
-    ADVERTISING_INTERVAL                             = 0x1A
-    LE_BLUETOOTH_DEVICE_ADDRESS                      = 0x1B
-    LE_ROLE                                          = 0x1C
-    SIMPLE_PAIRING_HASH_C_256                        = 0x1D
-    SIMPLE_PAIRING_RANDOMIZER_R_256                  = 0x1E
-    LIST_OF_32_BIT_SERVICE_SOLICITATION_UUIDS        = 0x1F
-    SERVICE_DATA_32_BIT_UUID                         = 0x20
-    SERVICE_DATA_128_BIT_UUID                        = 0x21
-    LE_SECURE_CONNECTIONS_CONFIRMATION_VALUE         = 0x22
-    LE_SECURE_CONNECTIONS_RANDOM_VALUE               = 0x23
-    URI                                              = 0x24
-    INDOOR_POSITIONING                               = 0x25
-    TRANSPORT_DISCOVERY_DATA                         = 0x26
-    LE_SUPPORTED_FEATURES                            = 0x27
-    CHANNEL_MAP_UPDATE_INDICATION                    = 0x28
-    PB_ADV                                           = 0x29
-    MESH_MESSAGE                                     = 0x2A
-    MESH_BEACON                                      = 0x2B
-    BIGINFO                                          = 0x2C
-    BROADCAST_CODE                                   = 0x2D
-    RESOLVABLE_SET_IDENTIFIER                        = 0x2E
-    ADVERTISING_INTERVAL_LONG                        = 0x2F
-    BROADCAST_NAME                                   = 0x30
-    ENCRYPTED_ADVERTISING_DATA                       = 0X31
-    PERIODIC_ADVERTISING_RESPONSE_TIMING_INFORMATION = 0X32
-    ELECTRONIC_SHELF_LABEL                           = 0X34
-    THREE_D_INFORMATION_DATA                         = 0x3D
-    MANUFACTURER_SPECIFIC_DATA                       = 0xFF
+    class Type(OpenIntEnum):
+        FLAGS                                               = 0x01
+        INCOMPLETE_LIST_OF_16_BIT_SERVICE_CLASS_UUIDS       = 0x02
+        COMPLETE_LIST_OF_16_BIT_SERVICE_CLASS_UUIDS         = 0x03
+        INCOMPLETE_LIST_OF_32_BIT_SERVICE_CLASS_UUIDS       = 0x04
+        COMPLETE_LIST_OF_32_BIT_SERVICE_CLASS_UUIDS         = 0x05
+        INCOMPLETE_LIST_OF_128_BIT_SERVICE_CLASS_UUIDS      = 0x06
+        COMPLETE_LIST_OF_128_BIT_SERVICE_CLASS_UUIDS        = 0x07
+        SHORTENED_LOCAL_NAME                                = 0x08
+        COMPLETE_LOCAL_NAME                                 = 0x09
+        TX_POWER_LEVEL                                      = 0x0A
+        CLASS_OF_DEVICE                                     = 0x0D
+        SIMPLE_PAIRING_HASH_C                               = 0x0E
+        SIMPLE_PAIRING_HASH_C_192                           = 0x0E
+        SIMPLE_PAIRING_RANDOMIZER_R                         = 0x0F
+        SIMPLE_PAIRING_RANDOMIZER_R_192                     = 0x0F
+        DEVICE_ID                                           = 0x10
+        SECURITY_MANAGER_TK_VALUE                           = 0x10
+        SECURITY_MANAGER_OUT_OF_BAND_FLAGS                  = 0x11
+        PERIPHERAL_CONNECTION_INTERVAL_RANGE                = 0x12
+        LIST_OF_16_BIT_SERVICE_SOLICITATION_UUIDS           = 0x14
+        LIST_OF_128_BIT_SERVICE_SOLICITATION_UUIDS          = 0x15
+        SERVICE_DATA_16_BIT_UUID                            = 0x16
+        PUBLIC_TARGET_ADDRESS                               = 0x17
+        RANDOM_TARGET_ADDRESS                               = 0x18
+        APPEARANCE                                          = 0x19
+        ADVERTISING_INTERVAL                                = 0x1A
+        LE_BLUETOOTH_DEVICE_ADDRESS                         = 0x1B
+        LE_ROLE                                             = 0x1C
+        SIMPLE_PAIRING_HASH_C_256                           = 0x1D
+        SIMPLE_PAIRING_RANDOMIZER_R_256                     = 0x1E
+        LIST_OF_32_BIT_SERVICE_SOLICITATION_UUIDS           = 0x1F
+        SERVICE_DATA_32_BIT_UUID                            = 0x20
+        SERVICE_DATA_128_BIT_UUID                           = 0x21
+        LE_SECURE_CONNECTIONS_CONFIRMATION_VALUE            = 0x22
+        LE_SECURE_CONNECTIONS_RANDOM_VALUE                  = 0x23
+        URI                                                 = 0x24
+        INDOOR_POSITIONING                                  = 0x25
+        TRANSPORT_DISCOVERY_DATA                            = 0x26
+        LE_SUPPORTED_FEATURES                               = 0x27
+        CHANNEL_MAP_UPDATE_INDICATION                       = 0x28
+        PB_ADV                                              = 0x29
+        MESH_MESSAGE                                        = 0x2A
+        MESH_BEACON                                         = 0x2B
+        BIGINFO                                             = 0x2C
+        BROADCAST_CODE                                      = 0x2D
+        RESOLVABLE_SET_IDENTIFIER                           = 0x2E
+        ADVERTISING_INTERVAL_LONG                           = 0x2F
+        BROADCAST_NAME                                      = 0x30
+        ENCRYPTED_ADVERTISING_DATA                          = 0x31
+        PERIODIC_ADVERTISING_RESPONSE_TIMING_INFORMATION    = 0x32
+        ELECTRONIC_SHELF_LABEL                              = 0x34
+        THREE_D_INFORMATION_DATA                            = 0x3D
+        MANUFACTURER_SPECIFIC_DATA                          = 0xFF
 
-    AD_TYPE_NAMES = {
-        FLAGS:                                            'FLAGS',
-        INCOMPLETE_LIST_OF_16_BIT_SERVICE_CLASS_UUIDS:    'INCOMPLETE_LIST_OF_16_BIT_SERVICE_CLASS_UUIDS',
-        COMPLETE_LIST_OF_16_BIT_SERVICE_CLASS_UUIDS:      'COMPLETE_LIST_OF_16_BIT_SERVICE_CLASS_UUIDS',
-        INCOMPLETE_LIST_OF_32_BIT_SERVICE_CLASS_UUIDS:    'INCOMPLETE_LIST_OF_32_BIT_SERVICE_CLASS_UUIDS',
-        COMPLETE_LIST_OF_32_BIT_SERVICE_CLASS_UUIDS:      'COMPLETE_LIST_OF_32_BIT_SERVICE_CLASS_UUIDS',
-        INCOMPLETE_LIST_OF_128_BIT_SERVICE_CLASS_UUIDS:   'INCOMPLETE_LIST_OF_128_BIT_SERVICE_CLASS_UUIDS',
-        COMPLETE_LIST_OF_128_BIT_SERVICE_CLASS_UUIDS:     'COMPLETE_LIST_OF_128_BIT_SERVICE_CLASS_UUIDS',
-        SHORTENED_LOCAL_NAME:                             'SHORTENED_LOCAL_NAME',
-        COMPLETE_LOCAL_NAME:                              'COMPLETE_LOCAL_NAME',
-        TX_POWER_LEVEL:                                   'TX_POWER_LEVEL',
-        CLASS_OF_DEVICE:                                  'CLASS_OF_DEVICE',
-        SIMPLE_PAIRING_HASH_C:                            'SIMPLE_PAIRING_HASH_C',
-        SIMPLE_PAIRING_HASH_C_192:                        'SIMPLE_PAIRING_HASH_C_192',
-        SIMPLE_PAIRING_RANDOMIZER_R:                      'SIMPLE_PAIRING_RANDOMIZER_R',
-        SIMPLE_PAIRING_RANDOMIZER_R_192:                  'SIMPLE_PAIRING_RANDOMIZER_R_192',
-        DEVICE_ID:                                        'DEVICE_ID',
-        SECURITY_MANAGER_TK_VALUE:                        'SECURITY_MANAGER_TK_VALUE',
-        SECURITY_MANAGER_OUT_OF_BAND_FLAGS:               'SECURITY_MANAGER_OUT_OF_BAND_FLAGS',
-        PERIPHERAL_CONNECTION_INTERVAL_RANGE:             'PERIPHERAL_CONNECTION_INTERVAL_RANGE',
-        LIST_OF_16_BIT_SERVICE_SOLICITATION_UUIDS:        'LIST_OF_16_BIT_SERVICE_SOLICITATION_UUIDS',
-        LIST_OF_128_BIT_SERVICE_SOLICITATION_UUIDS:       'LIST_OF_128_BIT_SERVICE_SOLICITATION_UUIDS',
-        SERVICE_DATA_16_BIT_UUID:                         'SERVICE_DATA_16_BIT_UUID',
-        PUBLIC_TARGET_ADDRESS:                            'PUBLIC_TARGET_ADDRESS',
-        RANDOM_TARGET_ADDRESS:                            'RANDOM_TARGET_ADDRESS',
-        APPEARANCE:                                       'APPEARANCE',
-        ADVERTISING_INTERVAL:                             'ADVERTISING_INTERVAL',
-        LE_BLUETOOTH_DEVICE_ADDRESS:                      'LE_BLUETOOTH_DEVICE_ADDRESS',
-        LE_ROLE:                                          'LE_ROLE',
-        SIMPLE_PAIRING_HASH_C_256:                        'SIMPLE_PAIRING_HASH_C_256',
-        SIMPLE_PAIRING_RANDOMIZER_R_256:                  'SIMPLE_PAIRING_RANDOMIZER_R_256',
-        LIST_OF_32_BIT_SERVICE_SOLICITATION_UUIDS:        'LIST_OF_32_BIT_SERVICE_SOLICITATION_UUIDS',
-        SERVICE_DATA_32_BIT_UUID:                         'SERVICE_DATA_32_BIT_UUID',
-        SERVICE_DATA_128_BIT_UUID:                        'SERVICE_DATA_128_BIT_UUID',
-        LE_SECURE_CONNECTIONS_CONFIRMATION_VALUE:         'LE_SECURE_CONNECTIONS_CONFIRMATION_VALUE',
-        LE_SECURE_CONNECTIONS_RANDOM_VALUE:               'LE_SECURE_CONNECTIONS_RANDOM_VALUE',
-        URI:                                              'URI',
-        INDOOR_POSITIONING:                               'INDOOR_POSITIONING',
-        TRANSPORT_DISCOVERY_DATA:                         'TRANSPORT_DISCOVERY_DATA',
-        LE_SUPPORTED_FEATURES:                            'LE_SUPPORTED_FEATURES',
-        CHANNEL_MAP_UPDATE_INDICATION:                    'CHANNEL_MAP_UPDATE_INDICATION',
-        PB_ADV:                                           'PB_ADV',
-        MESH_MESSAGE:                                     'MESH_MESSAGE',
-        MESH_BEACON:                                      'MESH_BEACON',
-        BIGINFO:                                          'BIGINFO',
-        BROADCAST_CODE:                                   'BROADCAST_CODE',
-        RESOLVABLE_SET_IDENTIFIER:                        'RESOLVABLE_SET_IDENTIFIER',
-        ADVERTISING_INTERVAL_LONG:                        'ADVERTISING_INTERVAL_LONG',
-        BROADCAST_NAME:                                   'BROADCAST_NAME',
-        ENCRYPTED_ADVERTISING_DATA:                       'ENCRYPTED_ADVERTISING_DATA',
-        PERIODIC_ADVERTISING_RESPONSE_TIMING_INFORMATION: 'PERIODIC_ADVERTISING_RESPONSE_TIMING_INFORMATION',
-        ELECTRONIC_SHELF_LABEL:                           'ELECTRONIC_SHELF_LABEL',
-        THREE_D_INFORMATION_DATA:                         'THREE_D_INFORMATION_DATA',
-        MANUFACTURER_SPECIFIC_DATA:                       'MANUFACTURER_SPECIFIC_DATA'
-    }
+    # For backward-compatibility
+    FLAGS                                            = Type.FLAGS
+    INCOMPLETE_LIST_OF_16_BIT_SERVICE_CLASS_UUIDS    = Type.INCOMPLETE_LIST_OF_16_BIT_SERVICE_CLASS_UUIDS
+    COMPLETE_LIST_OF_16_BIT_SERVICE_CLASS_UUIDS      = Type.COMPLETE_LIST_OF_16_BIT_SERVICE_CLASS_UUIDS
+    INCOMPLETE_LIST_OF_32_BIT_SERVICE_CLASS_UUIDS    = Type.INCOMPLETE_LIST_OF_32_BIT_SERVICE_CLASS_UUIDS
+    COMPLETE_LIST_OF_32_BIT_SERVICE_CLASS_UUIDS      = Type.COMPLETE_LIST_OF_32_BIT_SERVICE_CLASS_UUIDS
+    INCOMPLETE_LIST_OF_128_BIT_SERVICE_CLASS_UUIDS   = Type.INCOMPLETE_LIST_OF_128_BIT_SERVICE_CLASS_UUIDS
+    COMPLETE_LIST_OF_128_BIT_SERVICE_CLASS_UUIDS     = Type.COMPLETE_LIST_OF_128_BIT_SERVICE_CLASS_UUIDS
+    SHORTENED_LOCAL_NAME                             = Type.SHORTENED_LOCAL_NAME
+    COMPLETE_LOCAL_NAME                              = Type.COMPLETE_LOCAL_NAME
+    TX_POWER_LEVEL                                   = Type.TX_POWER_LEVEL
+    CLASS_OF_DEVICE                                  = Type.CLASS_OF_DEVICE
+    SIMPLE_PAIRING_HASH_C                            = Type.SIMPLE_PAIRING_HASH_C
+    SIMPLE_PAIRING_HASH_C_192                        = Type.SIMPLE_PAIRING_HASH_C_192
+    SIMPLE_PAIRING_RANDOMIZER_R                      = Type.SIMPLE_PAIRING_RANDOMIZER_R
+    SIMPLE_PAIRING_RANDOMIZER_R_192                  = Type.SIMPLE_PAIRING_RANDOMIZER_R_192
+    DEVICE_ID                                        = Type.DEVICE_ID
+    SECURITY_MANAGER_TK_VALUE                        = Type.SECURITY_MANAGER_TK_VALUE
+    SECURITY_MANAGER_OUT_OF_BAND_FLAGS               = Type.SECURITY_MANAGER_OUT_OF_BAND_FLAGS
+    PERIPHERAL_CONNECTION_INTERVAL_RANGE             = Type.PERIPHERAL_CONNECTION_INTERVAL_RANGE
+    LIST_OF_16_BIT_SERVICE_SOLICITATION_UUIDS        = Type.LIST_OF_16_BIT_SERVICE_SOLICITATION_UUIDS
+    LIST_OF_128_BIT_SERVICE_SOLICITATION_UUIDS       = Type.LIST_OF_128_BIT_SERVICE_SOLICITATION_UUIDS
+    SERVICE_DATA                                     = Type.SERVICE_DATA_16_BIT_UUID
+    SERVICE_DATA_16_BIT_UUID                         = Type.SERVICE_DATA_16_BIT_UUID
+    PUBLIC_TARGET_ADDRESS                            = Type.PUBLIC_TARGET_ADDRESS
+    RANDOM_TARGET_ADDRESS                            = Type.RANDOM_TARGET_ADDRESS
+    APPEARANCE                                       = Type.APPEARANCE
+    ADVERTISING_INTERVAL                             = Type.ADVERTISING_INTERVAL
+    LE_BLUETOOTH_DEVICE_ADDRESS                      = Type.LE_BLUETOOTH_DEVICE_ADDRESS
+    LE_ROLE                                          = Type.LE_ROLE
+    SIMPLE_PAIRING_HASH_C_256                        = Type.SIMPLE_PAIRING_HASH_C_256
+    SIMPLE_PAIRING_RANDOMIZER_R_256                  = Type.SIMPLE_PAIRING_RANDOMIZER_R_256
+    LIST_OF_32_BIT_SERVICE_SOLICITATION_UUIDS        = Type.LIST_OF_32_BIT_SERVICE_SOLICITATION_UUIDS
+    SERVICE_DATA_32_BIT_UUID                         = Type.SERVICE_DATA_32_BIT_UUID
+    SERVICE_DATA_128_BIT_UUID                        = Type.SERVICE_DATA_128_BIT_UUID
+    LE_SECURE_CONNECTIONS_CONFIRMATION_VALUE         = Type.LE_SECURE_CONNECTIONS_CONFIRMATION_VALUE
+    LE_SECURE_CONNECTIONS_RANDOM_VALUE               = Type.LE_SECURE_CONNECTIONS_RANDOM_VALUE
+    URI                                              = Type.URI
+    INDOOR_POSITIONING                               = Type.INDOOR_POSITIONING
+    TRANSPORT_DISCOVERY_DATA                         = Type.TRANSPORT_DISCOVERY_DATA
+    LE_SUPPORTED_FEATURES                            = Type.LE_SUPPORTED_FEATURES
+    CHANNEL_MAP_UPDATE_INDICATION                    = Type.CHANNEL_MAP_UPDATE_INDICATION
+    PB_ADV                                           = Type.PB_ADV
+    MESH_MESSAGE                                     = Type.MESH_MESSAGE
+    MESH_BEACON                                      = Type.MESH_BEACON
+    BIGINFO                                          = Type.BIGINFO
+    BROADCAST_CODE                                   = Type.BROADCAST_CODE
+    RESOLVABLE_SET_IDENTIFIER                        = Type.RESOLVABLE_SET_IDENTIFIER
+    ADVERTISING_INTERVAL_LONG                        = Type.ADVERTISING_INTERVAL_LONG
+    BROADCAST_NAME                                   = Type.BROADCAST_NAME
+    ENCRYPTED_ADVERTISING_DATA                       = Type.ENCRYPTED_ADVERTISING_DATA
+    PERIODIC_ADVERTISING_RESPONSE_TIMING_INFORMATION = Type.PERIODIC_ADVERTISING_RESPONSE_TIMING_INFORMATION
+    ELECTRONIC_SHELF_LABEL                           = Type.ELECTRONIC_SHELF_LABEL
+    THREE_D_INFORMATION_DATA                         = Type.THREE_D_INFORMATION_DATA
+    MANUFACTURER_SPECIFIC_DATA                       = Type.MANUFACTURER_SPECIFIC_DATA
 
     LE_LIMITED_DISCOVERABLE_MODE_FLAG = 0x01
     LE_GENERAL_DISCOVERABLE_MODE_FLAG = 0x02
@@ -1412,12 +1413,12 @@ class AdvertisingData:
     BR_EDR_CONTROLLER_FLAG            = 0x08
     BR_EDR_HOST_FLAG                  = 0x10
 
-    ad_structures: List[Tuple[int, bytes]]
+    ad_structures: list[tuple[int, bytes]]
 
     # fmt: on
     # pylint: enable=line-too-long
 
-    def __init__(self, ad_structures: Optional[List[Tuple[int, bytes]]] = None) -> None:
+    def __init__(self, ad_structures: Optional[list[tuple[int, bytes]]] = None) -> None:
         if ad_structures is None:
             ad_structures = []
         self.ad_structures = ad_structures[:]
@@ -1444,7 +1445,7 @@ class AdvertisingData:
         return ','.join(bit_flags_to_strings(flags, flag_names))
 
     @staticmethod
-    def uuid_list_to_objects(ad_data: bytes, uuid_size: int) -> List[UUID]:
+    def uuid_list_to_objects(ad_data: bytes, uuid_size: int) -> list[UUID]:
         uuids = []
         offset = 0
         while (offset + uuid_size) <= len(ad_data):
@@ -1461,8 +1462,8 @@ class AdvertisingData:
             ]
         )
 
-    @staticmethod
-    def ad_data_to_string(ad_type, ad_data):
+    @classmethod
+    def ad_data_to_string(cls, ad_type: int, ad_data: bytes) -> str:
         if ad_type == AdvertisingData.FLAGS:
             ad_type_str = 'Flags'
             ad_data_str = AdvertisingData.flags_to_string(ad_data[0], short=True)
@@ -1501,7 +1502,10 @@ class AdvertisingData:
             ad_data_str = f'"{ad_data.decode("utf-8")}"'
         elif ad_type == AdvertisingData.COMPLETE_LOCAL_NAME:
             ad_type_str = 'Complete Local Name'
-            ad_data_str = f'"{ad_data.decode("utf-8")}"'
+            try:
+                ad_data_str = f'"{ad_data.decode("utf-8")}"'
+            except UnicodeDecodeError:
+                ad_data_str = ad_data.hex()
         elif ad_type == AdvertisingData.TX_POWER_LEVEL:
             ad_type_str = 'TX Power Level'
             ad_data_str = str(ad_data[0])
@@ -1518,72 +1522,72 @@ class AdvertisingData:
             ad_type_str = 'Broadcast Name'
             ad_data_str = ad_data.decode('utf-8')
         else:
-            ad_type_str = AdvertisingData.AD_TYPE_NAMES.get(ad_type, f'0x{ad_type:02X}')
+            ad_type_str = AdvertisingData.Type(ad_type).name
             ad_data_str = ad_data.hex()
 
         return f'[{ad_type_str}]: {ad_data_str}'
 
     # pylint: disable=too-many-return-statements
-    @staticmethod
-    def ad_data_to_object(ad_type: int, ad_data: bytes) -> AdvertisingDataObject:
+    @classmethod
+    def ad_data_to_object(cls, ad_type: int, ad_data: bytes) -> AdvertisingDataObject:
         if ad_type in (
-            AdvertisingData.COMPLETE_LIST_OF_16_BIT_SERVICE_CLASS_UUIDS,
-            AdvertisingData.INCOMPLETE_LIST_OF_16_BIT_SERVICE_CLASS_UUIDS,
-            AdvertisingData.LIST_OF_16_BIT_SERVICE_SOLICITATION_UUIDS,
+            AdvertisingData.Type.COMPLETE_LIST_OF_16_BIT_SERVICE_CLASS_UUIDS,
+            AdvertisingData.Type.INCOMPLETE_LIST_OF_16_BIT_SERVICE_CLASS_UUIDS,
+            AdvertisingData.Type.LIST_OF_16_BIT_SERVICE_SOLICITATION_UUIDS,
         ):
             return AdvertisingData.uuid_list_to_objects(ad_data, 2)
 
         if ad_type in (
-            AdvertisingData.COMPLETE_LIST_OF_32_BIT_SERVICE_CLASS_UUIDS,
-            AdvertisingData.INCOMPLETE_LIST_OF_32_BIT_SERVICE_CLASS_UUIDS,
-            AdvertisingData.LIST_OF_32_BIT_SERVICE_SOLICITATION_UUIDS,
+            AdvertisingData.Type.COMPLETE_LIST_OF_32_BIT_SERVICE_CLASS_UUIDS,
+            AdvertisingData.Type.INCOMPLETE_LIST_OF_32_BIT_SERVICE_CLASS_UUIDS,
+            AdvertisingData.Type.LIST_OF_32_BIT_SERVICE_SOLICITATION_UUIDS,
         ):
             return AdvertisingData.uuid_list_to_objects(ad_data, 4)
 
         if ad_type in (
-            AdvertisingData.COMPLETE_LIST_OF_128_BIT_SERVICE_CLASS_UUIDS,
-            AdvertisingData.INCOMPLETE_LIST_OF_128_BIT_SERVICE_CLASS_UUIDS,
-            AdvertisingData.LIST_OF_128_BIT_SERVICE_SOLICITATION_UUIDS,
+            AdvertisingData.Type.COMPLETE_LIST_OF_128_BIT_SERVICE_CLASS_UUIDS,
+            AdvertisingData.Type.INCOMPLETE_LIST_OF_128_BIT_SERVICE_CLASS_UUIDS,
+            AdvertisingData.Type.LIST_OF_128_BIT_SERVICE_SOLICITATION_UUIDS,
         ):
             return AdvertisingData.uuid_list_to_objects(ad_data, 16)
 
-        if ad_type == AdvertisingData.SERVICE_DATA_16_BIT_UUID:
+        if ad_type == AdvertisingData.Type.SERVICE_DATA_16_BIT_UUID:
             return (UUID.from_bytes(ad_data[:2]), ad_data[2:])
 
-        if ad_type == AdvertisingData.SERVICE_DATA_32_BIT_UUID:
+        if ad_type == AdvertisingData.Type.SERVICE_DATA_32_BIT_UUID:
             return (UUID.from_bytes(ad_data[:4]), ad_data[4:])
 
-        if ad_type == AdvertisingData.SERVICE_DATA_128_BIT_UUID:
+        if ad_type == AdvertisingData.Type.SERVICE_DATA_128_BIT_UUID:
             return (UUID.from_bytes(ad_data[:16]), ad_data[16:])
 
         if ad_type in (
-            AdvertisingData.SHORTENED_LOCAL_NAME,
-            AdvertisingData.COMPLETE_LOCAL_NAME,
-            AdvertisingData.URI,
-            AdvertisingData.BROADCAST_NAME,
+            AdvertisingData.Type.SHORTENED_LOCAL_NAME,
+            AdvertisingData.Type.COMPLETE_LOCAL_NAME,
+            AdvertisingData.Type.URI,
+            AdvertisingData.Type.BROADCAST_NAME,
         ):
             return ad_data.decode("utf-8")
 
-        if ad_type in (AdvertisingData.TX_POWER_LEVEL, AdvertisingData.FLAGS):
+        if ad_type in (AdvertisingData.Type.TX_POWER_LEVEL, AdvertisingData.Type.FLAGS):
             return cast(int, struct.unpack('B', ad_data)[0])
 
-        if ad_type in (AdvertisingData.ADVERTISING_INTERVAL,):
+        if ad_type in (AdvertisingData.Type.ADVERTISING_INTERVAL,):
             return cast(int, struct.unpack('<H', ad_data)[0])
 
-        if ad_type == AdvertisingData.CLASS_OF_DEVICE:
+        if ad_type == AdvertisingData.Type.CLASS_OF_DEVICE:
             return cast(int, struct.unpack('<I', bytes([*ad_data, 0]))[0])
 
-        if ad_type == AdvertisingData.PERIPHERAL_CONNECTION_INTERVAL_RANGE:
-            return cast(Tuple[int, int], struct.unpack('<HH', ad_data))
+        if ad_type == AdvertisingData.Type.PERIPHERAL_CONNECTION_INTERVAL_RANGE:
+            return cast(tuple[int, int], struct.unpack('<HH', ad_data))
 
-        if ad_type == AdvertisingData.MANUFACTURER_SPECIFIC_DATA:
-            return (cast(int, struct.unpack_from('<H', ad_data, 0)[0]), ad_data[2:])
-
-        if ad_type == AdvertisingData.APPEARANCE:
+        if ad_type == AdvertisingData.Type.APPEARANCE:
             return Appearance.from_int(
                 cast(int, struct.unpack_from('<H', ad_data, 0)[0])
             )
 
+        if ad_type == AdvertisingData.Type.MANUFACTURER_SPECIFIC_DATA:
+            return (cast(int, struct.unpack_from('<H', ad_data, 0)[0]), ad_data[2:])
+
         return ad_data
 
     def append(self, data: bytes) -> None:
@@ -1597,7 +1601,80 @@ class AdvertisingData:
                 self.ad_structures.append((ad_type, ad_data))
             offset += length
 
-    def get_all(self, type_id: int, raw: bool = False) -> List[AdvertisingDataObject]:
+    @overload
+    def get_all(
+        self,
+        type_id: Literal[
+            AdvertisingData.Type.COMPLETE_LIST_OF_16_BIT_SERVICE_CLASS_UUIDS,
+            AdvertisingData.Type.INCOMPLETE_LIST_OF_16_BIT_SERVICE_CLASS_UUIDS,
+            AdvertisingData.Type.LIST_OF_16_BIT_SERVICE_SOLICITATION_UUIDS,
+            AdvertisingData.Type.COMPLETE_LIST_OF_32_BIT_SERVICE_CLASS_UUIDS,
+            AdvertisingData.Type.INCOMPLETE_LIST_OF_32_BIT_SERVICE_CLASS_UUIDS,
+            AdvertisingData.Type.LIST_OF_32_BIT_SERVICE_SOLICITATION_UUIDS,
+            AdvertisingData.Type.COMPLETE_LIST_OF_128_BIT_SERVICE_CLASS_UUIDS,
+            AdvertisingData.Type.INCOMPLETE_LIST_OF_128_BIT_SERVICE_CLASS_UUIDS,
+            AdvertisingData.Type.LIST_OF_128_BIT_SERVICE_SOLICITATION_UUIDS,
+        ],
+        raw: Literal[False] = False,
+    ) -> list[list[UUID]]: ...
+    @overload
+    def get_all(
+        self,
+        type_id: Literal[
+            AdvertisingData.Type.SERVICE_DATA_16_BIT_UUID,
+            AdvertisingData.Type.SERVICE_DATA_32_BIT_UUID,
+            AdvertisingData.Type.SERVICE_DATA_128_BIT_UUID,
+        ],
+        raw: Literal[False] = False,
+    ) -> list[tuple[UUID, bytes]]: ...
+    @overload
+    def get_all(
+        self,
+        type_id: Literal[
+            AdvertisingData.Type.SHORTENED_LOCAL_NAME,
+            AdvertisingData.Type.COMPLETE_LOCAL_NAME,
+            AdvertisingData.Type.URI,
+            AdvertisingData.Type.BROADCAST_NAME,
+        ],
+        raw: Literal[False] = False,
+    ) -> list[str]: ...
+    @overload
+    def get_all(
+        self,
+        type_id: Literal[
+            AdvertisingData.Type.TX_POWER_LEVEL,
+            AdvertisingData.Type.FLAGS,
+            AdvertisingData.Type.ADVERTISING_INTERVAL,
+            AdvertisingData.Type.CLASS_OF_DEVICE,
+        ],
+        raw: Literal[False] = False,
+    ) -> list[int]: ...
+    @overload
+    def get_all(
+        self,
+        type_id: Literal[AdvertisingData.Type.PERIPHERAL_CONNECTION_INTERVAL_RANGE,],
+        raw: Literal[False] = False,
+    ) -> list[tuple[int, int]]: ...
+    @overload
+    def get_all(
+        self,
+        type_id: Literal[AdvertisingData.Type.MANUFACTURER_SPECIFIC_DATA,],
+        raw: Literal[False] = False,
+    ) -> list[tuple[int, bytes]]: ...
+    @overload
+    def get_all(
+        self,
+        type_id: Literal[AdvertisingData.Type.APPEARANCE,],
+        raw: Literal[False] = False,
+    ) -> list[Appearance]: ...
+    @overload
+    def get_all(self, type_id: int, raw: Literal[True]) -> list[bytes]: ...
+    @overload
+    def get_all(
+        self, type_id: int, raw: bool = False
+    ) -> list[AdvertisingDataObject]: ...
+
+    def get_all(self, type_id: int, raw: bool = False) -> list[AdvertisingDataObject]:  # type: ignore[misc]
         '''
         Get Advertising Data Structure(s) with a given type
 
@@ -1609,6 +1686,79 @@ class AdvertisingData:
 
         return [process_ad_data(ad[1]) for ad in self.ad_structures if ad[0] == type_id]
 
+    @overload
+    def get(
+        self,
+        type_id: Literal[
+            AdvertisingData.Type.COMPLETE_LIST_OF_16_BIT_SERVICE_CLASS_UUIDS,
+            AdvertisingData.Type.INCOMPLETE_LIST_OF_16_BIT_SERVICE_CLASS_UUIDS,
+            AdvertisingData.Type.LIST_OF_16_BIT_SERVICE_SOLICITATION_UUIDS,
+            AdvertisingData.Type.COMPLETE_LIST_OF_32_BIT_SERVICE_CLASS_UUIDS,
+            AdvertisingData.Type.INCOMPLETE_LIST_OF_32_BIT_SERVICE_CLASS_UUIDS,
+            AdvertisingData.Type.LIST_OF_32_BIT_SERVICE_SOLICITATION_UUIDS,
+            AdvertisingData.Type.COMPLETE_LIST_OF_128_BIT_SERVICE_CLASS_UUIDS,
+            AdvertisingData.Type.INCOMPLETE_LIST_OF_128_BIT_SERVICE_CLASS_UUIDS,
+            AdvertisingData.Type.LIST_OF_128_BIT_SERVICE_SOLICITATION_UUIDS,
+        ],
+        raw: Literal[False] = False,
+    ) -> Optional[list[UUID]]: ...
+    @overload
+    def get(
+        self,
+        type_id: Literal[
+            AdvertisingData.Type.SERVICE_DATA_16_BIT_UUID,
+            AdvertisingData.Type.SERVICE_DATA_32_BIT_UUID,
+            AdvertisingData.Type.SERVICE_DATA_128_BIT_UUID,
+        ],
+        raw: Literal[False] = False,
+    ) -> Optional[tuple[UUID, bytes]]: ...
+    @overload
+    def get(
+        self,
+        type_id: Literal[
+            AdvertisingData.Type.SHORTENED_LOCAL_NAME,
+            AdvertisingData.Type.COMPLETE_LOCAL_NAME,
+            AdvertisingData.Type.URI,
+            AdvertisingData.Type.BROADCAST_NAME,
+        ],
+        raw: Literal[False] = False,
+    ) -> Optional[Optional[str]]: ...
+    @overload
+    def get(
+        self,
+        type_id: Literal[
+            AdvertisingData.Type.TX_POWER_LEVEL,
+            AdvertisingData.Type.FLAGS,
+            AdvertisingData.Type.ADVERTISING_INTERVAL,
+            AdvertisingData.Type.CLASS_OF_DEVICE,
+        ],
+        raw: Literal[False] = False,
+    ) -> Optional[int]: ...
+    @overload
+    def get(
+        self,
+        type_id: Literal[AdvertisingData.Type.PERIPHERAL_CONNECTION_INTERVAL_RANGE,],
+        raw: Literal[False] = False,
+    ) -> Optional[tuple[int, int]]: ...
+    @overload
+    def get(
+        self,
+        type_id: Literal[AdvertisingData.Type.MANUFACTURER_SPECIFIC_DATA,],
+        raw: Literal[False] = False,
+    ) -> Optional[tuple[int, bytes]]: ...
+    @overload
+    def get(
+        self,
+        type_id: Literal[AdvertisingData.Type.APPEARANCE,],
+        raw: Literal[False] = False,
+    ) -> Optional[Appearance]: ...
+    @overload
+    def get(self, type_id: int, raw: Literal[True]) -> Optional[bytes]: ...
+    @overload
+    def get(
+        self, type_id: int, raw: bool = False
+    ) -> Optional[AdvertisingDataObject]: ...
+
     def get(self, type_id: int, raw: bool = False) -> Optional[AdvertisingDataObject]:
         '''
         Get Advertising Data Structure(s) with a given type

bumble/gatt.py

@@ -27,29 +27,16 @@ import enum
 import functools
 import logging
 import struct
-from typing import (
-    Any,
-    Callable,
-    Dict,
-    Iterable,
-    List,
-    Optional,
-    Sequence,
-    SupportsBytes,
-    Type,
-    Union,
-    TYPE_CHECKING,
-)
+from typing import Iterable, List, Optional, Sequence, TypeVar, Union
 
 from bumble.colors import color
 from bumble.core import BaseBumbleError, 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
 
+# -----------------------------------------------------------------------------
+# Typing
+# -----------------------------------------------------------------------------
+_T = TypeVar('_T')
 
 # -----------------------------------------------------------------------------
 # Logging
@@ -299,6 +286,22 @@ GATT_ASHA_AUDIO_STATUS_CHARACTERISTIC         = UUID('38663f1a-e711-4cac-b641-32
 GATT_ASHA_VOLUME_CHARACTERISTIC               = UUID('00e4ca9e-ab14-41e4-8823-f9e70c7e91df', 'Volume')
 GATT_ASHA_LE_PSM_OUT_CHARACTERISTIC           = UUID('2d410339-82b6-42aa-b34e-e2e01df8cc1a', 'LE_PSM_OUT')
 
+# Apple Notification Center Service
+GATT_ANCS_SERVICE                            = UUID('7905F431-B5CE-4E99-A40F-4B1E122D00D0', 'Apple Notification Center')
+GATT_ANCS_NOTIFICATION_SOURCE_CHARACTERISTIC = UUID('9FBF120D-6301-42D9-8C58-25E699A21DBD', 'Notification Source')
+GATT_ANCS_CONTROL_POINT_CHARACTERISTIC       = UUID('69D1D8F3-45E1-49A8-9821-9BBDFDAAD9D9', 'Control Point')
+GATT_ANCS_DATA_SOURCE_CHARACTERISTIC         = UUID('22EAC6E9-24D6-4BB5-BE44-B36ACE7C7BFB', 'Data Source')
+
+# Apple Media Service
+GATT_AMS_SERVICE                         = UUID('89D3502B-0F36-433A-8EF4-C502AD55F8DC', 'Apple Media')
+GATT_AMS_REMOTE_COMMAND_CHARACTERISTIC   = UUID('9B3C81D8-57B1-4A8A-B8DF-0E56F7CA51C2', 'Remote Command')
+GATT_AMS_ENTITY_UPDATE_CHARACTERISTIC    = UUID('2F7CABCE-808D-411F-9A0C-BB92BA96C102', 'Entity Update')
+GATT_AMS_ENTITY_ATTRIBUTE_CHARACTERISTIC = UUID('C6B2F38C-23AB-46D8-A6AB-A3A870BBD5D7', 'Entity Attribute')
+
+# Misc Apple Services
+GATT_APPLE_CONTINUITY_SERVICE = UUID('D0611E78-BBB4-4591-A5F8-487910AE4366', 'Apple Continuity')
+GATT_APPLE_NEARBY_SERVICE     = UUID('9FA480E0-4967-4542-9390-D343DC5D04AE', 'Apple Nearby')
+
 # Misc
 GATT_DEVICE_NAME_CHARACTERISTIC                                = UUID.from_16_bits(0x2A00, 'Device Name')
 GATT_APPEARANCE_CHARACTERISTIC                                 = UUID.from_16_bits(0x2A01, 'Appearance')
@@ -315,6 +318,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
@@ -323,8 +327,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'))
@@ -438,7 +440,7 @@ class IncludedServiceDeclaration(Attribute):
 
 
 # -----------------------------------------------------------------------------
-class Characteristic(Attribute):
+class Characteristic(Attribute[_T]):
     '''
     See Vol 3, Part G - 3.3 CHARACTERISTIC DEFINITION
     '''
@@ -501,7 +503,7 @@ class Characteristic(Attribute):
         uuid: Union[str, bytes, UUID],
         properties: Characteristic.Properties,
         permissions: Union[str, Attribute.Permissions],
-        value: Any = b'',
+        value: Union[AttributeValue[_T], _T, None] = None,
         descriptors: Sequence[Descriptor] = (),
     ):
         super().__init__(uuid, permissions, value)
@@ -561,213 +563,10 @@ class CharacteristicDeclaration(Attribute):
 
 
 # -----------------------------------------------------------------------------
-class CharacteristicValue(AttributeValue):
+class CharacteristicValue(AttributeValue[_T]):
     """Same as AttributeValue, for backward compatibility"""
 
 
-# -----------------------------------------------------------------------------
-class CharacteristicAdapter:
-    '''
-    An adapter that can adapt Characteristic and AttributeProxy objects
-    by wrapping their `read_value()` and `write_value()` methods with ones that
-    return/accept encoded/decoded values.
-
-    For proxies (i.e used by a GATT client), the adaptation is one where the return
-    value of `read_value()` is decoded and the value passed to `write_value()` is
-    encoded. The `subscribe()` method, is wrapped with one where the values are decoded
-    before being passed to the subscriber.
-
-    For local values (i.e hosted by a GATT server) the adaptation is one where the
-    return value of `read_value()` is encoded and the value passed to `write_value()`
-    is decoded.
-    '''
-
-    read_value: Callable
-    write_value: Callable
-
-    def __init__(self, characteristic: Union[Characteristic, AttributeProxy]):
-        self.wrapped_characteristic = characteristic
-        self.subscribers: Dict[Callable, Callable] = (
-            {}
-        )  # Map from subscriber to proxy subscriber
-
-        if isinstance(characteristic, Characteristic):
-            self.read_value = self.read_encoded_value
-            self.write_value = self.write_encoded_value
-        else:
-            self.read_value = self.read_decoded_value
-            self.write_value = self.write_decoded_value
-            self.subscribe = self.wrapped_subscribe
-            self.unsubscribe = self.wrapped_unsubscribe
-
-    def __getattr__(self, name):
-        return getattr(self.wrapped_characteristic, name)
-
-    def __setattr__(self, name, value):
-        if name in (
-            'wrapped_characteristic',
-            'subscribers',
-            'read_value',
-            'write_value',
-            'subscribe',
-            'unsubscribe',
-        ):
-            super().__setattr__(name, value)
-        else:
-            setattr(self.wrapped_characteristic, name, value)
-
-    async def read_encoded_value(self, connection):
-        return self.encode_value(
-            await self.wrapped_characteristic.read_value(connection)
-        )
-
-    async def write_encoded_value(self, connection, value):
-        return await self.wrapped_characteristic.write_value(
-            connection, self.decode_value(value)
-        )
-
-    async def read_decoded_value(self):
-        return self.decode_value(await self.wrapped_characteristic.read_value())
-
-    async def write_decoded_value(self, value, with_response=False):
-        return await self.wrapped_characteristic.write_value(
-            self.encode_value(value), with_response
-        )
-
-    def encode_value(self, value):
-        return value
-
-    def decode_value(self, value):
-        return value
-
-    def wrapped_subscribe(self, subscriber=None):
-        if subscriber is not None:
-            if subscriber in self.subscribers:
-                # We already have a proxy subscriber
-                subscriber = self.subscribers[subscriber]
-            else:
-                # Create and register a proxy that will decode the value
-                original_subscriber = subscriber
-
-                def on_change(value):
-                    original_subscriber(self.decode_value(value))
-
-                self.subscribers[subscriber] = on_change
-                subscriber = on_change
-
-        return self.wrapped_characteristic.subscribe(subscriber)
-
-    def wrapped_unsubscribe(self, subscriber=None):
-        if subscriber in self.subscribers:
-            subscriber = self.subscribers.pop(subscriber)
-
-        return self.wrapped_characteristic.unsubscribe(subscriber)
-
-    def __str__(self) -> str:
-        wrapped = str(self.wrapped_characteristic)
-        return f'{self.__class__.__name__}({wrapped})'
-
-
-# -----------------------------------------------------------------------------
-class DelegatedCharacteristicAdapter(CharacteristicAdapter):
-    '''
-    Adapter that converts bytes values using an encode and a decode function.
-    '''
-
-    def __init__(self, characteristic, encode=None, decode=None):
-        super().__init__(characteristic)
-        self.encode = encode
-        self.decode = decode
-
-    def encode_value(self, value):
-        return self.encode(value) if self.encode else value
-
-    def decode_value(self, value):
-        return self.decode(value) if self.decode else value
-
-
-# -----------------------------------------------------------------------------
-class PackedCharacteristicAdapter(CharacteristicAdapter):
-    '''
-    Adapter that packs/unpacks characteristic values according to a standard
-    Python `struct` format.
-    For formats with a single value, the adapted `read_value` and `write_value`
-    methods return/accept single values. For formats with multiple values,
-    they return/accept a tuple with the same number of elements as is required for
-    the format.
-    '''
-
-    def __init__(self, characteristic, pack_format):
-        super().__init__(characteristic)
-        self.struct = struct.Struct(pack_format)
-
-    def pack(self, *values):
-        return self.struct.pack(*values)
-
-    def unpack(self, buffer):
-        return self.struct.unpack(buffer)
-
-    def encode_value(self, value):
-        return self.pack(*value if isinstance(value, tuple) else (value,))
-
-    def decode_value(self, value):
-        unpacked = self.unpack(value)
-        return unpacked[0] if len(unpacked) == 1 else unpacked
-
-
-# -----------------------------------------------------------------------------
-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 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.
-    '''
-
-    def __init__(self, characteristic, pack_format, keys):
-        super().__init__(characteristic, pack_format)
-        self.keys = keys
-
-    # pylint: disable=arguments-differ
-    def pack(self, values):
-        return super().pack(*(values[key] for key in self.keys))
-
-    def unpack(self, buffer):
-        return dict(zip(self.keys, super().unpack(buffer)))
-
-
-# -----------------------------------------------------------------------------
-class UTF8CharacteristicAdapter(CharacteristicAdapter):
-    '''
-    Adapter that converts strings to/from bytes using UTF-8 encoding
-    '''
-
-    def encode_value(self, value: str) -> bytes:
-        return value.encode('utf-8')
-
-    def decode_value(self, value: bytes) -> str:
-        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):
     '''
@@ -802,3 +601,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_adapters.py

@@ -0,0 +1,374 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# -----------------------------------------------------------------------------
+# GATT - Type Adapters
+# -----------------------------------------------------------------------------
+
+# -----------------------------------------------------------------------------
+# Imports
+# -----------------------------------------------------------------------------
+from __future__ import annotations
+import struct
+from typing import (
+    Any,
+    Callable,
+    Generic,
+    Iterable,
+    Literal,
+    Optional,
+    Type,
+    TypeVar,
+)
+
+from bumble.core import InvalidOperationError
+from bumble.gatt import Characteristic
+from bumble.gatt_client import CharacteristicProxy
+from bumble.utils import ByteSerializable, IntConvertible
+
+
+# -----------------------------------------------------------------------------
+# Typing
+# -----------------------------------------------------------------------------
+_T = TypeVar('_T')
+_T2 = TypeVar('_T2', bound=ByteSerializable)
+_T3 = TypeVar('_T3', bound=IntConvertible)
+
+
+# -----------------------------------------------------------------------------
+class CharacteristicAdapter(Characteristic, Generic[_T]):
+    '''Base class for GATT Characteristic adapters.'''
+
+    def __init__(self, characteristic: Characteristic) -> None:
+        super().__init__(
+            characteristic.uuid,
+            characteristic.properties,
+            characteristic.permissions,
+            characteristic.value,
+            characteristic.descriptors,
+        )
+
+
+# -----------------------------------------------------------------------------
+class CharacteristicProxyAdapter(CharacteristicProxy[_T]):
+    '''Base class for GATT CharacteristicProxy adapters.'''
+
+    def __init__(self, characteristic_proxy: CharacteristicProxy):
+        super().__init__(
+            characteristic_proxy.client,
+            characteristic_proxy.handle,
+            characteristic_proxy.end_group_handle,
+            characteristic_proxy.uuid,
+            characteristic_proxy.properties,
+        )
+
+
+# -----------------------------------------------------------------------------
+class DelegatedCharacteristicAdapter(CharacteristicAdapter[_T]):
+    '''
+    Adapter that converts bytes values using an encode and/or a decode function.
+    '''
+
+    def __init__(
+        self,
+        characteristic: Characteristic,
+        encode: Optional[Callable[[_T], bytes]] = None,
+        decode: Optional[Callable[[bytes], _T]] = None,
+    ):
+        super().__init__(characteristic)
+        self.encode = encode
+        self.decode = decode
+
+    def encode_value(self, value: _T) -> bytes:
+        if self.encode is None:
+            raise InvalidOperationError('delegated adapter does not have an encoder')
+        return self.encode(value)
+
+    def decode_value(self, value: bytes) -> _T:
+        if self.decode is None:
+            raise InvalidOperationError('delegate adapter does not have a decoder')
+        return self.decode(value)
+
+
+# -----------------------------------------------------------------------------
+class DelegatedCharacteristicProxyAdapter(CharacteristicProxyAdapter[_T]):
+    '''
+    Adapter that converts bytes values using an encode and a decode function.
+    '''
+
+    def __init__(
+        self,
+        characteristic_proxy: CharacteristicProxy,
+        encode: Optional[Callable[[_T], bytes]] = None,
+        decode: Optional[Callable[[bytes], _T]] = None,
+    ):
+        super().__init__(characteristic_proxy)
+        self.encode = encode
+        self.decode = decode
+
+    def encode_value(self, value: _T) -> bytes:
+        if self.encode is None:
+            raise InvalidOperationError('delegated adapter does not have an encoder')
+        return self.encode(value)
+
+    def decode_value(self, value: bytes) -> _T:
+        if self.decode is None:
+            raise InvalidOperationError('delegate adapter does not have a decoder')
+        return self.decode(value)
+
+
+# -----------------------------------------------------------------------------
+class PackedCharacteristicAdapter(CharacteristicAdapter):
+    '''
+    Adapter that packs/unpacks characteristic values according to a standard
+    Python `struct` format.
+    For formats with a single value, the adapted `read_value` and `write_value`
+    methods return/accept single values. For formats with multiple values,
+    they return/accept a tuple with the same number of elements as is required for
+    the format.
+    '''
+
+    def __init__(self, characteristic: Characteristic, pack_format: str) -> None:
+        super().__init__(characteristic)
+        self.struct = struct.Struct(pack_format)
+
+    def pack(self, *values) -> bytes:
+        return self.struct.pack(*values)
+
+    def unpack(self, buffer: bytes) -> tuple:
+        return self.struct.unpack(buffer)
+
+    def encode_value(self, value: Any) -> bytes:
+        return self.pack(*value if isinstance(value, tuple) else (value,))
+
+    def decode_value(self, value: bytes) -> Any:
+        unpacked = self.unpack(value)
+        return unpacked[0] if len(unpacked) == 1 else unpacked
+
+
+# -----------------------------------------------------------------------------
+class PackedCharacteristicProxyAdapter(CharacteristicProxyAdapter):
+    '''
+    Adapter that packs/unpacks characteristic values according to a standard
+    Python `struct` format.
+    For formats with a single value, the adapted `read_value` and `write_value`
+    methods return/accept single values. For formats with multiple values,
+    they return/accept a tuple with the same number of elements as is required for
+    the format.
+    '''
+
+    def __init__(self, characteristic_proxy, pack_format):
+        super().__init__(characteristic_proxy)
+        self.struct = struct.Struct(pack_format)
+
+    def pack(self, *values) -> bytes:
+        return self.struct.pack(*values)
+
+    def unpack(self, buffer: bytes) -> tuple:
+        return self.struct.unpack(buffer)
+
+    def encode_value(self, value: Any) -> bytes:
+        return self.pack(*value if isinstance(value, tuple) else (value,))
+
+    def decode_value(self, value: bytes) -> Any:
+        unpacked = self.unpack(value)
+        return unpacked[0] if len(unpacked) == 1 else unpacked
+
+
+# -----------------------------------------------------------------------------
+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 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.
+    '''
+
+    def __init__(
+        self, characteristic: Characteristic, pack_format: str, keys: Iterable[str]
+    ) -> None:
+        super().__init__(characteristic, pack_format)
+        self.keys = keys
+
+    # pylint: disable=arguments-differ
+    def pack(self, values) -> bytes:
+        return super().pack(*(values[key] for key in self.keys))
+
+    def unpack(self, buffer: bytes) -> Any:
+        return dict(zip(self.keys, super().unpack(buffer)))
+
+
+# -----------------------------------------------------------------------------
+class MappedCharacteristicProxyAdapter(PackedCharacteristicProxyAdapter):
+    '''
+    Adapter that packs/unpacks characteristic values according to a standard
+    Python `struct` format.
+    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.
+    '''
+
+    def __init__(
+        self,
+        characteristic_proxy: CharacteristicProxy,
+        pack_format: str,
+        keys: Iterable[str],
+    ) -> None:
+        super().__init__(characteristic_proxy, pack_format)
+        self.keys = keys
+
+    # pylint: disable=arguments-differ
+    def pack(self, values) -> bytes:
+        return super().pack(*(values[key] for key in self.keys))
+
+    def unpack(self, buffer: bytes) -> Any:
+        return dict(zip(self.keys, super().unpack(buffer)))
+
+
+# -----------------------------------------------------------------------------
+class UTF8CharacteristicAdapter(CharacteristicAdapter[str]):
+    '''
+    Adapter that converts strings to/from bytes using UTF-8 encoding
+    '''
+
+    def encode_value(self, value: str) -> bytes:
+        return value.encode('utf-8')
+
+    def decode_value(self, value: bytes) -> str:
+        return value.decode('utf-8')
+
+
+# -----------------------------------------------------------------------------
+class UTF8CharacteristicProxyAdapter(CharacteristicProxyAdapter[str]):
+    '''
+    Adapter that converts strings to/from bytes using UTF-8 encoding
+    '''
+
+    def encode_value(self, value: str) -> bytes:
+        return value.encode('utf-8')
+
+    def decode_value(self, value: bytes) -> str:
+        return value.decode('utf-8')
+
+
+# -----------------------------------------------------------------------------
+class SerializableCharacteristicAdapter(CharacteristicAdapter[_T2]):
+    '''
+    Adapter that converts any class to/from bytes using the class'
+    `to_bytes` and `__bytes__` methods, respectively.
+    '''
+
+    def __init__(self, characteristic: Characteristic, cls: Type[_T2]) -> None:
+        super().__init__(characteristic)
+        self.cls = cls
+
+    def encode_value(self, value: _T2) -> bytes:
+        return bytes(value)
+
+    def decode_value(self, value: bytes) -> _T2:
+        return self.cls.from_bytes(value)
+
+
+# -----------------------------------------------------------------------------
+class SerializableCharacteristicProxyAdapter(CharacteristicProxyAdapter[_T2]):
+    '''
+    Adapter that converts any class to/from bytes using the class'
+    `to_bytes` and `__bytes__` methods, respectively.
+    '''
+
+    def __init__(
+        self, characteristic_proxy: CharacteristicProxy, cls: Type[_T2]
+    ) -> None:
+        super().__init__(characteristic_proxy)
+        self.cls = cls
+
+    def encode_value(self, value: _T2) -> bytes:
+        return bytes(value)
+
+    def decode_value(self, value: bytes) -> _T2:
+        return self.cls.from_bytes(value)
+
+
+# -----------------------------------------------------------------------------
+class EnumCharacteristicAdapter(CharacteristicAdapter[_T3]):
+    '''
+    Adapter that converts int-enum-like classes to/from bytes using the class'
+    `int().to_bytes()` and `from_bytes()` methods, respectively.
+    '''
+
+    def __init__(
+        self,
+        characteristic: Characteristic,
+        cls: Type[_T3],
+        length: int,
+        byteorder: Literal['little', 'big'] = 'little',
+    ):
+        """
+        Initialize an instance.
+
+        Params:
+          characteristic: the Characteristic to adapt to/from
+          cls: the class to/from which to convert integer values
+          length: number of bytes used to represent integer values
+          byteorder: byte order of the byte representation of integers.
+        """
+        super().__init__(characteristic)
+        self.cls = cls
+        self.length = length
+        self.byteorder = byteorder
+
+    def encode_value(self, value: _T3) -> bytes:
+        return int(value).to_bytes(self.length, self.byteorder)
+
+    def decode_value(self, value: bytes) -> _T3:
+        int_value = int.from_bytes(value, self.byteorder)
+        return self.cls(int_value)
+
+
+# -----------------------------------------------------------------------------
+class EnumCharacteristicProxyAdapter(CharacteristicProxyAdapter[_T3]):
+    '''
+    Adapter that converts int-enum-like classes to/from bytes using the class'
+    `int().to_bytes()` and `from_bytes()` methods, respectively.
+    '''
+
+    def __init__(
+        self,
+        characteristic_proxy: CharacteristicProxy,
+        cls: Type[_T3],
+        length: int,
+        byteorder: Literal['little', 'big'] = 'little',
+    ):
+        """
+        Initialize an instance.
+
+        Params:
+          characteristic_proxy: the CharacteristicProxy to adapt to/from
+          cls: the class to/from which to convert integer values
+          length: number of bytes used to represent integer values
+          byteorder: byte order of the byte representation of integers.
+        """
+        super().__init__(characteristic_proxy)
+        self.cls = cls
+        self.length = length
+        self.byteorder = byteorder
+
+    def encode_value(self, value: _T3) -> bytes:
+        return int(value).to_bytes(self.length, self.byteorder)
+
+    def decode_value(self, value: bytes) -> _T3:
+        int_value = int.from_bytes(value, self.byteorder)
+        a = self.cls(int_value)
+        return self.cls(int_value)

bumble/gatt_client.py

@@ -29,16 +29,18 @@ import logging
 import struct
 from datetime import datetime
 from typing import (
+    Any,
+    Callable,
+    Dict,
+    Generic,
+    Iterable,
     List,
     Optional,
-    Dict,
-    Tuple,
-    Callable,
-    Union,
-    Any,
-    Iterable,
-    Type,
     Set,
+    Tuple,
+    Union,
+    Type,
+    TypeVar,
     TYPE_CHECKING,
 )
 
@@ -78,12 +80,18 @@ from .gatt import (
     GATT_INCLUDE_ATTRIBUTE_TYPE,
     Characteristic,
     ClientCharacteristicConfigurationBits,
+    InvalidServiceError,
     TemplateService,
 )
 
+# -----------------------------------------------------------------------------
+# Typing
+# -----------------------------------------------------------------------------
 if TYPE_CHECKING:
     from bumble.device import Connection
 
+_T = TypeVar('_T')
+
 # -----------------------------------------------------------------------------
 # Logging
 # -----------------------------------------------------------------------------
@@ -109,7 +117,7 @@ def show_services(services: Iterable[ServiceProxy]) -> None:
 # -----------------------------------------------------------------------------
 # Proxies
 # -----------------------------------------------------------------------------
-class AttributeProxy(EventEmitter):
+class AttributeProxy(EventEmitter, Generic[_T]):
     def __init__(
         self, client: Client, handle: int, end_group_handle: int, attribute_type: UUID
     ) -> None:
@@ -119,21 +127,21 @@ class AttributeProxy(EventEmitter):
         self.end_group_handle = end_group_handle
         self.type = attribute_type
 
-    async def read_value(self, no_long_read: bool = False) -> bytes:
+    async def read_value(self, no_long_read: bool = False) -> _T:
         return self.decode_value(
             await self.client.read_value(self.handle, no_long_read)
         )
 
-    async def write_value(self, value, with_response=False):
+    async def write_value(self, value: _T, with_response=False):
         return await self.client.write_value(
             self.handle, self.encode_value(value), with_response
         )
 
-    def encode_value(self, value: Any) -> bytes:
-        return value
+    def encode_value(self, value: _T) -> bytes:
+        return value  # type: ignore
 
-    def decode_value(self, value_bytes: bytes) -> Any:
-        return value_bytes
+    def decode_value(self, value: bytes) -> _T:
+        return value  # type: ignore
 
     def __str__(self) -> str:
         return f'Attribute(handle=0x{self.handle:04X}, type={self.type})'
@@ -162,29 +170,40 @@ 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})'
 
 
-class CharacteristicProxy(AttributeProxy):
+class CharacteristicProxy(AttributeProxy[_T]):
     properties: Characteristic.Properties
     descriptors: List[DescriptorProxy]
-    subscribers: Dict[Any, Callable[[bytes], Any]]
+    subscribers: Dict[Any, Callable[[_T], Any]]
 
     def __init__(
         self,
-        client,
-        handle,
-        end_group_handle,
-        uuid,
+        client: Client,
+        handle: int,
+        end_group_handle: int,
+        uuid: UUID,
         properties: int,
-    ):
+    ) -> None:
         super().__init__(client, handle, end_group_handle, uuid)
         self.uuid = uuid
         self.properties = Characteristic.Properties(properties)
@@ -192,21 +211,21 @@ class CharacteristicProxy(AttributeProxy):
         self.descriptors_discovered = False
         self.subscribers = {}  # Map from subscriber to proxy subscriber
 
-    def get_descriptor(self, descriptor_type):
+    def get_descriptor(self, descriptor_type: UUID) -> Optional[DescriptorProxy]:
         for descriptor in self.descriptors:
             if descriptor.type == descriptor_type:
                 return descriptor
 
         return None
 
-    async def discover_descriptors(self):
+    async def discover_descriptors(self) -> list[DescriptorProxy]:
         return await self.client.discover_descriptors(self)
 
     async def subscribe(
         self,
-        subscriber: Optional[Callable[[bytes], Any]] = None,
+        subscriber: Optional[Callable[[_T], Any]] = None,
         prefer_notify: bool = True,
-    ):
+    ) -> None:
         if subscriber is not None:
             if subscriber in self.subscribers:
                 # We already have a proxy subscriber
@@ -221,13 +240,13 @@ class CharacteristicProxy(AttributeProxy):
                 self.subscribers[subscriber] = on_change
                 subscriber = on_change
 
-        return await self.client.subscribe(self, subscriber, prefer_notify)
+        await self.client.subscribe(self, subscriber, prefer_notify)
 
-    async def unsubscribe(self, subscriber=None, force=False):
+    async def unsubscribe(self, subscriber=None, force=False) -> None:
         if subscriber in self.subscribers:
             subscriber = self.subscribers.pop(subscriber)
 
-        return await self.client.unsubscribe(self, subscriber, force)
+        await self.client.unsubscribe(self, subscriber, force)
 
     def __str__(self) -> str:
         return (
@@ -238,7 +257,7 @@ class CharacteristicProxy(AttributeProxy):
 
 
 class DescriptorProxy(AttributeProxy):
-    def __init__(self, client, handle, descriptor_type):
+    def __init__(self, client: Client, handle: int, descriptor_type: UUID) -> None:
         super().__init__(client, handle, 0, descriptor_type)
 
     def __str__(self) -> str:
@@ -667,7 +686,7 @@ class Client:
 
                     properties, handle = struct.unpack_from('<BH', attribute_value)
                     characteristic_uuid = UUID.from_bytes(attribute_value[3:])
-                    characteristic = CharacteristicProxy(
+                    characteristic: CharacteristicProxy = CharacteristicProxy(
                         self, handle, 0, characteristic_uuid, properties
                     )
 
@@ -793,7 +812,7 @@ class Client:
                     logger.warning(f'bogus handle value: {attribute_handle}')
                     return []
 
-                attribute = AttributeProxy(
+                attribute: AttributeProxy = AttributeProxy(
                     self, attribute_handle, 0, UUID.from_bytes(attribute_uuid)
                 )
                 attributes.append(attribute)
@@ -806,7 +825,7 @@ class Client:
     async def subscribe(
         self,
         characteristic: CharacteristicProxy,
-        subscriber: Optional[Callable[[bytes], Any]] = None,
+        subscriber: Optional[Callable[[Any], Any]] = None,
         prefer_notify: bool = True,
     ) -> None:
         # If we haven't already discovered the descriptors for this characteristic,
@@ -856,7 +875,7 @@ class Client:
     async def unsubscribe(
         self,
         characteristic: CharacteristicProxy,
-        subscriber: Optional[Callable[[bytes], Any]] = None,
+        subscriber: Optional[Callable[[Any], Any]] = None,
         force: bool = False,
     ) -> None:
         '''

bumble/gatt_server.py

@@ -36,7 +36,6 @@ from typing import (
     Tuple,
     TypeVar,
     Type,
-    Union,
     TYPE_CHECKING,
 )
 from pyee import EventEmitter
@@ -78,7 +77,6 @@ from bumble.gatt import (
     GATT_REQUEST_TIMEOUT,
     GATT_SECONDARY_SERVICE_ATTRIBUTE_TYPE,
     Characteristic,
-    CharacteristicAdapter,
     CharacteristicDeclaration,
     CharacteristicValue,
     IncludedServiceDeclaration,
@@ -469,7 +467,7 @@ class Server(EventEmitter):
             finally:
                 self.pending_confirmations[connection.handle] = None
 
-    async def notify_or_indicate_subscribers(
+    async def _notify_or_indicate_subscribers(
         self,
         indicate: bool,
         attribute: Attribute,
@@ -503,7 +501,9 @@ class Server(EventEmitter):
         value: Optional[bytes] = None,
         force: bool = False,
     ):
-        return await self.notify_or_indicate_subscribers(False, attribute, value, force)
+        return await self._notify_or_indicate_subscribers(
+            False, attribute, value, force
+        )
 
     async def indicate_subscribers(
         self,
@@ -511,7 +511,7 @@ class Server(EventEmitter):
         value: Optional[bytes] = None,
         force: bool = False,
     ):
-        return await self.notify_or_indicate_subscribers(True, attribute, value, force)
+        return await self._notify_or_indicate_subscribers(True, attribute, value, force)
 
     def on_disconnection(self, connection: Connection) -> None:
         if connection.handle in self.subscribers:

bumble/host.py

@@ -1,4 +1,4 @@
-# Copyright 2021-2022 Google LLC
+# Copyright 2021-2025 Google LLC
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -34,6 +34,8 @@ from typing import (
     TYPE_CHECKING,
 )
 
+import pyee
+
 from bumble.colors import color
 from bumble.l2cap import L2CAP_PDU
 from bumble.snoop import Snooper
@@ -42,6 +44,7 @@ from bumble import hci
 from bumble.core import (
     BT_BR_EDR_TRANSPORT,
     BT_LE_TRANSPORT,
+    PhysicalTransport,
     ConnectionPHY,
     ConnectionParameters,
 )
@@ -59,7 +62,19 @@ logger = logging.getLogger(__name__)
 
 
 # -----------------------------------------------------------------------------
-class AclPacketQueue:
+class DataPacketQueue(pyee.EventEmitter):
+    """
+    Flow-control queue for host->controller data packets (ACL, ISO).
+
+    The queue holds packets associated with a connection handle. The packets
+    are sent to the controller, up to a maximum total number of packets in flight.
+    A packet is considered to be "in flight" when it has been sent to the controller
+    but not completed yet. Packets are no longer "in flight" when the controller
+    declares them as completed.
+
+    The queue emits a 'flow' event whenever one or more packets are completed.
+    """
+
     max_packet_size: int
 
     def __init__(
@@ -68,53 +83,122 @@ class AclPacketQueue:
         max_in_flight: int,
         send: Callable[[hci.HCI_Packet], None],
     ) -> None:
+        super().__init__()
         self.max_packet_size = max_packet_size
         self.max_in_flight = max_in_flight
-        self.in_flight = 0
-        self.send = send
-        self.packets: Deque[hci.HCI_AclDataPacket] = collections.deque()
+        self._in_flight = 0  # Total number of packets in flight across all connections
+        self._in_flight_per_connection: dict[int, int] = collections.defaultdict(
+            int
+        )  # Number of packets in flight per connection
+        self._send = send
+        self._packets: Deque[tuple[hci.HCI_Packet, int]] = collections.deque()
+        self._queued = 0
+        self._completed = 0
 
-    def enqueue(self, packet: hci.HCI_AclDataPacket) -> None:
-        self.packets.appendleft(packet)
-        self.check_queue()
+    @property
+    def queued(self) -> int:
+        """Total number of packets queued since creation."""
+        return self._queued
 
-        if self.packets:
+    @property
+    def completed(self) -> int:
+        """Total number of packets completed since creation."""
+        return self._completed
+
+    @property
+    def pending(self) -> int:
+        """Number of packets that have been queued but not completed."""
+        return self._queued - self._completed
+
+    def enqueue(self, packet: hci.HCI_Packet, connection_handle: int) -> None:
+        """Enqueue a packet associated with a connection"""
+        self._packets.appendleft((packet, connection_handle))
+        self._queued += 1
+        self._check_queue()
+
+        if self._packets:
             logger.debug(
-                f'{self.in_flight} ACL packets in flight, '
-                f'{len(self.packets)} in queue'
+                f'{self._in_flight} packets in flight, '
+                f'{len(self._packets)} in queue'
             )
 
-    def check_queue(self) -> None:
-        while self.packets and self.in_flight < self.max_in_flight:
-            packet = self.packets.pop()
-            self.send(packet)
-            self.in_flight += 1
+    def flush(self, connection_handle: int) -> None:
+        """
+        Remove all packets associated with a connection.
 
-    def on_packets_completed(self, packet_count: int) -> None:
-        if packet_count > self.in_flight:
+        All packets associated with the connection that are in flight are implicitly
+        marked as completed, but no 'flow' event is emitted.
+        """
+
+        packets_to_keep = [
+            (packet, handle)
+            for (packet, handle) in self._packets
+            if handle != connection_handle
+        ]
+        if flushed_count := len(self._packets) - len(packets_to_keep):
+            self._completed += flushed_count
+            self._packets = collections.deque(packets_to_keep)
+
+        if connection_handle in self._in_flight_per_connection:
+            in_flight = self._in_flight_per_connection[connection_handle]
+            self._completed += in_flight
+            self._in_flight -= in_flight
+            del self._in_flight_per_connection[connection_handle]
+
+    def _check_queue(self) -> None:
+        while self._packets and self._in_flight < self.max_in_flight:
+            packet, connection_handle = self._packets.pop()
+            self._send(packet)
+            self._in_flight += 1
+            self._in_flight_per_connection[connection_handle] += 1
+
+    def on_packets_completed(self, packet_count: int, connection_handle: int) -> None:
+        """Mark one or more packets associated with a connection as completed."""
+        if connection_handle not in self._in_flight_per_connection:
             logger.warning(
-                color(
-                    '!!! {packet_count} completed but only '
-                    f'{self.in_flight} in flight'
-                )
+                f'received completion for unknown connection {connection_handle}'
             )
-            packet_count = self.in_flight
+            return
 
-        self.in_flight -= packet_count
-        self.check_queue()
+        in_flight_for_connection = self._in_flight_per_connection[connection_handle]
+        if packet_count <= in_flight_for_connection:
+            self._in_flight_per_connection[connection_handle] -= packet_count
+        else:
+            logger.warning(
+                f'{packet_count} completed for {connection_handle} '
+                f'but only {in_flight_for_connection} in flight'
+            )
+            self._in_flight_per_connection[connection_handle] = 0
+
+        if packet_count <= self._in_flight:
+            self._in_flight -= packet_count
+            self._completed += packet_count
+        else:
+            logger.warning(
+                f'{packet_count} completed but only {self._in_flight} in flight'
+            )
+            self._in_flight = 0
+            self._completed = self._queued
+
+        self._check_queue()
+        self.emit('flow')
 
 
 # -----------------------------------------------------------------------------
 class Connection:
     def __init__(
-        self, host: Host, handle: int, peer_address: hci.Address, transport: int
+        self,
+        host: Host,
+        handle: int,
+        peer_address: hci.Address,
+        transport: PhysicalTransport,
     ):
         self.host = host
         self.handle = handle
         self.peer_address = peer_address
         self.assembler = hci.HCI_AclDataPacketAssembler(self.on_acl_pdu)
         self.transport = transport
-        acl_packet_queue: Optional[AclPacketQueue] = (
+        acl_packet_queue: Optional[DataPacketQueue] = (
             host.le_acl_packet_queue
             if transport == BT_LE_TRANSPORT
             else host.acl_packet_queue
@@ -129,28 +213,37 @@ class Connection:
         l2cap_pdu = L2CAP_PDU.from_bytes(pdu)
         self.host.on_l2cap_pdu(self, l2cap_pdu.cid, l2cap_pdu.payload)
 
+    def __str__(self) -> str:
+        return (
+            f'Connection(transport={self.transport}, peer_address={self.peer_address})'
+        )
+
 
 # -----------------------------------------------------------------------------
 @dataclasses.dataclass
 class ScoLink:
     peer_address: hci.Address
-    handle: int
+    connection_handle: int
 
 
 # -----------------------------------------------------------------------------
 @dataclasses.dataclass
-class CisLink:
-    peer_address: hci.Address
+class IsoLink:
     handle: int
+    packet_queue: DataPacketQueue = dataclasses.field(repr=False)
+    packet_sequence_number: int = 0
 
 
 # -----------------------------------------------------------------------------
 class Host(AbortableEventEmitter):
     connections: Dict[int, Connection]
-    cis_links: Dict[int, CisLink]
+    cis_links: Dict[int, IsoLink]
+    bis_links: Dict[int, IsoLink]
     sco_links: Dict[int, ScoLink]
-    acl_packet_queue: Optional[AclPacketQueue] = None
-    le_acl_packet_queue: Optional[AclPacketQueue] = None
+    bigs: dict[int, set[int]]
+    acl_packet_queue: Optional[DataPacketQueue] = None
+    le_acl_packet_queue: Optional[DataPacketQueue] = None
+    iso_packet_queue: Optional[DataPacketQueue] = None
     hci_sink: Optional[TransportSink] = None
     hci_metadata: Dict[str, Any]
     long_term_key_provider: Optional[
@@ -169,7 +262,9 @@ class Host(AbortableEventEmitter):
         self.ready = False  # True when we can accept incoming packets
         self.connections = {}  # Connections, by connection handle
         self.cis_links = {}  # CIS links, by connection handle
+        self.bis_links = {}  # BIS links, by connection handle
         self.sco_links = {}  # SCO links, by connection handle
+        self.bigs = {}  # BIG Handle to BIS Handles
         self.pending_command = None
         self.pending_response: Optional[asyncio.Future[Any]] = None
         self.number_of_supported_advertising_sets = 0
@@ -387,6 +482,12 @@ class Host(AbortableEventEmitter):
                     hci.HCI_LE_TRANSMIT_POWER_REPORTING_EVENT,
                     hci.HCI_LE_BIGINFO_ADVERTISING_REPORT_EVENT,
                     hci.HCI_LE_SUBRATE_CHANGE_EVENT,
+                    hci.HCI_LE_CS_READ_REMOTE_SUPPORTED_CAPABILITIES_COMPLETE_EVENT,
+                    hci.HCI_LE_CS_PROCEDURE_ENABLE_COMPLETE_EVENT,
+                    hci.HCI_LE_CS_SECURITY_ENABLE_COMPLETE_EVENT,
+                    hci.HCI_LE_CS_CONFIG_COMPLETE_EVENT,
+                    hci.HCI_LE_CS_SUBEVENT_RESULT_EVENT,
+                    hci.HCI_LE_CS_SUBEVENT_RESULT_CONTINUE_EVENT,
                 ]
             )
 
@@ -411,39 +512,70 @@ class Host(AbortableEventEmitter):
                 f'hc_total_num_acl_data_packets={hc_total_num_acl_data_packets}'
             )
 
-            self.acl_packet_queue = AclPacketQueue(
+            self.acl_packet_queue = DataPacketQueue(
                 max_packet_size=hc_acl_data_packet_length,
                 max_in_flight=hc_total_num_acl_data_packets,
                 send=self.send_hci_packet,
             )
 
-        hc_le_acl_data_packet_length = 0
-        hc_total_num_le_acl_data_packets = 0
-        if self.supports_command(hci.HCI_LE_READ_BUFFER_SIZE_COMMAND):
+        le_acl_data_packet_length = 0
+        total_num_le_acl_data_packets = 0
+        iso_data_packet_length = 0
+        total_num_iso_data_packets = 0
+        if self.supports_command(hci.HCI_LE_READ_BUFFER_SIZE_V2_COMMAND):
+            response = await self.send_command(
+                hci.HCI_LE_Read_Buffer_Size_V2_Command(), check_result=True
+            )
+            le_acl_data_packet_length = (
+                response.return_parameters.le_acl_data_packet_length
+            )
+            total_num_le_acl_data_packets = (
+                response.return_parameters.total_num_le_acl_data_packets
+            )
+            iso_data_packet_length = response.return_parameters.iso_data_packet_length
+            total_num_iso_data_packets = (
+                response.return_parameters.total_num_iso_data_packets
+            )
+
+            logger.debug(
+                'HCI LE flow control: '
+                f'le_acl_data_packet_length={le_acl_data_packet_length},'
+                f'total_num_le_acl_data_packets={total_num_le_acl_data_packets}'
+                f'iso_data_packet_length={iso_data_packet_length},'
+                f'total_num_iso_data_packets={total_num_iso_data_packets}'
+            )
+        elif self.supports_command(hci.HCI_LE_READ_BUFFER_SIZE_COMMAND):
             response = await self.send_command(
                 hci.HCI_LE_Read_Buffer_Size_Command(), check_result=True
             )
-            hc_le_acl_data_packet_length = (
-                response.return_parameters.hc_le_acl_data_packet_length
+            le_acl_data_packet_length = (
+                response.return_parameters.le_acl_data_packet_length
             )
-            hc_total_num_le_acl_data_packets = (
-                response.return_parameters.hc_total_num_le_acl_data_packets
+            total_num_le_acl_data_packets = (
+                response.return_parameters.total_num_le_acl_data_packets
             )
 
             logger.debug(
                 'HCI LE ACL flow control: '
-                f'hc_le_acl_data_packet_length={hc_le_acl_data_packet_length},'
-                f'hc_total_num_le_acl_data_packets={hc_total_num_le_acl_data_packets}'
+                f'le_acl_data_packet_length={le_acl_data_packet_length},'
+                f'total_num_le_acl_data_packets={total_num_le_acl_data_packets}'
             )
 
-        if hc_le_acl_data_packet_length == 0 or hc_total_num_le_acl_data_packets == 0:
+        if le_acl_data_packet_length == 0 or total_num_le_acl_data_packets == 0:
             # LE and Classic share the same queue
             self.le_acl_packet_queue = self.acl_packet_queue
         else:
             # Create a separate queue for LE
-            self.le_acl_packet_queue = AclPacketQueue(
-                max_packet_size=hc_le_acl_data_packet_length,
-                max_in_flight=hc_total_num_le_acl_data_packets,
+            self.le_acl_packet_queue = DataPacketQueue(
+                max_packet_size=le_acl_data_packet_length,
+                max_in_flight=total_num_le_acl_data_packets,
+                send=self.send_hci_packet,
+            )
+
+        if iso_data_packet_length and total_num_iso_data_packets:
+            self.iso_packet_queue = DataPacketQueue(
+                max_packet_size=iso_data_packet_length,
+                max_in_flight=total_num_iso_data_packets,
                 send=self.send_hci_packet,
             )
 
@@ -595,11 +727,78 @@ class Host(AbortableEventEmitter):
                 data=l2cap_pdu[offset : offset + data_total_length],
             )
             logger.debug(f'>>> ACL packet enqueue: (CID={cid}) {acl_packet}')
-            packet_queue.enqueue(acl_packet)
+            packet_queue.enqueue(acl_packet, connection_handle)
             pb_flag = 1
             offset += data_total_length
             bytes_remaining -= data_total_length
 
+    def get_data_packet_queue(self, connection_handle: int) -> DataPacketQueue | None:
+        if connection := self.connections.get(connection_handle):
+            return connection.acl_packet_queue
+
+        if iso_link := self.cis_links.get(connection_handle) or self.bis_links.get(
+            connection_handle
+        ):
+            return iso_link.packet_queue
+
+        return None
+
+    def send_iso_sdu(self, connection_handle: int, sdu: bytes) -> None:
+        if not (
+            iso_link := self.cis_links.get(connection_handle)
+            or self.bis_links.get(connection_handle)
+        ):
+            logger.warning(f"no ISO link for connection handle {connection_handle}")
+            return
+
+        if iso_link.packet_queue is None:
+            logger.warning("ISO link has no data packet queue")
+            return
+
+        bytes_remaining = len(sdu)
+        offset = 0
+        while bytes_remaining:
+            is_first_fragment = offset == 0
+            header_length = 4 if is_first_fragment else 0
+            assert iso_link.packet_queue.max_packet_size > header_length
+            fragment_length = min(
+                bytes_remaining, iso_link.packet_queue.max_packet_size - header_length
+            )
+            is_last_fragment = bytes_remaining == fragment_length
+            iso_sdu_fragment = sdu[offset : offset + fragment_length]
+            iso_link.packet_queue.enqueue(
+                (
+                    hci.HCI_IsoDataPacket(
+                        connection_handle=connection_handle,
+                        data_total_length=header_length + fragment_length,
+                        packet_sequence_number=iso_link.packet_sequence_number,
+                        pb_flag=0b10 if is_last_fragment else 0b00,
+                        packet_status_flag=0,
+                        iso_sdu_length=len(sdu),
+                        iso_sdu_fragment=iso_sdu_fragment,
+                    )
+                    if is_first_fragment
+                    else hci.HCI_IsoDataPacket(
+                        connection_handle=connection_handle,
+                        data_total_length=fragment_length,
+                        pb_flag=0b11 if is_last_fragment else 0b01,
+                        iso_sdu_fragment=iso_sdu_fragment,
+                    )
+                ),
+                connection_handle,
+            )
+
+            offset += fragment_length
+            bytes_remaining -= fragment_length
+
+        iso_link.packet_sequence_number = (iso_link.packet_sequence_number + 1) & 0xFFFF
+
+    def remove_big(self, big_handle: int) -> None:
+        if big := self.bigs.pop(big_handle, None):
+            for connection_handle in big:
+                if bis_link := self.bis_links.pop(connection_handle, None):
+                    bis_link.packet_queue.flush(bis_link.handle)
+
     def supports_command(self, op_code: int) -> bool:
         return (
             self.local_supported_commands
@@ -727,16 +926,17 @@ class Host(AbortableEventEmitter):
     def on_hci_command_status_event(self, event):
         return self.on_command_processed(event)
 
-    def on_hci_number_of_completed_packets_event(self, event):
+    def on_hci_number_of_completed_packets_event(
+        self, event: hci.HCI_Number_Of_Completed_Packets_Event
+    ) -> None:
         for connection_handle, num_completed_packets in zip(
             event.connection_handles, event.num_completed_packets
         ):
-            if connection := self.connections.get(connection_handle):
-                connection.acl_packet_queue.on_packets_completed(num_completed_packets)
-            elif not (
-                self.cis_links.get(connection_handle)
-                or self.sco_links.get(connection_handle)
-            ):
+            if queue := self.get_data_packet_queue(connection_handle):
+                queue.on_packets_completed(num_completed_packets, connection_handle)
+                continue
+
+            if connection_handle not in self.sco_links:
                 logger.warning(
                     'received packet completion event for unknown handle '
                     f'0x{connection_handle:04X}'
@@ -784,7 +984,7 @@ class Host(AbortableEventEmitter):
                 event.peer_address,
                 getattr(event, 'local_resolvable_private_address', None),
                 getattr(event, 'peer_resolvable_private_address', None),
-                event.role,
+                hci.Role(event.role),
                 connection_parameters,
             )
         else:
@@ -854,11 +1054,7 @@ class Host(AbortableEventEmitter):
             return
 
         if event.status == hci.HCI_SUCCESS:
-            logger.debug(
-                f'### DISCONNECTION: [0x{handle:04X}] '
-                f'{connection.peer_address} '
-                f'reason={event.reason}'
-            )
+            logger.debug(f'### DISCONNECTION: {connection}, reason={event.reason}')
 
             # Notify the listeners
             self.emit('disconnection', handle, event.reason)
@@ -869,6 +1065,14 @@ class Host(AbortableEventEmitter):
                 or self.cis_links.pop(handle, 0)
                 or self.sco_links.pop(handle, 0)
             )
+
+            # Flush the data queues
+            if self.acl_packet_queue:
+                self.acl_packet_queue.flush(handle)
+            if self.le_acl_packet_queue:
+                self.le_acl_packet_queue.flush(handle)
+            if self.iso_packet_queue:
+                self.iso_packet_queue.flush(handle)
         else:
             logger.debug(f'### DISCONNECTION FAILED: {event.status}')
 
@@ -902,8 +1106,11 @@ class Host(AbortableEventEmitter):
 
         # Notify the client
         if event.status == hci.HCI_SUCCESS:
-            connection_phy = ConnectionPHY(event.tx_phy, event.rx_phy)
-            self.emit('connection_phy_update', connection.handle, connection_phy)
+            self.emit(
+                'connection_phy_update',
+                connection.handle,
+                ConnectionPHY(event.tx_phy, event.rx_phy),
+            )
         else:
             self.emit('connection_phy_update_failure', connection.handle, event.status)
 
@@ -953,12 +1160,94 @@ class Host(AbortableEventEmitter):
             event.cis_id,
         )
 
+    def on_hci_le_create_big_complete_event(self, event):
+        self.bigs[event.big_handle] = set(event.connection_handle)
+        if self.iso_packet_queue is None:
+            logger.warning("BIS established but ISO packets not supported")
+
+        for connection_handle in event.connection_handle:
+            self.bis_links[connection_handle] = IsoLink(
+                connection_handle, self.iso_packet_queue
+            )
+
+        self.emit(
+            'big_establishment',
+            event.status,
+            event.big_handle,
+            event.connection_handle,
+            event.big_sync_delay,
+            event.transport_latency_big,
+            event.phy,
+            event.nse,
+            event.bn,
+            event.pto,
+            event.irc,
+            event.max_pdu,
+            event.iso_interval,
+        )
+
+    def on_hci_le_big_sync_established_event(self, event):
+        self.bigs[event.big_handle] = set(event.connection_handle)
+        for connection_handle in event.connection_handle:
+            self.bis_links[connection_handle] = IsoLink(
+                connection_handle, self.iso_packet_queue
+            )
+
+        self.emit(
+            'big_sync_establishment',
+            event.status,
+            event.big_handle,
+            event.transport_latency_big,
+            event.nse,
+            event.bn,
+            event.pto,
+            event.irc,
+            event.max_pdu,
+            event.iso_interval,
+            event.connection_handle,
+        )
+
+    def on_hci_le_big_sync_lost_event(self, event):
+        self.remove_big(event.big_handle)
+        self.emit('big_sync_lost', event.big_handle, event.reason)
+
+    def on_hci_le_terminate_big_complete_event(self, event):
+        self.remove_big(event.big_handle)
+        self.emit('big_termination', event.reason, event.big_handle)
+
+    def on_hci_le_periodic_advertising_sync_transfer_received_event(self, event):
+        self.emit(
+            'periodic_advertising_sync_transfer',
+            event.status,
+            event.connection_handle,
+            event.sync_handle,
+            event.advertising_sid,
+            event.advertiser_address,
+            event.advertiser_phy,
+            event.periodic_advertising_interval,
+            event.advertiser_clock_accuracy,
+        )
+
+    def on_hci_le_periodic_advertising_sync_transfer_received_v2_event(self, event):
+        self.emit(
+            'periodic_advertising_sync_transfer',
+            event.status,
+            event.connection_handle,
+            event.sync_handle,
+            event.advertising_sid,
+            event.advertiser_address,
+            event.advertiser_phy,
+            event.periodic_advertising_interval,
+            event.advertiser_clock_accuracy,
+        )
+
     def on_hci_le_cis_established_event(self, event):
         # The remaining parameters are unused for now.
         if event.status == hci.HCI_SUCCESS:
-            self.cis_links[event.connection_handle] = CisLink(
-                handle=event.connection_handle,
-                peer_address=hci.Address.ANY,
+            if self.iso_packet_queue is None:
+                logger.warning("CIS established but ISO packets not supported")
+            self.cis_links[event.connection_handle] = IsoLink(
+                handle=event.connection_handle, packet_queue=self.iso_packet_queue
             )
             self.emit('cis_establishment', event.connection_handle)
         else:
@@ -1028,7 +1317,7 @@ class Host(AbortableEventEmitter):
 
             self.sco_links[event.connection_handle] = ScoLink(
                 peer_address=event.bd_addr,
-                handle=event.connection_handle,
+                connection_handle=event.connection_handle,
             )
 
             # Notify the client
@@ -1053,7 +1342,7 @@ class Host(AbortableEventEmitter):
                 f'role change for {event.bd_addr}: '
                 f'{hci.HCI_Constant.role_name(event.new_role)}'
             )
-            self.emit('role_change', event.bd_addr, event.new_role)
+            self.emit('role_change', event.bd_addr, hci.Role(event.new_role))
         else:
             logger.debug(
                 f'role change for {event.bd_addr} failed: '
@@ -1249,5 +1538,23 @@ class Host(AbortableEventEmitter):
                 int.from_bytes(event.le_features, 'little'),
             )
 
+    def on_hci_le_cs_read_remote_supported_capabilities_complete_event(self, event):
+        self.emit('cs_remote_supported_capabilities', event)
+
+    def on_hci_le_cs_security_enable_complete_event(self, event):
+        self.emit('cs_security', event)
+
+    def on_hci_le_cs_config_complete_event(self, event):
+        self.emit('cs_config', event)
+
+    def on_hci_le_cs_procedure_enable_complete_event(self, event):
+        self.emit('cs_procedure', event)
+
+    def on_hci_le_cs_subevent_result_event(self, event):
+        self.emit('cs_subevent_result', event)
+
+    def on_hci_le_cs_subevent_result_continue_event(self, event):
+        self.emit('cs_subevent_result_continue', event)
+
     def on_hci_vendor_event(self, event):
         self.emit('vendor_event', event)

bumble/l2cap.py

@@ -42,7 +42,6 @@ from typing import (
 from .utils import deprecated
 from .colors import color
 from .core import (
-    BT_CENTRAL_ROLE,
     InvalidStateError,
     InvalidArgumentError,
     InvalidPacketError,
@@ -52,6 +51,7 @@ from .core import (
 from .hci import (
     HCI_LE_Connection_Update_Command,
     HCI_Object,
+    Role,
     key_with_value,
     name_or_number,
 )
@@ -773,7 +773,6 @@ class ClassicChannel(EventEmitter):
         self.psm = psm
         self.source_cid = source_cid
         self.destination_cid = 0
-        self.response = None
         self.connection_result = None
         self.disconnection_result = None
         self.sink = None
@@ -783,27 +782,15 @@ class ClassicChannel(EventEmitter):
         self.state = new_state
 
     def send_pdu(self, pdu: Union[SupportsBytes, bytes]) -> None:
+        if self.state != self.State.OPEN:
+            raise InvalidStateError('channel not open')
         self.manager.send_pdu(self.connection, self.destination_cid, pdu)
 
     def send_control_frame(self, frame: L2CAP_Control_Frame) -> None:
         self.manager.send_control_frame(self.connection, self.signaling_cid, frame)
 
-    async def send_request(self, request: SupportsBytes) -> bytes:
-        # Check that there isn't already a request pending
-        if self.response:
-            raise InvalidStateError('request already pending')
-        if self.state != self.State.OPEN:
-            raise InvalidStateError('channel not open')
-
-        self.response = asyncio.get_running_loop().create_future()
-        self.send_pdu(request)
-        return await self.response
-
     def on_pdu(self, pdu: bytes) -> None:
-        if self.response:
-            self.response.set_result(pdu)
-            self.response = None
-        elif self.sink:
+        if self.sink:
             # pylint: disable=not-callable
             self.sink(pdu)
         else:
@@ -1921,7 +1908,7 @@ class ChannelManager:
     def on_l2cap_connection_parameter_update_request(
         self, connection: Connection, cid: int, request
     ):
-        if connection.role == BT_CENTRAL_ROLE:
+        if connection.role == Role.CENTRAL:
             self.send_control_frame(
                 connection,
                 cid,

bumble/link.py

@@ -20,7 +20,6 @@ import asyncio
 from functools import partial
 
 from bumble.core import (
-    BT_PERIPHERAL_ROLE,
     BT_BR_EDR_TRANSPORT,
     BT_LE_TRANSPORT,
     InvalidStateError,
@@ -28,6 +27,7 @@ from bumble.core import (
 from bumble.colors import color
 from bumble.hci import (
     Address,
+    Role,
     HCI_SUCCESS,
     HCI_CONNECTION_ACCEPT_TIMEOUT_ERROR,
     HCI_CONNECTION_TIMEOUT_ERROR,
@@ -292,7 +292,7 @@ class LocalLink:
             return
 
         async def task():
-            if responder_role != BT_PERIPHERAL_ROLE:
+            if responder_role != Role.PERIPHERAL:
                 initiator_controller.on_classic_role_change(
                     responder_controller.public_address, int(not (responder_role))
                 )

bumble/pairing.py

@@ -1,4 +1,4 @@
-# Copyright 2021-2023 Google LLC
+# Copyright 2021-2025 Google LLC
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -76,18 +76,18 @@ class OobData:
         return instance
 
     def to_ad(self) -> AdvertisingData:
-        ad_structures = []
+        ad_structures: list[tuple[int, bytes]] = []
         if self.address is not None:
             ad_structures.append(
-                (AdvertisingData.LE_BLUETOOTH_DEVICE_ADDRESS, bytes(self.address))
+                (AdvertisingData.Type.LE_BLUETOOTH_DEVICE_ADDRESS, bytes(self.address))
             )
         if self.role is not None:
-            ad_structures.append((AdvertisingData.LE_ROLE, bytes([self.role])))
+            ad_structures.append((AdvertisingData.Type.LE_ROLE, bytes([self.role])))
         if self.shared_data is not None:
             ad_structures.extend(self.shared_data.to_ad().ad_structures)
         if self.legacy_context is not None:
             ad_structures.append(
-                (AdvertisingData.SECURITY_MANAGER_TK_VALUE, self.legacy_context.tk)
+                (AdvertisingData.Type.SECURITY_MANAGER_TK_VALUE, self.legacy_context.tk)
             )
 
         return AdvertisingData(ad_structures)

bumble/pandora/host.py

@@ -25,7 +25,6 @@ from .config import Config
 from bumble.core import (
     BT_BR_EDR_TRANSPORT,
     BT_LE_TRANSPORT,
-    BT_PERIPHERAL_ROLE,
     UUID,
     AdvertisingData,
     Appearance,
@@ -47,6 +46,8 @@ from bumble.hci import (
     HCI_REMOTE_USER_TERMINATED_CONNECTION_ERROR,
     Address,
     Phy,
+    Role,
+    OwnAddressType,
 )
 from google.protobuf import any_pb2  # pytype: disable=pyi-error
 from google.protobuf import empty_pb2  # pytype: disable=pyi-error
@@ -114,11 +115,11 @@ SECONDARY_PHY_TO_BUMBLE_PHY_MAP: Dict[SecondaryPhy, Phy] = {
     SECONDARY_CODED: Phy.LE_CODED,
 }
 
-OWN_ADDRESS_MAP: Dict[host_pb2.OwnAddressType, bumble.hci.OwnAddressType] = {
-    host_pb2.PUBLIC: bumble.hci.OwnAddressType.PUBLIC,
-    host_pb2.RANDOM: bumble.hci.OwnAddressType.RANDOM,
-    host_pb2.RESOLVABLE_OR_PUBLIC: bumble.hci.OwnAddressType.RESOLVABLE_OR_PUBLIC,
-    host_pb2.RESOLVABLE_OR_RANDOM: bumble.hci.OwnAddressType.RESOLVABLE_OR_RANDOM,
+OWN_ADDRESS_MAP: Dict[host_pb2.OwnAddressType, OwnAddressType] = {
+    host_pb2.PUBLIC: OwnAddressType.PUBLIC,
+    host_pb2.RANDOM: OwnAddressType.RANDOM,
+    host_pb2.RESOLVABLE_OR_PUBLIC: OwnAddressType.RESOLVABLE_OR_PUBLIC,
+    host_pb2.RESOLVABLE_OR_RANDOM: OwnAddressType.RESOLVABLE_OR_RANDOM,
 }
 
 
@@ -250,7 +251,7 @@ class HostService(HostServicer):
             connection = await self.device.connect(
                 address,
                 transport=BT_LE_TRANSPORT,
-                own_address_type=request.own_address_type,
+                own_address_type=OwnAddressType(request.own_address_type),
             )
         except ConnectionError as e:
             if e.error_code == HCI_PAGE_TIMEOUT_ERROR:
@@ -371,18 +372,16 @@ class HostService(HostServicer):
             scan_response_data=scan_response_data,
         )
 
-        pending_connection: asyncio.Future[bumble.device.Connection] = (
-            asyncio.get_running_loop().create_future()
-        )
+        connections: asyncio.Queue[bumble.device.Connection] = asyncio.Queue()
 
         if request.connectable:
 
             def on_connection(connection: bumble.device.Connection) -> None:
                 if (
                     connection.transport == BT_LE_TRANSPORT
-                    and connection.role == BT_PERIPHERAL_ROLE
+                    and connection.role == Role.PERIPHERAL
                 ):
-                    pending_connection.set_result(connection)
+                    connections.put_nowait(connection)
 
             self.device.on('connection', on_connection)
 
@@ -397,8 +396,7 @@ class HostService(HostServicer):
                     await asyncio.sleep(1)
                     continue
 
-                connection = await pending_connection
-                pending_connection = asyncio.get_running_loop().create_future()
+                connection = await connections.get()
 
                 cookie = any_pb2.Any(value=connection.handle.to_bytes(4, 'big'))
                 yield AdvertiseResponse(connection=Connection(cookie=cookie))
@@ -492,14 +490,16 @@ class HostService(HostServicer):
                 target = Address(target_bytes, Address.RANDOM_DEVICE_ADDRESS)
                 advertising_type = AdvertisingType.DIRECTED_CONNECTABLE_LOW_DUTY
 
+        connections: asyncio.Queue[bumble.device.Connection] = asyncio.Queue()
+
         if request.connectable:
 
             def on_connection(connection: bumble.device.Connection) -> None:
                 if (
                     connection.transport == BT_LE_TRANSPORT
-                    and connection.role == BT_PERIPHERAL_ROLE
+                    and connection.role == Role.PERIPHERAL
                 ):
-                    pending_connection.set_result(connection)
+                    connections.put_nowait(connection)
 
             self.device.on('connection', on_connection)
 
@@ -510,19 +510,15 @@ class HostService(HostServicer):
                     await self.device.start_advertising(
                         target=target,
                         advertising_type=advertising_type,
-                        own_address_type=request.own_address_type,
+                        own_address_type=OwnAddressType(request.own_address_type),
                     )
 
                 if not request.connectable:
                     await asyncio.sleep(1)
                     continue
 
-                pending_connection: asyncio.Future[bumble.device.Connection] = (
-                    asyncio.get_running_loop().create_future()
-                )
-
                 self.log.debug('Wait for LE connection...')
-                connection = await pending_connection
+                connection = await connections.get()
 
                 self.log.debug(
                     f"Advertise: Connected to {connection.peer_address} (handle={connection.handle})"
@@ -563,7 +559,7 @@ class HostService(HostServicer):
         await self.device.start_scanning(
             legacy=request.legacy,
             active=not request.passive,
-            own_address_type=request.own_address_type,
+            own_address_type=OwnAddressType(request.own_address_type),
             scan_interval=(
                 int(request.interval)
                 if request.interval

bumble/pandora/security.py

@@ -24,11 +24,10 @@ from bumble import hci
 from bumble.core import (
     BT_BR_EDR_TRANSPORT,
     BT_LE_TRANSPORT,
-    BT_PERIPHERAL_ROLE,
     ProtocolError,
 )
 from bumble.device import Connection as BumbleConnection, Device
-from bumble.hci import HCI_Error
+from bumble.hci import HCI_Error, Role
 from bumble.utils import EventWatcher
 from bumble.pairing import PairingConfig, PairingDelegate as BasePairingDelegate
 from google.protobuf import any_pb2  # pytype: disable=pyi-error
@@ -318,7 +317,7 @@ class SecurityService(SecurityServicer):
 
                     if (
                         connection.transport == BT_LE_TRANSPORT
-                        and connection.role == BT_PERIPHERAL_ROLE
+                        and connection.role == Role.PERIPHERAL
                     ):
                         connection.request_pairing()
                     else:

bumble/pandora/utils.py

@@ -20,11 +20,11 @@ import inspect
 import logging
 
 from bumble.device import Device
-from bumble.hci import Address
+from bumble.hci import Address, AddressType
 from google.protobuf.message import Message  # pytype: disable=pyi-error
 from typing import Any, Dict, Generator, MutableMapping, Optional, Tuple
 
-ADDRESS_TYPES: Dict[str, int] = {
+ADDRESS_TYPES: Dict[str, AddressType] = {
     "public": Address.PUBLIC_DEVICE_ADDRESS,
     "random": Address.RANDOM_DEVICE_ADDRESS,
     "public_identity": Address.PUBLIC_IDENTITY_ADDRESS,

bumble/profiles/aics.py

@@ -24,16 +24,13 @@ import struct
 from dataclasses import dataclass
 from typing import Optional
 
-from bumble import gatt
 from bumble.device import Connection
 from bumble.att import ATT_Error
 from bumble.gatt import (
+    Attribute,
     Characteristic,
-    SerializableCharacteristicAdapter,
-    PackedCharacteristicAdapter,
     TemplateService,
     CharacteristicValue,
-    UTF8CharacteristicAdapter,
     GATT_AUDIO_INPUT_CONTROL_SERVICE,
     GATT_AUDIO_INPUT_STATE_CHARACTERISTIC,
     GATT_GAIN_SETTINGS_ATTRIBUTE_CHARACTERISTIC,
@@ -42,6 +39,14 @@ from bumble.gatt import (
     GATT_AUDIO_INPUT_CONTROL_POINT_CHARACTERISTIC,
     GATT_AUDIO_INPUT_DESCRIPTION_CHARACTERISTIC,
 )
+from bumble.gatt_adapters import (
+    CharacteristicProxy,
+    PackedCharacteristicProxyAdapter,
+    SerializableCharacteristicAdapter,
+    SerializableCharacteristicProxyAdapter,
+    UTF8CharacteristicAdapter,
+    UTF8CharacteristicProxyAdapter,
+)
 from bumble.gatt_client import ProfileServiceProxy, ServiceProxy
 from bumble.utils import OpenIntEnum
 
@@ -124,7 +129,7 @@ class AudioInputState:
     mute: Mute = Mute.NOT_MUTED
     gain_mode: GainMode = GainMode.MANUAL
     change_counter: int = 0
-    attribute_value: Optional[CharacteristicValue] = None
+    attribute: Optional[Attribute] = None
 
     def __bytes__(self) -> bytes:
         return bytes(
@@ -151,10 +156,8 @@ class AudioInputState:
         self.change_counter = (self.change_counter + 1) % (CHANGE_COUNTER_MAX_VALUE + 1)
 
     async def notify_subscribers_via_connection(self, connection: Connection) -> None:
-        assert self.attribute_value is not None
-        await connection.device.notify_subscribers(
-            attribute=self.attribute_value, value=bytes(self)
-        )
+        assert self.attribute is not None
+        await connection.device.notify_subscribers(attribute=self.attribute)
 
 
 @dataclass
@@ -315,24 +318,28 @@ class AudioInputDescription:
     '''
 
     audio_input_description: str = "Bluetooth"
-    attribute_value: Optional[CharacteristicValue] = None
+    attribute: Optional[Attribute] = None
 
     def on_read(self, _connection: Optional[Connection]) -> str:
         return self.audio_input_description
 
     async def on_write(self, connection: Optional[Connection], value: str) -> None:
         assert connection
-        assert self.attribute_value
+        assert self.attribute
 
         self.audio_input_description = value
-        await connection.device.notify_subscribers(
-            attribute=self.attribute_value, value=value
-        )
+        await connection.device.notify_subscribers(attribute=self.attribute)
 
 
 class AICSService(TemplateService):
     UUID = GATT_AUDIO_INPUT_CONTROL_SERVICE
 
+    audio_input_state_characteristic: Characteristic[AudioInputState]
+    audio_input_type_characteristic: Characteristic[bytes]
+    audio_input_status_characteristic: Characteristic[bytes]
+    audio_input_control_point_characteristic: Characteristic[bytes]
+    gain_settings_properties_characteristic: Characteristic[GainSettingsProperties]
+
     def __init__(
         self,
         audio_input_state: Optional[AudioInputState] = None,
@@ -374,9 +381,7 @@ class AICSService(TemplateService):
             ),
             AudioInputState,
         )
-        self.audio_input_state.attribute_value = (
-            self.audio_input_state_characteristic.value
-        )
+        self.audio_input_state.attribute = self.audio_input_state_characteristic
 
         self.gain_settings_properties_characteristic = (
             SerializableCharacteristicAdapter(
@@ -425,8 +430,8 @@ class AICSService(TemplateService):
                 ),
             )
         )
-        self.audio_input_description.attribute_value = (
-            self.audio_input_control_point_characteristic.value
+        self.audio_input_description.attribute = (
+            self.audio_input_control_point_characteristic
         )
 
         super().__init__(
@@ -448,57 +453,43 @@ class AICSService(TemplateService):
 class AICSServiceProxy(ProfileServiceProxy):
     SERVICE_CLASS = AICSService
 
+    audio_input_state: CharacteristicProxy[AudioInputState]
+    gain_settings_properties: CharacteristicProxy[GainSettingsProperties]
+    audio_input_status: CharacteristicProxy[int]
+    audio_input_control_point: CharacteristicProxy[bytes]
+
     def __init__(self, service_proxy: ServiceProxy) -> None:
         self.service_proxy = service_proxy
 
-        if not (
-            characteristics := service_proxy.get_characteristics_by_uuid(
+        self.audio_input_state = SerializableCharacteristicProxyAdapter(
+            service_proxy.get_required_characteristic_by_uuid(
                 GATT_AUDIO_INPUT_STATE_CHARACTERISTIC
-            )
-        ):
-            raise gatt.InvalidServiceError("Audio Input State Characteristic not found")
-        self.audio_input_state = SerializableCharacteristicAdapter(
-            characteristics[0], AudioInputState
+            ),
+            AudioInputState,
         )
 
-        if not (
-            characteristics := service_proxy.get_characteristics_by_uuid(
+        self.gain_settings_properties = SerializableCharacteristicProxyAdapter(
+            service_proxy.get_required_characteristic_by_uuid(
                 GATT_GAIN_SETTINGS_ATTRIBUTE_CHARACTERISTIC
-            )
-        ):
-            raise gatt.InvalidServiceError(
-                "Gain Settings Attribute Characteristic not found"
-            )
-        self.gain_settings_properties = SerializableCharacteristicAdapter(
-            characteristics[0], GainSettingsProperties
+            ),
+            GainSettingsProperties,
         )
 
-        if not (
-            characteristics := service_proxy.get_characteristics_by_uuid(
+        self.audio_input_status = PackedCharacteristicProxyAdapter(
+            service_proxy.get_required_characteristic_by_uuid(
                 GATT_AUDIO_INPUT_STATUS_CHARACTERISTIC
-            )
-        ):
-            raise gatt.InvalidServiceError(
-                "Audio Input Status Characteristic not found"
-            )
-        self.audio_input_status = PackedCharacteristicAdapter(characteristics[0], 'B')
+            ),
+            'B',
+        )
 
-        if not (
-            characteristics := service_proxy.get_characteristics_by_uuid(
+        self.audio_input_control_point = (
+            service_proxy.get_required_characteristic_by_uuid(
                 GATT_AUDIO_INPUT_CONTROL_POINT_CHARACTERISTIC
             )
-        ):
-            raise gatt.InvalidServiceError(
-                "Audio Input Control Point Characteristic not found"
-            )
-        self.audio_input_control_point = characteristics[0]
+        )
 
-        if not (
-            characteristics := service_proxy.get_characteristics_by_uuid(
+        self.audio_input_description = UTF8CharacteristicProxyAdapter(
+            service_proxy.get_required_characteristic_by_uuid(
                 GATT_AUDIO_INPUT_DESCRIPTION_CHARACTERISTIC
             )
-        ):
-            raise gatt.InvalidServiceError(
-                "Audio Input Description Characteristic not found"
-            )
-        self.audio_input_description = UTF8CharacteristicAdapter(characteristics[0])
+        )

bumble/profiles/ancs.py

@@ -0,0 +1,514 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+Apple Notification Center Service (ANCS).
+"""
+
+# -----------------------------------------------------------------------------
+# Imports
+# -----------------------------------------------------------------------------
+from __future__ import annotations
+import asyncio
+import dataclasses
+import datetime
+import enum
+import logging
+import struct
+from typing import Optional, Sequence, Union
+
+from pyee import EventEmitter
+
+from bumble.att import ATT_Error
+from bumble.device import Peer
+from bumble.gatt import (
+    Characteristic,
+    GATT_ANCS_SERVICE,
+    GATT_ANCS_NOTIFICATION_SOURCE_CHARACTERISTIC,
+    GATT_ANCS_CONTROL_POINT_CHARACTERISTIC,
+    GATT_ANCS_DATA_SOURCE_CHARACTERISTIC,
+    TemplateService,
+)
+from bumble.gatt_client import CharacteristicProxy, ProfileServiceProxy, ServiceProxy
+from bumble.gatt_adapters import SerializableCharacteristicProxyAdapter
+from bumble.utils import OpenIntEnum
+
+
+# -----------------------------------------------------------------------------
+# Constants
+# -----------------------------------------------------------------------------
+_DEFAULT_ATTRIBUTE_MAX_LENGTH = 65535
+
+
+# -----------------------------------------------------------------------------
+# Logging
+# -----------------------------------------------------------------------------
+logger = logging.getLogger(__name__)
+
+
+# -----------------------------------------------------------------------------
+# Protocol
+# -----------------------------------------------------------------------------
+class ActionId(OpenIntEnum):
+    POSITIVE = 0
+    NEGATIVE = 1
+
+
+class AppAttributeId(OpenIntEnum):
+    DISPLAY_NAME = 0
+
+
+class CategoryId(OpenIntEnum):
+    OTHER = 0
+    INCOMING_CALL = 1
+    MISSED_CALL = 2
+    VOICEMAIL = 3
+    SOCIAL = 4
+    SCHEDULE = 5
+    EMAIL = 6
+    NEWS = 7
+    HEALTH_AND_FITNESS = 8
+    BUSINESS_AND_FINANCE = 9
+    LOCATION = 10
+    ENTERTAINMENT = 11
+
+
+class CommandId(OpenIntEnum):
+    GET_NOTIFICATION_ATTRIBUTES = 0
+    GET_APP_ATTRIBUTES = 1
+    PERFORM_NOTIFICATION_ACTION = 2
+
+
+class EventId(OpenIntEnum):
+    NOTIFICATION_ADDED = 0
+    NOTIFICATION_MODIFIED = 1
+    NOTIFICATION_REMOVED = 2
+
+
+class EventFlags(enum.IntFlag):
+    SILENT = 1 << 0
+    IMPORTANT = 1 << 1
+    PRE_EXISTING = 1 << 2
+    POSITIVE_ACTION = 1 << 3
+    NEGATIVE_ACTION = 1 << 4
+
+
+class NotificationAttributeId(OpenIntEnum):
+    APP_IDENTIFIER = 0
+    TITLE = 1
+    SUBTITLE = 2
+    MESSAGE = 3
+    MESSAGE_SIZE = 4
+    DATE = 5
+    POSITIVE_ACTION_LABEL = 6
+    NEGATIVE_ACTION_LABEL = 7
+
+
+@dataclasses.dataclass
+class NotificationAttribute:
+    attribute_id: NotificationAttributeId
+    value: Union[str, int, datetime.datetime]
+
+
+@dataclasses.dataclass
+class AppAttribute:
+    attribute_id: AppAttributeId
+    value: str
+
+
+@dataclasses.dataclass
+class Notification:
+    event_id: EventId
+    event_flags: EventFlags
+    category_id: CategoryId
+    category_count: int
+    notification_uid: int
+
+    @classmethod
+    def from_bytes(cls, data: bytes) -> Notification:
+        return cls(
+            event_id=EventId(data[0]),
+            event_flags=EventFlags(data[1]),
+            category_id=CategoryId(data[2]),
+            category_count=data[3],
+            notification_uid=int.from_bytes(data[4:8], 'little'),
+        )
+
+    def __bytes__(self) -> bytes:
+        return struct.pack(
+            "<BBBBI",
+            self.event_id,
+            self.event_flags,
+            self.category_id,
+            self.category_count,
+            self.notification_uid,
+        )
+
+
+class ErrorCode(OpenIntEnum):
+    UNKNOWN_COMMAND = 0xA0
+    INVALID_COMMAND = 0xA1
+    INVALID_PARAMETER = 0xA2
+    ACTION_FAILED = 0xA3
+
+
+class ProtocolError(Exception):
+    pass
+
+
+class CommandError(Exception):
+    def __init__(self, error_code: ErrorCode) -> None:
+        self.error_code = error_code
+
+    def __str__(self) -> str:
+        return f"CommandError(error_code={self.error_code.name})"
+
+
+# -----------------------------------------------------------------------------
+# GATT Server-side
+# -----------------------------------------------------------------------------
+class Ancs(TemplateService):
+    UUID = GATT_ANCS_SERVICE
+
+    notification_source_characteristic: Characteristic
+    data_source_characteristic: Characteristic
+    control_point_characteristic: Characteristic
+
+    def __init__(self) -> None:
+        # TODO not the final implementation
+        self.notification_source_characteristic = Characteristic(
+            GATT_ANCS_NOTIFICATION_SOURCE_CHARACTERISTIC,
+            Characteristic.Properties.NOTIFY,
+            Characteristic.Permissions.READABLE,
+        )
+
+        # TODO not the final implementation
+        self.data_source_characteristic = Characteristic(
+            GATT_ANCS_DATA_SOURCE_CHARACTERISTIC,
+            Characteristic.Properties.NOTIFY,
+            Characteristic.Permissions.READABLE,
+        )
+
+        # TODO not the final implementation
+        self.control_point_characteristic = Characteristic(
+            GATT_ANCS_CONTROL_POINT_CHARACTERISTIC,
+            Characteristic.Properties.WRITE,
+            Characteristic.Permissions.WRITEABLE,
+        )
+
+        super().__init__(
+            [
+                self.notification_source_characteristic,
+                self.data_source_characteristic,
+                self.control_point_characteristic,
+            ]
+        )
+
+
+# -----------------------------------------------------------------------------
+# GATT Client-side
+# -----------------------------------------------------------------------------
+class AncsProxy(ProfileServiceProxy):
+    SERVICE_CLASS = Ancs
+
+    notification_source: CharacteristicProxy[Notification]
+    data_source: CharacteristicProxy
+    control_point: CharacteristicProxy[bytes]
+
+    def __init__(self, service_proxy: ServiceProxy):
+        self.notification_source = SerializableCharacteristicProxyAdapter(
+            service_proxy.get_required_characteristic_by_uuid(
+                GATT_ANCS_NOTIFICATION_SOURCE_CHARACTERISTIC
+            ),
+            Notification,
+        )
+
+        self.data_source = service_proxy.get_required_characteristic_by_uuid(
+            GATT_ANCS_DATA_SOURCE_CHARACTERISTIC
+        )
+
+        self.control_point = service_proxy.get_required_characteristic_by_uuid(
+            GATT_ANCS_CONTROL_POINT_CHARACTERISTIC
+        )
+
+
+class AncsClient(EventEmitter):
+    _expected_response_command_id: Optional[CommandId]
+    _expected_response_notification_uid: Optional[int]
+    _expected_response_app_identifier: Optional[str]
+    _expected_app_identifier: Optional[str]
+    _expected_response_tuples: int
+    _response_accumulator: bytes
+
+    def __init__(self, ancs_proxy: AncsProxy) -> None:
+        super().__init__()
+        self._ancs_proxy = ancs_proxy
+        self._command_semaphore = asyncio.Semaphore()
+        self._response: Optional[asyncio.Future] = None
+        self._reset_response()
+        self._started = False
+
+    @classmethod
+    async def for_peer(cls, peer: Peer) -> Optional[AncsClient]:
+        ancs_proxy = await peer.discover_service_and_create_proxy(AncsProxy)
+        if ancs_proxy is None:
+            return None
+        return cls(ancs_proxy)
+
+    async def start(self) -> None:
+        await self._ancs_proxy.notification_source.subscribe(self._on_notification)
+        await self._ancs_proxy.data_source.subscribe(self._on_data)
+        self._started = True
+
+    async def stop(self) -> None:
+        await self._ancs_proxy.notification_source.unsubscribe(self._on_notification)
+        await self._ancs_proxy.data_source.unsubscribe(self._on_data)
+        self._started = False
+
+    def _reset_response(self) -> None:
+        self._expected_response_command_id = None
+        self._expected_response_notification_uid = None
+        self._expected_app_identifier = None
+        self._expected_response_tuples = 0
+        self._response_accumulator = b""
+
+    def _on_notification(self, notification: Notification) -> None:
+        logger.debug(f"ANCS NOTIFICATION: {notification}")
+        self.emit("notification", notification)
+
+    def _on_data(self, data: bytes) -> None:
+        logger.debug(f"ANCS DATA: {data.hex()}")
+
+        if not self._response:
+            logger.warning("received unexpected data, discarding")
+            return
+
+        self._response_accumulator += data
+
+        # Try to parse the accumulated data until we have all we need.
+        if not self._response_accumulator:
+            logger.warning("empty data from data source")
+            return
+
+        command_id = self._response_accumulator[0]
+        if command_id != self._expected_response_command_id:
+            logger.warning(
+                "unexpected response command id: "
+                f"expected {self._expected_response_command_id} "
+                f"but got {command_id}"
+            )
+            self._reset_response()
+            if not self._response.done():
+                self._response.set_exception(ProtocolError())
+
+        if len(self._response_accumulator) < 5:
+            # Not enough data yet.
+            return
+
+        attributes: list[Union[NotificationAttribute, AppAttribute]] = []
+
+        if command_id == CommandId.GET_NOTIFICATION_ATTRIBUTES:
+            (notification_uid,) = struct.unpack_from(
+                "<I", self._response_accumulator, 1
+            )
+            if notification_uid != self._expected_response_notification_uid:
+                logger.warning(
+                    "unexpected response notification uid: "
+                    f"expected {self._expected_response_notification_uid} "
+                    f"but got {notification_uid}"
+                )
+                self._reset_response()
+                if not self._response.done():
+                    self._response.set_exception(ProtocolError())
+
+            attribute_data = self._response_accumulator[5:]
+            while len(attribute_data) >= 3:
+                attribute_id, attribute_data_length = struct.unpack_from(
+                    "<BH", attribute_data, 0
+                )
+                if len(attribute_data) < 3 + attribute_data_length:
+                    return
+                str_value = attribute_data[3 : 3 + attribute_data_length].decode(
+                    "utf-8"
+                )
+                value: Union[str, int, datetime.datetime]
+                if attribute_id == NotificationAttributeId.MESSAGE_SIZE:
+                    value = int(str_value)
+                elif attribute_id == NotificationAttributeId.DATE:
+                    year = int(str_value[:4])
+                    month = int(str_value[4:6])
+                    day = int(str_value[6:8])
+                    hour = int(str_value[9:11])
+                    minute = int(str_value[11:13])
+                    second = int(str_value[13:15])
+                    value = datetime.datetime(year, month, day, hour, minute, second)
+                else:
+                    value = str_value
+                attributes.append(
+                    NotificationAttribute(NotificationAttributeId(attribute_id), value)
+                )
+                attribute_data = attribute_data[3 + attribute_data_length :]
+        elif command_id == CommandId.GET_APP_ATTRIBUTES:
+            if 0 not in self._response_accumulator[1:]:
+                # No null-terminated string yet.
+                return
+
+            app_identifier_length = self._response_accumulator.find(0, 1) - 1
+            app_identifier = self._response_accumulator[
+                1 : 1 + app_identifier_length
+            ].decode("utf-8")
+            if app_identifier != self._expected_response_app_identifier:
+                logger.warning(
+                    "unexpected response app identifier: "
+                    f"expected {self._expected_response_app_identifier} "
+                    f"but got {app_identifier}"
+                )
+                self._reset_response()
+                if not self._response.done():
+                    self._response.set_exception(ProtocolError())
+
+            attribute_data = self._response_accumulator[1 + app_identifier_length + 1 :]
+            while len(attribute_data) >= 3:
+                attribute_id, attribute_data_length = struct.unpack_from(
+                    "<BH", attribute_data, 0
+                )
+                if len(attribute_data) < 3 + attribute_data_length:
+                    return
+                attributes.append(
+                    AppAttribute(
+                        AppAttributeId(attribute_id),
+                        attribute_data[3 : 3 + attribute_data_length].decode("utf-8"),
+                    )
+                )
+                attribute_data = attribute_data[3 + attribute_data_length :]
+        else:
+            logger.warning(f"unexpected response command id {command_id}")
+            return
+
+        if len(attributes) < self._expected_response_tuples:
+            # We have not received all the tuples yet.
+            return
+
+        if not self._response.done():
+            self._response.set_result(attributes)
+
+    async def _send_command(self, command: bytes) -> None:
+        try:
+            await self._ancs_proxy.control_point.write_value(
+                command, with_response=True
+            )
+        except ATT_Error as error:
+            raise CommandError(error_code=ErrorCode(error.error_code)) from error
+
+    async def get_notification_attributes(
+        self,
+        notification_uid: int,
+        attributes: Sequence[
+            Union[NotificationAttributeId, tuple[NotificationAttributeId, int]]
+        ],
+    ) -> list[NotificationAttribute]:
+        if not self._started:
+            raise RuntimeError("client not started")
+
+        command = struct.pack(
+            "<BI", CommandId.GET_NOTIFICATION_ATTRIBUTES, notification_uid
+        )
+        for attribute in attributes:
+            attribute_max_length = 0
+            if isinstance(attribute, tuple):
+                attribute_id, attribute_max_length = attribute
+                if attribute_id not in (
+                    NotificationAttributeId.TITLE,
+                    NotificationAttributeId.SUBTITLE,
+                    NotificationAttributeId.MESSAGE,
+                ):
+                    raise ValueError(
+                        "this attribute does not allow specifying a max length"
+                    )
+            else:
+                attribute_id = attribute
+                if attribute_id in (
+                    NotificationAttributeId.TITLE,
+                    NotificationAttributeId.SUBTITLE,
+                    NotificationAttributeId.MESSAGE,
+                ):
+                    attribute_max_length = _DEFAULT_ATTRIBUTE_MAX_LENGTH
+
+            if attribute_max_length:
+                command += struct.pack("<BH", attribute_id, attribute_max_length)
+            else:
+                command += struct.pack("B", attribute_id)
+
+        try:
+            async with self._command_semaphore:
+                self._expected_response_notification_uid = notification_uid
+                self._expected_response_tuples = len(attributes)
+                self._expected_response_command_id = (
+                    CommandId.GET_NOTIFICATION_ATTRIBUTES
+                )
+                self._response = asyncio.Future()
+
+                # Send the command.
+                await self._send_command(command)
+
+                # Wait for the response.
+                return await self._response
+        finally:
+            self._reset_response()
+
+    async def get_app_attributes(
+        self, app_identifier: str, attributes: Sequence[AppAttributeId]
+    ) -> list[AppAttribute]:
+        if not self._started:
+            raise RuntimeError("client not started")
+
+        command = (
+            bytes([CommandId.GET_APP_ATTRIBUTES])
+            + app_identifier.encode("utf-8")
+            + b"\0"
+        )
+        for attribute_id in attributes:
+            command += struct.pack("B", attribute_id)
+
+        try:
+            async with self._command_semaphore:
+                self._expected_response_app_identifier = app_identifier
+                self._expected_response_tuples = len(attributes)
+                self._expected_response_command_id = CommandId.GET_APP_ATTRIBUTES
+                self._response = asyncio.Future()
+
+                # Send the command.
+                await self._send_command(command)
+
+                # Wait for the response.
+                return await self._response
+        finally:
+            self._reset_response()
+
+    async def perform_action(self, notification_uid: int, action: ActionId) -> None:
+        if not self._started:
+            raise RuntimeError("client not started")
+
+        command = struct.pack(
+            "<BIB", CommandId.PERFORM_NOTIFICATION_ACTION, notification_uid, action
+        )
+
+        async with self._command_semaphore:
+            await self._send_command(command)
+
+    async def perform_positive_action(self, notification_uid: int) -> None:
+        return await self.perform_action(notification_uid, ActionId.POSITIVE)
+
+    async def perform_negative_action(self, notification_uid: int) -> None:
+        return await self.perform_action(notification_uid, ActionId.NEGATIVE)

bumble/profiles/ascs.py

@@ -17,6 +17,7 @@
 # Imports
 # -----------------------------------------------------------------------------
 from __future__ import annotations
+
 import enum
 import logging
 import struct
@@ -258,8 +259,8 @@ class AseReasonCode(enum.IntEnum):
 
 # -----------------------------------------------------------------------------
 class AudioRole(enum.IntEnum):
-    SINK = hci.HCI_LE_Setup_ISO_Data_Path_Command.Direction.CONTROLLER_TO_HOST
-    SOURCE = hci.HCI_LE_Setup_ISO_Data_Path_Command.Direction.HOST_TO_CONTROLLER
+    SINK = device.CisLink.Direction.CONTROLLER_TO_HOST
+    SOURCE = device.CisLink.Direction.HOST_TO_CONTROLLER
 
 
 # -----------------------------------------------------------------------------
@@ -300,7 +301,7 @@ class AseStateMachine(gatt.Characteristic):
     presentation_delay = 0
 
     # Additional parameters in ENABLING, STREAMING, DISABLING State
-    metadata = le_audio.Metadata()
+    metadata: le_audio.Metadata
 
     def __init__(
         self,
@@ -312,6 +313,7 @@ class AseStateMachine(gatt.Characteristic):
         self.ase_id = ase_id
         self._state = AseStateMachine.State.IDLE
         self.role = role
+        self.metadata = le_audio.Metadata()
 
         uuid = (
             gatt.GATT_SINK_ASE_CHARACTERISTIC
@@ -354,16 +356,7 @@ class AseStateMachine(gatt.Characteristic):
             cis_link.on('disconnection', self.on_cis_disconnection)
 
             async def post_cis_established():
-                await self.service.device.send_command(
-                    hci.HCI_LE_Setup_ISO_Data_Path_Command(
-                        connection_handle=cis_link.handle,
-                        data_path_direction=self.role,
-                        data_path_id=0x00,  # Fixed HCI
-                        codec_id=hci.CodingFormat(hci.CodecID.TRANSPARENT),
-                        controller_delay=0,
-                        codec_configuration=b'',
-                    )
-                )
+                await cis_link.setup_data_path(direction=self.role)
                 if self.role == AudioRole.SINK:
                     self.state = self.State.STREAMING
                 await self.service.device.notify_subscribers(self, self.value)
@@ -511,12 +504,8 @@ class AseStateMachine(gatt.Characteristic):
         self.state = self.State.RELEASING
 
         async def remove_cis_async():
-            await self.service.device.send_command(
-                hci.HCI_LE_Remove_ISO_Data_Path_Command(
-                    connection_handle=self.cis_link.handle,
-                    data_path_direction=self.role,
-                )
-            )
+            if self.cis_link:
+                await self.cis_link.remove_data_path(self.role)
             self.state = self.State.IDLE
             await self.service.device.notify_subscribers(self, self.value)
 

bumble/profiles/asha.py

@@ -134,12 +134,14 @@ class AshaService(gatt.TemplateService):
             ),
         )
 
-        self.audio_control_point_characteristic = gatt.Characteristic(
-            gatt.GATT_ASHA_AUDIO_CONTROL_POINT_CHARACTERISTIC,
-            gatt.Characteristic.Properties.WRITE
-            | gatt.Characteristic.Properties.WRITE_WITHOUT_RESPONSE,
-            gatt.Characteristic.WRITEABLE,
-            gatt.CharacteristicValue(write=self._on_audio_control_point_write),
+        self.audio_control_point_characteristic: gatt.Characteristic[bytes] = (
+            gatt.Characteristic(
+                gatt.GATT_ASHA_AUDIO_CONTROL_POINT_CHARACTERISTIC,
+                gatt.Characteristic.Properties.WRITE
+                | gatt.Characteristic.Properties.WRITE_WITHOUT_RESPONSE,
+                gatt.Characteristic.WRITEABLE,
+                gatt.CharacteristicValue(write=self._on_audio_control_point_write),
+            )
         )
         self.audio_status_characteristic = gatt.Characteristic(
             gatt.GATT_ASHA_AUDIO_STATUS_CHARACTERISTIC,
@@ -147,7 +149,7 @@ class AshaService(gatt.TemplateService):
             gatt.Characteristic.READABLE,
             bytes([AudioStatus.OK]),
         )
-        self.volume_characteristic = gatt.Characteristic(
+        self.volume_characteristic: gatt.Characteristic[bytes] = gatt.Characteristic(
             gatt.GATT_ASHA_VOLUME_CHARACTERISTIC,
             gatt.Characteristic.Properties.WRITE_WITHOUT_RESPONSE,
             gatt.Characteristic.WRITEABLE,
@@ -166,13 +168,13 @@ class AshaService(gatt.TemplateService):
             struct.pack('<H', self.psm),
         )
 
-        characteristics = [
+        characteristics = (
             self.read_only_properties_characteristic,
             self.audio_control_point_characteristic,
             self.audio_status_characteristic,
             self.volume_characteristic,
             self.le_psm_out_characteristic,
-        ]
+        )
 
         super().__init__(characteristics)
 
@@ -288,8 +290,8 @@ class AshaServiceProxy(gatt_client.ProfileServiceProxy):
                 'psm_characteristic',
             ),
         ):
-            if not (
-                characteristics := self.service_proxy.get_characteristics_by_uuid(uuid)
-            ):
-                raise gatt.InvalidServiceError(f"Missing {uuid} Characteristic")
-            setattr(self, attribute_name, characteristics[0])
+            setattr(
+                self,
+                attribute_name,
+                self.service_proxy.get_required_characteristic_by_uuid(uuid),
+            )

bumble/profiles/bass.py

@@ -20,11 +20,12 @@ from __future__ import annotations
 import dataclasses
 import logging
 import struct
-from typing import ClassVar, List, Optional, Sequence
+from typing import ClassVar, Optional, Sequence
 
 from bumble import core
 from bumble import device
 from bumble import gatt
+from bumble import gatt_adapters
 from bumble import gatt_client
 from bumble import hci
 from bumble import utils
@@ -52,7 +53,7 @@ def encode_subgroups(subgroups: Sequence[SubgroupInfo]) -> bytes:
     )
 
 
-def decode_subgroups(data: bytes) -> List[SubgroupInfo]:
+def decode_subgroups(data: bytes) -> list[SubgroupInfo]:
     num_subgroups = data[0]
     offset = 1
     subgroups = []
@@ -273,7 +274,7 @@ class BroadcastReceiveState:
     pa_sync_state: PeriodicAdvertisingSyncState
     big_encryption: BigEncryption
     bad_code: bytes
-    subgroups: List[SubgroupInfo]
+    subgroups: list[SubgroupInfo]
 
     @classmethod
     def from_bytes(cls, data: bytes) -> BroadcastReceiveState:
@@ -354,34 +355,27 @@ class BroadcastAudioScanServiceProxy(gatt_client.ProfileServiceProxy):
     SERVICE_CLASS = BroadcastAudioScanService
 
     broadcast_audio_scan_control_point: gatt_client.CharacteristicProxy
-    broadcast_receive_states: List[gatt.SerializableCharacteristicAdapter]
+    broadcast_receive_states: list[
+        gatt_client.CharacteristicProxy[Optional[BroadcastReceiveState]]
+    ]
 
     def __init__(self, service_proxy: gatt_client.ServiceProxy):
         self.service_proxy = service_proxy
 
-        if not (
-            characteristics := service_proxy.get_characteristics_by_uuid(
+        self.broadcast_audio_scan_control_point = (
+            service_proxy.get_required_characteristic_by_uuid(
                 gatt.GATT_BROADCAST_AUDIO_SCAN_CONTROL_POINT_CHARACTERISTIC
             )
-        ):
-            raise gatt.InvalidServiceError(
-                "Broadcast Audio Scan Control Point characteristic not found"
-            )
-        self.broadcast_audio_scan_control_point = characteristics[0]
+        )
 
-        if not (
-            characteristics := service_proxy.get_characteristics_by_uuid(
+        self.broadcast_receive_states = [
+            gatt_adapters.DelegatedCharacteristicProxyAdapter(
+                characteristic,
+                decode=lambda x: BroadcastReceiveState.from_bytes(x) if x else None,
+            )
+            for characteristic in service_proxy.get_characteristics_by_uuid(
                 gatt.GATT_BROADCAST_RECEIVE_STATE_CHARACTERISTIC
             )
-        ):
-            raise gatt.InvalidServiceError(
-                "Broadcast Receive State characteristic not found"
-            )
-        self.broadcast_receive_states = [
-            gatt.SerializableCharacteristicAdapter(
-                characteristic, BroadcastReceiveState
-            )
-            for characteristic in characteristics
         ]
 
     async def send_control_point_operation(

bumble/profiles/battery_service.py

@@ -16,14 +16,20 @@
 # -----------------------------------------------------------------------------
 # Imports
 # -----------------------------------------------------------------------------
-from ..gatt_client import ProfileServiceProxy
-from ..gatt import (
+from typing import Optional
+
+from bumble.gatt_client import ProfileServiceProxy
+from bumble.gatt import (
     GATT_BATTERY_SERVICE,
     GATT_BATTERY_LEVEL_CHARACTERISTIC,
     TemplateService,
     Characteristic,
     CharacteristicValue,
+)
+from bumble.gatt_client import CharacteristicProxy
+from bumble.gatt_adapters import (
     PackedCharacteristicAdapter,
+    PackedCharacteristicProxyAdapter,
 )
 
 
@@ -32,6 +38,8 @@ class BatteryService(TemplateService):
     UUID = GATT_BATTERY_SERVICE
     BATTERY_LEVEL_FORMAT = 'B'
 
+    battery_level_characteristic: Characteristic[int]
+
     def __init__(self, read_battery_level):
         self.battery_level_characteristic = PackedCharacteristicAdapter(
             Characteristic(
@@ -49,13 +57,15 @@ class BatteryService(TemplateService):
 class BatteryServiceProxy(ProfileServiceProxy):
     SERVICE_CLASS = BatteryService
 
+    battery_level: Optional[CharacteristicProxy[int]]
+
     def __init__(self, service_proxy):
         self.service_proxy = service_proxy
 
         if characteristics := service_proxy.get_characteristics_by_uuid(
             GATT_BATTERY_LEVEL_CHARACTERISTIC
         ):
-            self.battery_level = PackedCharacteristicAdapter(
+            self.battery_level = PackedCharacteristicProxyAdapter(
                 characteristics[0], pack_format=BatteryService.BATTERY_LEVEL_FORMAT
             )
         else:

bumble/profiles/device_information_service.py

@@ -19,7 +19,6 @@
 import struct
 from typing import Optional, Tuple
 
-from bumble.gatt_client import ServiceProxy, ProfileServiceProxy, CharacteristicProxy
 from bumble.gatt import (
     GATT_DEVICE_INFORMATION_SERVICE,
     GATT_FIRMWARE_REVISION_STRING_CHARACTERISTIC,
@@ -32,9 +31,12 @@ from bumble.gatt import (
     GATT_REGULATORY_CERTIFICATION_DATA_LIST_CHARACTERISTIC,
     TemplateService,
     Characteristic,
-    DelegatedCharacteristicAdapter,
-    UTF8CharacteristicAdapter,
 )
+from bumble.gatt_adapters import (
+    DelegatedCharacteristicProxyAdapter,
+    UTF8CharacteristicProxyAdapter,
+)
+from bumble.gatt_client import CharacteristicProxy, ProfileServiceProxy, ServiceProxy
 
 
 # -----------------------------------------------------------------------------
@@ -62,7 +64,7 @@ class DeviceInformationService(TemplateService):
         ieee_regulatory_certification_data_list: Optional[bytes] = None,
         # TODO: pnp_id
     ):
-        characteristics = [
+        characteristics: list[Characteristic[bytes]] = [
             Characteristic(
                 uuid,
                 Characteristic.Properties.READ,
@@ -107,14 +109,14 @@ class DeviceInformationService(TemplateService):
 class DeviceInformationServiceProxy(ProfileServiceProxy):
     SERVICE_CLASS = DeviceInformationService
 
-    manufacturer_name: Optional[UTF8CharacteristicAdapter]
-    model_number: Optional[UTF8CharacteristicAdapter]
-    serial_number: Optional[UTF8CharacteristicAdapter]
-    hardware_revision: Optional[UTF8CharacteristicAdapter]
-    firmware_revision: Optional[UTF8CharacteristicAdapter]
-    software_revision: Optional[UTF8CharacteristicAdapter]
-    system_id: Optional[DelegatedCharacteristicAdapter]
-    ieee_regulatory_certification_data_list: Optional[CharacteristicProxy]
+    manufacturer_name: Optional[CharacteristicProxy[str]]
+    model_number: Optional[CharacteristicProxy[str]]
+    serial_number: Optional[CharacteristicProxy[str]]
+    hardware_revision: Optional[CharacteristicProxy[str]]
+    firmware_revision: Optional[CharacteristicProxy[str]]
+    software_revision: Optional[CharacteristicProxy[str]]
+    system_id: Optional[CharacteristicProxy[tuple[int, int]]]
+    ieee_regulatory_certification_data_list: Optional[CharacteristicProxy[bytes]]
 
     def __init__(self, service_proxy: ServiceProxy):
         self.service_proxy = service_proxy
@@ -128,7 +130,7 @@ class DeviceInformationServiceProxy(ProfileServiceProxy):
             ('software_revision', GATT_SOFTWARE_REVISION_STRING_CHARACTERISTIC),
         ):
             if characteristics := service_proxy.get_characteristics_by_uuid(uuid):
-                characteristic = UTF8CharacteristicAdapter(characteristics[0])
+                characteristic = UTF8CharacteristicProxyAdapter(characteristics[0])
             else:
                 characteristic = None
             self.__setattr__(field, characteristic)
@@ -136,7 +138,7 @@ class DeviceInformationServiceProxy(ProfileServiceProxy):
         if characteristics := service_proxy.get_characteristics_by_uuid(
             GATT_SYSTEM_ID_CHARACTERISTIC
         ):
-            self.system_id = DelegatedCharacteristicAdapter(
+            self.system_id = DelegatedCharacteristicProxyAdapter(
                 characteristics[0],
                 encode=lambda v: DeviceInformationService.pack_system_id(*v),
                 decode=DeviceInformationService.unpack_system_id,

bumble/profiles/gap.py

@@ -25,14 +25,15 @@ from bumble.core import Appearance
 from bumble.gatt import (
     TemplateService,
     Characteristic,
-    CharacteristicAdapter,
-    DelegatedCharacteristicAdapter,
-    UTF8CharacteristicAdapter,
     GATT_GENERIC_ACCESS_SERVICE,
     GATT_DEVICE_NAME_CHARACTERISTIC,
     GATT_APPEARANCE_CHARACTERISTIC,
 )
-from bumble.gatt_client import ProfileServiceProxy, ServiceProxy
+from bumble.gatt_adapters import (
+    DelegatedCharacteristicProxyAdapter,
+    UTF8CharacteristicProxyAdapter,
+)
+from bumble.gatt_client import CharacteristicProxy, ProfileServiceProxy, ServiceProxy
 
 # -----------------------------------------------------------------------------
 # Logging
@@ -49,6 +50,9 @@ logger = logging.getLogger(__name__)
 class GenericAccessService(TemplateService):
     UUID = GATT_GENERIC_ACCESS_SERVICE
 
+    device_name_characteristic: Characteristic[bytes]
+    appearance_characteristic: Characteristic[bytes]
+
     def __init__(
         self, device_name: str, appearance: Union[Appearance, Tuple[int, int], int] = 0
     ):
@@ -84,8 +88,8 @@ class GenericAccessService(TemplateService):
 class GenericAccessServiceProxy(ProfileServiceProxy):
     SERVICE_CLASS = GenericAccessService
 
-    device_name: Optional[CharacteristicAdapter]
-    appearance: Optional[DelegatedCharacteristicAdapter]
+    device_name: Optional[CharacteristicProxy[str]]
+    appearance: Optional[CharacteristicProxy[Appearance]]
 
     def __init__(self, service_proxy: ServiceProxy):
         self.service_proxy = service_proxy
@@ -93,14 +97,14 @@ class GenericAccessServiceProxy(ProfileServiceProxy):
         if characteristics := service_proxy.get_characteristics_by_uuid(
             GATT_DEVICE_NAME_CHARACTERISTIC
         ):
-            self.device_name = UTF8CharacteristicAdapter(characteristics[0])
+            self.device_name = UTF8CharacteristicProxyAdapter(characteristics[0])
         else:
             self.device_name = None
 
         if characteristics := service_proxy.get_characteristics_by_uuid(
             GATT_APPEARANCE_CHARACTERISTIC
         ):
-            self.appearance = DelegatedCharacteristicAdapter(
+            self.appearance = DelegatedCharacteristicProxyAdapter(
                 characteristics[0],
                 decode=lambda value: Appearance.from_int(
                     struct.unpack_from('<H', value, 0)[0],

bumble/profiles/gatt_service.py

@@ -0,0 +1,167 @@
+# Copyright 2021-2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import annotations
+
+import struct
+from typing import TYPE_CHECKING
+
+from bumble import att
+from bumble import gatt
+from bumble import gatt_client
+from bumble import crypto
+
+if TYPE_CHECKING:
+    from bumble import device
+
+
+# -----------------------------------------------------------------------------
+class GenericAttributeProfileService(gatt.TemplateService):
+    '''See Vol 3, Part G - 7 - DEFINED GENERIC ATTRIBUTE PROFILE SERVICE.'''
+
+    UUID = gatt.GATT_GENERIC_ATTRIBUTE_SERVICE
+
+    client_supported_features_characteristic: gatt.Characteristic | None = None
+    server_supported_features_characteristic: gatt.Characteristic | None = None
+    database_hash_characteristic: gatt.Characteristic | None = None
+    service_changed_characteristic: gatt.Characteristic | None = None
+
+    def __init__(
+        self,
+        server_supported_features: gatt.ServerSupportedFeatures | None = None,
+        database_hash_enabled: bool = True,
+        service_change_enabled: bool = True,
+    ) -> None:
+
+        if server_supported_features is not None:
+            self.server_supported_features_characteristic = gatt.Characteristic(
+                uuid=gatt.GATT_SERVER_SUPPORTED_FEATURES_CHARACTERISTIC,
+                properties=gatt.Characteristic.Properties.READ,
+                permissions=gatt.Characteristic.Permissions.READABLE,
+                value=bytes([server_supported_features]),
+            )
+
+        if database_hash_enabled:
+            self.database_hash_characteristic = gatt.Characteristic(
+                uuid=gatt.GATT_DATABASE_HASH_CHARACTERISTIC,
+                properties=gatt.Characteristic.Properties.READ,
+                permissions=gatt.Characteristic.Permissions.READABLE,
+                value=gatt.CharacteristicValue(read=self.get_database_hash),
+            )
+
+        if service_change_enabled:
+            self.service_changed_characteristic = gatt.Characteristic(
+                uuid=gatt.GATT_SERVICE_CHANGED_CHARACTERISTIC,
+                properties=gatt.Characteristic.Properties.INDICATE,
+                permissions=gatt.Characteristic.Permissions(0),
+                value=b'',
+            )
+
+        if (database_hash_enabled and service_change_enabled) or (
+            server_supported_features
+            and (
+                server_supported_features & gatt.ServerSupportedFeatures.EATT_SUPPORTED
+            )
+        ):  # TODO: Support Multiple Handle Value Notifications
+            self.client_supported_features_characteristic = gatt.Characteristic(
+                uuid=gatt.GATT_CLIENT_SUPPORTED_FEATURES_CHARACTERISTIC,
+                properties=(
+                    gatt.Characteristic.Properties.READ
+                    | gatt.Characteristic.Properties.WRITE
+                ),
+                permissions=(
+                    gatt.Characteristic.Permissions.READABLE
+                    | gatt.Characteristic.Permissions.WRITEABLE
+                ),
+                value=bytes(1),
+            )
+
+        super().__init__(
+            characteristics=[
+                c
+                for c in (
+                    self.service_changed_characteristic,
+                    self.client_supported_features_characteristic,
+                    self.database_hash_characteristic,
+                    self.server_supported_features_characteristic,
+                )
+                if c is not None
+            ],
+            primary=True,
+        )
+
+    @classmethod
+    def get_attribute_data(cls, attribute: att.Attribute) -> bytes:
+        if attribute.type in (
+            gatt.GATT_PRIMARY_SERVICE_ATTRIBUTE_TYPE,
+            gatt.GATT_SECONDARY_SERVICE_ATTRIBUTE_TYPE,
+            gatt.GATT_INCLUDE_ATTRIBUTE_TYPE,
+            gatt.GATT_CHARACTERISTIC_ATTRIBUTE_TYPE,
+            gatt.GATT_CHARACTERISTIC_EXTENDED_PROPERTIES_DESCRIPTOR,
+        ):
+            assert isinstance(attribute.value, bytes)
+            return (
+                struct.pack("<H", attribute.handle)
+                + attribute.type.to_bytes()
+                + attribute.value
+            )
+        elif attribute.type in (
+            gatt.GATT_CHARACTERISTIC_USER_DESCRIPTION_DESCRIPTOR,
+            gatt.GATT_CLIENT_CHARACTERISTIC_CONFIGURATION_DESCRIPTOR,
+            gatt.GATT_SERVER_CHARACTERISTIC_CONFIGURATION_DESCRIPTOR,
+            gatt.GATT_CHARACTERISTIC_PRESENTATION_FORMAT_DESCRIPTOR,
+            gatt.GATT_CHARACTERISTIC_AGGREGATE_FORMAT_DESCRIPTOR,
+        ):
+            return struct.pack("<H", attribute.handle) + attribute.type.to_bytes()
+
+        return b''
+
+    def get_database_hash(self, connection: device.Connection | None) -> bytes:
+        assert connection
+
+        m = b''.join(
+            [
+                self.get_attribute_data(attribute)
+                for attribute in connection.device.gatt_server.attributes
+            ]
+        )
+
+        return crypto.aes_cmac(m=m, k=bytes(16))
+
+
+class GenericAttributeProfileServiceProxy(gatt_client.ProfileServiceProxy):
+    SERVICE_CLASS = GenericAttributeProfileService
+
+    client_supported_features_characteristic: gatt_client.CharacteristicProxy | None = (
+        None
+    )
+    server_supported_features_characteristic: gatt_client.CharacteristicProxy | None = (
+        None
+    )
+    database_hash_characteristic: gatt_client.CharacteristicProxy | None = None
+    service_changed_characteristic: gatt_client.CharacteristicProxy | None = None
+
+    _CHARACTERISTICS = {
+        gatt.GATT_CLIENT_SUPPORTED_FEATURES_CHARACTERISTIC: 'client_supported_features_characteristic',
+        gatt.GATT_SERVER_SUPPORTED_FEATURES_CHARACTERISTIC: 'server_supported_features_characteristic',
+        gatt.GATT_DATABASE_HASH_CHARACTERISTIC: 'database_hash_characteristic',
+        gatt.GATT_SERVICE_CHANGED_CHARACTERISTIC: 'service_changed_characteristic',
+    }
+
+    def __init__(self, service_proxy: gatt_client.ServiceProxy) -> None:
+        self.service_proxy = service_proxy
+
+        for uuid, attribute_name in self._CHARACTERISTICS.items():
+            if characteristics := self.service_proxy.get_characteristics_by_uuid(uuid):
+                setattr(self, attribute_name, characteristics[0])

bumble/profiles/gmap.py

@@ -22,7 +22,6 @@ from typing import Optional
 
 from bumble.gatt import (
     TemplateService,
-    DelegatedCharacteristicAdapter,
     Characteristic,
     GATT_GAMING_AUDIO_SERVICE,
     GATT_GMAP_ROLE_CHARACTERISTIC,
@@ -30,9 +29,9 @@ from bumble.gatt import (
     GATT_UGT_FEATURES_CHARACTERISTIC,
     GATT_BGS_FEATURES_CHARACTERISTIC,
     GATT_BGR_FEATURES_CHARACTERISTIC,
-    InvalidServiceError,
 )
-from bumble.gatt_client import ProfileServiceProxy, ServiceProxy
+from bumble.gatt_adapters import DelegatedCharacteristicProxyAdapter
+from bumble.gatt_client import CharacteristicProxy, ProfileServiceProxy, ServiceProxy
 from enum import IntFlag
 
 
@@ -151,48 +150,49 @@ class GamingAudioService(TemplateService):
 class GamingAudioServiceProxy(ProfileServiceProxy):
     SERVICE_CLASS = GamingAudioService
 
+    ugg_features: Optional[CharacteristicProxy[UggFeatures]] = None
+    ugt_features: Optional[CharacteristicProxy[UgtFeatures]] = None
+    bgs_features: Optional[CharacteristicProxy[BgsFeatures]] = None
+    bgr_features: Optional[CharacteristicProxy[BgrFeatures]] = None
+
     def __init__(self, service_proxy: ServiceProxy) -> None:
         self.service_proxy = service_proxy
 
-        if not (
-            characteristics := service_proxy.get_characteristics_by_uuid(
+        self.gmap_role = DelegatedCharacteristicProxyAdapter(
+            service_proxy.get_required_characteristic_by_uuid(
                 GATT_GMAP_ROLE_CHARACTERISTIC
-            )
-        ):
-            raise InvalidServiceError("GMAP Role Characteristic not found")
-        self.gmap_role = DelegatedCharacteristicAdapter(
-            characteristic=characteristics[0],
+            ),
             decode=lambda value: GmapRole(value[0]),
         )
 
         if characteristics := service_proxy.get_characteristics_by_uuid(
             GATT_UGG_FEATURES_CHARACTERISTIC
         ):
-            self.ugg_features = DelegatedCharacteristicAdapter(
-                characteristic=characteristics[0],
+            self.ugg_features = DelegatedCharacteristicProxyAdapter(
+                characteristics[0],
                 decode=lambda value: UggFeatures(value[0]),
             )
 
         if characteristics := service_proxy.get_characteristics_by_uuid(
             GATT_UGT_FEATURES_CHARACTERISTIC
         ):
-            self.ugt_features = DelegatedCharacteristicAdapter(
-                characteristic=characteristics[0],
+            self.ugt_features = DelegatedCharacteristicProxyAdapter(
+                characteristics[0],
                 decode=lambda value: UgtFeatures(value[0]),
             )
 
         if characteristics := service_proxy.get_characteristics_by_uuid(
             GATT_BGS_FEATURES_CHARACTERISTIC
         ):
-            self.bgs_features = DelegatedCharacteristicAdapter(
-                characteristic=characteristics[0],
+            self.bgs_features = DelegatedCharacteristicProxyAdapter(
+                characteristics[0],
                 decode=lambda value: BgsFeatures(value[0]),
             )
 
         if characteristics := service_proxy.get_characteristics_by_uuid(
             GATT_BGR_FEATURES_CHARACTERISTIC
         ):
-            self.bgr_features = DelegatedCharacteristicAdapter(
-                characteristic=characteristics[0],
+            self.bgr_features = DelegatedCharacteristicProxyAdapter(
+                characteristics[0],
                 decode=lambda value: BgrFeatures(value[0]),
             )

bumble/profiles/hap.py

@@ -18,14 +18,15 @@
 from __future__ import annotations
 import asyncio
 import functools
-from bumble import att, gatt, gatt_client
+from dataclasses import dataclass, field
+import logging
+from typing import Any, Dict, List, Optional, Set, Union
+
+from bumble import att, gatt, gatt_adapters, gatt_client
 from bumble.core import InvalidArgumentError, InvalidStateError
 from bumble.device import Device, Connection
 from bumble.utils import AsyncRunner, OpenIntEnum
 from bumble.hci import Address
-from dataclasses import dataclass, field
-import logging
-from typing import Any, Dict, List, Optional, Set, Union
 
 
 # -----------------------------------------------------------------------------
@@ -631,11 +632,12 @@ class HearingAccessServiceProxy(gatt_client.ProfileServiceProxy):
 
     hearing_aid_preset_control_point: gatt_client.CharacteristicProxy
     preset_control_point_indications: asyncio.Queue
+    active_preset_index_notification: asyncio.Queue
 
     def __init__(self, service_proxy: gatt_client.ServiceProxy) -> None:
         self.service_proxy = service_proxy
 
-        self.server_features = gatt.PackedCharacteristicAdapter(
+        self.server_features = gatt_adapters.PackedCharacteristicProxyAdapter(
             service_proxy.get_characteristics_by_uuid(
                 gatt.GATT_HEARING_AID_FEATURES_CHARACTERISTIC
             )[0],
@@ -648,7 +650,7 @@ class HearingAccessServiceProxy(gatt_client.ProfileServiceProxy):
             )[0]
         )
 
-        self.active_preset_index = gatt.PackedCharacteristicAdapter(
+        self.active_preset_index = gatt_adapters.PackedCharacteristicProxyAdapter(
             service_proxy.get_characteristics_by_uuid(
                 gatt.GATT_ACTIVE_PRESET_INDEX_CHARACTERISTIC
             )[0],

bumble/profiles/heart_rate_service.py

@@ -16,13 +16,14 @@
 # -----------------------------------------------------------------------------
 # Imports
 # -----------------------------------------------------------------------------
+from __future__ import annotations
 from enum import IntEnum
 import struct
+from typing import Optional
 
 from bumble import core
-from ..gatt_client import ProfileServiceProxy
-from ..att import ATT_Error
-from ..gatt import (
+from bumble.att import ATT_Error
+from bumble.gatt import (
     GATT_HEART_RATE_SERVICE,
     GATT_HEART_RATE_MEASUREMENT_CHARACTERISTIC,
     GATT_BODY_SENSOR_LOCATION_CHARACTERISTIC,
@@ -30,10 +31,13 @@ from ..gatt import (
     TemplateService,
     Characteristic,
     CharacteristicValue,
-    SerializableCharacteristicAdapter,
+)
+from bumble.gatt_adapters import (
     DelegatedCharacteristicAdapter,
     PackedCharacteristicAdapter,
+    SerializableCharacteristicAdapter,
 )
+from bumble.gatt_client import CharacteristicProxy, ProfileServiceProxy
 
 
 # -----------------------------------------------------------------------------
@@ -43,6 +47,10 @@ class HeartRateService(TemplateService):
     CONTROL_POINT_NOT_SUPPORTED = 0x80
     RESET_ENERGY_EXPENDED = 0x01
 
+    heart_rate_measurement_characteristic: Characteristic[HeartRateMeasurement]
+    body_sensor_location_characteristic: Characteristic[BodySensorLocation]
+    heart_rate_control_point_characteristic: Characteristic[int]
+
     class BodySensorLocation(IntEnum):
         OTHER = 0
         CHEST = 1
@@ -198,6 +206,14 @@ class HeartRateService(TemplateService):
 class HeartRateServiceProxy(ProfileServiceProxy):
     SERVICE_CLASS = HeartRateService
 
+    heart_rate_measurement: Optional[
+        CharacteristicProxy[HeartRateService.HeartRateMeasurement]
+    ]
+    body_sensor_location: Optional[
+        CharacteristicProxy[HeartRateService.BodySensorLocation]
+    ]
+    heart_rate_control_point: Optional[CharacteristicProxy[int]]
+
     def __init__(self, service_proxy):
         self.service_proxy = service_proxy
 

bumble/profiles/le_audio.py

@@ -17,23 +17,35 @@
 # -----------------------------------------------------------------------------
 from __future__ import annotations
 import dataclasses
+import enum
 import struct
-from typing import List, Type
+from typing import Any, List, Type
 from typing_extensions import Self
 
+from bumble.profiles import bap
 from bumble import utils
 
 
 # -----------------------------------------------------------------------------
 # Classes
 # -----------------------------------------------------------------------------
+class AudioActiveState(utils.OpenIntEnum):
+    NO_AUDIO_DATA_TRANSMITTED = 0x00
+    AUDIO_DATA_TRANSMITTED = 0x01
+
+
+class AssistedListeningStream(utils.OpenIntEnum):
+    UNSPECIFIED_AUDIO_ENHANCEMENT = 0x00
+
+
 @dataclasses.dataclass
 class Metadata:
     '''Bluetooth Assigned Numbers, Section 6.12.6 - Metadata LTV structures.
 
-    As Metadata fields may extend, and Spec doesn't forbid duplication, we don't parse
-    Metadata into a key-value style dataclass here. Rather, we encourage users to parse
-    again outside the lib.
+    As Metadata fields may extend, and the spec may not guarantee the uniqueness of
+    tags, we don't automatically parse the Metadata data into specific classes.
+    Users of this class may decode the data by themselves, or use the Entry.decode
+    method.
     '''
 
     class Tag(utils.OpenIntEnum):
@@ -57,6 +69,44 @@ class Metadata:
         tag: Metadata.Tag
         data: bytes
 
+        def decode(self) -> Any:
+            """
+            Decode the data into an object, if possible.
+
+            If no specific object class exists to represent the data, the raw data
+            bytes are returned.
+            """
+
+            if self.tag in (
+                Metadata.Tag.PREFERRED_AUDIO_CONTEXTS,
+                Metadata.Tag.STREAMING_AUDIO_CONTEXTS,
+            ):
+                return bap.ContextType(struct.unpack("<H", self.data)[0])
+
+            if self.tag in (
+                Metadata.Tag.PROGRAM_INFO,
+                Metadata.Tag.PROGRAM_INFO_URI,
+                Metadata.Tag.BROADCAST_NAME,
+            ):
+                return self.data.decode("utf-8")
+
+            if self.tag == Metadata.Tag.LANGUAGE:
+                return self.data.decode("ascii")
+
+            if self.tag == Metadata.Tag.CCID_LIST:
+                return list(self.data)
+
+            if self.tag == Metadata.Tag.PARENTAL_RATING:
+                return self.data[0]
+
+            if self.tag == Metadata.Tag.AUDIO_ACTIVE_STATE:
+                return AudioActiveState(self.data[0])
+
+            if self.tag == Metadata.Tag.ASSISTED_LISTENING_STREAM:
+                return AssistedListeningStream(self.data[0])
+
+            return self.data
+
         @classmethod
         def from_bytes(cls: Type[Self], data: bytes) -> Self:
             return cls(tag=Metadata.Tag(data[0]), data=data[1:])
@@ -66,6 +116,29 @@ class Metadata:
 
     entries: List[Entry] = dataclasses.field(default_factory=list)
 
+    def pretty_print(self, indent: str) -> str:
+        """Convenience method to generate a string with one key-value pair per line."""
+
+        max_key_length = 0
+        keys = []
+        values = []
+        for entry in self.entries:
+            key = entry.tag.name
+            max_key_length = max(max_key_length, len(key))
+            keys.append(key)
+            decoded = entry.decode()
+            if isinstance(decoded, enum.Enum):
+                values.append(decoded.name)
+            elif isinstance(decoded, bytes):
+                values.append(decoded.hex())
+            else:
+                values.append(str(decoded))
+
+        return '\n'.join(
+            f'{indent}{key}: {" " * (max_key_length-len(key))}{value}'
+            for key, value in zip(keys, values)
+        )
+
     @classmethod
     def from_bytes(cls: Type[Self], data: bytes) -> Self:
         entries = []
@@ -81,3 +154,13 @@ class Metadata:
 
     def __bytes__(self) -> bytes:
         return b''.join([bytes(entry) for entry in self.entries])
+
+    def __str__(self) -> str:
+        entries_str = []
+        for entry in self.entries:
+            decoded = entry.decode()
+            entries_str.append(
+                f'{entry.tag.name}: '
+                f'{decoded.hex() if isinstance(decoded, bytes) else decoded!r}'
+            )
+        return f'Metadata(entries={", ".join(entry_str for entry_str in entries_str)})'

bumble/profiles/mcp.py

@@ -208,7 +208,7 @@ class MediaControlService(gatt.TemplateService):
             properties=gatt.Characteristic.Properties.READ
             | gatt.Characteristic.Properties.NOTIFY,
             permissions=gatt.Characteristic.Permissions.READ_REQUIRES_ENCRYPTION,
-            value=media_player_name or 'Bumble Player',
+            value=(media_player_name or 'Bumble Player').encode(),
         )
         self.track_changed_characteristic = gatt.Characteristic(
             uuid=gatt.GATT_TRACK_CHANGED_CHARACTERISTIC,
@@ -247,14 +247,16 @@ class MediaControlService(gatt.TemplateService):
             permissions=gatt.Characteristic.Permissions.READ_REQUIRES_ENCRYPTION,
             value=b'',
         )
-        self.media_control_point_characteristic = gatt.Characteristic(
-            uuid=gatt.GATT_MEDIA_CONTROL_POINT_CHARACTERISTIC,
-            properties=gatt.Characteristic.Properties.WRITE
-            | gatt.Characteristic.Properties.WRITE_WITHOUT_RESPONSE
-            | gatt.Characteristic.Properties.NOTIFY,
-            permissions=gatt.Characteristic.Permissions.READ_REQUIRES_ENCRYPTION
-            | gatt.Characteristic.Permissions.WRITE_REQUIRES_ENCRYPTION,
-            value=gatt.CharacteristicValue(write=self.on_media_control_point),
+        self.media_control_point_characteristic: gatt.Characteristic[bytes] = (
+            gatt.Characteristic(
+                uuid=gatt.GATT_MEDIA_CONTROL_POINT_CHARACTERISTIC,
+                properties=gatt.Characteristic.Properties.WRITE
+                | gatt.Characteristic.Properties.WRITE_WITHOUT_RESPONSE
+                | gatt.Characteristic.Properties.NOTIFY,
+                permissions=gatt.Characteristic.Permissions.READ_REQUIRES_ENCRYPTION
+                | gatt.Characteristic.Permissions.WRITE_REQUIRES_ENCRYPTION,
+                value=gatt.CharacteristicValue(write=self.on_media_control_point),
+            )
         )
         self.media_control_point_opcodes_supported_characteristic = gatt.Characteristic(
             uuid=gatt.GATT_MEDIA_CONTROL_POINT_OPCODES_SUPPORTED_CHARACTERISTIC,

bumble/profiles/pacs.py

@@ -25,6 +25,7 @@ from typing import Optional, Sequence, Union
 from bumble.profiles.bap import AudioLocation, CodecSpecificCapabilities, ContextType
 from bumble.profiles import le_audio
 from bumble import gatt
+from bumble import gatt_adapters
 from bumble import gatt_client
 from bumble import hci
 
@@ -72,6 +73,19 @@ class PacRecord:
             metadata=metadata,
         )
 
+    @classmethod
+    def list_from_bytes(cls, data: bytes) -> list[PacRecord]:
+        """Parse a serialized list of records preceded by a one byte list length."""
+        record_count = data[0]
+        records = []
+        offset = 1
+        for _ in range(record_count):
+            record = PacRecord.from_bytes(data[offset:])
+            offset += len(bytes(record))
+            records.append(record)
+
+        return records
+
     def __bytes__(self) -> bytes:
         capabilities_bytes = bytes(self.codec_specific_capabilities)
         metadata_bytes = bytes(self.metadata)
@@ -172,39 +186,70 @@ class PublishedAudioCapabilitiesService(gatt.TemplateService):
 class PublishedAudioCapabilitiesServiceProxy(gatt_client.ProfileServiceProxy):
     SERVICE_CLASS = PublishedAudioCapabilitiesService
 
-    sink_pac: Optional[gatt_client.CharacteristicProxy] = None
-    sink_audio_locations: Optional[gatt_client.CharacteristicProxy] = None
-    source_pac: Optional[gatt_client.CharacteristicProxy] = None
-    source_audio_locations: Optional[gatt_client.CharacteristicProxy] = None
-    available_audio_contexts: gatt_client.CharacteristicProxy
-    supported_audio_contexts: gatt_client.CharacteristicProxy
+    sink_pac: Optional[gatt_client.CharacteristicProxy[list[PacRecord]]] = None
+    sink_audio_locations: Optional[gatt_client.CharacteristicProxy[AudioLocation]] = (
+        None
+    )
+    source_pac: Optional[gatt_client.CharacteristicProxy[list[PacRecord]]] = None
+    source_audio_locations: Optional[gatt_client.CharacteristicProxy[AudioLocation]] = (
+        None
+    )
+    available_audio_contexts: gatt_client.CharacteristicProxy[tuple[ContextType, ...]]
+    supported_audio_contexts: gatt_client.CharacteristicProxy[tuple[ContextType, ...]]
 
     def __init__(self, service_proxy: gatt_client.ServiceProxy):
         self.service_proxy = service_proxy
 
-        self.available_audio_contexts = service_proxy.get_characteristics_by_uuid(
-            gatt.GATT_AVAILABLE_AUDIO_CONTEXTS_CHARACTERISTIC
-        )[0]
-        self.supported_audio_contexts = service_proxy.get_characteristics_by_uuid(
-            gatt.GATT_SUPPORTED_AUDIO_CONTEXTS_CHARACTERISTIC
-        )[0]
+        self.available_audio_contexts = (
+            gatt_adapters.DelegatedCharacteristicProxyAdapter(
+                service_proxy.get_required_characteristic_by_uuid(
+                    gatt.GATT_AVAILABLE_AUDIO_CONTEXTS_CHARACTERISTIC
+                ),
+                decode=lambda x: tuple(map(ContextType, struct.unpack('<HH', x))),
+            )
+        )
+
+        self.supported_audio_contexts = (
+            gatt_adapters.DelegatedCharacteristicProxyAdapter(
+                service_proxy.get_required_characteristic_by_uuid(
+                    gatt.GATT_SUPPORTED_AUDIO_CONTEXTS_CHARACTERISTIC
+                ),
+                decode=lambda x: tuple(map(ContextType, struct.unpack('<HH', x))),
+            )
+        )
 
         if characteristics := service_proxy.get_characteristics_by_uuid(
             gatt.GATT_SINK_PAC_CHARACTERISTIC
         ):
-            self.sink_pac = characteristics[0]
+            self.sink_pac = gatt_adapters.DelegatedCharacteristicProxyAdapter(
+                characteristics[0],
+                decode=PacRecord.list_from_bytes,
+            )
 
         if characteristics := service_proxy.get_characteristics_by_uuid(
             gatt.GATT_SOURCE_PAC_CHARACTERISTIC
         ):
-            self.source_pac = characteristics[0]
+            self.source_pac = gatt_adapters.DelegatedCharacteristicProxyAdapter(
+                characteristics[0],
+                decode=PacRecord.list_from_bytes,
+            )
 
         if characteristics := service_proxy.get_characteristics_by_uuid(
             gatt.GATT_SINK_AUDIO_LOCATION_CHARACTERISTIC
         ):
-            self.sink_audio_locations = characteristics[0]
+            self.sink_audio_locations = (
+                gatt_adapters.DelegatedCharacteristicProxyAdapter(
+                    characteristics[0],
+                    decode=lambda x: AudioLocation(struct.unpack('<I', x)[0]),
+                )
+            )
 
         if characteristics := service_proxy.get_characteristics_by_uuid(
             gatt.GATT_SOURCE_AUDIO_LOCATION_CHARACTERISTIC
         ):
-            self.source_audio_locations = characteristics[0]
+            self.source_audio_locations = (
+                gatt_adapters.DelegatedCharacteristicProxyAdapter(
+                    characteristics[0],
+                    decode=lambda x: AudioLocation(struct.unpack('<I', x)[0]),
+                )
+            )

bumble/profiles/tmap.py

@@ -24,12 +24,11 @@ import struct
 from bumble.gatt import (
     TemplateService,
     Characteristic,
-    DelegatedCharacteristicAdapter,
-    InvalidServiceError,
     GATT_TELEPHONY_AND_MEDIA_AUDIO_SERVICE,
     GATT_TMAP_ROLE_CHARACTERISTIC,
 )
-from bumble.gatt_client import ProfileServiceProxy, ServiceProxy
+from bumble.gatt_adapters import DelegatedCharacteristicProxyAdapter
+from bumble.gatt_client import CharacteristicProxy, ProfileServiceProxy, ServiceProxy
 
 
 # -----------------------------------------------------------------------------
@@ -54,6 +53,8 @@ class Role(enum.IntFlag):
 class TelephonyAndMediaAudioService(TemplateService):
     UUID = GATT_TELEPHONY_AND_MEDIA_AUDIO_SERVICE
 
+    role_characteristic: Characteristic[bytes]
+
     def __init__(self, role: Role):
         self.role_characteristic = Characteristic(
             GATT_TMAP_ROLE_CHARACTERISTIC,
@@ -69,20 +70,15 @@ class TelephonyAndMediaAudioService(TemplateService):
 class TelephonyAndMediaAudioServiceProxy(ProfileServiceProxy):
     SERVICE_CLASS = TelephonyAndMediaAudioService
 
-    role: DelegatedCharacteristicAdapter
+    role: CharacteristicProxy[Role]
 
     def __init__(self, service_proxy: ServiceProxy):
         self.service_proxy = service_proxy
 
-        if not (
-            characteristics := service_proxy.get_characteristics_by_uuid(
+        self.role = DelegatedCharacteristicProxyAdapter(
+            service_proxy.get_required_characteristic_by_uuid(
                 GATT_TMAP_ROLE_CHARACTERISTIC
-            )
-        ):
-            raise InvalidServiceError('TMAP Role characteristic not found')
-
-        self.role = DelegatedCharacteristicAdapter(
-            characteristics[0],
+            ),
             decode=lambda value: Role(
                 struct.unpack_from('<H', value, 0)[0],
             ),

bumble/profiles/vcs.py

@@ -1,4 +1,4 @@
-# Copyright 2021-2024 Google LLC
+# Copyright 2021-2025 Google LLC
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -17,14 +17,17 @@
 # Imports
 # -----------------------------------------------------------------------------
 from __future__ import annotations
+import dataclasses
 import enum
 
+from typing import Optional, Sequence
+
 from bumble import att
 from bumble import device
 from bumble import gatt
+from bumble import gatt_adapters
 from bumble import gatt_client
 
-from typing import Optional, Sequence
 
 # -----------------------------------------------------------------------------
 # Constants
@@ -67,6 +70,20 @@ class VolumeControlPointOpcode(enum.IntEnum):
     MUTE                        = 0x06
 
 
+@dataclasses.dataclass
+class VolumeState:
+    volume_setting: int
+    mute: int
+    change_counter: int
+
+    @classmethod
+    def from_bytes(cls, data: bytes) -> VolumeState:
+        return cls(data[0], data[1], data[2])
+
+    def __bytes__(self) -> bytes:
+        return bytes([self.volume_setting, self.mute, self.change_counter])
+
+
 # -----------------------------------------------------------------------------
 # Server
 # -----------------------------------------------------------------------------
@@ -126,16 +143,8 @@ class VolumeControlService(gatt.TemplateService):
             included_services=list(included_services),
         )
 
-    @property
-    def volume_state_bytes(self) -> bytes:
-        return bytes([self.volume_setting, self.muted, self.change_counter])
-
-    @volume_state_bytes.setter
-    def volume_state_bytes(self, new_value: bytes) -> None:
-        self.volume_setting, self.muted, self.change_counter = new_value
-
     def _on_read_volume_state(self, _connection: Optional[device.Connection]) -> bytes:
-        return self.volume_state_bytes
+        return bytes(VolumeState(self.volume_setting, self.muted, self.change_counter))
 
     def _on_write_volume_control_point(
         self, connection: Optional[device.Connection], value: bytes
@@ -153,14 +162,9 @@ class VolumeControlService(gatt.TemplateService):
             self.change_counter = (self.change_counter + 1) % 256
             connection.abort_on(
                 'disconnection',
-                connection.device.notify_subscribers(
-                    attribute=self.volume_state,
-                    value=self.volume_state_bytes,
-                ),
-            )
-            self.emit(
-                'volume_state', self.volume_setting, self.muted, self.change_counter
+                connection.device.notify_subscribers(attribute=self.volume_state),
             )
+            self.emit('volume_state_change')
 
     def _on_relative_volume_down(self) -> bool:
         old_volume = self.volume_setting
@@ -206,25 +210,27 @@ class VolumeControlService(gatt.TemplateService):
 class VolumeControlServiceProxy(gatt_client.ProfileServiceProxy):
     SERVICE_CLASS = VolumeControlService
 
-    volume_control_point: gatt_client.CharacteristicProxy
+    volume_control_point: gatt_client.CharacteristicProxy[bytes]
+    volume_state: gatt_client.CharacteristicProxy[VolumeState]
+    volume_flags: gatt_client.CharacteristicProxy[VolumeFlags]
 
     def __init__(self, service_proxy: gatt_client.ServiceProxy) -> None:
         self.service_proxy = service_proxy
 
-        self.volume_state = gatt.PackedCharacteristicAdapter(
-            service_proxy.get_characteristics_by_uuid(
+        self.volume_state = gatt_adapters.SerializableCharacteristicProxyAdapter(
+            service_proxy.get_required_characteristic_by_uuid(
                 gatt.GATT_VOLUME_STATE_CHARACTERISTIC
-            )[0],
-            'BBB',
+            ),
+            VolumeState,
         )
 
-        self.volume_control_point = service_proxy.get_characteristics_by_uuid(
+        self.volume_control_point = service_proxy.get_required_characteristic_by_uuid(
             gatt.GATT_VOLUME_CONTROL_POINT_CHARACTERISTIC
-        )[0]
-
-        self.volume_flags = gatt.PackedCharacteristicAdapter(
-            service_proxy.get_characteristics_by_uuid(
-                gatt.GATT_VOLUME_FLAGS_CHARACTERISTIC
-            )[0],
-            'B',
+        )
+
+        self.volume_flags = gatt_adapters.DelegatedCharacteristicProxyAdapter(
+            service_proxy.get_required_characteristic_by_uuid(
+                gatt.GATT_VOLUME_FLAGS_CHARACTERISTIC
+            ),
+            decode=lambda data: VolumeFlags(data[0]),
         )

bumble/profiles/vocs.py

@@ -24,17 +24,19 @@ from bumble.device import Connection
 from bumble.att import ATT_Error
 from bumble.gatt import (
     Characteristic,
-    DelegatedCharacteristicAdapter,
     TemplateService,
     CharacteristicValue,
-    UTF8CharacteristicAdapter,
-    InvalidServiceError,
     GATT_VOLUME_OFFSET_CONTROL_SERVICE,
     GATT_VOLUME_OFFSET_STATE_CHARACTERISTIC,
     GATT_AUDIO_LOCATION_CHARACTERISTIC,
     GATT_VOLUME_OFFSET_CONTROL_POINT_CHARACTERISTIC,
     GATT_AUDIO_OUTPUT_DESCRIPTION_CHARACTERISTIC,
 )
+from bumble.gatt_adapters import (
+    DelegatedCharacteristicProxyAdapter,
+    SerializableCharacteristicProxyAdapter,
+    UTF8CharacteristicProxyAdapter,
+)
 from bumble.gatt_client import ProfileServiceProxy, ServiceProxy
 from bumble.utils import OpenIntEnum
 from bumble.profiles.bap import AudioLocation
@@ -67,7 +69,7 @@ class ErrorCode(OpenIntEnum):
 class VolumeOffsetState:
     volume_offset: int = 0
     change_counter: int = 0
-    attribute_value: Optional[CharacteristicValue] = None
+    attribute: Optional[Characteristic] = None
 
     def __bytes__(self) -> bytes:
         return struct.pack('<hB', self.volume_offset, self.change_counter)
@@ -81,10 +83,8 @@ class VolumeOffsetState:
         self.change_counter = (self.change_counter + 1) % (CHANGE_COUNTER_MAX_VALUE + 1)
 
     async def notify_subscribers_via_connection(self, connection: Connection) -> None:
-        assert self.attribute_value is not None
-        await connection.device.notify_subscribers(
-            attribute=self.attribute_value, value=bytes(self)
-        )
+        assert self.attribute is not None
+        await connection.device.notify_subscribers(attribute=self.attribute)
 
     def on_read(self, _connection: Optional[Connection]) -> bytes:
         return bytes(self)
@@ -93,7 +93,7 @@ class VolumeOffsetState:
 @dataclass
 class VocsAudioLocation:
     audio_location: AudioLocation = AudioLocation.NOT_ALLOWED
-    attribute_value: Optional[CharacteristicValue] = None
+    attribute: Optional[Characteristic] = None
 
     def __bytes__(self) -> bytes:
         return struct.pack('<I', self.audio_location)
@@ -108,12 +108,10 @@ class VocsAudioLocation:
 
     async def on_write(self, connection: Optional[Connection], value: bytes) -> None:
         assert connection
-        assert self.attribute_value
+        assert self.attribute
 
         self.audio_location = AudioLocation(int.from_bytes(value, 'little'))
-        await connection.device.notify_subscribers(
-            attribute=self.attribute_value, value=value
-        )
+        await connection.device.notify_subscribers(attribute=self.attribute)
 
 
 @dataclass
@@ -152,7 +150,7 @@ class VolumeOffsetControlPoint:
 @dataclass
 class AudioOutputDescription:
     audio_output_description: str = ''
-    attribute_value: Optional[CharacteristicValue] = None
+    attribute: Optional[Characteristic] = None
 
     @classmethod
     def from_bytes(cls, data: bytes):
@@ -166,12 +164,10 @@ class AudioOutputDescription:
 
     async def on_write(self, connection: Optional[Connection], value: bytes) -> None:
         assert connection
-        assert self.attribute_value
+        assert self.attribute
 
         self.audio_output_description = value.decode('utf-8')
-        await connection.device.notify_subscribers(
-            attribute=self.attribute_value, value=value
-        )
+        await connection.device.notify_subscribers(attribute=self.attribute)
 
 
 # -----------------------------------------------------------------------------
@@ -203,48 +199,45 @@ class VolumeOffsetControlService(TemplateService):
             VolumeOffsetControlPoint(self.volume_offset_state)
         )
 
-        self.volume_offset_state_characteristic = DelegatedCharacteristicAdapter(
-            Characteristic(
-                uuid=GATT_VOLUME_OFFSET_STATE_CHARACTERISTIC,
-                properties=(
-                    Characteristic.Properties.READ | Characteristic.Properties.NOTIFY
-                ),
-                permissions=Characteristic.Permissions.READ_REQUIRES_ENCRYPTION,
-                value=CharacteristicValue(read=self.volume_offset_state.on_read),
+        self.volume_offset_state_characteristic: Characteristic[bytes] = Characteristic(
+            uuid=GATT_VOLUME_OFFSET_STATE_CHARACTERISTIC,
+            properties=(
+                Characteristic.Properties.READ | Characteristic.Properties.NOTIFY
             ),
-            encode=lambda value: bytes(value),
+            permissions=Characteristic.Permissions.READ_REQUIRES_ENCRYPTION,
+            value=CharacteristicValue(read=self.volume_offset_state.on_read),
         )
 
-        self.audio_location_characteristic = DelegatedCharacteristicAdapter(
+        self.audio_location_characteristic: Characteristic[bytes] = Characteristic(
+            uuid=GATT_AUDIO_LOCATION_CHARACTERISTIC,
+            properties=(
+                Characteristic.Properties.READ
+                | Characteristic.Properties.NOTIFY
+                | Characteristic.Properties.WRITE_WITHOUT_RESPONSE
+            ),
+            permissions=(
+                Characteristic.Permissions.READ_REQUIRES_ENCRYPTION
+                | Characteristic.Permissions.WRITE_REQUIRES_ENCRYPTION
+            ),
+            value=CharacteristicValue(
+                read=self.audio_location.on_read,
+                write=self.audio_location.on_write,
+            ),
+        )
+        self.audio_location.attribute = self.audio_location_characteristic
+
+        self.volume_offset_control_point_characteristic: Characteristic[bytes] = (
             Characteristic(
-                uuid=GATT_AUDIO_LOCATION_CHARACTERISTIC,
-                properties=(
-                    Characteristic.Properties.READ
-                    | Characteristic.Properties.NOTIFY
-                    | Characteristic.Properties.WRITE_WITHOUT_RESPONSE
-                ),
-                permissions=(
-                    Characteristic.Permissions.READ_REQUIRES_ENCRYPTION
-                    | Characteristic.Permissions.WRITE_REQUIRES_ENCRYPTION
-                ),
+                uuid=GATT_VOLUME_OFFSET_CONTROL_POINT_CHARACTERISTIC,
+                properties=Characteristic.Properties.WRITE,
+                permissions=Characteristic.Permissions.WRITE_REQUIRES_ENCRYPTION,
                 value=CharacteristicValue(
-                    read=self.audio_location.on_read,
-                    write=self.audio_location.on_write,
+                    write=self.volume_offset_control_point.on_write
                 ),
-            ),
-            encode=lambda value: bytes(value),
-            decode=VocsAudioLocation.from_bytes,
-        )
-        self.audio_location.attribute_value = self.audio_location_characteristic.value
-
-        self.volume_offset_control_point_characteristic = Characteristic(
-            uuid=GATT_VOLUME_OFFSET_CONTROL_POINT_CHARACTERISTIC,
-            properties=Characteristic.Properties.WRITE,
-            permissions=Characteristic.Permissions.WRITE_REQUIRES_ENCRYPTION,
-            value=CharacteristicValue(write=self.volume_offset_control_point.on_write),
+            )
         )
 
-        self.audio_output_description_characteristic = DelegatedCharacteristicAdapter(
+        self.audio_output_description_characteristic: Characteristic[bytes] = (
             Characteristic(
                 uuid=GATT_AUDIO_OUTPUT_DESCRIPTION_CHARACTERISTIC,
                 properties=(
@@ -262,9 +255,8 @@ class VolumeOffsetControlService(TemplateService):
                 ),
             )
         )
-
-        self.audio_output_description.attribute_value = (
-            self.audio_output_description_characteristic.value
+        self.audio_output_description.attribute = (
+            self.audio_output_description_characteristic
         )
 
         super().__init__(
@@ -287,44 +279,29 @@ class VolumeOffsetControlServiceProxy(ProfileServiceProxy):
     def __init__(self, service_proxy: ServiceProxy) -> None:
         self.service_proxy = service_proxy
 
-        if not (
-            characteristics := service_proxy.get_characteristics_by_uuid(
+        self.volume_offset_state = SerializableCharacteristicProxyAdapter(
+            service_proxy.get_required_characteristic_by_uuid(
                 GATT_VOLUME_OFFSET_STATE_CHARACTERISTIC
-            )
-        ):
-            raise InvalidServiceError("Volume Offset State characteristic not found")
-        self.volume_offset_state = DelegatedCharacteristicAdapter(
-            characteristics[0], decode=VolumeOffsetState.from_bytes
+            ),
+            VolumeOffsetState,
         )
 
-        if not (
-            characteristics := service_proxy.get_characteristics_by_uuid(
+        self.audio_location = DelegatedCharacteristicProxyAdapter(
+            service_proxy.get_required_characteristic_by_uuid(
                 GATT_AUDIO_LOCATION_CHARACTERISTIC
-            )
-        ):
-            raise InvalidServiceError("Audio Location characteristic not found")
-        self.audio_location = DelegatedCharacteristicAdapter(
-            characteristics[0],
-            encode=lambda value: bytes(value),
-            decode=VocsAudioLocation.from_bytes,
+            ),
+            encode=lambda value: bytes([int(value)]),
+            decode=lambda data: AudioLocation(data[0]),
         )
 
-        if not (
-            characteristics := service_proxy.get_characteristics_by_uuid(
+        self.volume_offset_control_point = (
+            service_proxy.get_required_characteristic_by_uuid(
                 GATT_VOLUME_OFFSET_CONTROL_POINT_CHARACTERISTIC
             )
-        ):
-            raise InvalidServiceError(
-                "Volume Offset Control Point characteristic not found"
-            )
-        self.volume_offset_control_point = characteristics[0]
+        )
 
-        if not (
-            characteristics := service_proxy.get_characteristics_by_uuid(
+        self.audio_output_description = UTF8CharacteristicProxyAdapter(
+            service_proxy.get_required_characteristic_by_uuid(
                 GATT_AUDIO_OUTPUT_DESCRIPTION_CHARACTERISTIC
             )
-        ):
-            raise InvalidServiceError(
-                "Audio Output Description characteristic not found"
-            )
-        self.audio_output_description = UTF8CharacteristicAdapter(characteristics[0])
+        )

bumble/sdp.py

@@ -16,15 +16,21 @@
 # Imports
 # -----------------------------------------------------------------------------
 from __future__ import annotations
+import asyncio
 import logging
 import struct
-from typing import Dict, List, Type, Optional, Tuple, Union, NewType, TYPE_CHECKING
+from typing import Iterable, NewType, Optional, Union, Sequence, Type, TYPE_CHECKING
 from typing_extensions import Self
 
-from . import core, l2cap
-from .colors import color
-from .core import InvalidStateError, InvalidArgumentError, InvalidPacketError
-from .hci import HCI_Object, name_or_number, key_with_value
+from bumble import core, l2cap
+from bumble.colors import color
+from bumble.core import (
+    InvalidStateError,
+    InvalidArgumentError,
+    InvalidPacketError,
+    ProtocolError,
+)
+from bumble.hci import HCI_Object, name_or_number, key_with_value
 
 if TYPE_CHECKING:
     from .device import Device, Connection
@@ -124,7 +130,7 @@ SDP_ATTRIBUTE_ID_NAMES = {
 SDP_PUBLIC_BROWSE_ROOT = core.UUID.from_16_bits(0x1002, 'PublicBrowseRoot')
 
 # To be used in searches where an attribute ID list allows a range to be specified
-SDP_ALL_ATTRIBUTES_RANGE = (0x0000FFFF, 4)  # Express this as tuple so we can convey the desired encoding size
+SDP_ALL_ATTRIBUTES_RANGE = (0x0000, 0xFFFF)
 
 # fmt: on
 # pylint: enable=line-too-long
@@ -242,11 +248,11 @@ class DataElement:
         return DataElement(DataElement.BOOLEAN, value)
 
     @staticmethod
-    def sequence(value: List[DataElement]) -> DataElement:
+    def sequence(value: Iterable[DataElement]) -> DataElement:
         return DataElement(DataElement.SEQUENCE, value)
 
     @staticmethod
-    def alternative(value: List[DataElement]) -> DataElement:
+    def alternative(value: Iterable[DataElement]) -> DataElement:
         return DataElement(DataElement.ALTERNATIVE, value)
 
     @staticmethod
@@ -473,7 +479,9 @@ class ServiceAttribute:
         self.value = value
 
     @staticmethod
-    def list_from_data_elements(elements: List[DataElement]) -> List[ServiceAttribute]:
+    def list_from_data_elements(
+        elements: Sequence[DataElement],
+    ) -> list[ServiceAttribute]:
         attribute_list = []
         for i in range(0, len(elements) // 2):
             attribute_id, attribute_value = elements[2 * i : 2 * (i + 1)]
@@ -486,7 +494,7 @@ class ServiceAttribute:
 
     @staticmethod
     def find_attribute_in_list(
-        attribute_list: List[ServiceAttribute], attribute_id: int
+        attribute_list: Iterable[ServiceAttribute], attribute_id: int
     ) -> Optional[DataElement]:
         return next(
             (
@@ -534,7 +542,12 @@ class SDP_PDU:
     See Bluetooth spec @ Vol 3, Part B - 4.2 PROTOCOL DATA UNIT FORMAT
     '''
 
-    sdp_pdu_classes: Dict[int, Type[SDP_PDU]] = {}
+    RESPONSE_PDU_IDS = {
+        SDP_SERVICE_SEARCH_REQUEST: SDP_SERVICE_SEARCH_RESPONSE,
+        SDP_SERVICE_ATTRIBUTE_REQUEST: SDP_SERVICE_ATTRIBUTE_RESPONSE,
+        SDP_SERVICE_SEARCH_ATTRIBUTE_REQUEST: SDP_SERVICE_SEARCH_ATTRIBUTE_RESPONSE,
+    }
+    sdp_pdu_classes: dict[int, Type[SDP_PDU]] = {}
     name = None
     pdu_id = 0
 
@@ -558,7 +571,7 @@ class SDP_PDU:
     @staticmethod
     def parse_service_record_handle_list_preceded_by_count(
         data: bytes, offset: int
-    ) -> Tuple[int, List[int]]:
+    ) -> tuple[int, list[int]]:
         count = struct.unpack_from('>H', data, offset - 2)[0]
         handle_list = [
             struct.unpack_from('>I', data, offset + x * 4)[0] for x in range(count)
@@ -639,6 +652,8 @@ class SDP_ErrorResponse(SDP_PDU):
     See Bluetooth spec @ Vol 3, Part B - 4.4.1 SDP_ErrorResponse PDU
     '''
 
+    error_code: int
+
 
 # -----------------------------------------------------------------------------
 @SDP_PDU.subclass(
@@ -675,7 +690,7 @@ class SDP_ServiceSearchResponse(SDP_PDU):
     See Bluetooth spec @ Vol 3, Part B - 4.5.2 SDP_ServiceSearchResponse PDU
     '''
 
-    service_record_handle_list: List[int]
+    service_record_handle_list: list[int]
     total_service_record_count: int
     current_service_record_count: int
     continuation_state: bytes
@@ -752,31 +767,99 @@ class SDP_ServiceSearchAttributeResponse(SDP_PDU):
     See Bluetooth spec @ Vol 3, Part B - 4.7.2 SDP_ServiceSearchAttributeResponse PDU
     '''
 
-    attribute_list_byte_count: int
-    attribute_list: bytes
+    attribute_lists_byte_count: int
+    attribute_lists: bytes
     continuation_state: bytes
 
 
 # -----------------------------------------------------------------------------
 class Client:
-    channel: Optional[l2cap.ClassicChannel]
-
-    def __init__(self, connection: Connection) -> None:
+    def __init__(self, connection: Connection, mtu: int = 0) -> None:
         self.connection = connection
-        self.pending_request = None
-        self.channel = None
+        self.channel: Optional[l2cap.ClassicChannel] = None
+        self.mtu = mtu
+        self.request_semaphore = asyncio.Semaphore(1)
+        self.pending_request: Optional[SDP_PDU] = None
+        self.pending_response: Optional[asyncio.futures.Future[SDP_PDU]] = None
+        self.next_transaction_id = 0
 
     async def connect(self) -> None:
         self.channel = await self.connection.create_l2cap_channel(
-            spec=l2cap.ClassicChannelSpec(SDP_PSM)
+            spec=(
+                l2cap.ClassicChannelSpec(SDP_PSM, self.mtu)
+                if self.mtu
+                else l2cap.ClassicChannelSpec(SDP_PSM)
+            )
         )
+        self.channel.sink = self.on_pdu
 
     async def disconnect(self) -> None:
         if self.channel:
             await self.channel.disconnect()
             self.channel = None
 
-    async def search_services(self, uuids: List[core.UUID]) -> List[int]:
+    def make_transaction_id(self) -> int:
+        transaction_id = self.next_transaction_id
+        self.next_transaction_id = (self.next_transaction_id + 1) & 0xFFFF
+        return transaction_id
+
+    def on_pdu(self, pdu: bytes) -> None:
+        if not self.pending_request:
+            logger.warning('received response with no pending request')
+            return
+        assert self.pending_response is not None
+
+        response = SDP_PDU.from_bytes(pdu)
+
+        # Check that the transaction ID is what we expect
+        if self.pending_request.transaction_id != response.transaction_id:
+            logger.warning(
+                f"received response with transaction ID {response.transaction_id} "
+                f"but expected {self.pending_request.transaction_id}"
+            )
+            return
+
+        # Check if the response is an error
+        if isinstance(response, SDP_ErrorResponse):
+            self.pending_response.set_exception(
+                ProtocolError(error_code=response.error_code)
+            )
+            return
+
+        # Check that the type of the response matches the request
+        if response.pdu_id != SDP_PDU.RESPONSE_PDU_IDS.get(self.pending_request.pdu_id):
+            logger.warning("response type mismatch")
+            return
+
+        self.pending_response.set_result(response)
+
+    async def send_request(self, request: SDP_PDU) -> SDP_PDU:
+        assert self.channel is not None
+        async with self.request_semaphore:
+            assert self.pending_request is None
+            assert self.pending_response is None
+
+            # Create a future value to hold the eventual response
+            self.pending_response = asyncio.get_running_loop().create_future()
+            self.pending_request = request
+
+            try:
+                self.channel.send_pdu(bytes(request))
+                return await self.pending_response
+            finally:
+                self.pending_request = None
+                self.pending_response = None
+
+    async def search_services(self, uuids: Iterable[core.UUID]) -> list[int]:
+        """
+        Search for services by UUID.
+
+        Args:
+          uuids: service the UUIDs to search for.
+
+        Returns:
+          A list of matching service record handles.
+        """
         if self.pending_request is not None:
             raise InvalidStateError('request already pending')
         if self.channel is None:
@@ -791,16 +874,16 @@ class Client:
         continuation_state = bytes([0])
         watchdog = SDP_CONTINUATION_WATCHDOG
         while watchdog > 0:
-            response_pdu = await self.channel.send_request(
+            response = await self.send_request(
                 SDP_ServiceSearchRequest(
-                    transaction_id=0,  # Transaction ID TODO: pick a real value
+                    transaction_id=self.make_transaction_id(),
                     service_search_pattern=service_search_pattern,
                     maximum_service_record_count=0xFFFF,
                     continuation_state=continuation_state,
                 )
             )
-            response = SDP_PDU.from_bytes(response_pdu)
             logger.debug(f'<<< Response: {response}')
+            assert isinstance(response, SDP_ServiceSearchResponse)
             service_record_handle_list += response.service_record_handle_list
             continuation_state = response.continuation_state
             if len(continuation_state) == 1 and continuation_state[0] == 0:
@@ -811,8 +894,21 @@ class Client:
         return service_record_handle_list
 
     async def search_attributes(
-        self, uuids: List[core.UUID], attribute_ids: List[Union[int, Tuple[int, int]]]
-    ) -> List[List[ServiceAttribute]]:
+        self,
+        uuids: Iterable[core.UUID],
+        attribute_ids: Iterable[Union[int, tuple[int, int]]],
+    ) -> list[list[ServiceAttribute]]:
+        """
+        Search for attributes by UUID and attribute IDs.
+
+        Args:
+          uuids: the service UUIDs to search for.
+          attribute_ids: list of attribute IDs or (start, end) attribute ID ranges.
+          (use (0, 0xFFFF) to include all attributes)
+
+        Returns:
+          A list of list of attributes, one list per matching service.
+        """
         if self.pending_request is not None:
             raise InvalidStateError('request already pending')
         if self.channel is None:
@@ -824,8 +920,8 @@ class Client:
         attribute_id_list = DataElement.sequence(
             [
                 (
-                    DataElement.unsigned_integer(
-                        attribute_id[0], value_size=attribute_id[1]
+                    DataElement.unsigned_integer_32(
+                        attribute_id[0] << 16 | attribute_id[1]
                     )
                     if isinstance(attribute_id, tuple)
                     else DataElement.unsigned_integer_16(attribute_id)
@@ -839,17 +935,17 @@ class Client:
         continuation_state = bytes([0])
         watchdog = SDP_CONTINUATION_WATCHDOG
         while watchdog > 0:
-            response_pdu = await self.channel.send_request(
+            response = await self.send_request(
                 SDP_ServiceSearchAttributeRequest(
-                    transaction_id=0,  # Transaction ID TODO: pick a real value
+                    transaction_id=self.make_transaction_id(),
                     service_search_pattern=service_search_pattern,
                     maximum_attribute_byte_count=0xFFFF,
                     attribute_id_list=attribute_id_list,
                     continuation_state=continuation_state,
                 )
             )
-            response = SDP_PDU.from_bytes(response_pdu)
             logger.debug(f'<<< Response: {response}')
+            assert isinstance(response, SDP_ServiceSearchAttributeResponse)
             accumulator += response.attribute_lists
             continuation_state = response.continuation_state
             if len(continuation_state) == 1 and continuation_state[0] == 0:
@@ -872,8 +968,18 @@ class Client:
     async def get_attributes(
         self,
         service_record_handle: int,
-        attribute_ids: List[Union[int, Tuple[int, int]]],
-    ) -> List[ServiceAttribute]:
+        attribute_ids: Iterable[Union[int, tuple[int, int]]],
+    ) -> list[ServiceAttribute]:
+        """
+        Get attributes for a service.
+
+        Args:
+          service_record_handle: the handle for a service
+          attribute_ids: list or attribute IDs or (start, end) attribute ID handles.
+
+        Returns:
+          A list of attributes.
+        """
         if self.pending_request is not None:
             raise InvalidStateError('request already pending')
         if self.channel is None:
@@ -882,8 +988,8 @@ class Client:
         attribute_id_list = DataElement.sequence(
             [
                 (
-                    DataElement.unsigned_integer(
-                        attribute_id[0], value_size=attribute_id[1]
+                    DataElement.unsigned_integer_32(
+                        attribute_id[0] << 16 | attribute_id[1]
                     )
                     if isinstance(attribute_id, tuple)
                     else DataElement.unsigned_integer_16(attribute_id)
@@ -897,17 +1003,17 @@ class Client:
         continuation_state = bytes([0])
         watchdog = SDP_CONTINUATION_WATCHDOG
         while watchdog > 0:
-            response_pdu = await self.channel.send_request(
+            response = await self.send_request(
                 SDP_ServiceAttributeRequest(
-                    transaction_id=0,  # Transaction ID TODO: pick a real value
+                    transaction_id=self.make_transaction_id(),
                     service_record_handle=service_record_handle,
                     maximum_attribute_byte_count=0xFFFF,
                     attribute_id_list=attribute_id_list,
                     continuation_state=continuation_state,
                 )
             )
-            response = SDP_PDU.from_bytes(response_pdu)
             logger.debug(f'<<< Response: {response}')
+            assert isinstance(response, SDP_ServiceAttributeResponse)
             accumulator += response.attribute_list
             continuation_state = response.continuation_state
             if len(continuation_state) == 1 and continuation_state[0] == 0:
@@ -933,17 +1039,17 @@ class Client:
 
 # -----------------------------------------------------------------------------
 class Server:
-    CONTINUATION_STATE = bytes([0x01, 0x43])
+    CONTINUATION_STATE = bytes([0x01, 0x00])
     channel: Optional[l2cap.ClassicChannel]
-    Service = NewType('Service', List[ServiceAttribute])
-    service_records: Dict[int, Service]
-    current_response: Union[None, bytes, Tuple[int, List[int]]]
+    Service = NewType('Service', list[ServiceAttribute])
+    service_records: dict[int, Service]
+    current_response: Union[None, bytes, tuple[int, list[int]]]
 
     def __init__(self, device: Device) -> None:
         self.device = device
         self.service_records = {}  # Service records maps, by record handle
         self.channel = None
-        self.current_response = None
+        self.current_response = None  # Current response data, used for continuations
 
     def register(self, l2cap_channel_manager: l2cap.ChannelManager) -> None:
         l2cap_channel_manager.create_classic_server(
@@ -954,7 +1060,7 @@ class Server:
         logger.debug(f'{color(">>> Sending SDP Response", "blue")}: {response}')
         self.channel.send_pdu(response)
 
-    def match_services(self, search_pattern: DataElement) -> Dict[int, Service]:
+    def match_services(self, search_pattern: DataElement) -> dict[int, Service]:
         # Find the services for which the attributes in the pattern is a subset of the
         # service's attribute values (NOTE: the value search recurses into sequences)
         matching_services = {}
@@ -1011,6 +1117,31 @@ class Server:
                 )
             )
 
+    def check_continuation(
+        self,
+        continuation_state: bytes,
+        transaction_id: int,
+    ) -> Optional[bool]:
+        # Check if this is a valid continuation
+        if len(continuation_state) > 1:
+            if (
+                self.current_response is None
+                or continuation_state != self.CONTINUATION_STATE
+            ):
+                self.send_response(
+                    SDP_ErrorResponse(
+                        transaction_id=transaction_id,
+                        error_code=SDP_INVALID_CONTINUATION_STATE_ERROR,
+                    )
+                )
+                return None
+            return True
+
+        # Cleanup any partial response leftover
+        self.current_response = None
+
+        return False
+
     def get_next_response_payload(self, maximum_size):
         if len(self.current_response) > maximum_size:
             payload = self.current_response[:maximum_size]
@@ -1025,7 +1156,7 @@ class Server:
 
     @staticmethod
     def get_service_attributes(
-        service: Service, attribute_ids: List[DataElement]
+        service: Service, attribute_ids: Iterable[DataElement]
     ) -> DataElement:
         attributes = []
         for attribute_id in attribute_ids:
@@ -1053,30 +1184,24 @@ class Server:
 
     def on_sdp_service_search_request(self, request: SDP_ServiceSearchRequest) -> None:
         # Check if this is a continuation
-        if len(request.continuation_state) > 1:
-            if self.current_response is None:
-                self.send_response(
-                    SDP_ErrorResponse(
-                        transaction_id=request.transaction_id,
-                        error_code=SDP_INVALID_CONTINUATION_STATE_ERROR,
-                    )
-                )
-                return
-        else:
-            # Cleanup any partial response leftover
-            self.current_response = None
+        if (
+            continuation := self.check_continuation(
+                request.continuation_state, request.transaction_id
+            )
+        ) is None:
+            return
 
+        if not continuation:
             # Find the matching services
             matching_services = self.match_services(request.service_search_pattern)
             service_record_handles = list(matching_services.keys())
+            logger.debug(f'Service Record Handles: {service_record_handles}')
 
             # Only return up to the maximum requested
             service_record_handles_subset = service_record_handles[
                 : request.maximum_service_record_count
             ]
 
-            # Serialize to a byte array, and remember the total count
-            logger.debug(f'Service Record Handles: {service_record_handles}')
             self.current_response = (
                 len(service_record_handles),
                 service_record_handles_subset,
@@ -1084,15 +1209,21 @@ class Server:
 
         # Respond, keeping any unsent handles for later
         assert isinstance(self.current_response, tuple)
-        service_record_handles = self.current_response[1][
-            : request.maximum_service_record_count
+        assert self.channel is not None
+        total_service_record_count, service_record_handles = self.current_response
+        maximum_service_record_count = (self.channel.peer_mtu - 11) // 4
+        service_record_handles_remaining = service_record_handles[
+            maximum_service_record_count:
         ]
+        service_record_handles = service_record_handles[:maximum_service_record_count]
         self.current_response = (
-            self.current_response[0],
-            self.current_response[1][request.maximum_service_record_count :],
+            total_service_record_count,
+            service_record_handles_remaining,
         )
         continuation_state = (
-            Server.CONTINUATION_STATE if self.current_response[1] else bytes([0])
+            Server.CONTINUATION_STATE
+            if service_record_handles_remaining
+            else bytes([0])
         )
         service_record_handle_list = b''.join(
             [struct.pack('>I', handle) for handle in service_record_handles]
@@ -1100,7 +1231,7 @@ class Server:
         self.send_response(
             SDP_ServiceSearchResponse(
                 transaction_id=request.transaction_id,
-                total_service_record_count=self.current_response[0],
+                total_service_record_count=total_service_record_count,
                 current_service_record_count=len(service_record_handles),
                 service_record_handle_list=service_record_handle_list,
                 continuation_state=continuation_state,
@@ -1111,19 +1242,14 @@ class Server:
         self, request: SDP_ServiceAttributeRequest
     ) -> None:
         # Check if this is a continuation
-        if len(request.continuation_state) > 1:
-            if self.current_response is None:
-                self.send_response(
-                    SDP_ErrorResponse(
-                        transaction_id=request.transaction_id,
-                        error_code=SDP_INVALID_CONTINUATION_STATE_ERROR,
-                    )
-                )
-                return
-        else:
-            # Cleanup any partial response leftover
-            self.current_response = None
+        if (
+            continuation := self.check_continuation(
+                request.continuation_state, request.transaction_id
+            )
+        ) is None:
+            return
 
+        if not continuation:
             # Check that the service exists
             service = self.service_records.get(request.service_record_handle)
             if service is None:
@@ -1145,14 +1271,18 @@ class Server:
             self.current_response = bytes(attribute_list)
 
         # Respond, keeping any pending chunks for later
+        assert self.channel is not None
+        maximum_attribute_byte_count = min(
+            request.maximum_attribute_byte_count, self.channel.peer_mtu - 9
+        )
         attribute_list_response, continuation_state = self.get_next_response_payload(
-            request.maximum_attribute_byte_count
+            maximum_attribute_byte_count
         )
         self.send_response(
             SDP_ServiceAttributeResponse(
                 transaction_id=request.transaction_id,
                 attribute_list_byte_count=len(attribute_list_response),
-                attribute_list=attribute_list,
+                attribute_list=attribute_list_response,
                 continuation_state=continuation_state,
             )
         )
@@ -1161,18 +1291,14 @@ class Server:
         self, request: SDP_ServiceSearchAttributeRequest
     ) -> None:
         # Check if this is a continuation
-        if len(request.continuation_state) > 1:
-            if self.current_response is None:
-                self.send_response(
-                    SDP_ErrorResponse(
-                        transaction_id=request.transaction_id,
-                        error_code=SDP_INVALID_CONTINUATION_STATE_ERROR,
-                    )
-                )
-        else:
-            # Cleanup any partial response leftover
-            self.current_response = None
+        if (
+            continuation := self.check_continuation(
+                request.continuation_state, request.transaction_id
+            )
+        ) is None:
+            return
 
+        if not continuation:
             # Find the matching services
             matching_services = self.match_services(
                 request.service_search_pattern
@@ -1192,14 +1318,18 @@ class Server:
             self.current_response = bytes(attribute_lists)
 
         # Respond, keeping any pending chunks for later
+        assert self.channel is not None
+        maximum_attribute_byte_count = min(
+            request.maximum_attribute_byte_count, self.channel.peer_mtu - 9
+        )
         attribute_lists_response, continuation_state = self.get_next_response_payload(
-            request.maximum_attribute_byte_count
+            maximum_attribute_byte_count
         )
         self.send_response(
             SDP_ServiceSearchAttributeResponse(
                 transaction_id=request.transaction_id,
                 attribute_lists_byte_count=len(attribute_lists_response),
-                attribute_lists=attribute_lists,
+                attribute_lists=attribute_lists_response,
                 continuation_state=continuation_state,
             )
         )

bumble/smp.py

@@ -46,13 +46,13 @@ from pyee import EventEmitter
 from .colors import color
 from .hci import (
     Address,
+    Role,
     HCI_LE_Enable_Encryption_Command,
     HCI_Object,
     key_with_value,
 )
 from .core import (
     BT_BR_EDR_TRANSPORT,
-    BT_CENTRAL_ROLE,
     BT_LE_TRANSPORT,
     AdvertisingData,
     InvalidArgumentError,
@@ -1326,7 +1326,7 @@ class Session:
         self.connection.abort_on('disconnection', self.on_pairing())
 
     def on_connection_encryption_change(self) -> None:
-        if self.connection.is_encrypted:
+        if self.connection.is_encrypted and not self.completed:
             if self.is_responder:
                 # The responder distributes its keys first, the initiator later
                 self.distribute_keys()
@@ -1975,7 +1975,7 @@ class Manager(EventEmitter):
 
         # Look for a session with this connection, and create one if none exists
         if not (session := self.sessions.get(connection.handle)):
-            if connection.role == BT_CENTRAL_ROLE:
+            if connection.role == Role.CENTRAL:
                 logger.warning('Remote starts pairing as Peripheral!')
             pairing_config = self.pairing_config_factory(connection)
             session = self.session_proxy(
@@ -1995,7 +1995,7 @@ class Manager(EventEmitter):
 
     async def pair(self, connection: Connection) -> None:
         # TODO: check if there's already a session for this connection
-        if connection.role != BT_CENTRAL_ROLE:
+        if connection.role != Role.CENTRAL:
             logger.warning('Start pairing as Peripheral!')
         pairing_config = self.pairing_config_factory(connection)
         session = self.session_proxy(

bumble/transport/usb.py

@@ -115,9 +115,7 @@ async def open_usb_transport(spec: str) -> Transport:
             self.acl_out = acl_out
             self.acl_out_transfer = device.getTransfer()
             self.acl_out_transfer_ready = asyncio.Semaphore(1)
-            self.packets: asyncio.Queue[bytes] = (
-                asyncio.Queue()
-            )  # Queue of packets waiting to be sent
+            self.packets = asyncio.Queue[bytes]()  # Queue of packets waiting to be sent
             self.loop = asyncio.get_running_loop()
             self.queue_task = None
             self.cancel_done = self.loop.create_future()

bumble/utils.py

@@ -447,7 +447,7 @@ def deprecated(msg: str):
     def wrapper(function):
         @functools.wraps(function)
         def inner(*args, **kwargs):
-            warnings.warn(msg, DeprecationWarning)
+            warnings.warn(msg, DeprecationWarning, stacklevel=2)
             return function(*args, **kwargs)
 
         return inner
@@ -464,7 +464,7 @@ def experimental(msg: str):
     def wrapper(function):
         @functools.wraps(function)
         def inner(*args, **kwargs):
-            warnings.warn(msg, FutureWarning)
+            warnings.warn(msg, FutureWarning, stacklevel=2)
             return function(*args, **kwargs)
 
         return inner
@@ -502,3 +502,13 @@ class ByteSerializable(Protocol):
     def from_bytes(cls, data: bytes) -> Self: ...
 
     def __bytes__(self) -> bytes: ...
+
+
+# -----------------------------------------------------------------------------
+class IntConvertible(Protocol):
+    """
+    Type protocol for classes that can be instantiated from int and converted to int.
+    """
+
+    def __init__(self, value: int) -> None: ...
+    def __int__(self) -> int: ...

bumble/vendor/android/hci.py

@@ -299,7 +299,7 @@ class HCI_Android_Vendor_Event(HCI_Extended_Event):
 
 
 HCI_Android_Vendor_Event.register_subevents(globals())
-HCI_Event.vendor_factory = HCI_Android_Vendor_Event.subclass_from_parameters
+HCI_Event.add_vendor_factory(HCI_Android_Vendor_Event.subclass_from_parameters)
 
 
 # -----------------------------------------------------------------------------

docs/mkdocs/mkdocs.yml

@@ -39,12 +39,14 @@ nav:
   - Drivers:
     - drivers/index.md
     - Realtek: drivers/realtek.md
+    - Intel: drivers/intel.md
   - API:
     - Guide: api/guide.md
     - Examples: api/examples.md
     - Reference: api/reference.md
   - Apps & Tools:
     - apps_and_tools/index.md
+    - Auracast: apps_and_tools/auracast.md
     - Console: apps_and_tools/console.md
     - Bench: apps_and_tools/bench.md
     - Speaker: apps_and_tools/speaker.md
@@ -108,8 +110,8 @@ markdown_extensions:
   - pymdownx.details
   - pymdownx.superfences
   - pymdownx.emoji:
-      emoji_index: !!python/name:materialx.emoji.twemoji
-      emoji_generator: !!python/name:materialx.emoji.to_svg
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
   - pymdownx.tabbed:
       alternate_style: true
   - codehilite:

docs/mkdocs/src/apps_and_tools/auracast.md

@@ -0,0 +1,202 @@
+AURACAST TOOL
+=============
+
+The "auracast" tool implements commands that implement broadcasting, receiving
+and controlling LE Audio broadcasts.
+
+=== "Running as an installed package"
+    ```
+    $ bumble-auracast
+    ```
+
+=== "Running from source"
+    ```
+    $ python3 apps/auracast.py <args>
+    ```
+
+# Python Dependencies
+Try installing the optional `[auracast]` dependencies:
+
+=== "From source"
+    ```bash
+    $ python3 -m pip install ".[auracast]"
+    ```
+
+=== "From PyPI"
+    ```bash
+    $ python3 -m pip install "bumble[auracast]"
+    ```
+
+## LC3
+The `auracast` app depends on the `lc3` python module, which is available
+either as PyPI module (currently only available for Linux x86_64).
+When installing Bumble with the optional `auracast` dependency, the `lc3`
+module will be installed from the `lc3py` PyPI package if available.
+If not, you will need to install it separately. This can be done with:
+```bash
+$ python3 -m pip install "git+https://github.com/google/liblc3.git"
+```
+
+## SoundDevice
+The `sounddevice` module is required for audio output to the host's sound
+output device(s) and/or input from the host's input device(s).
+If not installed, the `auracast` app is still functional, but will be limited
+to non-device inputs and output (files, external processes, ...)
+
+On macOS and Windows, the `sounddevice` module gets installed with the
+native PortAudio libraries included.
+
+For Linux, however, PortAudio must be installed separately.
+This is typically done with a command like:
+```bash
+$ sudo apt install libportaudio2
+```
+
+Visit the [sounddevice documentation](https://python-sounddevice.readthedocs.io/)
+for details.
+
+
+# General Usage
+```
+Usage: bumble-auracast [OPTIONS] COMMAND [ARGS]...
+
+Options:
+  --help  Show this message and exit.
+
+Commands:
+  assist    Scan for broadcasts on behalf of an audio server
+  pair      Pair with an audio server
+  receive   Receive a broadcast source
+  scan      Scan for public broadcasts
+  transmit  Transmit a broadcast source
+```
+
+Use `bumble-auracast <command> --help` to get more detailed usage information
+for a specific `<command>`.
+
+## `assist`
+Act as a broadcast assistant.
+
+Use `bumble-auracast assist --help` for details on the commands and options.
+
+The assistant commands are:
+
+### `monitor-state`
+Subscribe to the state characteristic and monitor changes.
+
+### `add-source`
+Add a broadcast source. This will instruct the device to start
+receiving a broadcast.
+
+### `modify-source`
+Modify a broadcast source.
+
+### `remove-source`
+Remote a broadcast source.
+
+## `pair`
+Pair with a device.
+
+## `receive`
+Receive a broadcast source.
+
+The `--output` option specifies where to send the decoded audio samples.
+The following outputs are supported:
+
+### Sound Device
+The `--output` argument is either `device`, to send the audio to the hosts's default sound device, or `device:<DEVICE_ID>` where `<DEVICE_ID>`
+is the integer ID of one of the available sound devices.
+When invoked with `--output "device:?"`, a list of available devices and
+their IDs is printed out.
+
+### Standard Output
+With `--output stdout`, the decoded audio samples are written to the
+standard output (currently always as float32 PCM samples)
+
+### FFPlay
+With `--output ffplay`, the decoded audio samples are piped to `ffplay`
+in a child process. This option is only available if `ffplay` is a command that is available on the host.
+
+### File
+With `--output <filename>` or `--output file:<filename>`, the decoded audio
+samples are written to a file (currently always as float32 PCM)
+
+## `transmit`
+Broadcast an audio source as a transmitter.
+
+The `--input` and `--input-format` options specify what audio input
+source to transmit.
+The following inputs are supported:
+
+### Sound Device
+The `--input` argument is either `device`, to use the host's default sound
+device (typically a builtin microphone), or `device:<DEVICE_ID>` where
+`<DEVICE_ID>` is the integer ID of one of the available sound devices.
+When invoked with `--input "device:?"`, a list of available devices and their
+IDs is printed out.
+
+### Standard Input
+With `--input stdout`, the audio samples are read from the standard input.
+(currently always as int16 PCM).
+
+### File
+With `--input <filename>` or `--input file:<filename>`, the audio samples
+are read from a .wav or raw PCM file.
+
+Use the `--input-format <FORMAT>` option to specify the format of the audio
+samples in raw PCM files. `<FORMAT>` is expressed as:
+`<sample-type>,<sample-rate>,<channels>`
+(the only supported <sample-type> currently is 'int16le' for 16 bit signed integers with little-endian byte order)
+
+## `scan`
+Scan for public broadcasts.
+
+A live display of the available broadcasts is displayed continuously.
+
+# Compatibility With Some Products
+The `auracast` app has been tested for compatibility with a few products.
+The list is still very limited. Please let us know if there are products
+that are not working well, or if there are specific instructions that should
+be shared to allow better compatibiity with certain products.
+
+## Transmitters
+
+The `receive` command has been tested to successfully receive broadcasts from
+the following transmitters:
+
+  * JBL GO 4
+  * Flairmesh FlooGoo FMA120
+  * Eppfun AK3040Pro Max
+  * HIGHGAZE BA-25T
+  * Nexum Audio VOCE and USB dongle
+
+## Receivers
+
+### Pixel Buds Pro 2
+
+The Pixel Buds Pro 2 can be used as a broadcast receiver, controlled by the
+`auracast assist` command, instructing the buds to receive a broadcast.
+
+Use the `assist --command add-source` command to tell the buds to receive a
+broadcast.
+
+Use the `assist --command monitor-state` command to monitor the current sync/receive
+state of the buds.
+
+### JBL
+The JBL GO 4 and other JBL products that support the Auracast feature can be used
+as transmitters or receivers.
+
+When running in receiver mode (pressing the Auracast button while not already playing),
+the JBL speaker will scan for broadcast advertisements with a specific manufacturer data.
+Use the `--manufacturer-data` option of the `transmit` command in order to include data
+that will let the speaker recognize the broadcast as a compatible source.
+
+The manufacturer ID for JBL is 87.
+Using an option like `--manufacturer-data 87:00000000000000000000000000000000dffd` should work (tested on the
+JBL GO 4. The `dffd` value at the end of the payload may be different on other models?).
+
+
+### Others
+
+  * Nexum Audio VOCE and USB dongle

docs/mkdocs/src/apps_and_tools/index.md

@@ -4,12 +4,13 @@ APPS & TOOLS
 Included in the project are a few apps and tools, built on top of the core libraries.
 These include:
 
-  * [Console](console.md) - an interactive text-based console
-  * [Bench](bench.md) - Speed and Latency benchmarking between two devices (LE and Classic)
-  * [Pair](pair.md) - Pair/bond two devices (LE and Classic)
-  * [Unbond](unbond.md) - Remove a previously established bond
-  * [HCI Bridge](hci_bridge.md) - a HCI transport bridge to connect two HCI transports and filter/snoop the HCI packets
-  * [Golden Gate Bridge](gg_bridge.md) - a bridge between GATT and UDP to use with the Golden Gate "stack tool"
-  * [Show](show.md) - Parse a file with HCI packets and print the details of each packet in a human readable form
+  * [Auracast](auracast.md) - Commands to broadcast, receive and/or control LE Audio.
+  * [Console](console.md) - An interactive text-based console.
+  * [Bench](bench.md) - Speed and Latency benchmarking between two devices (LE and Classic).
+  * [Pair](pair.md) - Pair/bond two devices (LE and Classic).
+  * [Unbond](unbond.md) - Remove a previously established bond.
+  * [HCI Bridge](hci_bridge.md) - An HCI transport bridge to connect two HCI transports and filter/snoop the HCI packets.
+  * [Golden Gate Bridge](gg_bridge.md) - Bridge between GATT and UDP to use with the Golden Gate "stack tool".
+  * [Show](show.md) - Parse a file with HCI packets and print the details of each packet in a human readable form.
   * [Speaker](speaker.md) - Virtual Bluetooth speaker, with a command line and browser-based UI.
   * [Link Relay](link_relay.md) - WebSocket relay for virtual RemoteLink instances to communicate with each other.

docs/mkdocs/src/getting_started.md

@@ -9,9 +9,9 @@ for your platform.
 Throughout the documentation, when shell commands are shown, it is assumed that you can
 invoke Python as
 ```
-$ python
+$ python3
 ```
-If invoking python is different on your platform (it may be `python3` for example, or just `py` or `py.exe`),
+If invoking python is different on your platform (it may be `python` for example, or just `py` or `py.exe`),
 adjust accordingly.
 
 You may be simply using Bumble as a module for your own application or as a dependency to your own
@@ -30,12 +30,18 @@ manager, or from source.
     python environment, or in a virtual environment, such as a `venv`, `pyenv` or `conda` environment.
     See the [Python Environments page](development/python_environments.md) page for details.
 
+### Install from PyPI
+
+```
+$ python3 -m pip install bumble
+```
+
 ### Install From Source
 
 Install with `pip`. Run in a command shell in the directory where you downloaded the source
 distribution
 ```
-$ python -m pip install -e .
+$ python3 -m pip install -e .
 ```
 
 ### Install from GitHub
@@ -44,21 +50,21 @@ You can install directly from GitHub without first downloading the repo.
 
 Install the latest commit from the main branch with `pip`:
 ```
-$ python -m pip install git+https://github.com/google/bumble.git
+$ python3 -m pip install git+https://github.com/google/bumble.git
 ```
 
 You can specify a specific tag.
 
 Install tag `v0.0.1` with `pip`:
 ```
-$ python -m pip install git+https://github.com/google/bumble.git@v0.0.1
+$ python3 -m pip install git+https://github.com/google/bumble.git@v0.0.1
 ```
 
 You can also specify a specific commit.
 
 Install commit `27c0551` with `pip`:
 ```
-$ python -m pip install git+https://github.com/google/bumble.git@27c0551
+$ python3 -m pip install git+https://github.com/google/bumble.git@27c0551
 ```
 
 # Working On The Bumble Code
@@ -78,21 +84,21 @@ directory of the project.
 
 ```bash
 $ export PYTHONPATH=.
-$ python apps/console.py serial:/dev/tty.usbmodem0006839912171
+$ python3 apps/console.py serial:/dev/tty.usbmodem0006839912171
 ```
 
 or running an example, with the working directory set to the `examples` subdirectory
 ```bash
 $ cd examples
 $ export PYTHONPATH=..
-$ python run_scanner.py usb:0
+$ python3 run_scanner.py usb:0
 ```
 
 Or course, `export PYTHONPATH` only needs to be invoked once, not before each app/script execution.
 
 Setting `PYTHONPATH` locally with each command would look something like:
 ```
-$ PYTHONPATH=. python examples/run_advertiser.py examples/device1.json serial:/dev/tty.usbmodem0006839912171
+$ PYTHONPATH=. python3 examples/run_advertiser.py examples/device1.json serial:/dev/tty.usbmodem0006839912171
 ```
 
 # Where To Go Next

docs/mkdocs/src/platforms/android.md

@@ -35,11 +35,11 @@ the command line.
     visit [this Android Studio user guide page](https://developer.android.com/studio/run/emulator-commandline)
 
 The `-packet-streamer-endpoint <endpoint>` command line option may be used to enable
-Bluetooth emulation and tell the emulator which virtual controller to connect to. 
+Bluetooth emulation and tell the emulator which virtual controller to connect to.
 
 ## Connecting to Netsim
 
-If the emulator doesn't have Bluetooth emulation enabled by default, use the 
+If the emulator doesn't have Bluetooth emulation enabled by default, use the
 `-packet-streamer-endpoint default` option to tell it to connect to Netsim.
 If Netsim is not running, the emulator will start it automatically.
 
@@ -60,17 +60,17 @@ the Bumble `android-netsim` transport in `host` mode (the default).
 
 !!! example "Run the example GATT server connected to the emulator via Netsim"
     ``` shell
-    $ python run_gatt_server.py device1.json android-netsim
+    $ python3 run_gatt_server.py device1.json android-netsim
     ```
 
 By default, the Bumble `android-netsim` transport will try to automatically discover
 the port number on which the netsim process is exposing its gRPC server interface. If
-that discovery process fails, or if you want to specify the interface manually, you 
+that discovery process fails, or if you want to specify the interface manually, you
 can pass a `hostname` and `port` as parameters to the transport, as: `android-netsim:<host>:<port>`.
 
 !!! example "Run the example GATT server connected to the emulator via Netsim on a localhost, port 8877"
     ``` shell
-    $ python run_gatt_server.py device1.json android-netsim:localhost:8877
+    $ python3 run_gatt_server.py device1.json android-netsim:localhost:8877
     ```
 
 ### Multiple Instances
@@ -84,7 +84,7 @@ For example: `android-netsim:localhost:8877,name=bumble1`
 This is an advanced use case, which may not be officially supported, but should work in recent
 versions of the emulator.
 
-The first step is to run the Bumble HCI bridge, specifying netsim as the "host" end of the 
+The first step is to run the Bumble HCI bridge, specifying netsim as the "host" end of the
 bridge, and another controller (typically a USB Bluetooth dongle, but any other supported
 transport can work as well) as the "controller" end of the bridge.
 

examples/cs_initiator.json

@@ -0,0 +1,9 @@
+{
+    "name": "Bumble CS Initiator",
+    "address": "F0:F1:F2:F3:F4:F5",
+    "advertising_interval": 100,
+    "keystore": "JsonKeyStore",
+    "irk": "865F81FF5A8B486EAAE29A27AD9F77DC",
+    "identity_address_type": 1,
+    "channel_sounding_enabled": true
+}

examples/cs_reflector.json

@@ -0,0 +1,9 @@
+{
+    "name": "Bumble CS Reflector",
+    "address": "F0:F1:F2:F3:F4:F6",
+    "advertising_interval": 100,
+    "keystore": "JsonKeyStore",
+    "irk": "0c7d74db03a1c98e7be691f76141d53d",
+    "identity_address_type": 1,
+    "channel_sounding_enabled": true
+}

examples/heart_rate_server.py

@@ -102,7 +102,6 @@ async def main() -> None:
         )
 
         # Notify subscribers of the current value as soon as they subscribe
-        @heart_rate_service.heart_rate_measurement_characteristic.on('subscription')
         def on_subscription(connection, notify_enabled, indicate_enabled):
             if notify_enabled or indicate_enabled:
                 AsyncRunner.spawn(
@@ -112,6 +111,10 @@ async def main() -> None:
                     )
                 )
 
+        heart_rate_service.heart_rate_measurement_characteristic.on(
+            'subscription', on_subscription
+        )
+
         # Go!
         await device.power_on()
         await device.start_advertising(auto_restart=True)

examples/mobly/bench/one_device_bench_test.py

@@ -28,7 +28,7 @@ class OneDeviceBenchTest(base_test.BaseTestClass):
 
     def test_l2cap_client_ping(self):
         runner = self.dut.bench.runL2capClient(
-            "ping", "4B:2A:67:76:2B:E3", 128, True, 100, 970, 100
+            "ping", "4B:2A:67:76:2B:E3", 128, True, 100, 970, 100, "HIGH"
         )
         print("### Initial status:", runner)
         final_status = self.dut.bench.waitForRunnerCompletion(runner["id"])
@@ -36,12 +36,34 @@ class OneDeviceBenchTest(base_test.BaseTestClass):
 
     def test_l2cap_client_send(self):
         runner = self.dut.bench.runL2capClient(
-            "send", "7E:90:D0:F2:7A:11", 131, True, 100, 970, 0
+            "send",
+            "F1:F1:F1:F1:F1:F1",
+            128,
+            True,
+            100,
+            970,
+            0,
+            "HIGH",
+            10000,
         )
         print("### Initial status:", runner)
         final_status = self.dut.bench.waitForRunnerCompletion(runner["id"])
         print("### Final status:", final_status)
 
+    def test_gatt_client_send(self):
+        runner = self.dut.bench.runGattClient(
+            "send", "F1:F1:F1:F1:F1:F1", 128, True, 100, 970, 100, "HIGH"
+        )
+        print("### Initial status:", runner)
+        final_status = self.dut.bench.waitForRunnerCompletion(runner["id"])
+        print("### Final status:", final_status)
+
+    def test_gatt_server_receive(self):
+        runner = self.dut.bench.runGattServer("receive")
+        print("### Initial status:", runner)
+        final_status = self.dut.bench.waitForRunnerCompletion(runner["id"])
+        print("### Final status:", final_status)
+
 
 if __name__ == "__main__":
     test_runner.main()

examples/mobly/bench/sample_config.yml

@@ -2,8 +2,8 @@ TestBeds:
   - Name: BenchTestBed
     Controllers:
         AndroidDevice:
-          - serial: 37211FDJG000DJ
+          - serial: emulator-5554
             local_bt_address: 94:45:60:5E:03:B0
 
-          - serial: 23071FDEE001F7
-            local_bt_address: DC:E5:5B:E5:51:2C
+          #- serial: 23071FDEE001F7
+          #  local_bt_address: DC:E5:5B:E5:51:2C

examples/run_ancs_client.py

@@ -0,0 +1,215 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# -----------------------------------------------------------------------------
+# Imports
+# -----------------------------------------------------------------------------
+import asyncio
+import sys
+import os
+import logging
+from bumble.colors import color
+
+from bumble.device import Device, Peer
+from bumble.transport import open_transport
+from bumble.profiles.ancs import (
+    AncsClient,
+    AppAttribute,
+    AppAttributeId,
+    EventFlags,
+    EventId,
+    Notification,
+    NotificationAttributeId,
+)
+
+
+# -----------------------------------------------------------------------------
+_cached_app_names: dict[str, str] = {}
+_notification_queue = asyncio.Queue[Notification]()
+
+
+async def process_notifications(ancs_client: AncsClient):
+    while True:
+        notification = await _notification_queue.get()
+
+        prefix = " "
+        if notification.event_id == EventId.NOTIFICATION_ADDED:
+            print_color = "green"
+            if notification.event_flags & EventFlags.PRE_EXISTING:
+                prefix = " Existing "
+            else:
+                prefix = " New "
+        elif notification.event_id == EventId.NOTIFICATION_REMOVED:
+            print_color = "red"
+        elif notification.event_id == EventId.NOTIFICATION_MODIFIED:
+            print_color = "yellow"
+        else:
+            print_color = "white"
+
+        print(
+            color(
+                (
+                    f"[{notification.event_id.name}]{prefix}Notification "
+                    f"({notification.notification_uid}):"
+                ),
+                print_color,
+            )
+        )
+        print(color("  Event ID:      ", "yellow"), notification.event_id.name)
+        print(color("  Event Flags:   ", "yellow"), notification.event_flags.name)
+        print(color("  Category ID:   ", "yellow"), notification.category_id.name)
+        print(color("  Category Count:", "yellow"), notification.category_count)
+
+        if notification.event_id not in (
+            EventId.NOTIFICATION_ADDED,
+            EventId.NOTIFICATION_MODIFIED,
+        ):
+            continue
+
+        requested_attributes = [
+            NotificationAttributeId.APP_IDENTIFIER,
+            NotificationAttributeId.TITLE,
+            NotificationAttributeId.SUBTITLE,
+            NotificationAttributeId.MESSAGE,
+            NotificationAttributeId.DATE,
+        ]
+        if notification.event_flags & EventFlags.NEGATIVE_ACTION:
+            requested_attributes.append(NotificationAttributeId.NEGATIVE_ACTION_LABEL)
+        if notification.event_flags & EventFlags.POSITIVE_ACTION:
+            requested_attributes.append(NotificationAttributeId.POSITIVE_ACTION_LABEL)
+
+        attributes = await ancs_client.get_notification_attributes(
+            notification.notification_uid, requested_attributes
+        )
+        max_attribute_name_width = max(
+            (len(attribute.attribute_id.name) for attribute in attributes)
+        )
+        app_identifier = str(
+            next(
+                (
+                    attribute.value
+                    for attribute in attributes
+                    if attribute.attribute_id == NotificationAttributeId.APP_IDENTIFIER
+                )
+            )
+        )
+        if app_identifier not in _cached_app_names:
+            app_attributes = await ancs_client.get_app_attributes(
+                app_identifier, [AppAttributeId.DISPLAY_NAME]
+            )
+            _cached_app_names[app_identifier] = app_attributes[0].value
+        app_name = _cached_app_names[app_identifier]
+
+        for attribute in attributes:
+            padding = ' ' * (
+                max_attribute_name_width - len(attribute.attribute_id.name)
+            )
+            suffix = (
+                f" ({app_name})"
+                if attribute.attribute_id == NotificationAttributeId.APP_IDENTIFIER
+                else ""
+            )
+            print(
+                color(f"  {attribute.attribute_id.name}:{padding}", "blue"),
+                f"{attribute.value}{suffix}",
+            )
+
+        print()
+
+
+def on_ancs_notification(notification: Notification) -> None:
+    _notification_queue.put_nowait(notification)
+
+
+async def handle_command_client(
+    ancs_client: AncsClient, reader: asyncio.StreamReader, writer: asyncio.StreamWriter
+) -> None:
+    while True:
+        command = (await reader.readline()).decode("utf-8").strip()
+
+        try:
+            command_name, command_args = command.split(" ", 1)
+            if command_name == "+":
+                notification_uid = int(command_args)
+                await ancs_client.perform_positive_action(notification_uid)
+            elif command_name == "-":
+                notification_uid = int(command_args)
+                await ancs_client.perform_negative_action(notification_uid)
+            else:
+                writer.write(f"unknown command {command_name}".encode("utf-8"))
+        except Exception as error:
+            writer.write(f"ERROR: {error}\n".encode("utf-8"))
+
+
+# -----------------------------------------------------------------------------
+async def main() -> None:
+    if len(sys.argv) < 3:
+        print(
+            'Usage: run_ancs_client.py <device-config> <transport-spec> '
+            '<bluetooth-address> <mtu>'
+        )
+        print('example: run_ancs_client.py device1.json usb:0 E1:CA:72:48:C4:E8 512')
+        return
+    device_config, transport_spec, bluetooth_address, mtu = sys.argv[1:]
+
+    print('<<< connecting to HCI...')
+    async with await open_transport(transport_spec) as hci_transport:
+        print('<<< connected')
+
+        # Create a device to manage the host, with a custom listener
+        device = Device.from_config_file_with_hci(
+            device_config, hci_transport.source, hci_transport.sink
+        )
+        await device.power_on()
+
+        # Connect to the peer
+        print(f'=== Connecting to {bluetooth_address}...')
+        connection = await device.connect(bluetooth_address)
+        print(f'=== Connected: {connection}')
+
+        await connection.encrypt()
+
+        peer = Peer(connection)
+        mtu_int = int(mtu)
+        if mtu_int:
+            new_mtu = await peer.request_mtu(mtu_int)
+            print(f'ATT MTU = {new_mtu}')
+        ancs_client = await AncsClient.for_peer(peer)
+        if ancs_client is None:
+            print("!!! no ANCS service found")
+            return
+        await ancs_client.start()
+
+        print('Subscribing to updates')
+        ancs_client.on("notification", on_ancs_notification)
+
+        # Process all notifications in a task.
+        notification_processing_task = asyncio.create_task(
+            process_notifications(ancs_client)
+        )
+
+        # Accept a TCP connection to handle commands.
+        tcp_server = await asyncio.start_server(
+            lambda reader, writer: handle_command_client(ancs_client, reader, writer),
+            '127.0.0.1',
+            9000,
+        )
+        print("Accepting command client on port 9000")
+        async with tcp_server:
+            await tcp_server.serve_forever()
+
+
+# -----------------------------------------------------------------------------
+logging.basicConfig(level=os.environ.get('BUMBLE_LOGLEVEL', 'INFO').upper())
+asyncio.run(main())

examples/run_channel_sounding.py

@@ -0,0 +1,154 @@
+# Copyright 2024 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# -----------------------------------------------------------------------------
+# Imports
+# -----------------------------------------------------------------------------
+from __future__ import annotations
+
+import asyncio
+import logging
+import sys
+import os
+import functools
+
+from bumble import core
+from bumble import hci
+from bumble.device import Connection, Device, ChannelSoundingCapabilities
+from bumble.transport import open_transport_or_link
+
+# From https://cs.android.com/android/platform/superproject/main/+/main:packages/modules/Bluetooth/system/gd/hci/distance_measurement_manager.cc.
+CS_TONE_ANTENNA_CONFIG_MAPPING_TABLE = [
+    [0, 4, 5, 6],
+    [1, 7, 7, 7],
+    [2, 7, 7, 7],
+    [3, 7, 7, 7],
+]
+CS_PREFERRED_PEER_ANTENNA_MAPPING_TABLE = [1, 1, 1, 1, 3, 7, 15, 3]
+CS_ANTENNA_PERMUTATION_ARRAY = [
+    [1, 2, 3, 4],
+    [2, 1, 3, 4],
+    [1, 3, 2, 4],
+    [3, 1, 2, 4],
+    [3, 2, 1, 4],
+    [2, 3, 1, 4],
+    [1, 2, 4, 3],
+    [2, 1, 4, 3],
+    [1, 4, 2, 3],
+    [4, 1, 2, 3],
+    [4, 2, 1, 3],
+    [2, 4, 1, 3],
+    [1, 4, 3, 2],
+    [4, 1, 3, 2],
+    [1, 3, 4, 2],
+    [3, 1, 4, 2],
+    [3, 4, 1, 2],
+    [4, 3, 1, 2],
+    [4, 2, 3, 1],
+    [2, 4, 3, 1],
+    [4, 3, 2, 1],
+    [3, 4, 2, 1],
+    [3, 2, 4, 1],
+    [2, 3, 4, 1],
+]
+
+
+# -----------------------------------------------------------------------------
+async def main() -> None:
+    if len(sys.argv) < 3:
+        print(
+            'Usage: run_channel_sounding.py <config-file> <transport-spec-for-device>'
+            '[target_address](If missing, run as reflector)'
+        )
+        print('example: run_channel_sounding.py cs_reflector.json usb:0')
+        print(
+            'example: run_channel_sounding.py cs_initiator.json usb:0 F0:F1:F2:F3:F4:F5'
+        )
+        return
+
+    print('<<< connecting to HCI...')
+    async with await open_transport_or_link(sys.argv[2]) as hci_transport:
+        print('<<< connected')
+
+        device = Device.from_config_file_with_hci(
+            sys.argv[1], hci_transport.source, hci_transport.sink
+        )
+        await device.power_on()
+        assert (local_cs_capabilities := device.cs_capabilities)
+
+        if len(sys.argv) == 3:
+            print('<<< Start Advertising')
+            await device.start_advertising(
+                own_address_type=hci.OwnAddressType.RANDOM, auto_restart=True
+            )
+
+            def on_cs_capabilities(
+                connection: Connection, capabilities: ChannelSoundingCapabilities
+            ):
+                del capabilities
+                print('<<< Set CS Settings')
+                asyncio.create_task(device.set_default_cs_settings(connection))
+
+            device.on(
+                'connection',
+                lambda connection: connection.on(
+                    'channel_sounding_capabilities',
+                    functools.partial(on_cs_capabilities, connection),
+                ),
+            )
+        else:
+            target_address = hci.Address(sys.argv[3])
+
+            print(f'<<< Connecting to {target_address}')
+            connection = await device.connect(
+                target_address, transport=core.BT_LE_TRANSPORT
+            )
+            print('<<< ACL Connected')
+            if not (await device.get_long_term_key(connection.handle, b'', 0)):
+                print('<<< No bond, start pairing')
+                await connection.pair()
+                print('<<< Pairing complete')
+
+            print('<<< Encrypting Connection')
+            await connection.encrypt()
+
+            print('<<< Getting remote CS Capabilities...')
+            remote_capabilities = await device.get_remote_cs_capabilities(connection)
+            print('<<< Set CS Settings...')
+            await device.set_default_cs_settings(connection)
+            print('<<< Set CS Config...')
+            config = await device.create_cs_config(connection)
+            print('<<< Enable CS Security...')
+            await device.enable_cs_security(connection)
+            tone_antenna_config_selection = CS_TONE_ANTENNA_CONFIG_MAPPING_TABLE[
+                local_cs_capabilities.num_antennas_supported - 1
+            ][remote_capabilities.num_antennas_supported - 1]
+            print('<<< Set CS Procedure Parameters...')
+            await device.set_cs_procedure_parameters(
+                connection=connection,
+                config=config,
+                tone_antenna_config_selection=tone_antenna_config_selection,
+                preferred_peer_antenna=CS_PREFERRED_PEER_ANTENNA_MAPPING_TABLE[
+                    tone_antenna_config_selection
+                ],
+            )
+            print('<<< Enable CS Procedure...')
+            await device.enable_cs_procedure(connection=connection, config=config)
+
+        await hci_transport.source.terminated
+
+
+# -----------------------------------------------------------------------------
+logging.basicConfig(level=os.environ.get('BUMBLE_LOGLEVEL', 'DEBUG').upper())
+asyncio.run(main())

examples/run_gatt_client_and_server.py

@@ -70,13 +70,13 @@ async def main() -> None:
     descriptor = Descriptor(
         GATT_CHARACTERISTIC_USER_DESCRIPTION_DESCRIPTOR,
         Descriptor.READABLE,
-        'My Description',
+        'My Description'.encode(),
     )
-    manufacturer_name_characteristic = Characteristic(
+    manufacturer_name_characteristic = Characteristic[bytes](
         GATT_MANUFACTURER_NAME_STRING_CHARACTERISTIC,
         Characteristic.Properties.READ,
         Characteristic.READABLE,
-        "Fitbit",
+        "Fitbit".encode(),
         [descriptor],
     )
     device_info_service = Service(

examples/run_gatt_server.py

@@ -94,13 +94,13 @@ async def main() -> None:
         descriptor = Descriptor(
             GATT_CHARACTERISTIC_USER_DESCRIPTION_DESCRIPTOR,
             Descriptor.READABLE,
-            'My Description',
+            'My Description'.encode(),
         )
         manufacturer_name_characteristic = Characteristic(
             GATT_MANUFACTURER_NAME_STRING_CHARACTERISTIC,
             Characteristic.Properties.READ,
             Characteristic.READABLE,
-            'Fitbit',
+            'Fitbit'.encode(),
             [descriptor],
         )
         device_info_service = Service(

examples/run_gatt_with_adapters.py

@@ -1,4 +1,4 @@
-# Copyright 2024 Google LLC
+# Copyright 2025 Google LLC
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -18,6 +18,8 @@
 from __future__ import annotations
 import asyncio
 import dataclasses
+import functools
+import enum
 import logging
 import os
 import random
@@ -25,9 +27,11 @@ import struct
 import sys
 from typing import Any, List, Union
 
-from bumble.device import Connection, Device, Peer
+from bumble.device import Device, Peer
 from bumble import transport
 from bumble import gatt
+from bumble import gatt_adapters
+from bumble import gatt_client
 from bumble import hci
 from bumble import core
 
@@ -36,6 +40,9 @@ from bumble import core
 SERVICE_UUID = core.UUID("50DB505C-8AC4-4738-8448-3B1D9CC09CC5")
 CHARACTERISTIC_UUID_BASE = "D901B45B-4916-412E-ACCA-0000000000"
 
+DEFAULT_CLIENT_ADDRESS = "F0:F1:F2:F3:F4:F5"
+DEFAULT_SERVER_ADDRESS = "F1:F2:F3:F4:F5:F6"
+
 
 # -----------------------------------------------------------------------------
 @dataclasses.dataclass
@@ -65,6 +72,12 @@ class CustomClass:
         return struct.pack(">II", self.a, self.b)
 
 
+# -----------------------------------------------------------------------------
+class CustomEnum(enum.IntEnum):
+    FOO = 1234
+    BAR = 5678
+
+
 # -----------------------------------------------------------------------------
 async def client(device: Device, address: hci.Address) -> None:
     print(f'=== Connecting to {address}...')
@@ -78,72 +91,105 @@ async def client(device: Device, address: hci.Address) -> None:
     print("*** Discovery complete")
 
     service = peer.get_services_by_uuid(SERVICE_UUID)[0]
-    characteristics = []
-    for index in range(1, 9):
+    characteristics: list[gatt_client.CharacteristicProxy] = []
+    for index in range(1, 10):
         characteristics.append(
             service.get_characteristics_by_uuid(
-                CHARACTERISTIC_UUID_BASE + f"{index:02X}"
+                core.UUID(CHARACTERISTIC_UUID_BASE + f"{index:02X}")
             )[0]
         )
 
     # Read all characteristics as raw bytes.
     for characteristic in characteristics:
         value = await characteristic.read_value()
-        print(f"### {characteristic} = {value} ({value.hex()})")
+        print(f"### {characteristic} = {value!r} ({value.hex()})")
+
+    # Subscribe to all characteristics as a raw bytes listener.
+    def on_raw_characteristic_update(characteristic, value):
+        print(f"^^^ Update[RAW] {characteristic.uuid} value = {value.hex()}")
+
+    for characteristic in characteristics:
+        await characteristic.subscribe(
+            functools.partial(on_raw_characteristic_update, characteristic)
+        )
+
+    # Function to subscribe to adapted characteristics
+    def on_adapted_characteristic_update(characteristic, value):
+        print(
+            f"^^^ Update[ADAPTED] {characteristic.uuid} value = {value!r}, "
+            f"type={type(value)}"
+        )
 
     # Static characteristic with a bytes value.
     c1 = characteristics[0]
     c1_value = await c1.read_value()
-    print(f"@@@ C1 {c1} value = {c1_value} (type={type(c1_value)})")
+    print(f"@@@ C1 {c1} value = {c1_value!r} (type={type(c1_value)})")
     await c1.write_value("happy π day".encode("utf-8"))
+    await c1.subscribe(functools.partial(on_adapted_characteristic_update, c1))
 
     # Static characteristic with a string value.
-    c2 = gatt.UTF8CharacteristicAdapter(characteristics[1])
+    c2 = gatt_adapters.UTF8CharacteristicProxyAdapter(characteristics[1])
     c2_value = await c2.read_value()
     print(f"@@@ C2 {c2} value = {c2_value} (type={type(c2_value)})")
     await c2.write_value("happy π day")
+    await c2.subscribe(functools.partial(on_adapted_characteristic_update, c2))
 
     # Static characteristic with a tuple value.
-    c3 = gatt.PackedCharacteristicAdapter(characteristics[2], ">III")
+    c3 = gatt_adapters.PackedCharacteristicProxyAdapter(characteristics[2], ">III")
     c3_value = await c3.read_value()
     print(f"@@@ C3 {c3} value = {c3_value} (type={type(c3_value)})")
     await c3.write_value((2001, 2002, 2003))
+    await c3.subscribe(functools.partial(on_adapted_characteristic_update, c3))
 
     # Static characteristic with a named tuple value.
-    c4 = gatt.MappedCharacteristicAdapter(
+    c4 = gatt_adapters.MappedCharacteristicProxyAdapter(
         characteristics[3], ">III", ["f1", "f2", "f3"]
     )
     c4_value = await c4.read_value()
     print(f"@@@ C4 {c4} value = {c4_value} (type={type(c4_value)})")
     await c4.write_value({"f1": 4001, "f2": 4002, "f3": 4003})
+    await c4.subscribe(functools.partial(on_adapted_characteristic_update, c4))
 
     # Static characteristic with a serializable value.
-    c5 = gatt.SerializableCharacteristicAdapter(
+    c5 = gatt_adapters.SerializableCharacteristicProxyAdapter(
         characteristics[4], CustomSerializableClass
     )
     c5_value = await c5.read_value()
     print(f"@@@ C5 {c5} value = {c5_value} (type={type(c5_value)})")
     await c5.write_value(CustomSerializableClass(56, 57))
+    await c5.subscribe(functools.partial(on_adapted_characteristic_update, c5))
 
     # Static characteristic with a delegated value.
-    c6 = gatt.DelegatedCharacteristicAdapter(
+    c6 = gatt_adapters.DelegatedCharacteristicProxyAdapter(
         characteristics[5], encode=CustomClass.encode, decode=CustomClass.decode
     )
     c6_value = await c6.read_value()
     print(f"@@@ C6 {c6} value = {c6_value} (type={type(c6_value)})")
     await c6.write_value(CustomClass(6, 7))
+    await c6.subscribe(functools.partial(on_adapted_characteristic_update, c6))
 
     # Dynamic characteristic with a bytes value.
     c7 = characteristics[6]
     c7_value = await c7.read_value()
-    print(f"@@@ C7 {c7} value = {c7_value} (type={type(c7_value)})")
+    print(f"@@@ C7 {c7} value = {c7_value!r} (type={type(c7_value)})")
     await c7.write_value(bytes.fromhex("01020304"))
+    await c7.subscribe(functools.partial(on_adapted_characteristic_update, c7))
 
     # Dynamic characteristic with a string value.
-    c8 = gatt.UTF8CharacteristicAdapter(characteristics[7])
+    c8 = gatt_adapters.UTF8CharacteristicProxyAdapter(characteristics[7])
     c8_value = await c8.read_value()
     print(f"@@@ C8 {c8} value = {c8_value} (type={type(c8_value)})")
     await c8.write_value("howdy")
+    await c8.subscribe(functools.partial(on_adapted_characteristic_update, c8))
+
+    # Static characteristic with an enum value
+    c9 = gatt_adapters.EnumCharacteristicProxyAdapter(
+        characteristics[8], CustomEnum, 3, 'big'
+    )
+    c9_value = await c9.read_value()
+    print(f"@@@ C9 {c9} value = {c9_value.name} (type={type(c9_value)})")
+    await c9.write_value(CustomEnum.BAR)
+    await c9.subscribe(functools.partial(on_adapted_characteristic_update, c9))
 
 
 # -----------------------------------------------------------------------------
@@ -175,142 +221,213 @@ def on_characteristic_write(characteristic: gatt.Characteristic, value: Any) ->
     print(f"<<< WRITE: {characteristic} <- {value}  ({type(value)})")
 
 
+# -----------------------------------------------------------------------------
+async def server(device: Device) -> None:
+    # Static characteristic with a bytes value.
+    c1 = gatt.Characteristic(
+        CHARACTERISTIC_UUID_BASE + "01",
+        gatt.Characteristic.Properties.READ
+        | gatt.Characteristic.Properties.WRITE
+        | gatt.Characteristic.Properties.NOTIFY,
+        gatt.Characteristic.READABLE | gatt.Characteristic.WRITEABLE,
+        b'hello',
+    )
+
+    # Static characteristic with a string value.
+    c2 = gatt_adapters.UTF8CharacteristicAdapter(
+        gatt.Characteristic(
+            CHARACTERISTIC_UUID_BASE + "02",
+            gatt.Characteristic.Properties.READ
+            | gatt.Characteristic.Properties.WRITE
+            | gatt.Characteristic.Properties.NOTIFY,
+            gatt.Characteristic.READABLE | gatt.Characteristic.WRITEABLE,
+            'hello',
+        )
+    )
+
+    # Static characteristic with a tuple value.
+    c3 = gatt_adapters.PackedCharacteristicAdapter(
+        gatt.Characteristic(
+            CHARACTERISTIC_UUID_BASE + "03",
+            gatt.Characteristic.Properties.READ
+            | gatt.Characteristic.Properties.WRITE
+            | gatt.Characteristic.Properties.NOTIFY,
+            gatt.Characteristic.READABLE | gatt.Characteristic.WRITEABLE,
+            (1007, 1008, 1009),
+        ),
+        ">III",
+    )
+
+    # Static characteristic with a named tuple value.
+    c4 = gatt_adapters.MappedCharacteristicAdapter(
+        gatt.Characteristic(
+            CHARACTERISTIC_UUID_BASE + "04",
+            gatt.Characteristic.Properties.READ
+            | gatt.Characteristic.Properties.WRITE
+            | gatt.Characteristic.Properties.NOTIFY,
+            gatt.Characteristic.READABLE | gatt.Characteristic.WRITEABLE,
+            {"f1": 3007, "f2": 3008, "f3": 3009},
+        ),
+        ">III",
+        ["f1", "f2", "f3"],
+    )
+
+    # Static characteristic with a serializable value.
+    c5 = gatt_adapters.SerializableCharacteristicAdapter(
+        gatt.Characteristic(
+            CHARACTERISTIC_UUID_BASE + "05",
+            gatt.Characteristic.Properties.READ
+            | gatt.Characteristic.Properties.WRITE
+            | gatt.Characteristic.Properties.NOTIFY,
+            gatt.Characteristic.READABLE | gatt.Characteristic.WRITEABLE,
+            CustomSerializableClass(11, 12),
+        ),
+        CustomSerializableClass,
+    )
+
+    # Static characteristic with a delegated value.
+    c6 = gatt_adapters.DelegatedCharacteristicAdapter(
+        gatt.Characteristic(
+            CHARACTERISTIC_UUID_BASE + "06",
+            gatt.Characteristic.Properties.READ
+            | gatt.Characteristic.Properties.WRITE
+            | gatt.Characteristic.Properties.NOTIFY,
+            gatt.Characteristic.READABLE | gatt.Characteristic.WRITEABLE,
+            CustomClass(1, 2),
+        ),
+        encode=CustomClass.encode,
+        decode=CustomClass.decode,
+    )
+
+    # Dynamic characteristic with a bytes value.
+    c7 = gatt.Characteristic(
+        CHARACTERISTIC_UUID_BASE + "07",
+        gatt.Characteristic.Properties.READ
+        | gatt.Characteristic.Properties.WRITE
+        | gatt.Characteristic.Properties.NOTIFY,
+        gatt.Characteristic.READABLE | gatt.Characteristic.WRITEABLE,
+        gatt.CharacteristicValue(
+            read=lambda connection: dynamic_read("bytes"),
+            write=lambda connection, value: dynamic_write("bytes", value),
+        ),
+    )
+
+    # Dynamic characteristic with a string value.
+    c8 = gatt_adapters.UTF8CharacteristicAdapter(
+        gatt.Characteristic(
+            CHARACTERISTIC_UUID_BASE + "08",
+            gatt.Characteristic.Properties.READ
+            | gatt.Characteristic.Properties.WRITE
+            | gatt.Characteristic.Properties.NOTIFY,
+            gatt.Characteristic.READABLE | gatt.Characteristic.WRITEABLE,
+            gatt.CharacteristicValue(
+                read=lambda connection: dynamic_read("string"),
+                write=lambda connection, value: dynamic_write("string", value),
+            ),
+        )
+    )
+
+    # Static characteristic with an enum value
+    c9 = gatt_adapters.EnumCharacteristicAdapter(
+        gatt.Characteristic(
+            CHARACTERISTIC_UUID_BASE + "09",
+            gatt.Characteristic.Properties.READ
+            | gatt.Characteristic.Properties.WRITE
+            | gatt.Characteristic.Properties.NOTIFY,
+            gatt.Characteristic.READABLE | gatt.Characteristic.WRITEABLE,
+            CustomEnum.FOO,
+        ),
+        cls=CustomEnum,
+        length=3,
+        byteorder='big',
+    )
+
+    characteristics: List[gatt.Characteristic] = [
+        c1,
+        c2,
+        c3,
+        c4,
+        c5,
+        c6,
+        c7,
+        c8,
+        c9,
+    ]
+
+    # Listen for read and write events.
+    for characteristic in characteristics:
+        characteristic.on(
+            "read",
+            lambda _, value, c=characteristic: on_characteristic_read(c, value),
+        )
+        characteristic.on(
+            "write",
+            lambda _, value, c=characteristic: on_characteristic_write(c, value),
+        )
+
+    device.add_service(gatt.Service(SERVICE_UUID, characteristics))
+
+    # Notify every 3 seconds
+    i = 0
+    while True:
+        await asyncio.sleep(3)
+
+        # Notifying can be done with the characteristic's current value, or
+        # by explicitly passing a value to notify with. Both variants are used
+        # here: for c1..c4 we set the value and then notify, for c4..c9 we notify
+        # with an explicit value.
+        c1.value = f'hello c1 {i}'.encode()
+        await device.notify_subscribers(c1)
+        c2.value = f'hello c2 {i}'
+        await device.notify_subscribers(c2)
+        c3.value = (1000 + i, 2000 + i, 3000 + i)
+        await device.notify_subscribers(c3)
+        c4.value = {"f1": 4000 + i, "f2": 5000 + i, "f3": 6000 + i}
+        await device.notify_subscribers(c4)
+        await device.notify_subscribers(c5, CustomSerializableClass(1000 + i, 2000 + i))
+        await device.notify_subscribers(c6, CustomClass(3000 + i, 4000 + i))
+        await device.notify_subscribers(c7, bytes([1, 2, 3, i % 256]))
+        await device.notify_subscribers(c8, f'hello c8 {i}')
+        await device.notify_subscribers(
+            c9, CustomEnum.FOO if i % 2 == 0 else CustomEnum.BAR
+        )
+
+        i += 1
+
+
 # -----------------------------------------------------------------------------
 async def main() -> None:
     if len(sys.argv) < 2:
-        print("Usage: run_gatt_with_adapters.py <transport-spec> [<bluetooth-address>]")
-        print("example: run_gatt_with_adapters.py usb:0 E1:CA:72:48:C4:E8")
+        print("Usage: run_gatt_with_adapters.py <transport-spec> client|server")
+        print("example: run_gatt_with_adapters.py usb:0 F0:F1:F2:F3:F4:F5")
         return
 
     async with await transport.open_transport(sys.argv[1]) as hci_transport:
+        is_client = sys.argv[2] == "client"
+
         # Create a device to manage the host
         device = Device.with_hci(
             "Bumble",
-            hci.Address("F0:F1:F2:F3:F4:F5"),
+            hci.Address(
+                DEFAULT_CLIENT_ADDRESS if is_client else DEFAULT_SERVER_ADDRESS
+            ),
             hci_transport.source,
             hci_transport.sink,
         )
 
-        # Static characteristic with a bytes value.
-        c1 = gatt.Characteristic(
-            CHARACTERISTIC_UUID_BASE + "01",
-            gatt.Characteristic.Properties.READ | gatt.Characteristic.Properties.WRITE,
-            gatt.Characteristic.READABLE | gatt.Characteristic.WRITEABLE,
-            b'hello',
-        )
-
-        # Static characteristic with a string value.
-        c2 = gatt.UTF8CharacteristicAdapter(
-            gatt.Characteristic(
-                CHARACTERISTIC_UUID_BASE + "02",
-                gatt.Characteristic.Properties.READ
-                | gatt.Characteristic.Properties.WRITE,
-                gatt.Characteristic.READABLE | gatt.Characteristic.WRITEABLE,
-                'hello',
-            )
-        )
-
-        # Static characteristic with a tuple value.
-        c3 = gatt.PackedCharacteristicAdapter(
-            gatt.Characteristic(
-                CHARACTERISTIC_UUID_BASE + "03",
-                gatt.Characteristic.Properties.READ
-                | gatt.Characteristic.Properties.WRITE,
-                gatt.Characteristic.READABLE | gatt.Characteristic.WRITEABLE,
-                (1007, 1008, 1009),
-            ),
-            ">III",
-        )
-
-        # Static characteristic with a named tuple value.
-        c4 = gatt.MappedCharacteristicAdapter(
-            gatt.Characteristic(
-                CHARACTERISTIC_UUID_BASE + "04",
-                gatt.Characteristic.Properties.READ
-                | gatt.Characteristic.Properties.WRITE,
-                gatt.Characteristic.READABLE | gatt.Characteristic.WRITEABLE,
-                {"f1": 3007, "f2": 3008, "f3": 3009},
-            ),
-            ">III",
-            ["f1", "f2", "f3"],
-        )
-
-        # Static characteristic with a serializable value.
-        c5 = gatt.SerializableCharacteristicAdapter(
-            gatt.Characteristic(
-                CHARACTERISTIC_UUID_BASE + "05",
-                gatt.Characteristic.Properties.READ
-                | gatt.Characteristic.Properties.WRITE,
-                gatt.Characteristic.READABLE | gatt.Characteristic.WRITEABLE,
-                CustomSerializableClass(11, 12),
-            ),
-            CustomSerializableClass,
-        )
-
-        # Static characteristic with a delegated value.
-        c6 = gatt.DelegatedCharacteristicAdapter(
-            gatt.Characteristic(
-                CHARACTERISTIC_UUID_BASE + "06",
-                gatt.Characteristic.Properties.READ
-                | gatt.Characteristic.Properties.WRITE,
-                gatt.Characteristic.READABLE | gatt.Characteristic.WRITEABLE,
-                CustomClass(1, 2),
-            ),
-            encode=CustomClass.encode,
-            decode=CustomClass.decode,
-        )
-
-        # Dynamic characteristic with a bytes value.
-        c7 = gatt.Characteristic(
-            CHARACTERISTIC_UUID_BASE + "07",
-            gatt.Characteristic.Properties.READ | gatt.Characteristic.Properties.WRITE,
-            gatt.Characteristic.READABLE | gatt.Characteristic.WRITEABLE,
-            gatt.CharacteristicValue(
-                read=lambda connection: dynamic_read("bytes"),
-                write=lambda connection, value: dynamic_write("bytes", value),
-            ),
-        )
-
-        # Dynamic characteristic with a string value.
-        c8 = gatt.UTF8CharacteristicAdapter(
-            gatt.Characteristic(
-                CHARACTERISTIC_UUID_BASE + "08",
-                gatt.Characteristic.Properties.READ
-                | gatt.Characteristic.Properties.WRITE,
-                gatt.Characteristic.READABLE | gatt.Characteristic.WRITEABLE,
-                gatt.CharacteristicValue(
-                    read=lambda connection: dynamic_read("string"),
-                    write=lambda connection, value: dynamic_write("string", value),
-                ),
-            )
-        )
-
-        characteristics: List[
-            Union[gatt.Characteristic, gatt.CharacteristicAdapter]
-        ] = [c1, c2, c3, c4, c5, c6, c7, c8]
-
-        # Listen for read and write events.
-        for characteristic in characteristics:
-            characteristic.on(
-                "read",
-                lambda _, value, c=characteristic: on_characteristic_read(c, value),
-            )
-            characteristic.on(
-                "write",
-                lambda _, value, c=characteristic: on_characteristic_write(c, value),
-            )
-
-        device.add_service(gatt.Service(SERVICE_UUID, characteristics))  # type: ignore
-
         # Get things going
         await device.power_on()
 
-        # Connect to a peer
-        if len(sys.argv) > 2:
-            await client(device, hci.Address(sys.argv[2]))
+        if is_client:
+            # Connect a client to a peer
+            await client(device, hci.Address(DEFAULT_SERVER_ADDRESS))
         else:
+            # Advertise so a peer can connect
             await device.start_advertising(auto_restart=True)
 
+            # Setup a server
+            await server(device)
+
         await hci_transport.source.wait_for_termination()
 
 

examples/run_vcp_renderer.py

@@ -42,7 +42,7 @@ from bumble.profiles.bap import (
 from bumble.profiles.pacs import PacRecord, PublishedAudioCapabilitiesService
 from bumble.profiles.cap import CommonAudioServiceService
 from bumble.profiles.csip import CoordinatedSetIdentificationService, SirkType
-from bumble.profiles.vcp import VolumeControlService
+from bumble.profiles.vcs import VolumeControlService
 
 from bumble.transport import open_transport_or_link
 
@@ -117,13 +117,17 @@ async def main() -> None:
 
         ws: Optional[websockets.WebSocketServerProtocol] = None
 
-        def on_volume_state(volume_setting: int, muted: int, change_counter: int):
+        def on_volume_state_change():
             if ws:
                 asyncio.create_task(
-                    ws.send(dumps_volume_state(volume_setting, muted, change_counter))
+                    ws.send(
+                        dumps_volume_state(
+                            vcs.volume_setting, vcs.muted, vcs.change_counter
+                        )
+                    )
                 )
 
-        vcs.on('volume_state', on_volume_state)
+        vcs.on('volume_state_change', on_volume_state_change)
 
         advertising_data = (
             bytes(
@@ -170,16 +174,10 @@ async def main() -> None:
             ws = websocket
             async for message in websocket:
                 volume_state = json.loads(message)
-                vcs.volume_state_bytes = bytes(
-                    [
-                        volume_state['volume_setting'],
-                        volume_state['muted'],
-                        volume_state['change_counter'],
-                    ]
-                )
-                await device.notify_subscribers(
-                    vcs.volume_state, vcs.volume_state_bytes
-                )
+                vcs.volume_setting = volume_state['volume_setting']
+                vcs.muted = volume_state['muted']
+                vcs.change_counter = volume_state['change_counter']
+                await device.notify_subscribers(vcs.volume_state)
             ws = None
 
         await websockets.serve(serve, 'localhost', 8989)

extras/android/BtBench/app/build.gradle.kts

@@ -10,7 +10,7 @@ android {
 
     defaultConfig {
         applicationId = "com.github.google.bumble.btbench"
-        minSdk = 30
+        minSdk = 33
         targetSdk = 34
         versionCode = 1
         versionName = "1.0"

extras/android/BtBench/app/src/main/AndroidManifest.xml

@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="utf-8"?>
 <manifest xmlns:android="http://schemas.android.com/apk/res/android"
     package="com.github.google.bumble.btbench">
-     <uses-sdk android:minSdkVersion="30" android:targetSdkVersion="34" />
+     <uses-sdk android:minSdkVersion="33" android:targetSdkVersion="34" />
     <!-- Request legacy Bluetooth permissions on older devices. -->
     <uses-permission android:name="android.permission.BLUETOOTH" android:maxSdkVersion="30" />
     <uses-permission android:name="android.permission.BLUETOOTH_ADMIN" android:maxSdkVersion="30" />
@@ -9,6 +9,8 @@
     <uses-permission android:name="android.permission.BLUETOOTH_SCAN" android:usesPermissionFlags="neverForLocation"/>
     <uses-permission android:name="android.permission.BLUETOOTH_ADVERTISE" />
     <uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
+    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
+    <uses-permission android:name="android.permission.INTERNET" />
 
     <uses-feature android:name="android.hardware.bluetooth" android:required="true"/>
     <uses-feature android:name="android.hardware.bluetooth_le" android:required="true"/>

extras/android/BtBench/app/src/main/java/com/github/google/bumble/btbench/Advertiser.kt

@@ -0,0 +1,39 @@
+package com.github.google.bumble.btbench
+
+import android.annotation.SuppressLint
+import android.bluetooth.BluetoothAdapter
+import android.bluetooth.le.AdvertiseCallback
+import android.bluetooth.le.AdvertiseData
+import android.bluetooth.le.AdvertiseSettings
+import android.bluetooth.le.AdvertiseSettings.ADVERTISE_MODE_LOW_LATENCY
+import android.os.Build
+import java.util.logging.Logger
+
+private val Log = Logger.getLogger("btbench.advertiser")
+
+class Advertiser(private val bluetoothAdapter: BluetoothAdapter) : AdvertiseCallback() {
+    @SuppressLint("MissingPermission")
+    fun start() {
+        val advertiseSettingsBuilder = AdvertiseSettings.Builder()
+            .setAdvertiseMode(ADVERTISE_MODE_LOW_LATENCY)
+            .setConnectable(true)
+        advertiseSettingsBuilder.setDiscoverable(true)
+        val advertiseSettings = advertiseSettingsBuilder.build()
+        val advertiseData = AdvertiseData.Builder().build()
+        val scanData = AdvertiseData.Builder().setIncludeDeviceName(true).build()
+        bluetoothAdapter.bluetoothLeAdvertiser.startAdvertising(advertiseSettings, advertiseData, scanData, this)
+    }
+
+    @SuppressLint("MissingPermission")
+    fun stop() {
+        bluetoothAdapter.bluetoothLeAdvertiser.stopAdvertising(this)
+    }
+
+    override fun onStartFailure(errorCode: Int) {
+        Log.warning("failed to start advertising: $errorCode")
+    }
+
+    override fun onStartSuccess(settingsInEffect: AdvertiseSettings) {
+        Log.info("advertising started: $settingsInEffect")
+    }
+}

extras/android/BtBench/app/src/main/java/com/github/google/bumble/btbench/AutomationSnippet.java

@@ -22,11 +22,13 @@ import androidx.test.core.app.ApplicationProvider;
 
 import com.google.android.mobly.snippet.Snippet;
 import com.google.android.mobly.snippet.rpc.Rpc;
+import com.google.android.mobly.snippet.rpc.RpcOptional;
 
 import org.json.JSONArray;
 import org.json.JSONException;
 import org.json.JSONObject;
 
+import java.io.IOException;
 import java.security.InvalidParameterException;
 import java.util.ArrayList;
 import java.util.UUID;
@@ -71,12 +73,15 @@ public class AutomationSnippet implements Snippet {
     private final Context mContext;
     private final ArrayList<Runner> mRunners = new ArrayList<>();
 
-    public AutomationSnippet() {
+    public AutomationSnippet() throws IOException {
         mContext = ApplicationProvider.getApplicationContext();
         BluetoothManager bluetoothManager = mContext.getSystemService(BluetoothManager.class);
         mBluetoothAdapter = bluetoothManager.getAdapter();
         if (mBluetoothAdapter == null) {
-            throw new RuntimeException("bluetooth not supported");
+            throw new IOException("bluetooth not supported");
+        }
+        if (!mBluetoothAdapter.isEnabled()) {
+            throw new IOException("bluetooth not enabled");
         }
     }
 
@@ -85,32 +90,46 @@ public class AutomationSnippet implements Snippet {
         switch (mode) {
             case "rfcomm-client":
                 runnable = new RfcommClient(model, mBluetoothAdapter,
-                                          (PacketIO packetIO) -> createIoClient(model, scenario,
-                                                                                packetIO));
+                                            (PacketIO packetIO) -> createIoClient(model, scenario,
+                                                                                  packetIO));
                 break;
 
             case "rfcomm-server":
                 runnable = new RfcommServer(model, mBluetoothAdapter,
-                                          (PacketIO packetIO) -> createIoClient(model, scenario,
-                                                                                packetIO));
+                                            (PacketIO packetIO) -> createIoClient(model, scenario,
+                                                                                  packetIO));
                 break;
 
             case "l2cap-client":
                 runnable = new L2capClient(model, mBluetoothAdapter, mContext,
-                                         (PacketIO packetIO) -> createIoClient(model, scenario,
-                                                                               packetIO));
+                                           (PacketIO packetIO) -> createIoClient(model, scenario,
+                                                                                 packetIO));
                 break;
 
             case "l2cap-server":
                 runnable = new L2capServer(model, mBluetoothAdapter,
-                                         (PacketIO packetIO) -> createIoClient(model, scenario,
-                                                                               packetIO));
+                                           (PacketIO packetIO) -> createIoClient(model, scenario,
+                                                                                 packetIO));
+                break;
+
+            case "gatt-client":
+                runnable = new GattClient(model, mBluetoothAdapter, mContext,
+                                          (PacketIO packetIO) -> createIoClient(model, scenario,
+                                                                                packetIO));
+                break;
+
+            case "gatt-server":
+                runnable = new GattServer(model, mBluetoothAdapter, mContext,
+                                          (PacketIO packetIO) -> createIoClient(model, scenario,
+                                                                                packetIO));
                 break;
 
             default:
                 return null;
         }
 
+        model.setMode(mode);
+        model.setScenario(scenario);
         runnable.run();
         Runner runner = new Runner(runnable, mode, scenario, model);
         mRunners.add(runner);
@@ -140,7 +159,21 @@ public class AutomationSnippet implements Snippet {
         JSONObject result = new JSONObject();
         result.put("status", model.getStatus());
         result.put("running", model.getRunning());
+        result.put("peer_bluetooth_address", model.getPeerBluetoothAddress());
+        result.put("mode", model.getMode());
+        result.put("scenario", model.getScenario());
+        result.put("sender_packet_size", model.getSenderPacketSize());
+        result.put("sender_packet_count", model.getSenderPacketCount());
+        result.put("sender_packet_interval", model.getSenderPacketInterval());
+        result.put("packets_sent", model.getPacketsSent());
+        result.put("packets_received", model.getPacketsReceived());
         result.put("l2cap_psm", model.getL2capPsm());
+        result.put("use_2m_phy", model.getUse2mPhy());
+        result.put("connection_priority", model.getConnectionPriority());
+        result.put("mtu", model.getMtu());
+        result.put("rx_phy", model.getRxPhy());
+        result.put("tx_phy", model.getTxPhy());
+        result.put("startup_delay", model.getStartupDelay());
         if (model.getStatus().equals("OK")) {
             JSONObject stats = new JSONObject();
             result.put("stats", stats);
@@ -167,12 +200,12 @@ public class AutomationSnippet implements Snippet {
 
     @Rpc(description = "Run a scenario in RFComm Client mode")
     public JSONObject runRfcommClient(String scenario, String peerBluetoothAddress, int packetCount,
-                                      int packetSize, int packetInterval) throws JSONException {
-        assert (mBluetoothAdapter != null);
-
+                                      int packetSize, int packetInterval,
+                                      @RpcOptional Integer startupDelay) throws JSONException {
         // We only support "send" and "ping" for this mode for now
         if (!(scenario.equals("send") || scenario.equals("ping"))) {
-            throw new InvalidParameterException("only 'send' and 'ping' are supported for this mode");
+            throw new InvalidParameterException(
+                    "only 'send' and 'ping' are supported for this mode");
         }
 
         AppViewModel model = new AppViewModel();
@@ -180,6 +213,9 @@ public class AutomationSnippet implements Snippet {
         model.setSenderPacketCount(packetCount);
         model.setSenderPacketSize(packetSize);
         model.setSenderPacketInterval(packetInterval);
+        if (startupDelay != null) {
+            model.setStartupDelay(startupDelay);
+        }
 
         Runner runner = runScenario(model, "rfcomm-client", scenario);
         assert runner != null;
@@ -187,15 +223,18 @@ public class AutomationSnippet implements Snippet {
     }
 
     @Rpc(description = "Run a scenario in RFComm Server mode")
-    public JSONObject runRfcommServer(String scenario) throws JSONException {
-        assert (mBluetoothAdapter != null);
-
+    public JSONObject runRfcommServer(String scenario,
+                                      @RpcOptional Integer startupDelay) throws JSONException {
         // We only support "receive" and "pong" for this mode for now
         if (!(scenario.equals("receive") || scenario.equals("pong"))) {
-            throw new InvalidParameterException("only 'receive' and 'pong' are supported for this mode");
+            throw new InvalidParameterException(
+                    "only 'receive' and 'pong' are supported for this mode");
         }
 
         AppViewModel model = new AppViewModel();
+        if (startupDelay != null) {
+            model.setStartupDelay(startupDelay);
+        }
 
         Runner runner = runScenario(model, "rfcomm-server", scenario);
         assert runner != null;
@@ -205,12 +244,12 @@ public class AutomationSnippet implements Snippet {
     @Rpc(description = "Run a scenario in L2CAP Client mode")
     public JSONObject runL2capClient(String scenario, String peerBluetoothAddress, int psm,
                                      boolean use_2m_phy, int packetCount, int packetSize,
-                                     int packetInterval) throws JSONException {
-        assert (mBluetoothAdapter != null);
-
+                                     int packetInterval, @RpcOptional String connectionPriority,
+                                     @RpcOptional Integer startupDelay) throws JSONException {
         // We only support "send" and "ping" for this mode for now
         if (!(scenario.equals("send") || scenario.equals("ping"))) {
-            throw new InvalidParameterException("only 'send' and 'ping' are supported for this mode");
+            throw new InvalidParameterException(
+                    "only 'send' and 'ping' are supported for this mode");
         }
 
         AppViewModel model = new AppViewModel();
@@ -220,28 +259,83 @@ public class AutomationSnippet implements Snippet {
         model.setSenderPacketCount(packetCount);
         model.setSenderPacketSize(packetSize);
         model.setSenderPacketInterval(packetInterval);
-
+        if (connectionPriority != null) {
+            model.setConnectionPriority(connectionPriority);
+        }
+        if (startupDelay != null) {
+            model.setStartupDelay(startupDelay);
+        }
         Runner runner = runScenario(model, "l2cap-client", scenario);
         assert runner != null;
         return runner.toJson();
     }
 
     @Rpc(description = "Run a scenario in L2CAP Server mode")
-    public JSONObject runL2capServer(String scenario) throws JSONException {
-        assert (mBluetoothAdapter != null);
-
+    public JSONObject runL2capServer(String scenario,
+                                     @RpcOptional Integer startupDelay) throws JSONException {
         // We only support "receive" and "pong" for this mode for now
         if (!(scenario.equals("receive") || scenario.equals("pong"))) {
-            throw new InvalidParameterException("only 'receive' and 'pong' are supported for this mode");
+            throw new InvalidParameterException(
+                    "only 'receive' and 'pong' are supported for this mode");
         }
 
         AppViewModel model = new AppViewModel();
+        if (startupDelay != null) {
+            model.setStartupDelay(startupDelay);
+        }
 
         Runner runner = runScenario(model, "l2cap-server", scenario);
         assert runner != null;
         return runner.toJson();
     }
 
+    @Rpc(description = "Run a scenario in GATT Client mode")
+    public JSONObject runGattClient(String scenario, String peerBluetoothAddress,
+                                    boolean use_2m_phy, int packetCount, int packetSize,
+                                    int packetInterval, @RpcOptional String connectionPriority,
+                                    @RpcOptional Integer startupDelay) throws JSONException {
+        // We only support "send" and "ping" for this mode for now
+        if (!(scenario.equals("send") || scenario.equals("ping"))) {
+            throw new InvalidParameterException(
+                    "only 'send' and 'ping' are supported for this mode");
+        }
+
+        AppViewModel model = new AppViewModel();
+        model.setPeerBluetoothAddress(peerBluetoothAddress);
+        model.setUse2mPhy(use_2m_phy);
+        model.setSenderPacketCount(packetCount);
+        model.setSenderPacketSize(packetSize);
+        model.setSenderPacketInterval(packetInterval);
+        if (connectionPriority != null) {
+            model.setConnectionPriority(connectionPriority);
+        }
+        if (startupDelay != null) {
+            model.setStartupDelay(startupDelay);
+        }
+        Runner runner = runScenario(model, "gatt-client", scenario);
+        assert runner != null;
+        return runner.toJson();
+    }
+
+    @Rpc(description = "Run a scenario in GATT Server mode")
+    public JSONObject runGattServer(String scenario,
+                                    @RpcOptional Integer startupDelay) throws JSONException {
+        // We only support "receive" and "pong" for this mode for now
+        if (!(scenario.equals("receive") || scenario.equals("pong"))) {
+            throw new InvalidParameterException(
+                    "only 'receive' and 'pong' are supported for this mode");
+        }
+
+        AppViewModel model = new AppViewModel();
+        if (startupDelay != null) {
+            model.setStartupDelay(startupDelay);
+        }
+
+        Runner runner = runScenario(model, "gatt-server", scenario);
+        assert runner != null;
+        return runner.toJson();
+    }
+
     @Rpc(description = "Stop a Runner")
     public JSONObject stopRunner(String runnerId) throws JSONException {
         Runner runner = findRunner(runnerId);
@@ -276,7 +370,7 @@ public class AutomationSnippet implements Snippet {
         JSONObject result = new JSONObject();
         JSONArray runners = new JSONArray();
         result.put("runners", runners);
-        for (Runner runner: mRunners) {
+        for (Runner runner : mRunners) {
             runners.put(runner.toJson());
         }
 

extras/android/BtBench/app/src/main/java/com/github/google/bumble/btbench/Connection.kt

@@ -0,0 +1,109 @@
+package com.github.google.bumble.btbench
+
+import android.annotation.SuppressLint
+import android.bluetooth.BluetoothAdapter
+import android.bluetooth.BluetoothDevice
+import android.bluetooth.BluetoothGatt
+import android.bluetooth.BluetoothGattCallback
+import android.bluetooth.BluetoothManager
+import android.bluetooth.BluetoothProfile
+import android.content.Context
+import android.os.Build
+import androidx.core.content.ContextCompat
+import java.util.logging.Logger
+
+private val Log = Logger.getLogger("btbench.connection")
+
+open class Connection(
+    private val viewModel: AppViewModel,
+    private val bluetoothAdapter: BluetoothAdapter,
+    private val context: Context
+) : BluetoothGattCallback() {
+    var remoteDevice: BluetoothDevice? = null
+    var gatt: BluetoothGatt? = null
+
+    @SuppressLint("MissingPermission")
+    open fun connect() {
+        val addressIsPublic = viewModel.peerBluetoothAddress.endsWith("/P")
+        val address = viewModel.peerBluetoothAddress.take(17)
+        remoteDevice = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
+            bluetoothAdapter.getRemoteLeDevice(
+                address,
+                if (addressIsPublic) {
+                    BluetoothDevice.ADDRESS_TYPE_PUBLIC
+                } else {
+                    BluetoothDevice.ADDRESS_TYPE_RANDOM
+                }
+            )
+        } else {
+            bluetoothAdapter.getRemoteDevice(address)
+        }
+
+        gatt = remoteDevice?.connectGatt(
+            context,
+            false,
+            this,
+            BluetoothDevice.TRANSPORT_LE,
+            if (viewModel.use2mPhy) BluetoothDevice.PHY_LE_2M_MASK else BluetoothDevice.PHY_LE_1M_MASK
+        )
+    }
+
+    @SuppressLint("MissingPermission")
+    open fun disconnect() {
+        gatt?.disconnect()
+    }
+
+    override fun onMtuChanged(gatt: BluetoothGatt, mtu: Int, status: Int) {
+        Log.info("MTU update: mtu=$mtu status=$status")
+        viewModel.mtu = mtu
+    }
+
+    override fun onPhyUpdate(gatt: BluetoothGatt, txPhy: Int, rxPhy: Int, status: Int) {
+        Log.info("PHY update: tx=$txPhy, rx=$rxPhy, status=$status")
+        viewModel.txPhy = txPhy
+        viewModel.rxPhy = rxPhy
+    }
+
+    override fun onPhyRead(gatt: BluetoothGatt, txPhy: Int, rxPhy: Int, status: Int) {
+        Log.info("PHY: tx=$txPhy, rx=$rxPhy, status=$status")
+        viewModel.txPhy = txPhy
+        viewModel.rxPhy = rxPhy
+    }
+
+    @SuppressLint("MissingPermission")
+    override fun onConnectionStateChange(
+        gatt: BluetoothGatt?, status: Int, newState: Int
+    ) {
+        if (status != BluetoothGatt.GATT_SUCCESS) {
+            Log.warning("onConnectionStateChange status=$status")
+        }
+
+        if (gatt != null && newState == BluetoothProfile.STATE_CONNECTED) {
+            if (viewModel.use2mPhy) {
+                Log.info("requesting 2M PHY")
+                gatt.setPreferredPhy(
+                    BluetoothDevice.PHY_LE_2M_MASK,
+                    BluetoothDevice.PHY_LE_2M_MASK,
+                    BluetoothDevice.PHY_OPTION_NO_PREFERRED
+                )
+            }
+            gatt.readPhy()
+
+            // Request an MTU update, even though we don't use GATT, because Android
+            // won't request a larger link layer maximum data length otherwise.
+            gatt.requestMtu(517)
+
+            // Request a specific connection priority
+            val connectionPriority = when (viewModel.connectionPriority) {
+                "BALANCED" -> BluetoothGatt.CONNECTION_PRIORITY_BALANCED
+                "LOW_POWER" -> BluetoothGatt.CONNECTION_PRIORITY_LOW_POWER
+                "HIGH" -> BluetoothGatt.CONNECTION_PRIORITY_HIGH
+                "DCK" -> BluetoothGatt.CONNECTION_PRIORITY_DCK
+                else -> 0
+            }
+            if (!gatt.requestConnectionPriority(connectionPriority)) {
+                Log.warning("requestConnectionPriority failed")
+            }
+        }
+    }
+}

extras/android/BtBench/app/src/main/java/com/github/google/bumble/btbench/Gatt.kt

@@ -0,0 +1,23 @@
+// Copyright 2024 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package com.github.google.bumble.btbench
+
+import java.util.UUID
+
+var CCCD_UUID = UUID.fromString("00002902-0000-1000-8000-00805F9B34FB")
+
+val BENCH_SERVICE_UUID = UUID.fromString("50DB505C-8AC4-4738-8448-3B1D9CC09CC5")
+val BENCH_TX_UUID = UUID.fromString("E789C754-41A1-45F4-A948-A0A1A90DBA53")
+val BENCH_RX_UUID = UUID.fromString("016A2CC7-E14B-4819-935F-1F56EAE4098D")

extras/android/BtBench/app/src/main/java/com/github/google/bumble/btbench/GattClient.kt

@@ -0,0 +1,224 @@
+// Copyright 2024 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package com.github.google.bumble.btbench
+
+import android.annotation.SuppressLint
+import android.bluetooth.BluetoothAdapter
+import android.bluetooth.BluetoothGatt
+import android.bluetooth.BluetoothGattCharacteristic
+import android.bluetooth.BluetoothGattDescriptor
+import android.bluetooth.BluetoothProfile
+import android.content.Context
+import java.io.IOException
+import java.util.UUID
+import java.util.concurrent.CountDownLatch
+import java.util.concurrent.Semaphore
+import java.util.logging.Logger
+import kotlin.concurrent.thread
+
+private val Log = Logger.getLogger("btbench.gatt-client")
+
+
+class GattClientConnection(
+    viewModel: AppViewModel,
+    bluetoothAdapter: BluetoothAdapter,
+    context: Context
+) : Connection(viewModel, bluetoothAdapter, context), PacketIO {
+    override var packetSink: PacketSink? = null
+    private val discoveryDone: CountDownLatch = CountDownLatch(1)
+    private val writeSemaphore: Semaphore = Semaphore(1)
+    var rxCharacteristic: BluetoothGattCharacteristic? = null
+    var txCharacteristic: BluetoothGattCharacteristic? = null
+
+    override fun connect() {
+        super.connect()
+
+        // Check if we're already connected and have discovered the services
+        if (gatt?.getService(BENCH_SERVICE_UUID) != null) {
+            Log.fine("already connected")
+            onServicesDiscovered(gatt, BluetoothGatt.GATT_SUCCESS)
+        }
+    }
+
+    @SuppressLint("MissingPermission")
+    override fun onConnectionStateChange(
+        gatt: BluetoothGatt?, status: Int, newState: Int
+    ) {
+        super.onConnectionStateChange(gatt, status, newState)
+        if (status != BluetoothGatt.GATT_SUCCESS) {
+            Log.warning("onConnectionStateChange status=$status")
+            discoveryDone.countDown()
+            return
+        }
+        if (gatt != null && newState == BluetoothProfile.STATE_CONNECTED) {
+            if (!gatt.discoverServices()) {
+                Log.warning("discoverServices could not start")
+                discoveryDone.countDown()
+            }
+        }
+    }
+
+    @SuppressLint("MissingPermission")
+    override fun onServicesDiscovered(gatt: BluetoothGatt?, status: Int) {
+        Log.fine("onServicesDiscovered")
+
+        if (status != BluetoothGatt.GATT_SUCCESS) {
+            Log.warning("failed to discover services: ${status}")
+            discoveryDone.countDown()
+            return
+        }
+
+        // Find the service
+        val service = gatt!!.getService(BENCH_SERVICE_UUID)
+        if (service == null) {
+            Log.warning("GATT Service not found")
+            discoveryDone.countDown()
+            return
+        }
+
+        // Find the RX and TX characteristics
+        rxCharacteristic = service.getCharacteristic(BENCH_RX_UUID)
+        if (rxCharacteristic == null) {
+            Log.warning("GATT RX Characteristics not found")
+            discoveryDone.countDown()
+            return
+        }
+        txCharacteristic = service.getCharacteristic(BENCH_TX_UUID)
+        if (txCharacteristic == null) {
+            Log.warning("GATT TX Characteristics not found")
+            discoveryDone.countDown()
+            return
+        }
+
+        // Subscribe to the RX characteristic
+        Log.fine("subscribing to RX")
+        gatt.setCharacteristicNotification(rxCharacteristic, true)
+        val cccdDescriptor = rxCharacteristic!!.getDescriptor(CCCD_UUID)
+        gatt.writeDescriptor(cccdDescriptor, BluetoothGattDescriptor.ENABLE_NOTIFICATION_VALUE);
+
+        Log.info("GATT discovery complete")
+        discoveryDone.countDown()
+    }
+
+    override fun onCharacteristicWrite(
+        gatt: BluetoothGatt?,
+        characteristic: BluetoothGattCharacteristic?,
+        status: Int
+    ) {
+        // Now we can write again
+        writeSemaphore.release()
+
+        if (status != BluetoothGatt.GATT_SUCCESS) {
+            Log.warning("onCharacteristicWrite failed: $status")
+            return
+        }
+    }
+
+    override fun onCharacteristicChanged(
+        gatt: BluetoothGatt,
+        characteristic: BluetoothGattCharacteristic,
+        value: ByteArray
+    ) {
+        if (characteristic.uuid == BENCH_RX_UUID && packetSink != null) {
+            val packet = Packet.from(value)
+            packetSink!!.onPacket(packet)
+        }
+    }
+
+    @SuppressLint("MissingPermission")
+    override fun sendPacket(packet: Packet) {
+        if (txCharacteristic == null) {
+            Log.warning("No TX characteristic, dropping")
+            return
+        }
+
+        // Wait until we can write
+        writeSemaphore.acquire()
+
+        // Write the data
+        val data = packet.toBytes()
+        val clampedData = if (data.size > 512) {
+            // Clamp the data to the maximum allowed characteristic data size
+            data.copyOf(512)
+        } else {
+            data
+        }
+        gatt?.writeCharacteristic(
+            txCharacteristic!!,
+            clampedData,
+            BluetoothGattCharacteristic.WRITE_TYPE_NO_RESPONSE
+        )
+    }
+
+    override
+    fun disconnect() {
+        super.disconnect()
+        discoveryDone.countDown()
+    }
+
+    fun waitForDiscoveryCompletion() {
+        discoveryDone.await()
+    }
+}
+
+class GattClient(
+    private val viewModel: AppViewModel,
+    bluetoothAdapter: BluetoothAdapter,
+    context: Context,
+    private val createIoClient: (packetIo: PacketIO) -> IoClient
+) : Mode {
+    private var connection: GattClientConnection =
+        GattClientConnection(viewModel, bluetoothAdapter, context)
+    private var clientThread: Thread? = null
+
+    @SuppressLint("MissingPermission")
+    override fun run() {
+        viewModel.running = true
+
+        clientThread = thread(name = "GattClient") {
+            connection.connect()
+
+            viewModel.aborter = {
+                connection.disconnect()
+            }
+
+            // Discover the rx and tx characteristics
+            connection.waitForDiscoveryCompletion()
+            if (connection.rxCharacteristic == null || connection.txCharacteristic == null) {
+                connection.disconnect()
+                viewModel.running = false
+                return@thread
+            }
+
+            val ioClient = createIoClient(connection)
+
+            try {
+                ioClient.run()
+                viewModel.status = "OK"
+            } catch (error: IOException) {
+                Log.info("run ended abruptly")
+                viewModel.status = "ABORTED"
+                viewModel.lastError = "IO_ERROR"
+            } finally {
+                connection.disconnect()
+                viewModel.running = false
+            }
+        }
+    }
+
+    override fun waitForCompletion() {
+        clientThread?.join()
+    }
+}

extras/android/BtBench/app/src/main/java/com/github/google/bumble/btbench/GattServer.kt

@@ -0,0 +1,243 @@
+// Copyright 2024 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package com.github.google.bumble.btbench
+
+import android.annotation.SuppressLint
+import android.bluetooth.BluetoothAdapter
+import android.bluetooth.BluetoothDevice
+import android.bluetooth.BluetoothGatt
+import android.bluetooth.BluetoothGattCharacteristic
+import android.bluetooth.BluetoothGattDescriptor
+import android.bluetooth.BluetoothGattServer
+import android.bluetooth.BluetoothGattServerCallback
+import android.bluetooth.BluetoothGattService
+import android.bluetooth.BluetoothManager
+import android.bluetooth.BluetoothStatusCodes
+import android.content.Context
+import androidx.core.content.ContextCompat
+import java.io.IOException
+import java.util.concurrent.CountDownLatch
+import java.util.concurrent.LinkedBlockingQueue
+import java.util.concurrent.Semaphore
+import java.util.logging.Logger
+import kotlin.concurrent.thread
+import kotlin.experimental.and
+
+private val Log = Logger.getLogger("btbench.gatt-server")
+
+@SuppressLint("MissingPermission")
+class GattServer(
+    private val viewModel: AppViewModel,
+    private val bluetoothAdapter: BluetoothAdapter,
+    context: Context,
+    private val createIoClient: (packetIo: PacketIO) -> IoClient
+) : Mode, PacketIO, BluetoothGattServerCallback() {
+    override var packetSink: PacketSink? = null
+    private val gattServer: BluetoothGattServer
+    private val rxCharacteristic: BluetoothGattCharacteristic?
+    private val txCharacteristic: BluetoothGattCharacteristic?
+    private val notifySemaphore: Semaphore = Semaphore(1)
+    private val ready: CountDownLatch = CountDownLatch(1)
+    private var peerDevice: BluetoothDevice? = null
+    private var clientThread: Thread? = null
+    private var sinkQueue: LinkedBlockingQueue<Packet>? = null
+
+    init {
+        val bluetoothManager = ContextCompat.getSystemService(context, BluetoothManager::class.java)
+        gattServer = bluetoothManager!!.openGattServer(context, this)
+        val benchService = gattServer.getService(BENCH_SERVICE_UUID)
+        if (benchService == null) {
+            rxCharacteristic = BluetoothGattCharacteristic(
+                BENCH_RX_UUID,
+                BluetoothGattCharacteristic.PROPERTY_NOTIFY,
+                0
+            )
+            txCharacteristic = BluetoothGattCharacteristic(
+                BENCH_TX_UUID,
+                BluetoothGattCharacteristic.PROPERTY_WRITE_NO_RESPONSE,
+                BluetoothGattCharacteristic.PERMISSION_WRITE
+            )
+            val rxCCCD = BluetoothGattDescriptor(
+                CCCD_UUID,
+                BluetoothGattDescriptor.PERMISSION_READ or BluetoothGattDescriptor.PERMISSION_WRITE
+            )
+            rxCharacteristic.addDescriptor(rxCCCD)
+
+            val service =
+                BluetoothGattService(BENCH_SERVICE_UUID, BluetoothGattService.SERVICE_TYPE_PRIMARY)
+            service.addCharacteristic(rxCharacteristic)
+            service.addCharacteristic(txCharacteristic)
+
+            gattServer.addService(service)
+        } else {
+            rxCharacteristic = benchService.getCharacteristic(BENCH_RX_UUID)
+            txCharacteristic = benchService.getCharacteristic(BENCH_TX_UUID)
+        }
+    }
+
+    override fun onCharacteristicWriteRequest(
+        device: BluetoothDevice?,
+        requestId: Int,
+        characteristic: BluetoothGattCharacteristic?,
+        preparedWrite: Boolean,
+        responseNeeded: Boolean,
+        offset: Int,
+        value: ByteArray?
+    ) {
+        Log.info("onCharacteristicWriteRequest")
+        if (characteristic != null && characteristic.uuid == BENCH_TX_UUID) {
+            if (packetSink == null) {
+                Log.warning("no sink, dropping")
+            } else if (offset != 0) {
+                Log.warning("offset != 0")
+            } else if (value == null) {
+                Log.warning("no value")
+            } else {
+                // Deliver the packet in a separate thread so that we don't block this
+                // callback.
+                sinkQueue?.put(Packet.from(value))
+            }
+        }
+
+        if (responseNeeded) {
+            gattServer.sendResponse(device, requestId, BluetoothGatt.GATT_SUCCESS, offset, value)
+        }
+    }
+
+    override fun onNotificationSent(device: BluetoothDevice?, status: Int) {
+        if (status == BluetoothGatt.GATT_SUCCESS) {
+            notifySemaphore.release()
+        }
+    }
+
+    override fun onDescriptorWriteRequest(
+        device: BluetoothDevice?,
+        requestId: Int,
+        descriptor: BluetoothGattDescriptor?,
+        preparedWrite: Boolean,
+        responseNeeded: Boolean,
+        offset: Int,
+        value: ByteArray?
+    ) {
+        if (descriptor?.uuid == CCCD_UUID && descriptor?.characteristic?.uuid == BENCH_RX_UUID) {
+            if (offset == 0 && value?.size == 2) {
+                if (value[0].and(1).toInt() != 0) {
+                    // Subscription
+                    Log.fine("peer subscribed to RX")
+                    peerDevice = device
+                    ready.countDown()
+                }
+            }
+        }
+
+        if (responseNeeded) {
+            gattServer.sendResponse(device, requestId, BluetoothGatt.GATT_SUCCESS, offset, value)
+        }
+    }
+
+    @SuppressLint("MissingPermission")
+    override fun sendPacket(packet: Packet) {
+        if (peerDevice == null) {
+            Log.warning("no peer device, cannot send")
+            return
+        }
+        if (rxCharacteristic == null) {
+            Log.warning("no RX characteristic, cannot send")
+            return
+        }
+
+        // Wait until we can notify
+        notifySemaphore.acquire()
+
+        // Send the packet via a notification
+        val result = gattServer.notifyCharacteristicChanged(
+            peerDevice!!,
+            rxCharacteristic,
+            false,
+            packet.toBytes()
+        )
+        if (result != BluetoothStatusCodes.SUCCESS) {
+            Log.warning("notifyCharacteristicChanged failed: $result")
+            notifySemaphore.release()
+        }
+    }
+
+    override fun run() {
+        viewModel.running = true
+
+        // Start advertising
+        Log.fine("starting advertiser")
+        val advertiser = Advertiser(bluetoothAdapter)
+        advertiser.start()
+
+        clientThread = thread(name = "GattServer") {
+            // Wait for a subscriber
+            Log.info("waiting for RX subscriber")
+            viewModel.aborter = {
+                ready.countDown()
+            }
+            ready.await()
+            if (peerDevice == null) {
+                Log.warning("server interrupted")
+                viewModel.running = false
+                gattServer.close()
+                return@thread
+            }
+            Log.info("RX subscriber accepted")
+
+            // Stop advertising
+            Log.info("stopping advertiser")
+            advertiser.stop()
+
+            sinkQueue = LinkedBlockingQueue()
+            val sinkWriterThread = thread(name = "SinkWriter") {
+                while (true) {
+                    try {
+                        val packet = sinkQueue!!.take()
+                        if (packetSink == null) {
+                            Log.warning("no sink, dropping packet")
+                            continue
+                        }
+                        packetSink!!.onPacket(packet)
+                    } catch (error: InterruptedException) {
+                        Log.warning("sink writer interrupted")
+                        break
+                    }
+                }
+            }
+
+            val ioClient = createIoClient(this)
+
+            try {
+                ioClient.run()
+                viewModel.status = "OK"
+            } catch (error: IOException) {
+                Log.info("run ended abruptly")
+                viewModel.status = "ABORTED"
+                viewModel.lastError = "IO_ERROR"
+            } finally {
+                sinkWriterThread.interrupt()
+                sinkWriterThread.join()
+                gattServer.close()
+                viewModel.running = false
+            }
+        }
+    }
+
+    override fun waitForCompletion() {
+        clientThread?.join()
+        Log.info("server thread completed")
+    }
+}

extras/android/BtBench/app/src/main/java/com/github/google/bumble/btbench/L2capClient.kt

@@ -16,89 +16,25 @@ package com.github.google.bumble.btbench
 
 import android.annotation.SuppressLint
 import android.bluetooth.BluetoothAdapter
-import android.bluetooth.BluetoothDevice
-import android.bluetooth.BluetoothGatt
-import android.bluetooth.BluetoothGattCallback
-import android.bluetooth.BluetoothProfile
 import android.content.Context
-import android.os.Build
 import java.util.logging.Logger
 
 private val Log = Logger.getLogger("btbench.l2cap-client")
 
 class L2capClient(
     private val viewModel: AppViewModel,
-    private val bluetoothAdapter: BluetoothAdapter,
-    private val context: Context,
+    bluetoothAdapter: BluetoothAdapter,
+    context: Context,
     private val createIoClient: (packetIo: PacketIO) -> IoClient
 ) : Mode {
+    private var connection: Connection = Connection(viewModel, bluetoothAdapter, context)
     private var socketClient: SocketClient? = null
 
     @SuppressLint("MissingPermission")
     override fun run() {
         viewModel.running = true
-        val addressIsPublic = viewModel.peerBluetoothAddress.endsWith("/P")
-        val address = viewModel.peerBluetoothAddress.take(17)
-        val remoteDevice = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
-            bluetoothAdapter.getRemoteLeDevice(
-                address,
-                if (addressIsPublic) {
-                    BluetoothDevice.ADDRESS_TYPE_PUBLIC
-                } else {
-                    BluetoothDevice.ADDRESS_TYPE_RANDOM
-                }
-            )
-        } else {
-            bluetoothAdapter.getRemoteDevice(address)
-        }
-
-        val gatt = remoteDevice.connectGatt(
-            context,
-            false,
-            object : BluetoothGattCallback() {
-                override fun onMtuChanged(gatt: BluetoothGatt, mtu: Int, status: Int) {
-                    Log.info("MTU update: mtu=$mtu status=$status")
-                    viewModel.mtu = mtu
-                }
-
-                override fun onPhyUpdate(gatt: BluetoothGatt, txPhy: Int, rxPhy: Int, status: Int) {
-                    Log.info("PHY update: tx=$txPhy, rx=$rxPhy, status=$status")
-                    viewModel.txPhy = txPhy
-                    viewModel.rxPhy = rxPhy
-                }
-
-                override fun onPhyRead(gatt: BluetoothGatt, txPhy: Int, rxPhy: Int, status: Int) {
-                    Log.info("PHY: tx=$txPhy, rx=$rxPhy, status=$status")
-                    viewModel.txPhy = txPhy
-                    viewModel.rxPhy = rxPhy
-                }
-
-                override fun onConnectionStateChange(
-                    gatt: BluetoothGatt?, status: Int, newState: Int
-                ) {
-                    if (gatt != null && newState == BluetoothProfile.STATE_CONNECTED) {
-                        if (viewModel.use2mPhy) {
-                            Log.info("requesting 2M PHY")
-                            gatt.setPreferredPhy(
-                                BluetoothDevice.PHY_LE_2M_MASK,
-                                BluetoothDevice.PHY_LE_2M_MASK,
-                                BluetoothDevice.PHY_OPTION_NO_PREFERRED
-                            )
-                        }
-                        gatt.readPhy()
-
-                        // Request an MTU update, even though we don't use GATT, because Android
-                        // won't request a larger link layer maximum data length otherwise.
-                        gatt.requestMtu(517)
-                    }
-                }
-            },
-            BluetoothDevice.TRANSPORT_LE,
-            if (viewModel.use2mPhy) BluetoothDevice.PHY_LE_2M_MASK else BluetoothDevice.PHY_LE_1M_MASK
-        )
-
-        val socket = remoteDevice.createInsecureL2capChannel(viewModel.l2capPsm)
-
+        connection.connect()
+        val socket = connection.remoteDevice!!.createInsecureL2capChannel(viewModel.l2capPsm)
         socketClient = SocketClient(viewModel, socket, createIoClient)
         socketClient!!.run()
     }

extras/android/BtBench/app/src/main/java/com/github/google/bumble/btbench/L2capServer.kt

@@ -37,34 +37,15 @@ class L2capServer(
     @SuppressLint("MissingPermission")
     override fun run() {
         // Advertise so that the peer can find us and connect.
-        val callback = object : AdvertiseCallback() {
-            override fun onStartFailure(errorCode: Int) {
-                Log.warning("failed to start advertising: $errorCode")
-            }
-
-            override fun onStartSuccess(settingsInEffect: AdvertiseSettings) {
-                Log.info("advertising started: $settingsInEffect")
-            }
-        }
-        val advertiseSettingsBuilder = AdvertiseSettings.Builder()
-            .setAdvertiseMode(ADVERTISE_MODE_LOW_LATENCY)
-            .setConnectable(true)
-        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.UPSIDE_DOWN_CAKE) {
-            advertiseSettingsBuilder.setDiscoverable(true)
-        }
-        val advertiseSettings = advertiseSettingsBuilder.build()
-        val advertiseData = AdvertiseData.Builder().build()
-        val scanData = AdvertiseData.Builder().setIncludeDeviceName(true).build()
-        val advertiser = bluetoothAdapter.bluetoothLeAdvertiser
-
+        val advertiser = Advertiser(bluetoothAdapter)
         val serverSocket = bluetoothAdapter.listenUsingInsecureL2capChannel()
         viewModel.l2capPsm = serverSocket.psm
         Log.info("psm = $serverSocket.psm")
 
         socketServer = SocketServer(viewModel, serverSocket, createIoClient)
         socketServer!!.run(
-            { advertiser.stopAdvertising(callback) },
-            { advertiser.startAdvertising(advertiseSettings, advertiseData, scanData, callback) }
+            { advertiser.stop() },
+            { advertiser.start() }
         )
     }
 

extras/android/BtBench/app/src/main/java/com/github/google/bumble/btbench/MainActivity.kt

@@ -17,9 +17,12 @@ package com.github.google.bumble.btbench
 import android.Manifest
 import android.annotation.SuppressLint
 import android.bluetooth.BluetoothAdapter
+import android.bluetooth.BluetoothDevice
 import android.bluetooth.BluetoothManager
+import android.content.BroadcastReceiver
 import android.content.Context
 import android.content.Intent
+import android.content.IntentFilter
 import android.content.pm.PackageManager
 import android.os.Build
 import android.os.Bundle
@@ -66,6 +69,7 @@ import androidx.compose.ui.unit.dp
 import androidx.compose.ui.unit.sp
 import androidx.core.content.ContextCompat
 import com.github.google.bumble.btbench.ui.theme.BTBenchTheme
+import java.io.IOException
 import java.util.logging.Logger
 
 private val Log = Logger.getLogger("bumble.main-activity")
@@ -76,6 +80,7 @@ const val SENDER_PACKET_SIZE_PREF_KEY = "sender_packet_size"
 const val SENDER_PACKET_INTERVAL_PREF_KEY = "sender_packet_interval"
 const val SCENARIO_PREF_KEY = "scenario"
 const val MODE_PREF_KEY = "mode"
+const val CONNECTION_PRIORITY_PREF_KEY = "connection_priority"
 
 class MainActivity : ComponentActivity() {
     private val appViewModel = AppViewModel()
@@ -84,6 +89,47 @@ class MainActivity : ComponentActivity() {
         super.onCreate(savedInstanceState)
         appViewModel.loadPreferences(getPreferences(Context.MODE_PRIVATE))
         checkPermissions()
+        registerReceivers()
+    }
+
+    private fun registerReceivers() {
+        val pairingRequestIntentFilter = IntentFilter(BluetoothDevice.ACTION_PAIRING_REQUEST)
+        registerReceiver(object: BroadcastReceiver() {
+            @SuppressLint("MissingPermission")
+            override fun onReceive(context: Context, intent: Intent) {
+                Log.info("ACTION_PAIRING_REQUEST")
+                val extras = intent.extras
+                if (extras != null) {
+                    for (key in extras.keySet()) {
+                        Log.info("$key: ${extras.get(key)}")
+                    }
+                }
+                val device: BluetoothDevice? = intent.getParcelableExtra(BluetoothDevice.EXTRA_DEVICE)
+                if (device != null) {
+                    if (checkSelfPermission(Manifest.permission.BLUETOOTH_PRIVILEGED) == PackageManager.PERMISSION_GRANTED) {
+                        Log.info("confirming pairing")
+                        device.setPairingConfirmation(true)
+                    } else {
+                        Log.info("we don't have BLUETOOTH_PRIVILEGED, not confirming")
+                    }
+                }
+
+            }
+        }, pairingRequestIntentFilter)
+
+        val bondStateChangedIntentFilter = IntentFilter(BluetoothDevice.ACTION_BOND_STATE_CHANGED)
+        registerReceiver(object: BroadcastReceiver() {
+            @SuppressLint("MissingPermission")
+            override fun onReceive(context: Context, intent: Intent) {
+                Log.info("ACTION_BOND_STATE_CHANGED")
+                val extras = intent.extras
+                if (extras != null) {
+                    for (key in extras.keySet()) {
+                        Log.info("$key: ${extras.get(key)}")
+                    }
+                }
+            }
+        }, bondStateChangedIntentFilter)
     }
 
     private fun checkPermissions() {
@@ -144,9 +190,7 @@ class MainActivity : ComponentActivity() {
         initBluetooth()
         setContent {
             MainView(
-                appViewModel,
-                ::becomeDiscoverable,
-                ::runScenario
+                appViewModel, ::becomeDiscoverable, ::runScenario
             )
         }
 
@@ -182,6 +226,8 @@ class MainActivity : ComponentActivity() {
                 "rfcomm-server" -> appViewModel.mode = RFCOMM_SERVER_MODE
                 "l2cap-client" -> appViewModel.mode = L2CAP_CLIENT_MODE
                 "l2cap-server" -> appViewModel.mode = L2CAP_SERVER_MODE
+                "gatt-client" -> appViewModel.mode = GATT_CLIENT_MODE
+                "gatt-server" -> appViewModel.mode = GATT_SERVER_MODE
             }
         }
         intent.getStringExtra("autostart")?.let {
@@ -195,19 +241,24 @@ class MainActivity : ComponentActivity() {
 
     private fun runScenario() {
         if (bluetoothAdapter == null) {
-            return
+            throw IOException("bluetooth not enabled")
         }
 
         val runner = when (appViewModel.mode) {
             RFCOMM_CLIENT_MODE -> RfcommClient(appViewModel, bluetoothAdapter!!, ::createIoClient)
             RFCOMM_SERVER_MODE -> RfcommServer(appViewModel, bluetoothAdapter!!, ::createIoClient)
             L2CAP_CLIENT_MODE -> L2capClient(
-                appViewModel,
-                bluetoothAdapter!!,
-                baseContext,
-                ::createIoClient
+                appViewModel, bluetoothAdapter!!, baseContext, ::createIoClient
             )
+
             L2CAP_SERVER_MODE -> L2capServer(appViewModel, bluetoothAdapter!!, ::createIoClient)
+            GATT_CLIENT_MODE -> GattClient(
+                appViewModel, bluetoothAdapter!!, baseContext, ::createIoClient
+            )
+            GATT_SERVER_MODE -> GattServer(
+                appViewModel, bluetoothAdapter!!, baseContext, ::createIoClient
+            )
+
             else -> throw IllegalStateException()
         }
         runner.run()
@@ -281,7 +332,7 @@ fun MainView(
                         keyboardController?.hide()
                         focusManager.clearFocus()
                     }),
-                    enabled = (appViewModel.mode == RFCOMM_CLIENT_MODE) or (appViewModel.mode == L2CAP_CLIENT_MODE)
+                    enabled = (appViewModel.mode == RFCOMM_CLIENT_MODE || appViewModel.mode == L2CAP_CLIENT_MODE || appViewModel.mode == GATT_CLIENT_MODE)
                 )
                 Divider()
                 TextField(
@@ -349,24 +400,45 @@ fun MainView(
                         keyboardController?.hide()
                         focusManager.clearFocus()
                     }),
-                    enabled = (appViewModel.scenario == PING_SCENARIO)
+                    enabled = (appViewModel.scenario == PING_SCENARIO || appViewModel.scenario == SEND_SCENARIO)
                 )
                 Divider()
-                ActionButton(
-                    text = "Become Discoverable", onClick = becomeDiscoverable, true
-                )
                 Row(
                     horizontalArrangement = Arrangement.SpaceBetween,
                     verticalAlignment = Alignment.CenterVertically
                 ) {
                     Text(text = "2M PHY")
                     Spacer(modifier = Modifier.padding(start = 8.dp))
-                    Switch(
-                        enabled = (appViewModel.mode == L2CAP_CLIENT_MODE || appViewModel.mode == L2CAP_SERVER_MODE),
+                    Switch(enabled = (appViewModel.mode == L2CAP_CLIENT_MODE || appViewModel.mode == L2CAP_SERVER_MODE || appViewModel.mode == GATT_CLIENT_MODE || appViewModel.mode == GATT_SERVER_MODE),
                         checked = appViewModel.use2mPhy,
-                        onCheckedChange = { appViewModel.use2mPhy = it }
-                    )
-
+                        onCheckedChange = { appViewModel.use2mPhy = it })
+                    Column(Modifier.selectableGroup()) {
+                        listOf(
+                            "BALANCED", "LOW", "HIGH", "DCK"
+                        ).forEach { text ->
+                            Row(
+                                Modifier
+                                    .selectable(
+                                        selected = (text == appViewModel.connectionPriority),
+                                        onClick = { appViewModel.updateConnectionPriority(text) },
+                                        role = Role.RadioButton,
+                                    )
+                                    .padding(horizontal = 16.dp),
+                                verticalAlignment = Alignment.CenterVertically
+                            ) {
+                                RadioButton(
+                                    selected = (text == appViewModel.connectionPriority),
+                                    onClick = null,
+                                    enabled = (appViewModel.mode == L2CAP_CLIENT_MODE || appViewModel.mode == L2CAP_SERVER_MODE || appViewModel.mode == GATT_CLIENT_MODE || appViewModel.mode == GATT_SERVER_MODE)
+                                )
+                                Text(
+                                    text = text,
+                                    style = MaterialTheme.typography.bodyLarge,
+                                    modifier = Modifier.padding(start = 16.dp)
+                                )
+                            }
+                        }
+                    }
                 }
                 Row {
                     Column(Modifier.selectableGroup()) {
@@ -374,7 +446,9 @@ fun MainView(
                             RFCOMM_CLIENT_MODE,
                             RFCOMM_SERVER_MODE,
                             L2CAP_CLIENT_MODE,
-                            L2CAP_SERVER_MODE
+                            L2CAP_SERVER_MODE,
+                            GATT_CLIENT_MODE,
+                            GATT_SERVER_MODE
                         ).forEach { text ->
                             Row(
                                 Modifier
@@ -387,8 +461,7 @@ fun MainView(
                                 verticalAlignment = Alignment.CenterVertically
                             ) {
                                 RadioButton(
-                                    selected = (text == appViewModel.mode),
-                                    onClick = null
+                                    selected = (text == appViewModel.mode), onClick = null
                                 )
                                 Text(
                                     text = text,
@@ -400,10 +473,7 @@ fun MainView(
                     }
                     Column(Modifier.selectableGroup()) {
                         listOf(
-                            SEND_SCENARIO,
-                            RECEIVE_SCENARIO,
-                            PING_SCENARIO,
-                            PONG_SCENARIO
+                            SEND_SCENARIO, RECEIVE_SCENARIO, PING_SCENARIO, PONG_SCENARIO
                         ).forEach { text ->
                             Row(
                                 Modifier
@@ -416,8 +486,7 @@ fun MainView(
                                 verticalAlignment = Alignment.CenterVertically
                             ) {
                                 RadioButton(
-                                    selected = (text == appViewModel.scenario),
-                                    onClick = null
+                                    selected = (text == appViewModel.scenario), onClick = null
                                 )
                                 Text(
                                     text = text,
@@ -435,20 +504,29 @@ fun MainView(
                     ActionButton(
                         text = "Stop", onClick = appViewModel::abort, enabled = appViewModel.running
                     )
+                    ActionButton(
+                        text = "Become Discoverable", onClick = becomeDiscoverable, true
+                    )
                 }
                 Divider()
-                Text(
-                    text = if (appViewModel.mtu != 0) "MTU: ${appViewModel.mtu}" else ""
-                )
-                Text(
-                    text = if (appViewModel.rxPhy != 0 || appViewModel.txPhy != 0) "PHY: tx=${appViewModel.txPhy}, rx=${appViewModel.rxPhy}" else ""
-                )
+                if (appViewModel.mtu != 0) {
+                    Text(
+                        text = "MTU: ${appViewModel.mtu}"
+                    )
+                }
+                if (appViewModel.rxPhy != 0) {
+                    Text(
+                        text = "PHY: tx=${appViewModel.txPhy}, rx=${appViewModel.rxPhy}"
+                    )
+                }
                 Text(
                     text = "Status: ${appViewModel.status}"
                 )
-                Text(
-                    text = "Last Error: ${appViewModel.lastError}"
-                )
+                if (appViewModel.lastError.isNotEmpty()) {
+                    Text(
+                        text = "Last Error: ${appViewModel.lastError}"
+                    )
+                }
                 Text(
                     text = "Packets Sent: ${appViewModel.packetsSent}"
                 )

extras/android/BtBench/app/src/main/java/com/github/google/bumble/btbench/Model.kt

@@ -25,6 +25,7 @@ import java.util.UUID
 
 val DEFAULT_RFCOMM_UUID: UUID = UUID.fromString("E6D55659-C8B4-4B85-96BB-B1143AF6D3AE")
 const val DEFAULT_PEER_BLUETOOTH_ADDRESS = "AA:BB:CC:DD:EE:FF"
+const val DEFAULT_STARTUP_DELAY = 3000
 const val DEFAULT_SENDER_PACKET_COUNT = 100
 const val DEFAULT_SENDER_PACKET_SIZE = 1024
 const val DEFAULT_SENDER_PACKET_INTERVAL = 100
@@ -34,6 +35,8 @@ const val L2CAP_CLIENT_MODE = "L2CAP Client"
 const val L2CAP_SERVER_MODE = "L2CAP Server"
 const val RFCOMM_CLIENT_MODE = "RFCOMM Client"
 const val RFCOMM_SERVER_MODE = "RFCOMM Server"
+const val GATT_CLIENT_MODE = "GATT Client"
+const val GATT_SERVER_MODE = "GATT Server"
 
 const val SEND_SCENARIO = "Send"
 const val RECEIVE_SCENARIO = "Receive"
@@ -47,8 +50,10 @@ class AppViewModel : ViewModel() {
     var mode by mutableStateOf(RFCOMM_SERVER_MODE)
     var scenario by mutableStateOf(RECEIVE_SCENARIO)
     var peerBluetoothAddress by mutableStateOf(DEFAULT_PEER_BLUETOOTH_ADDRESS)
+    var startupDelay by mutableIntStateOf(DEFAULT_STARTUP_DELAY)
     var l2capPsm by mutableIntStateOf(DEFAULT_PSM)
     var use2mPhy by mutableStateOf(true)
+    var connectionPriority by mutableStateOf("BALANCED")
     var mtu by mutableIntStateOf(0)
     var rxPhy by mutableIntStateOf(0)
     var txPhy by mutableIntStateOf(0)
@@ -98,6 +103,11 @@ class AppViewModel : ViewModel() {
         if (savedScenario != null) {
             scenario = savedScenario
         }
+
+        val savedConnectionPriority = preferences.getString(CONNECTION_PRIORITY_PREF_KEY, null)
+        if (savedConnectionPriority != null) {
+            connectionPriority = savedConnectionPriority
+        }
     }
 
     fun updatePeerBluetoothAddress(peerBluetoothAddress: String) {
@@ -220,6 +230,14 @@ class AppViewModel : ViewModel() {
         }
     }
 
+    fun updateConnectionPriority(connectionPriority: String) {
+        this.connectionPriority = connectionPriority
+        with(preferences!!.edit()) {
+            putString(CONNECTION_PRIORITY_PREF_KEY, connectionPriority)
+            apply()
+        }
+    }
+
     fun clear() {
         status = ""
         lastError = ""

extras/android/BtBench/app/src/main/java/com/github/google/bumble/btbench/Packet.kt

@@ -17,6 +17,7 @@ package com.github.google.bumble.btbench
 import android.bluetooth.BluetoothSocket
 import java.io.IOException
 import java.nio.ByteBuffer
+import java.nio.ByteOrder
 import java.util.logging.Logger
 import kotlin.math.min
 
@@ -37,11 +38,16 @@ abstract class Packet(val type: Int, val payload: ByteArray = ByteArray(0)) {
                 RESET -> ResetPacket()
                 SEQUENCE -> SequencePacket(
                     data[1].toInt(),
-                    ByteBuffer.wrap(data, 2, 4).getInt(),
-                    data.sliceArray(6..<data.size)
+                    ByteBuffer.wrap(data, 2, 4).order(ByteOrder.LITTLE_ENDIAN).getInt(),
+                    ByteBuffer.wrap(data, 6, 4).order(ByteOrder.LITTLE_ENDIAN).getInt(),
+                    data.sliceArray(10..<data.size)
+                )
+
+                ACK -> AckPacket(
+                    data[1].toInt(),
+                    ByteBuffer.wrap(data, 2, 4).order(ByteOrder.LITTLE_ENDIAN).getInt()
                 )
 
-                ACK -> AckPacket(data[1].toInt(), ByteBuffer.wrap(data, 2, 4).getInt())
                 else -> GenericPacket(data[0].toInt(), data.sliceArray(1..<data.size))
             }
         }
@@ -57,16 +63,24 @@ class ResetPacket : Packet(RESET)
 
 class AckPacket(val flags: Int, val sequenceNumber: Int) : Packet(ACK) {
     override fun toBytes(): ByteArray {
-        return ByteBuffer.allocate(1 + 1 + 4).put(type.toByte()).put(flags.toByte())
+        return ByteBuffer.allocate(6).order(
+            ByteOrder.LITTLE_ENDIAN
+        ).put(type.toByte()).put(flags.toByte())
             .putInt(sequenceNumber).array()
     }
 }
 
-class SequencePacket(val flags: Int, val sequenceNumber: Int, payload: ByteArray) :
+class SequencePacket(
+    val flags: Int,
+    val sequenceNumber: Int,
+    val timestamp: Int,
+    payload: ByteArray
+) :
     Packet(SEQUENCE, payload) {
     override fun toBytes(): ByteArray {
-        return ByteBuffer.allocate(1 + 1 + 4 + payload.size).put(type.toByte()).put(flags.toByte())
-            .putInt(sequenceNumber).put(payload).array()
+        return ByteBuffer.allocate(10 + payload.size).order(ByteOrder.LITTLE_ENDIAN)
+            .put(type.toByte()).put(flags.toByte())
+            .putInt(sequenceNumber).putInt(timestamp).put(payload).array()
     }
 }
 

extras/android/BtBench/app/src/main/java/com/github/google/bumble/btbench/Pinger.kt

@@ -19,8 +19,6 @@ import java.util.logging.Logger
 import kotlin.time.Duration.Companion.milliseconds
 import kotlin.time.TimeSource
 
-private const val DEFAULT_STARTUP_DELAY = 3000
-
 private val Log = Logger.getLogger("btbench.pinger")
 
 class Pinger(private val viewModel: AppViewModel, private val packetIO: PacketIO) : IoClient,
@@ -36,8 +34,8 @@ class Pinger(private val viewModel: AppViewModel, private val packetIO: PacketIO
     override fun run() {
         viewModel.clear()
 
-        Log.info("startup delay: $DEFAULT_STARTUP_DELAY")
-        Thread.sleep(DEFAULT_STARTUP_DELAY.toLong());
+        Log.info("startup delay: ${viewModel.startupDelay}")
+        Thread.sleep(viewModel.startupDelay.toLong());
         Log.info("running")
 
         Log.info("sending reset")
@@ -48,19 +46,23 @@ class Pinger(private val viewModel: AppViewModel, private val packetIO: PacketIO
 
         val startTime = TimeSource.Monotonic.markNow()
         for (i in 0..<packetCount) {
-            val now = TimeSource.Monotonic.markNow()
-            val targetTime = startTime + (i * viewModel.senderPacketInterval).milliseconds
-            val delay = targetTime - now
-            if (delay.isPositive()) {
-                Log.info("sleeping ${delay.inWholeMilliseconds} ms")
-                Thread.sleep(delay.inWholeMilliseconds)
+            var now = TimeSource.Monotonic.markNow()
+            if (viewModel.senderPacketInterval > 0) {
+                val targetTime = startTime + (i * viewModel.senderPacketInterval).milliseconds
+                val delay = targetTime - now
+                if (delay.isPositive()) {
+                    Log.info("sleeping ${delay.inWholeMilliseconds} ms")
+                    Thread.sleep(delay.inWholeMilliseconds)
+                    now = TimeSource.Monotonic.markNow()
+                }
             }
             pingTimes.add(TimeSource.Monotonic.markNow())
             packetIO.sendPacket(
                 SequencePacket(
                     if (i < packetCount - 1) 0 else Packet.LAST_FLAG,
                     i,
-                    ByteArray(packetSize - 6)
+                    (now - startTime).inWholeMicroseconds.toInt(),
+                    ByteArray(packetSize - 10)
                 )
             )
             viewModel.packetsSent = i + 1

extras/android/BtBench/app/src/main/java/com/github/google/bumble/btbench/Ponger.kt

@@ -14,6 +14,7 @@
 
 package com.github.google.bumble.btbench
 
+import java.util.concurrent.CountDownLatch
 import java.util.logging.Logger
 import kotlin.time.TimeSource
 
@@ -23,6 +24,7 @@ class Ponger(private val viewModel: AppViewModel, private val packetIO: PacketIO
     private var startTime: TimeSource.Monotonic.ValueTimeMark = TimeSource.Monotonic.markNow()
     private var lastPacketTime: TimeSource.Monotonic.ValueTimeMark = TimeSource.Monotonic.markNow()
     private var expectedSequenceNumber: Int = 0
+    private val done = CountDownLatch(1)
 
     init {
         packetIO.packetSink = this
@@ -30,6 +32,7 @@ class Ponger(private val viewModel: AppViewModel, private val packetIO: PacketIO
 
     override fun run() {
         viewModel.clear()
+        done.await()
     }
 
     override fun abort() {}
@@ -58,5 +61,10 @@ class Ponger(private val viewModel: AppViewModel, private val packetIO: PacketIO
 
         packetIO.sendPacket(AckPacket(packet.flags, packet.sequenceNumber))
         viewModel.packetsSent += 1
+
+        if (packet.flags and Packet.LAST_FLAG != 0) {
+            Log.info("received last packet")
+            done.countDown()
+        }
     }
 }

extras/android/BtBench/app/src/main/java/com/github/google/bumble/btbench/Receiver.kt

@@ -14,6 +14,7 @@
 
 package com.github.google.bumble.btbench
 
+import java.util.concurrent.CountDownLatch
 import java.util.logging.Logger
 import kotlin.time.DurationUnit
 import kotlin.time.TimeSource
@@ -24,6 +25,7 @@ class Receiver(private val viewModel: AppViewModel, private val packetIO: Packet
     private var startTime: TimeSource.Monotonic.ValueTimeMark = TimeSource.Monotonic.markNow()
     private var lastPacketTime: TimeSource.Monotonic.ValueTimeMark = TimeSource.Monotonic.markNow()
     private var bytesReceived = 0
+    private val done = CountDownLatch(1)
 
     init {
         packetIO.packetSink = this
@@ -31,6 +33,7 @@ class Receiver(private val viewModel: AppViewModel, private val packetIO: Packet
 
     override fun run() {
         viewModel.clear()
+        done.await()
     }
 
     override fun abort() {}
@@ -62,6 +65,7 @@ class Receiver(private val viewModel: AppViewModel, private val packetIO: Packet
             Log.info("throughput: $throughput")
             viewModel.throughput = throughput
             packetIO.sendPacket(AckPacket(packet.flags, packet.sequenceNumber))
+            done.countDown()
         }
     }
 }

extras/android/BtBench/app/src/main/java/com/github/google/bumble/btbench/Sender.kt

@@ -16,11 +16,10 @@ package com.github.google.bumble.btbench
 
 import java.util.concurrent.Semaphore
 import java.util.logging.Logger
+import kotlin.time.Duration.Companion.milliseconds
 import kotlin.time.DurationUnit
 import kotlin.time.TimeSource
 
-private const val DEFAULT_STARTUP_DELAY = 3000
-
 private val Log = Logger.getLogger("btbench.sender")
 
 class Sender(private val viewModel: AppViewModel, private val packetIO: PacketIO) : IoClient,
@@ -36,8 +35,8 @@ class Sender(private val viewModel: AppViewModel, private val packetIO: PacketIO
     override fun run() {
         viewModel.clear()
 
-        Log.info("startup delay: $DEFAULT_STARTUP_DELAY")
-        Thread.sleep(DEFAULT_STARTUP_DELAY.toLong());
+        Log.info("startup delay: ${viewModel.startupDelay}")
+        Thread.sleep(viewModel.startupDelay.toLong());
         Log.info("running")
 
         Log.info("sending reset")
@@ -47,20 +46,32 @@ class Sender(private val viewModel: AppViewModel, private val packetIO: PacketIO
 
         val packetCount = viewModel.senderPacketCount
         val packetSize = viewModel.senderPacketSize
-        for (i in 0..<packetCount - 1) {
-            packetIO.sendPacket(SequencePacket(0, i, ByteArray(packetSize - 6)))
+        for (i in 0..<packetCount) {
+            var now = TimeSource.Monotonic.markNow()
+            if (viewModel.senderPacketInterval > 0) {
+                val targetTime = startTime + (i * viewModel.senderPacketInterval).milliseconds
+                val delay = targetTime - now
+                if (delay.isPositive()) {
+                    Log.info("sleeping ${delay.inWholeMilliseconds} ms")
+                    Thread.sleep(delay.inWholeMilliseconds)
+                }
+                now = TimeSource.Monotonic.markNow()
+            }
+            val flags = when (i) {
+                packetCount - 1 -> Packet.LAST_FLAG
+                else -> 0
+            }
+            packetIO.sendPacket(
+                SequencePacket(
+                    flags,
+                    i,
+                    (now - startTime).inWholeMicroseconds.toInt(),
+                    ByteArray(packetSize - 10)
+                )
+            )
             bytesSent += packetSize
             viewModel.packetsSent = i + 1
         }
-        packetIO.sendPacket(
-            SequencePacket(
-                Packet.LAST_FLAG,
-                packetCount - 1,
-                ByteArray(packetSize - 6)
-            )
-        )
-        bytesSent += packetSize
-        viewModel.packetsSent = packetCount
 
         // Wait for the ACK
         Log.info("waiting for ACK")

pyproject.toml

@@ -57,19 +57,21 @@ development = [
 ]
 avatar = [
     "pandora-avatar == 0.0.10",
-    "rootcanal == 1.10.0 ; python_version>='3.10'",
+    "rootcanal == 1.11.1 ; python_version>='3.10'",
 ]
 pandora = ["bt-test-interfaces >= 0.0.6"]
 documentation = [
-    "mkdocs >= 1.4.0",
-    "mkdocs-material >= 8.5.6",
-    "mkdocstrings[python] >= 0.19.0",
+    "mkdocs >= 1.6.0",
+    "mkdocs-material >= 9.6",
+    "mkdocstrings[python] >= 0.27.0",
 ]
-lc3 = [
-    "lc3 @ git+https://github.com/google/liblc3.git",
+auracast = [
+    "lc3py >= 1.1.3; python_version>='3.10' and ((platform_system=='Linux' and platform_machine=='x86_64') or (platform_system=='Darwin' and platform_machine=='arm64'))",
+    "sounddevice >= 0.5.1",
 ]
 
 [project.scripts]
+bumble-auracast = "bumble.apps.auracast:main"
 bumble-ble-rpa-tool = "bumble.apps.ble_rpa_tool:main"
 bumble-console = "bumble.apps.console:main"
 bumble-controller-info = "bumble.apps.controller_info:main"
@@ -153,7 +155,7 @@ disable = [
 ]
 
 [tool.pylint.main]
-ignore = "pandora" # FIXME: pylint does not support stubs yet:
+ignore=["pandora", "mobly"] # FIXME: pylint does not support stubs yet
 
 [tool.pylint.typecheck]
 signature-mutators = "AsyncRunner.run_in_task"
@@ -190,6 +192,10 @@ ignore_missing_imports = true
 module = "serial_asyncio.*"
 ignore_missing_imports = true
 
+[[tool.mypy.overrides]]
+module = "sounddevice.*"
+ignore_missing_imports = true
+
 [[tool.mypy.overrides]]
 module = "usb.*"
 ignore_missing_imports = true

rust/README.md

@@ -69,3 +69,68 @@ To regenerate the assigned number tables based on the Python codebase:
 ```
 PYTHONPATH=.. cargo run --bin gen-assigned-numbers --features dev-tools
 ```
+
+## HCI packets
+
+Sending a command packet from a device is composed to of two major steps.
+There are more generalized ways of dealing with packets in other scenarios.
+
+### Construct the command
+Pick a command from `src/internal/hci/packets.pdl` and construct its associated "builder" struct.
+
+```rust
+// The "LE Set Scan Enable" command can be found in the Core Bluetooth Spec.
+// It can also be found in `packets.pdl` as `packet LeSetScanEnable : Command`
+fn main() {
+    let device = init_device_as_desired();
+    
+    let le_set_scan_enable_command_builder = LeSetScanEnableBuilder {
+        filter_duplicates: Enable::Disabled,
+        le_scan_enable: Enable::Enabled,
+    };
+}
+```
+
+### Send the command and interpret the event response
+Send the command from an initialized device, and then receive the response.
+
+```rust
+fn main() {
+    // ...
+    
+    // `check_result` to false to receive the event response even if the controller returns a failure code
+    let event = device.send_command(le_set_scan_enable_command_builder.into(), /*check_result*/ false);
+    // Coerce the event into the expected format. A `Command` should have an associated event response
+    // "<command name>Complete".
+    let le_set_scan_enable_complete_event: LeSetScanEnableComplete = event.try_into().unwrap();
+}
+```
+
+### Generic packet handling
+At the very least, you should expect to at least know _which_ kind of base packet you are dealing with. Base packets in 
+`packets.pdl` can be identified because they do not extend any other packet. They are easily found with the regex:
+`^packet [^:]* \{`. For Bluetooth LE (BLE) HCI, one should find some kind of header preceding the packet with the purpose of
+packet disambiguation. We do some of that disambiguation for H4 BLE packets using the `WithPacketHeader` trait at `internal/hci/mod.rs`.
+
+Say you've identified a series of bytes that are certainly an `Acl` packet. They can be parsed using the `Acl` struct.
+```rust
+fn main() {
+    let bytes = bytes_that_are_certainly_acl();
+    let acl_packet = Acl::parse(bytes).unwrap();
+}
+```
+
+Since you don't yet know what kind of `Acl` packet it is, you need to specialize it and then handle the various
+potential cases.
+```rust
+fn main() {
+    // ...
+    match acl_packet.specialize() {
+        Payload(bytes) => do_something(bytes),
+        None => do_something_else(),
+    }
+}
+```
+
+Some packets may yet further embed other packets, in which case you may need to further specialize until no more
+specialization is needed.

rust/examples/broadcast.rs

@@ -25,7 +25,6 @@ use clap::Parser as _;
 use pyo3::PyResult;
 use rand::Rng;
 use std::path;
-
 #[pyo3_asyncio::tokio::main]
 async fn main() -> PyResult<()> {
     env_logger::builder()

rust/pytests/wrapper/hci.rs

@@ -28,7 +28,7 @@ use bumble::wrapper::{
 };
 use pyo3::{
     exceptions::PyException,
-    {PyErr, PyResult},
+    FromPyObject, IntoPy, Python, {PyErr, PyResult},
 };
 
 #[pyo3_asyncio::tokio::test]
@@ -78,6 +78,28 @@ async fn test_hci_roundtrip_success_and_failure() -> PyResult<()> {
     Ok(())
 }
 
+#[pyo3_asyncio::tokio::test]
+fn valid_error_code_extraction_succeeds() -> PyResult<()> {
+    let error_code = Python::with_gil(|py| {
+        let python_error_code_success = 0x00_u8.into_py(py);
+        ErrorCode::extract(python_error_code_success.as_ref(py))
+    })?;
+
+    assert_eq!(ErrorCode::Success, error_code);
+    Ok(())
+}
+
+#[pyo3_asyncio::tokio::test]
+fn invalid_error_code_extraction_fails() -> PyResult<()> {
+    let failed_extraction = Python::with_gil(|py| {
+        let python_invalid_error_code = 0xFE_u8.into_py(py);
+        ErrorCode::extract(python_invalid_error_code.as_ref(py))
+    });
+
+    assert!(failed_extraction.is_err());
+    Ok(())
+}
+
 async fn create_local_device(address: Address) -> PyResult<Device> {
     let link = Link::new_local_link()?;
     let controller = Controller::new("C1", None, None, Some(link), Some(address.clone())).await?;

rust/src/wrapper/hci.rs

@@ -178,7 +178,11 @@ impl IntoPy<PyObject> for AddressType {
 
 impl<'source> FromPyObject<'source> for ErrorCode {
     fn extract(ob: &'source PyAny) -> PyResult<Self> {
-        ob.extract()
+        // Bumble represents error codes simply as a single-byte number (in Rust, u8)
+        let value: u8 = ob.extract()?;
+        ErrorCode::try_from(value).map_err(|b| {
+            PyErr::new::<PyException, _>(format!("Failed to map {b} to an error code"))
+        })
     }
 }
 

tests/aics_test.py

@@ -33,7 +33,7 @@ from bumble.profiles.aics import (
     AudioInputControlPointOpCode,
     ErrorCode,
 )
-from bumble.profiles.vcp import VolumeControlService, VolumeControlServiceProxy
+from bumble.profiles.vcs import VolumeControlService, VolumeControlServiceProxy
 
 from .test_utils import TwoDevices
 

tests/device_test.py

@@ -24,7 +24,6 @@ import pytest
 from bumble.core import (
     BT_BR_EDR_TRANSPORT,
     BT_LE_TRANSPORT,
-    BT_PERIPHERAL_ROLE,
     ConnectionParameters,
 )
 from bumble.device import (
@@ -34,7 +33,7 @@ from bumble.device import (
     Device,
     PeriodicAdvertisingParameters,
 )
-from bumble.host import AclPacketQueue, Host
+from bumble.host import DataPacketQueue, Host
 from bumble.hci import (
     HCI_ACCEPT_CONNECTION_REQUEST_COMMAND,
     HCI_COMMAND_STATUS_PENDING,
@@ -43,6 +42,7 @@ from bumble.hci import (
     HCI_CONNECTION_FAILED_TO_BE_ESTABLISHED_ERROR,
     Address,
     OwnAddressType,
+    Role,
     HCI_Command_Complete_Event,
     HCI_Command_Status_Event,
     HCI_Connection_Complete_Event,
@@ -50,12 +50,7 @@ from bumble.hci import (
     HCI_Error,
     HCI_Packet,
 )
-from bumble.gatt import (
-    GATT_GENERIC_ACCESS_SERVICE,
-    GATT_CHARACTERISTIC_ATTRIBUTE_TYPE,
-    GATT_DEVICE_NAME_CHARACTERISTIC,
-    GATT_APPEARANCE_CHARACTERISTIC,
-)
+from bumble import gatt
 
 from .test_utils import TwoDevices, async_barrier
 
@@ -90,9 +85,9 @@ async def test_device_connect_parallel():
     def _send(packet):
         pass
 
-    d0.host.acl_packet_queue = AclPacketQueue(0, 0, _send)
-    d1.host.acl_packet_queue = AclPacketQueue(0, 0, _send)
-    d2.host.acl_packet_queue = AclPacketQueue(0, 0, _send)
+    d0.host.acl_packet_queue = DataPacketQueue(0, 0, _send)
+    d1.host.acl_packet_queue = DataPacketQueue(0, 0, _send)
+    d2.host.acl_packet_queue = DataPacketQueue(0, 0, _send)
 
     # enable classic
     d0.classic_enabled = True
@@ -300,7 +295,7 @@ async def test_legacy_advertising_disconnection(auto_restart):
         peer_address,
         None,
         None,
-        BT_PERIPHERAL_ROLE,
+        Role.PERIPHERAL,
         ConnectionParameters(0, 0, 0),
     )
 
@@ -358,7 +353,7 @@ async def test_extended_advertising_connection(own_address_type):
         peer_address,
         None,
         None,
-        BT_PERIPHERAL_ROLE,
+        Role.PERIPHERAL,
         ConnectionParameters(0, 0, 0),
     )
     device.on_advertising_set_termination(
@@ -402,7 +397,7 @@ async def test_extended_advertising_connection_out_of_order(own_address_type):
         Address('F0:F1:F2:F3:F4:F5'),
         None,
         None,
-        BT_PERIPHERAL_ROLE,
+        Role.PERIPHERAL,
         ConnectionParameters(0, 0, 0),
     )
 
@@ -592,32 +587,54 @@ async def test_power_on_default_static_address_should_not_be_any():
 
 
 # -----------------------------------------------------------------------------
-def test_gatt_services_with_gas():
+def test_gatt_services_with_gas_and_gatt():
     device = Device(host=Host(None, None))
 
-    # there should be one service and two chars, therefore 5 attributes
-    assert len(device.gatt_server.attributes) == 5
-    assert device.gatt_server.attributes[0].uuid == GATT_GENERIC_ACCESS_SERVICE
-    assert device.gatt_server.attributes[1].type == GATT_CHARACTERISTIC_ATTRIBUTE_TYPE
-    assert device.gatt_server.attributes[2].uuid == GATT_DEVICE_NAME_CHARACTERISTIC
-    assert device.gatt_server.attributes[3].type == GATT_CHARACTERISTIC_ATTRIBUTE_TYPE
-    assert device.gatt_server.attributes[4].uuid == GATT_APPEARANCE_CHARACTERISTIC
+    # there should be 2 service, 5 chars, and 1 descriptors, therefore 13 attributes
+    assert len(device.gatt_server.attributes) == 13
+    assert device.gatt_server.attributes[0].uuid == gatt.GATT_GENERIC_ACCESS_SERVICE
+    assert (
+        device.gatt_server.attributes[1].type == gatt.GATT_CHARACTERISTIC_ATTRIBUTE_TYPE
+    )
+    assert device.gatt_server.attributes[2].uuid == gatt.GATT_DEVICE_NAME_CHARACTERISTIC
+    assert (
+        device.gatt_server.attributes[3].type == gatt.GATT_CHARACTERISTIC_ATTRIBUTE_TYPE
+    )
+    assert device.gatt_server.attributes[4].uuid == gatt.GATT_APPEARANCE_CHARACTERISTIC
 
-
-# -----------------------------------------------------------------------------
-def test_gatt_services_without_gas():
-    device = Device(host=Host(None, None), generic_access_service=False)
-
-    # there should be no services
-    assert len(device.gatt_server.attributes) == 0
+    assert device.gatt_server.attributes[5].uuid == gatt.GATT_GENERIC_ATTRIBUTE_SERVICE
+    assert (
+        device.gatt_server.attributes[6].type == gatt.GATT_CHARACTERISTIC_ATTRIBUTE_TYPE
+    )
+    assert (
+        device.gatt_server.attributes[7].uuid
+        == gatt.GATT_SERVICE_CHANGED_CHARACTERISTIC
+    )
+    assert (
+        device.gatt_server.attributes[8].type
+        == gatt.GATT_CLIENT_CHARACTERISTIC_CONFIGURATION_DESCRIPTOR
+    )
+    assert (
+        device.gatt_server.attributes[9].type == gatt.GATT_CHARACTERISTIC_ATTRIBUTE_TYPE
+    )
+    assert (
+        device.gatt_server.attributes[10].uuid
+        == gatt.GATT_CLIENT_SUPPORTED_FEATURES_CHARACTERISTIC
+    )
+    assert (
+        device.gatt_server.attributes[11].type
+        == gatt.GATT_CHARACTERISTIC_ATTRIBUTE_TYPE
+    )
+    assert (
+        device.gatt_server.attributes[12].uuid == gatt.GATT_DATABASE_HASH_CHARACTERISTIC
+    )
 
 
 # -----------------------------------------------------------------------------
 async def run_test_device():
     await test_device_connect_parallel()
     await test_flush()
-    await test_gatt_services_with_gas()
-    await test_gatt_services_without_gas()
+    await test_gatt_services_with_gas_and_gatt()
 
 
 # -----------------------------------------------------------------------------

tests/gatt_service_test.py

@@ -0,0 +1,143 @@
+# Copyright 2021-2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# -----------------------------------------------------------------------------
+# Imports
+# -----------------------------------------------------------------------------
+from __future__ import annotations
+import pytest
+
+from . import test_utils
+
+from bumble import device
+from bumble import gatt
+from bumble.profiles import gatt_service
+
+
+# -----------------------------------------------------------------------------
+@pytest.mark.asyncio
+async def test_database_hash():
+    devices = await test_utils.TwoDevices.create_with_connection()
+    devices[0].gatt_server.services.clear()
+    devices[0].gatt_server.attributes.clear()
+    devices[0].gatt_server.attributes_by_handle.clear()
+    devices[0].add_service(
+        gatt.Service(
+            gatt.GATT_GENERIC_ACCESS_SERVICE,
+            characteristics=[
+                gatt.Characteristic(
+                    gatt.GATT_DEVICE_NAME_CHARACTERISTIC,
+                    (
+                        gatt.Characteristic.Properties.READ
+                        | gatt.Characteristic.Properties.WRITE
+                    ),
+                    gatt.Characteristic.Permissions.READ_REQUIRES_AUTHENTICATION,
+                ),
+                gatt.Characteristic(
+                    gatt.GATT_APPEARANCE_CHARACTERISTIC,
+                    gatt.Characteristic.Properties.READ,
+                    gatt.Characteristic.Permissions.READ_REQUIRES_AUTHENTICATION,
+                ),
+            ],
+        )
+    )
+    devices[0].add_service(
+        gatt_service.GenericAttributeProfileService(
+            server_supported_features=None,
+            database_hash_enabled=True,
+            service_change_enabled=True,
+        )
+    )
+    devices[0].gatt_server.add_attribute(
+        gatt.Service(gatt.GATT_GLUCOSE_SERVICE, characteristics=[])
+    )
+    # There is a special attribute order in the spec, so we need to add attribute one by
+    # one here.
+    battery_service = gatt.Service(
+        gatt.GATT_BATTERY_SERVICE,
+        characteristics=[
+            gatt.Characteristic(
+                gatt.GATT_BATTERY_LEVEL_CHARACTERISTIC,
+                properties=gatt.Characteristic.Properties.READ,
+                permissions=gatt.Characteristic.Permissions.READ_REQUIRES_AUTHENTICATION,
+            )
+        ],
+        primary=False,
+    )
+    battery_service.handle = 0x0014
+    battery_service.end_group_handle = 0x0016
+    devices[0].gatt_server.add_attribute(
+        gatt.IncludedServiceDeclaration(battery_service)
+    )
+    c = gatt.Characteristic(
+        '2A18',
+        properties=(
+            gatt.Characteristic.Properties.READ
+            | gatt.Characteristic.Properties.INDICATE
+            | gatt.Characteristic.Properties.EXTENDED_PROPERTIES
+        ),
+        permissions=gatt.Characteristic.Permissions.READ_REQUIRES_AUTHENTICATION,
+    )
+    devices[0].gatt_server.add_attribute(
+        gatt.CharacteristicDeclaration(c, devices[0].gatt_server.next_handle() + 1)
+    )
+    devices[0].gatt_server.add_attribute(c)
+    devices[0].gatt_server.add_attribute(
+        gatt.Descriptor(
+            gatt.GATT_CLIENT_CHARACTERISTIC_CONFIGURATION_DESCRIPTOR,
+            gatt.Descriptor.Permissions.READ_REQUIRES_AUTHENTICATION,
+            b'\x02\x00',
+        ),
+    )
+    devices[0].gatt_server.add_attribute(
+        gatt.Descriptor(
+            gatt.GATT_CHARACTERISTIC_EXTENDED_PROPERTIES_DESCRIPTOR,
+            gatt.Descriptor.Permissions.READ_REQUIRES_AUTHENTICATION,
+            b'\x00\x00',
+        ),
+    )
+    devices[0].add_service(battery_service)
+
+    peer = device.Peer(devices.connections[1])
+    client = await peer.discover_service_and_create_proxy(
+        gatt_service.GenericAttributeProfileServiceProxy
+    )
+    assert client.database_hash_characteristic
+    assert await client.database_hash_characteristic.read_value() == bytes.fromhex(
+        'F1CA2D48ECF58BAC8A8830BBB9FBA990'
+    )
+
+
+# -----------------------------------------------------------------------------
+@pytest.mark.asyncio
+async def test_service_changed():
+    devices = await test_utils.TwoDevices.create_with_connection()
+    assert (service := devices[0].gatt_service)
+
+    peer = device.Peer(devices.connections[1])
+    assert (
+        client := await peer.discover_service_and_create_proxy(
+            gatt_service.GenericAttributeProfileServiceProxy
+        )
+    )
+    assert client.service_changed_characteristic
+    indications = []
+    await client.service_changed_characteristic.subscribe(
+        indications.append, prefer_notify=False
+    )
+    await devices[0].indicate_subscribers(
+        service.service_changed_characteristic, b'1234'
+    )
+    await test_utils.async_barrier()
+    assert indications[0] == b'1234'

tests/gatt_test.py

@@ -17,32 +17,43 @@
 # -----------------------------------------------------------------------------
 from __future__ import annotations
 import asyncio
+import enum
 import logging
 import os
 import struct
 import pytest
+from typing import Any
 from typing_extensions import Self
 from unittest.mock import AsyncMock, Mock, ANY
 
 from bumble.controller import Controller
-from bumble.gatt_client import CharacteristicProxy
 from bumble.link import LocalLink
 from bumble.device import Device, Peer
 from bumble.host import Host
 from bumble.gatt import (
     GATT_BATTERY_LEVEL_CHARACTERISTIC,
     GATT_CLIENT_CHARACTERISTIC_CONFIGURATION_DESCRIPTOR,
-    CharacteristicAdapter,
-    SerializableCharacteristicAdapter,
-    DelegatedCharacteristicAdapter,
-    PackedCharacteristicAdapter,
-    MappedCharacteristicAdapter,
-    UTF8CharacteristicAdapter,
     Service,
     Characteristic,
     CharacteristicValue,
     Descriptor,
 )
+from bumble.gatt_client import CharacteristicProxy
+from bumble.gatt_adapters import (
+    CharacteristicProxyAdapter,
+    SerializableCharacteristicAdapter,
+    SerializableCharacteristicProxyAdapter,
+    DelegatedCharacteristicAdapter,
+    DelegatedCharacteristicProxyAdapter,
+    PackedCharacteristicAdapter,
+    PackedCharacteristicProxyAdapter,
+    MappedCharacteristicAdapter,
+    MappedCharacteristicProxyAdapter,
+    UTF8CharacteristicAdapter,
+    UTF8CharacteristicProxyAdapter,
+    EnumCharacteristicAdapter,
+    EnumCharacteristicProxyAdapter,
+)
 from bumble.transport import AsyncPipeSink
 from bumble.core import UUID
 from bumble.att import (
@@ -199,7 +210,7 @@ async def test_characteristic_encoding():
     await async_barrier()
     assert characteristic.value == bytes([125])
 
-    cd = DelegatedCharacteristicAdapter(c, encode=lambda x: bytes([x // 2]))
+    cd = DelegatedCharacteristicProxyAdapter(c, encode=lambda x: bytes([x // 2]))
     await cd.write_value(100, with_response=True)
     await async_barrier()
     assert characteristic.value == bytes([50])
@@ -207,7 +218,7 @@ async def test_characteristic_encoding():
     c2 = peer.get_characteristics_by_uuid(async_characteristic.uuid)
     assert len(c2) == 1
     c2 = c2[0]
-    cd2 = PackedCharacteristicAdapter(c2, ">I")
+    cd2 = PackedCharacteristicProxyAdapter(c2, ">I")
     cd2v = await cd2.read_value()
     assert cd2v == 0x05060708
 
@@ -249,7 +260,7 @@ async def test_characteristic_encoding():
     await async_barrier()
     assert last_change is None
 
-    cd = DelegatedCharacteristicAdapter(c, decode=lambda x: x[0])
+    cd = DelegatedCharacteristicProxyAdapter(c, decode=lambda x: x[0])
     await cd.subscribe(on_change)
     await server.notify_subscribers(characteristic)
     await async_barrier()
@@ -314,21 +325,16 @@ async def test_attribute_getters():
 # -----------------------------------------------------------------------------
 @pytest.mark.asyncio
 async def test_CharacteristicAdapter() -> None:
-    # Check that the CharacteristicAdapter base class is transparent
     v = bytes([1, 2, 3])
-    c = Characteristic(
+    c: Characteristic[Any] = Characteristic(
         GATT_BATTERY_LEVEL_CHARACTERISTIC,
         Characteristic.Properties.READ,
         Characteristic.READABLE,
         v,
     )
-    a = CharacteristicAdapter(c)
-
-    value = await a.read_value(None)
-    assert value == v
 
     v = bytes([3, 4, 5])
-    await a.write_value(None, v)
+    await c.write_value(None, v)
     assert c.value == v
 
     # Simple delegated adapter
@@ -415,11 +421,171 @@ async def test_CharacteristicAdapter() -> None:
 
     class_read_value = await class_c.read_value(None)
     assert class_read_value == class_value_bytes
-    c.value = b''
+    class_c.value = b''
     await class_c.write_value(None, class_value_bytes)
-    assert isinstance(c.value, BlaBla)
-    assert c.value.a == 3
-    assert c.value.b == 4
+    assert isinstance(class_c.value, BlaBla)
+    assert class_c.value.a == class_value.a
+    assert class_c.value.b == class_value.b
+
+    # Enum adapter
+    class MyEnum(enum.IntEnum):
+        ENUM_1 = 1234
+        ENUM_2 = 5678
+
+    enum_value = MyEnum.ENUM_2
+    enum_value_bytes = int(enum_value).to_bytes(3, 'big')
+    c.value = enum_value
+    enum_c = EnumCharacteristicAdapter(c, MyEnum, 3, 'big')
+    enum_read_value = await enum_c.read_value(None)
+    assert enum_read_value == enum_value_bytes
+    enum_c.value = b''
+    await enum_c.write_value(None, enum_value_bytes)
+    assert isinstance(enum_c.value, MyEnum)
+    assert enum_c.value == enum_value
+
+
+# -----------------------------------------------------------------------------
+@pytest.mark.asyncio
+async def test_CharacteristicProxyAdapter() -> None:
+    class Client:
+        def __init__(self, value):
+            self.value = value
+
+        async def read_value(self, handle, no_long_read=False) -> bytes:
+            return self.value
+
+        async def write_value(self, handle, value, with_response=False):
+            self.value = value
+
+    class TestAttributeProxy(CharacteristicProxy):
+        def __init__(self, value) -> None:
+            super().__init__(Client(value), 0, 0, None, 0)  # type: ignore
+
+        @property
+        def value(self):
+            return self.client.value
+
+        @value.setter
+        def value(self, value):
+            self.client.value = value
+
+    v = bytes([1, 2, 3])
+    c = TestAttributeProxy(v)
+    a: CharacteristicProxyAdapter = CharacteristicProxyAdapter(c)
+
+    value = await a.read_value()
+    assert value == v
+
+    v = bytes([3, 4, 5])
+    await a.write_value(v)
+    assert c.value == v
+
+    # Simple delegated adapter
+    delegated = DelegatedCharacteristicProxyAdapter(
+        c, lambda x: bytes(reversed(x)), lambda x: bytes(reversed(x))
+    )
+
+    delegated_value = await delegated.read_value()
+    assert delegated_value == bytes(reversed(v))
+
+    delegated_value2 = bytes([3, 4, 5])
+    await delegated.write_value(delegated_value2)
+    assert c.value == bytes(reversed(delegated_value2))
+
+    # Packed adapter with single element format
+    packed_value_ref = 1234
+    packed_value_bytes = struct.pack('>H', packed_value_ref)
+    c.value = packed_value_bytes
+    packed = PackedCharacteristicProxyAdapter(c, '>H')
+
+    packed_value_read = await packed.read_value()
+    assert packed_value_read == packed_value_ref
+    c.value = None
+    await packed.write_value(packed_value_ref)
+    assert c.value == packed_value_bytes
+
+    # Packed adapter with multi-element format
+    v1 = 1234
+    v2 = 5678
+    packed_multi_value_bytes = struct.pack('>HH', v1, v2)
+    c.value = packed_multi_value_bytes
+    packed_multi = PackedCharacteristicProxyAdapter(c, '>HH')
+
+    packed_multi_read_value = await packed_multi.read_value()
+    assert packed_multi_read_value == (v1, v2)
+    c.value = b''
+    await packed_multi.write_value((v1, v2))
+    assert c.value == packed_multi_value_bytes
+
+    # Mapped adapter
+    v1 = 1234
+    v2 = 5678
+    packed_mapped_value_bytes = struct.pack('>HH', v1, v2)
+    mapped = {'v1': v1, 'v2': v2}
+    c.value = packed_mapped_value_bytes
+    packed_mapped = MappedCharacteristicProxyAdapter(c, '>HH', ('v1', 'v2'))
+
+    packed_mapped_read_value = await packed_mapped.read_value()
+    assert packed_mapped_read_value == mapped
+    c.value = b''
+    await packed_mapped.write_value(mapped)
+    assert c.value == packed_mapped_value_bytes
+
+    # UTF-8 adapter
+    string_value = 'Hello π'
+    string_value_bytes = string_value.encode('utf-8')
+    c.value = string_value_bytes
+    string_c = UTF8CharacteristicProxyAdapter(c)
+
+    string_read_value = await string_c.read_value()
+    assert string_read_value == string_value
+    c.value = b''
+    await string_c.write_value(string_value)
+    assert c.value == string_value_bytes
+
+    # Class adapter
+    class BlaBla:
+        def __init__(self, a: int, b: int) -> None:
+            self.a = a
+            self.b = b
+
+        @classmethod
+        def from_bytes(cls, data: bytes) -> Self:
+            a, b = struct.unpack(">II", data)
+            return cls(a, b)
+
+        def __bytes__(self) -> bytes:
+            return struct.pack(">II", self.a, self.b)
+
+    class_value = BlaBla(3, 4)
+    class_value_bytes = struct.pack(">II", 3, 4)
+    c.value = class_value_bytes
+    class_c = SerializableCharacteristicProxyAdapter(c, BlaBla)
+
+    class_read_value = await class_c.read_value()
+    assert isinstance(class_read_value, BlaBla)
+    assert class_read_value.a == class_value.a
+    assert class_read_value.b == class_value.b
+    c.value = b''
+    await class_c.write_value(class_value)
+    assert c.value == class_value_bytes
+
+    # Enum adapter
+    class MyEnum(enum.IntEnum):
+        ENUM_1 = 1234
+        ENUM_2 = 5678
+
+    enum_value = MyEnum.ENUM_1
+    enum_value_bytes = int(enum_value).to_bytes(3, 'little')
+    c.value = enum_value_bytes
+    enum_c = EnumCharacteristicProxyAdapter(c, MyEnum, 3)
+
+    enum_read_value = await enum_c.read_value()
+    assert isinstance(enum_read_value, MyEnum)
+    assert enum_read_value == enum_value
+    c.value = b''
+    await enum_c.write_value(enum_value)
+    assert c.value == enum_value_bytes
 
 
 # -----------------------------------------------------------------------------
@@ -601,7 +767,7 @@ async def test_read_write2():
     v1 = await c1.read_value()
     assert v1 == v
 
-    a1 = PackedCharacteristicAdapter(c1, '>I')
+    a1 = PackedCharacteristicProxyAdapter(c1, '>I')
     v1 = await a1.read_value()
     assert v1 == struct.unpack('>I', v)[0]
 
@@ -957,11 +1123,12 @@ async def test_discover_all():
     peer = Peer(connection)
 
     await peer.discover_all()
-    assert len(peer.gatt_client.services) == 3
-    # service 1800 gets added automatically
+    assert len(peer.gatt_client.services) == 4
+    # service 1800 and 1801 get added automatically
     assert peer.gatt_client.services[0].uuid == UUID('1800')
-    assert peer.gatt_client.services[1].uuid == service1.uuid
-    assert peer.gatt_client.services[2].uuid == service2.uuid
+    assert peer.gatt_client.services[1].uuid == UUID('1801')
+    assert peer.gatt_client.services[2].uuid == service1.uuid
+    assert peer.gatt_client.services[3].uuid == service2.uuid
     s = peer.get_services_by_uuid(service1.uuid)
     assert len(s) == 1
     assert len(s[0].characteristics) == 2
@@ -1084,10 +1251,18 @@ CharacteristicDeclaration(handle=0x0002, value_handle=0x0003, uuid=UUID-16:2A00
 Characteristic(handle=0x0003, end=0x0003, uuid=UUID-16:2A00 (Device Name), READ)
 CharacteristicDeclaration(handle=0x0004, value_handle=0x0005, uuid=UUID-16:2A01 (Appearance), READ)
 Characteristic(handle=0x0005, end=0x0005, uuid=UUID-16:2A01 (Appearance), READ)
-Service(handle=0x0006, end=0x0009, uuid=3A657F47-D34F-46B3-B1EC-698E29B6B829)
-CharacteristicDeclaration(handle=0x0007, value_handle=0x0008, uuid=FDB159DB-036C-49E3-B3DB-6325AC750806, READ|WRITE|NOTIFY)
-Characteristic(handle=0x0008, end=0x0009, uuid=FDB159DB-036C-49E3-B3DB-6325AC750806, READ|WRITE|NOTIFY)
-Descriptor(handle=0x0009, type=UUID-16:2902 (Client Characteristic Configuration), value=0000)"""
+Service(handle=0x0006, end=0x000D, uuid=UUID-16:1801 (Generic Attribute))
+CharacteristicDeclaration(handle=0x0007, value_handle=0x0008, uuid=UUID-16:2A05 (Service Changed), INDICATE)
+Characteristic(handle=0x0008, end=0x0009, uuid=UUID-16:2A05 (Service Changed), INDICATE)
+Descriptor(handle=0x0009, type=UUID-16:2902 (Client Characteristic Configuration), value=0000)
+CharacteristicDeclaration(handle=0x000A, value_handle=0x000B, uuid=UUID-16:2B29 (Client Supported Features), READ|WRITE)
+Characteristic(handle=0x000B, end=0x000B, uuid=UUID-16:2B29 (Client Supported Features), READ|WRITE)
+CharacteristicDeclaration(handle=0x000C, value_handle=0x000D, uuid=UUID-16:2B2A (Database Hash), READ)
+Characteristic(handle=0x000D, end=0x000D, uuid=UUID-16:2B2A (Database Hash), READ)
+Service(handle=0x000E, end=0x0011, uuid=3A657F47-D34F-46B3-B1EC-698E29B6B829)
+CharacteristicDeclaration(handle=0x000F, value_handle=0x0010, uuid=FDB159DB-036C-49E3-B3DB-6325AC750806, READ|WRITE|NOTIFY)
+Characteristic(handle=0x0010, end=0x0011, uuid=FDB159DB-036C-49E3-B3DB-6325AC750806, READ|WRITE|NOTIFY)
+Descriptor(handle=0x0011, type=UUID-16:2902 (Client Characteristic Configuration), value=0000)"""
     )
 
 
@@ -1105,6 +1280,7 @@ async def async_main():
     await test_CharacteristicValue()
     await test_CharacteristicValue_async()
     await test_CharacteristicAdapter()
+    await test_CharacteristicProxyAdapter()
 
 
 # -----------------------------------------------------------------------------

tests/gmap_test.py

@@ -78,7 +78,11 @@ async def test_init_service(gmap_client: GamingAudioServiceProxy):
         | GmapRole.BROADCAST_GAME_RECEIVER
         | GmapRole.BROADCAST_GAME_SENDER
     )
+    assert gmap_client.ugg_features is not None
     assert await gmap_client.ugg_features.read_value() == UggFeatures.UGG_MULTISINK
+    assert gmap_client.ugt_features is not None
     assert await gmap_client.ugt_features.read_value() == UgtFeatures.UGT_SOURCE
+    assert gmap_client.bgr_features is not None
     assert await gmap_client.bgr_features.read_value() == BgrFeatures.BGR_MULTISINK
+    assert gmap_client.bgs_features is not None
     assert await gmap_client.bgs_features.read_value() == BgsFeatures.BGS_96_KBPS

tests/hci_test.py

@@ -15,6 +15,7 @@
 # -----------------------------------------------------------------------------
 # Imports
 # -----------------------------------------------------------------------------
+import struct
 
 from bumble.hci import (
     HCI_DISCONNECT_COMMAND,
@@ -22,6 +23,7 @@ from bumble.hci import (
     HCI_LE_CODED_PHY_BIT,
     HCI_LE_READ_BUFFER_SIZE_COMMAND,
     HCI_RESET_COMMAND,
+    HCI_VENDOR_EVENT,
     HCI_SUCCESS,
     HCI_LE_CONNECTION_COMPLETE_EVENT,
     HCI_LE_ENHANCED_CONNECTION_COMPLETE_V2_EVENT,
@@ -67,6 +69,7 @@ from bumble.hci import (
     HCI_Read_Local_Version_Information_Command,
     HCI_Reset_Command,
     HCI_Set_Event_Mask_Command,
+    HCI_Vendor_Event,
 )
 
 
@@ -167,8 +170,8 @@ def test_HCI_Command_Complete_Event():
         command_opcode=HCI_LE_READ_BUFFER_SIZE_COMMAND,
         return_parameters=HCI_LE_Read_Buffer_Size_Command.create_return_parameters(
             status=0,
-            hc_le_acl_data_packet_length=1234,
-            hc_total_num_le_acl_data_packets=56,
+            le_acl_data_packet_length=1234,
+            total_num_le_acl_data_packets=56,
         ),
     )
     basic_check(event)
@@ -213,6 +216,41 @@ def test_HCI_Number_Of_Completed_Packets_Event():
     basic_check(event)
 
 
+# -----------------------------------------------------------------------------
+def test_HCI_Vendor_Event():
+    data = bytes.fromhex('01020304')
+    event = HCI_Vendor_Event(data=data)
+    event_bytes = bytes(event)
+    parsed = HCI_Packet.from_bytes(event_bytes)
+    assert isinstance(parsed, HCI_Vendor_Event)
+    assert parsed.data == data
+
+    class HCI_Custom_Event(HCI_Event):
+        def __init__(self, blabla):
+            super().__init__(HCI_VENDOR_EVENT, parameters=struct.pack("<I", blabla))
+            self.name = 'HCI_CUSTOM_EVENT'
+            self.blabla = blabla
+
+    def create_event(payload):
+        if payload[0] == 1:
+            return HCI_Custom_Event(blabla=struct.unpack('<I', payload)[0])
+        return None
+
+    HCI_Event.add_vendor_factory(create_event)
+    parsed = HCI_Packet.from_bytes(event_bytes)
+    assert isinstance(parsed, HCI_Custom_Event)
+    assert parsed.blabla == 0x04030201
+    event_bytes2 = event_bytes[:3] + bytes([7]) + event_bytes[4:]
+    parsed = HCI_Packet.from_bytes(event_bytes2)
+    assert not isinstance(parsed, HCI_Custom_Event)
+    assert isinstance(parsed, HCI_Vendor_Event)
+    HCI_Event.remove_vendor_factory(create_event)
+
+    parsed = HCI_Packet.from_bytes(event_bytes)
+    assert not isinstance(parsed, HCI_Custom_Event)
+    assert isinstance(parsed, HCI_Vendor_Event)
+
+
 # -----------------------------------------------------------------------------
 def test_HCI_Command():
     command = HCI_Command(0x5566)
@@ -576,6 +614,7 @@ def run_test_events():
     test_HCI_Command_Complete_Event()
     test_HCI_Command_Status_Event()
     test_HCI_Number_Of_Completed_Packets_Event()
+    test_HCI_Vendor_Event()
 
 
 # -----------------------------------------------------------------------------

tests/host_test.py

@@ -16,11 +16,14 @@
 # Imports
 # -----------------------------------------------------------------------------
 import logging
+import unittest.mock
 import pytest
+import unittest
 
 from bumble.controller import Controller
-from bumble.host import Host
+from bumble.host import Host, DataPacketQueue
 from bumble.transport import AsyncPipeSink
+from bumble.hci import HCI_AclDataPacket
 
 # -----------------------------------------------------------------------------
 # Logging
@@ -60,3 +63,90 @@ async def test_reset(supported_commands: str, lmp_features: str):
     assert host.local_lmp_features == int.from_bytes(
         bytes.fromhex(lmp_features), 'little'
     )
+
+
+# -----------------------------------------------------------------------------
+def test_data_packet_queue():
+    controller = unittest.mock.Mock()
+    queue = DataPacketQueue(10, 2, controller.send)
+    assert queue.queued == 0
+    assert queue.completed == 0
+    packet = HCI_AclDataPacket(
+        connection_handle=123, pb_flag=0, bc_flag=0, data_total_length=0, data=b''
+    )
+
+    queue.enqueue(packet, packet.connection_handle)
+    assert queue.queued == 1
+    assert queue.completed == 0
+    assert controller.send.call_count == 1
+
+    queue.enqueue(packet, packet.connection_handle)
+    assert queue.queued == 2
+    assert queue.completed == 0
+    assert controller.send.call_count == 2
+
+    queue.enqueue(packet, packet.connection_handle)
+    assert queue.queued == 3
+    assert queue.completed == 0
+    assert controller.send.call_count == 2
+
+    queue.on_packets_completed(1, 8000)
+    assert queue.queued == 3
+    assert queue.completed == 0
+    assert controller.send.call_count == 2
+
+    queue.on_packets_completed(1, 123)
+    assert queue.queued == 3
+    assert queue.completed == 1
+    assert controller.send.call_count == 3
+
+    queue.enqueue(packet, packet.connection_handle)
+    assert queue.queued == 4
+    assert queue.completed == 1
+    assert controller.send.call_count == 3
+
+    queue.on_packets_completed(2, 123)
+    assert queue.queued == 4
+    assert queue.completed == 3
+    assert controller.send.call_count == 4
+
+    queue.on_packets_completed(1, 123)
+    assert queue.queued == 4
+    assert queue.completed == 4
+    assert controller.send.call_count == 4
+
+    queue.enqueue(packet, 123)
+    queue.enqueue(packet, 123)
+    queue.enqueue(packet, 123)
+    queue.enqueue(packet, 124)
+    queue.enqueue(packet, 124)
+    queue.enqueue(packet, 124)
+    queue.on_packets_completed(1, 123)
+    assert queue.queued == 10
+    assert queue.completed == 5
+    queue.flush(123)
+    queue.flush(124)
+    assert queue.queued == 10
+    assert queue.completed == 10
+
+    queue.enqueue(packet, 123)
+    queue.on_packets_completed(1, 124)
+    assert queue.queued == 11
+    assert queue.completed == 10
+    queue.on_packets_completed(1000, 123)
+    assert queue.queued == 11
+    assert queue.completed == 11
+
+    drain_listener = unittest.mock.Mock()
+    queue.on('flow', drain_listener.on_flow)
+    queue.enqueue(packet, 123)
+    assert drain_listener.on_flow.call_count == 0
+    queue.on_packets_completed(1, 123)
+    assert drain_listener.on_flow.call_count == 1
+    queue.enqueue(packet, 123)
+    queue.enqueue(packet, 123)
+    queue.enqueue(packet, 123)
+    queue.flush(123)
+    assert drain_listener.on_flow.call_count == 1
+    assert queue.queued == 15
+    assert queue.completed == 15

tests/import_test.py

@@ -53,7 +53,7 @@ def test_import():
         le_audio,
         pacs,
         pbp,
-        vcp,
+        vcs,
     )
 
     assert att
@@ -87,7 +87,7 @@ def test_import():
     assert le_audio
     assert pacs
     assert pbp
-    assert vcp
+    assert vcs
 
 
 # -----------------------------------------------------------------------------

tests/sdp_test.py

@@ -20,12 +20,11 @@ import logging
 import os
 import pytest
 
-from bumble.core import UUID, BT_L2CAP_PROTOCOL_ID, BT_RFCOMM_PROTOCOL_ID
+from bumble.core import UUID, BT_L2CAP_PROTOCOL_ID
 from bumble.sdp import (
     DataElement,
     ServiceAttribute,
     Client,
-    Server,
     SDP_SERVICE_RECORD_HANDLE_ATTRIBUTE_ID,
     SDP_BROWSE_GROUP_LIST_ATTRIBUTE_ID,
     SDP_PUBLIC_BROWSE_ROOT,
@@ -174,9 +173,10 @@ def test_data_elements() -> None:
 
 
 # -----------------------------------------------------------------------------
-def sdp_records():
+def sdp_records(record_count=1):
     return {
-        0x00010001: [
+        0x00010001
+        + i: [
             ServiceAttribute(
                 SDP_SERVICE_RECORD_HANDLE_ATTRIBUTE_ID,
                 DataElement.unsigned_integer_32(0x00010001),
@@ -200,6 +200,7 @@ def sdp_records():
                 ),
             ),
         ]
+        for i in range(record_count)
     }
 
 
@@ -216,19 +217,55 @@ async def test_service_search():
     devices.devices[0].sdp_server.service_records.update(sdp_records())
 
     # Search for service
-    client = Client(devices.connections[1])
-    await client.connect()
-    services = await client.search_services(
-        [UUID('E6D55659-C8B4-4B85-96BB-B1143AF6D3AE')]
-    )
+    async with Client(devices.connections[1]) as client:
+        services = await client.search_services(
+            [UUID('E6D55659-C8B4-4B85-96BB-B1143AF6D3AF')]
+        )
+        assert len(services) == 0
 
-    # Then
-    assert services[0] == 0x00010001
+        services = await client.search_services(
+            [UUID('E6D55659-C8B4-4B85-96BB-B1143AF6D3AE')]
+        )
+        assert len(services) == 1
+        assert services[0] == 0x00010001
+
+        services = await client.search_services(
+            [BT_L2CAP_PROTOCOL_ID, SDP_PUBLIC_BROWSE_ROOT]
+        )
+        assert len(services) == 1
+        assert services[0] == 0x00010001
+
+        services = await client.search_services(
+            [BT_L2CAP_PROTOCOL_ID, SDP_PUBLIC_BROWSE_ROOT]
+        )
+        assert len(services) == 1
+        assert services[0] == 0x00010001
 
 
 # -----------------------------------------------------------------------------
 @pytest.mark.asyncio
-async def test_service_attribute():
+async def test_service_search_with_continuation():
+    # Setup connections
+    devices = TwoDevices()
+    await devices.setup_connection()
+
+    # Register SDP service
+    records = sdp_records(100)
+    devices.devices[0].sdp_server.service_records.update(records)
+
+    # Search for service
+    async with Client(devices.connections[1], mtu=48) as client:
+        services = await client.search_services(
+            [UUID('E6D55659-C8B4-4B85-96BB-B1143AF6D3AE')]
+        )
+        assert len(services) == len(records)
+        for i in range(len(records)):
+            assert services[i] == 0x00010001 + i
+
+
+# -----------------------------------------------------------------------------
+@pytest.mark.asyncio
+async def test_service_attributes():
     # Setup connections
     devices = TwoDevices()
     await devices.setup_connection()
@@ -236,15 +273,43 @@ async def test_service_attribute():
     # Register SDP service
     devices.devices[0].sdp_server.service_records.update(sdp_records())
 
-    # Search for service
-    client = Client(devices.connections[1])
-    await client.connect()
-    attributes = await client.get_attributes(
-        0x00010001, [SDP_SERVICE_RECORD_HANDLE_ATTRIBUTE_ID]
-    )
+    # Get attributes
+    async with Client(devices.connections[1]) as client:
+        attributes = await client.get_attributes(0x00010001, [1234])
+        assert len(attributes) == 0
 
-    # Then
-    assert attributes[0].value.value == sdp_records()[0x00010001][0].value.value
+        attributes = await client.get_attributes(
+            0x00010001, [SDP_SERVICE_RECORD_HANDLE_ATTRIBUTE_ID]
+        )
+        assert len(attributes) == 1
+        assert attributes[0].value.value == sdp_records()[0x00010001][0].value.value
+
+
+# -----------------------------------------------------------------------------
+@pytest.mark.asyncio
+async def test_service_attributes_with_continuation():
+    # Setup connections
+    devices = TwoDevices()
+    await devices.setup_connection()
+
+    # Register SDP service
+    records = {
+        0x00010001: [
+            ServiceAttribute(
+                x,
+                DataElement.unsigned_integer_32(0x00010001),
+            )
+            for x in range(100)
+        ]
+    }
+    devices.devices[0].sdp_server.service_records.update(records)
+
+    # Get attributes
+    async with Client(devices.connections[1], mtu=48) as client:
+        attributes = await client.get_attributes(0x00010001, list(range(100)))
+        assert len(attributes) == 100
+        for i, attribute in enumerate(attributes):
+            assert attribute.id == i
 
 
 # -----------------------------------------------------------------------------
@@ -255,19 +320,81 @@ async def test_service_search_attribute():
     await devices.setup_connection()
 
     # Register SDP service
-    devices.devices[0].sdp_server.service_records.update(sdp_records())
+    records = {
+        0x00010001: [
+            ServiceAttribute(
+                4,
+                DataElement.sequence(
+                    [DataElement.uuid(UUID('E6D55659-C8B4-4B85-96BB-B1143AF6D3AE'))]
+                ),
+            ),
+            ServiceAttribute(
+                3,
+                DataElement.sequence(
+                    [DataElement.uuid(UUID('E6D55659-C8B4-4B85-96BB-B1143AF6D3AE'))]
+                ),
+            ),
+            ServiceAttribute(
+                1,
+                DataElement.sequence(
+                    [DataElement.uuid(UUID('E6D55659-C8B4-4B85-96BB-B1143AF6D3AE'))]
+                ),
+            ),
+        ]
+    }
+
+    devices.devices[0].sdp_server.service_records.update(records)
 
     # Search for service
-    client = Client(devices.connections[1])
-    await client.connect()
-    attributes = await client.search_attributes(
-        [UUID('E6D55659-C8B4-4B85-96BB-B1143AF6D3AE')], [(0x0000FFFF, 8)]
-    )
+    async with Client(devices.connections[1]) as client:
+        attributes = await client.search_attributes(
+            [UUID('E6D55659-C8B4-4B85-96BB-B1143AF6D3AE')], [(0, 0xFFFF)]
+        )
+        assert len(attributes) == 1
+        assert len(attributes[0]) == 3
+        assert attributes[0][0].id == 1
+        assert attributes[0][1].id == 3
+        assert attributes[0][2].id == 4
 
-    # Then
-    for expect, actual in zip(attributes, sdp_records().values()):
-        assert expect.id == actual.id
-        assert expect.value == actual.value
+        attributes = await client.search_attributes(
+            [UUID('E6D55659-C8B4-4B85-96BB-B1143AF6D3AE')], [1, 2, 3]
+        )
+        assert len(attributes) == 1
+        assert len(attributes[0]) == 2
+        assert attributes[0][0].id == 1
+        assert attributes[0][1].id == 3
+
+
+# -----------------------------------------------------------------------------
+@pytest.mark.asyncio
+async def test_service_search_attribute_with_continuation():
+    # Setup connections
+    devices = TwoDevices()
+    await devices.setup_connection()
+
+    # Register SDP service
+    records = {
+        0x00010001: [
+            ServiceAttribute(
+                x,
+                DataElement.sequence(
+                    [DataElement.uuid(UUID('E6D55659-C8B4-4B85-96BB-B1143AF6D3AE'))]
+                ),
+            )
+            for x in range(100)
+        ]
+    }
+    devices.devices[0].sdp_server.service_records.update(records)
+
+    # Search for service
+    async with Client(devices.connections[1], mtu=48) as client:
+        attributes = await client.search_attributes(
+            [UUID('E6D55659-C8B4-4B85-96BB-B1143AF6D3AE')], [(0, 0xFFFF)]
+        )
+        assert len(attributes) == 1
+        assert len(attributes[0]) == 100
+        for i in range(100):
+            assert attributes[0][i].id == i
 
 
 # -----------------------------------------------------------------------------
@@ -287,9 +414,12 @@ async def test_client_async_context():
 # -----------------------------------------------------------------------------
 async def run():
     test_data_elements()
-    await test_service_attribute()
+    await test_service_attributes()
+    await test_service_attributes_with_continuation()
     await test_service_search()
+    await test_service_search_with_continuation()
     await test_service_search_attribute()
+    await test_service_search_attribute_with_continuation()
 
 
 # -----------------------------------------------------------------------------

tests/self_test.py

@@ -24,7 +24,7 @@ import pytest
 from unittest.mock import AsyncMock, MagicMock, patch
 
 from bumble.controller import Controller
-from bumble.core import BT_BR_EDR_TRANSPORT, BT_PERIPHERAL_ROLE, BT_CENTRAL_ROLE
+from bumble.core import BT_BR_EDR_TRANSPORT, BT_LE_TRANSPORT
 from bumble.link import LocalLink
 from bumble.device import Device, Peer
 from bumble.host import Host
@@ -39,6 +39,7 @@ from bumble.smp import (
 )
 from bumble.core import ProtocolError
 from bumble.keys import PairingKeys
+from bumble.hci import Role
 
 
 # -----------------------------------------------------------------------------
@@ -111,7 +112,7 @@ async def test_self_connection():
 @pytest.mark.asyncio
 @pytest.mark.parametrize(
     'responder_role,',
-    (BT_CENTRAL_ROLE, BT_PERIPHERAL_ROLE),
+    (Role.CENTRAL, Role.PERIPHERAL),
 )
 async def test_self_classic_connection(responder_role):
     # Create two devices, each with a controller, attached to the same link

tests/vcp_test.py

@@ -20,7 +20,7 @@ import pytest_asyncio
 import logging
 
 from bumble import device
-from bumble.profiles import vcp
+from bumble.profiles import vcs
 from .test_utils import TwoDevices
 
 # -----------------------------------------------------------------------------
@@ -34,7 +34,7 @@ logger = logging.getLogger(__name__)
 async def vcp_client():
     devices = TwoDevices()
     devices[0].add_service(
-        vcp.VolumeControlService(volume_setting=32, muted=1, volume_flags=1)
+        vcs.VolumeControlService(volume_setting=32, muted=1, volume_flags=1)
     )
 
     await devices.setup_connection()
@@ -48,76 +48,76 @@ async def vcp_client():
 
     peer = device.Peer(devices.connections[1])
     vcp_client = await peer.discover_service_and_create_proxy(
-        vcp.VolumeControlServiceProxy
+        vcs.VolumeControlServiceProxy
     )
     yield vcp_client
 
 
 # -----------------------------------------------------------------------------
 @pytest.mark.asyncio
-async def test_init_service(vcp_client: vcp.VolumeControlServiceProxy):
+async def test_init_service(vcp_client: vcs.VolumeControlServiceProxy):
     assert (await vcp_client.volume_flags.read_value()) == 1
-    assert (await vcp_client.volume_state.read_value()) == (32, 1, 0)
+    assert (await vcp_client.volume_state.read_value()) == vcs.VolumeState(32, 1, 0)
 
 
 # -----------------------------------------------------------------------------
 @pytest.mark.asyncio
-async def test_relative_volume_down(vcp_client: vcp.VolumeControlServiceProxy):
+async def test_relative_volume_down(vcp_client: vcs.VolumeControlServiceProxy):
     await vcp_client.volume_control_point.write_value(
-        bytes([vcp.VolumeControlPointOpcode.RELATIVE_VOLUME_DOWN, 0])
+        bytes([vcs.VolumeControlPointOpcode.RELATIVE_VOLUME_DOWN, 0])
     )
-    assert (await vcp_client.volume_state.read_value()) == (16, 1, 1)
+    assert (await vcp_client.volume_state.read_value()) == vcs.VolumeState(16, 1, 1)
 
 
 # -----------------------------------------------------------------------------
 @pytest.mark.asyncio
-async def test_relative_volume_up(vcp_client: vcp.VolumeControlServiceProxy):
+async def test_relative_volume_up(vcp_client: vcs.VolumeControlServiceProxy):
     await vcp_client.volume_control_point.write_value(
-        bytes([vcp.VolumeControlPointOpcode.RELATIVE_VOLUME_UP, 0])
+        bytes([vcs.VolumeControlPointOpcode.RELATIVE_VOLUME_UP, 0])
     )
-    assert (await vcp_client.volume_state.read_value()) == (48, 1, 1)
+    assert (await vcp_client.volume_state.read_value()) == vcs.VolumeState(48, 1, 1)
 
 
 # -----------------------------------------------------------------------------
 @pytest.mark.asyncio
-async def test_unmute_relative_volume_down(vcp_client: vcp.VolumeControlServiceProxy):
+async def test_unmute_relative_volume_down(vcp_client: vcs.VolumeControlServiceProxy):
     await vcp_client.volume_control_point.write_value(
-        bytes([vcp.VolumeControlPointOpcode.UNMUTE_RELATIVE_VOLUME_DOWN, 0])
+        bytes([vcs.VolumeControlPointOpcode.UNMUTE_RELATIVE_VOLUME_DOWN, 0])
     )
-    assert (await vcp_client.volume_state.read_value()) == (16, 0, 1)
+    assert (await vcp_client.volume_state.read_value()) == vcs.VolumeState(16, 0, 1)
 
 
 # -----------------------------------------------------------------------------
 @pytest.mark.asyncio
-async def test_unmute_relative_volume_up(vcp_client: vcp.VolumeControlServiceProxy):
+async def test_unmute_relative_volume_up(vcp_client: vcs.VolumeControlServiceProxy):
     await vcp_client.volume_control_point.write_value(
-        bytes([vcp.VolumeControlPointOpcode.UNMUTE_RELATIVE_VOLUME_UP, 0])
+        bytes([vcs.VolumeControlPointOpcode.UNMUTE_RELATIVE_VOLUME_UP, 0])
     )
-    assert (await vcp_client.volume_state.read_value()) == (48, 0, 1)
+    assert (await vcp_client.volume_state.read_value()) == vcs.VolumeState(48, 0, 1)
 
 
 # -----------------------------------------------------------------------------
 @pytest.mark.asyncio
-async def test_set_absolute_volume(vcp_client: vcp.VolumeControlServiceProxy):
+async def test_set_absolute_volume(vcp_client: vcs.VolumeControlServiceProxy):
     await vcp_client.volume_control_point.write_value(
-        bytes([vcp.VolumeControlPointOpcode.SET_ABSOLUTE_VOLUME, 0, 255])
+        bytes([vcs.VolumeControlPointOpcode.SET_ABSOLUTE_VOLUME, 0, 255])
     )
-    assert (await vcp_client.volume_state.read_value()) == (255, 1, 1)
+    assert (await vcp_client.volume_state.read_value()) == vcs.VolumeState(255, 1, 1)
 
 
 # -----------------------------------------------------------------------------
 @pytest.mark.asyncio
-async def test_mute(vcp_client: vcp.VolumeControlServiceProxy):
+async def test_mute(vcp_client: vcs.VolumeControlServiceProxy):
     await vcp_client.volume_control_point.write_value(
-        bytes([vcp.VolumeControlPointOpcode.MUTE, 0])
+        bytes([vcs.VolumeControlPointOpcode.MUTE, 0])
     )
-    assert (await vcp_client.volume_state.read_value()) == (32, 1, 0)
+    assert (await vcp_client.volume_state.read_value()) == vcs.VolumeState(32, 1, 0)
 
 
 # -----------------------------------------------------------------------------
 @pytest.mark.asyncio
-async def test_unmute(vcp_client: vcp.VolumeControlServiceProxy):
+async def test_unmute(vcp_client: vcs.VolumeControlServiceProxy):
     await vcp_client.volume_control_point.write_value(
-        bytes([vcp.VolumeControlPointOpcode.UNMUTE, 0])
+        bytes([vcs.VolumeControlPointOpcode.UNMUTE, 0])
     )
-    assert (await vcp_client.volume_state.read_value()) == (32, 0, 1)
+    assert (await vcp_client.volume_state.read_value()) == vcs.VolumeState(32, 0, 1)

tests/vocs_test.py

@@ -32,9 +32,8 @@ from bumble.profiles.vocs import (
     SetVolumeOffsetOpCode,
     VolumeOffsetControlServiceProxy,
     VolumeOffsetState,
-    VocsAudioLocation,
 )
-from bumble.profiles.vcp import VolumeControlService, VolumeControlServiceProxy
+from bumble.profiles.vcs import VolumeControlService, VolumeControlServiceProxy
 from bumble.profiles.bap import AudioLocation
 
 from .test_utils import TwoDevices
@@ -81,9 +80,7 @@ async def test_init_service(vocs_client: VolumeOffsetControlServiceProxy):
         volume_offset=0,
         change_counter=0,
     )
-    assert await vocs_client.audio_location.read_value() == VocsAudioLocation(
-        audio_location=AudioLocation.NOT_ALLOWED
-    )
+    assert await vocs_client.audio_location.read_value() == AudioLocation.NOT_ALLOWED
     description = await vocs_client.audio_output_description.read_value()
     assert description == ''
 
@@ -162,11 +159,9 @@ async def test_set_volume_offset(vocs_client: VolumeOffsetControlServiceProxy):
 
 @pytest.mark.asyncio
 async def test_set_audio_channel_location(vocs_client: VolumeOffsetControlServiceProxy):
-    new_audio_location = VocsAudioLocation(audio_location=AudioLocation.FRONT_LEFT)
+    new_audio_location = AudioLocation.FRONT_LEFT
 
-    await vocs_client.audio_location.write_value(
-        struct.pack('<I', new_audio_location.audio_location)
-    )
+    await vocs_client.audio_location.write_value(new_audio_location)
 
     location = await vocs_client.audio_location.read_value()
     assert location == new_audio_location