add test

Unify ISO methods

.github/workflows/code-check.yml

@@ -16,7 +16,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13.0"]
       fail-fast: false
 
     steps:
@@ -33,7 +33,7 @@ jobs:
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
-        python -m pip install ".[build,test,development,pandora]"
+        python -m pip install ".[build,test,development]"
     - name: Check
       run: |
         invoke project.pre-commit

.github/workflows/python-avatar.yml

@@ -32,7 +32,7 @@ jobs:
       - name: Install
         run: |
           python -m pip install --upgrade pip
-          python -m pip install .[avatar,pandora]
+          python -m pip install .[avatar]
       - name: Rootcanal
         run: nohup python -m rootcanal > rootcanal.log &
       - name: Test

.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

@@ -16,25 +16,35 @@
 # Imports
 # -----------------------------------------------------------------------------
 from __future__ import annotations
+
 import asyncio
 import contextlib
 import dataclasses
+import functools
 import logging
 import os
+import wave
+import itertools
 from typing import cast, Any, AsyncGenerator, Coroutine, Dict, 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 \".[lc3]\"`.") from e
+
 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
 
@@ -49,7 +59,7 @@ 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
 
@@ -62,17 +72,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 +91,36 @@ 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.SERVICE_DATA
             ):
                 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
+                core.AdvertisingData.APPEARANCE
             )
 
             if manufacturer_data := advertisement.data.get(
-                bumble.core.AdvertisingData.MANUFACTURER_SPECIFIC_DATA
+                core.AdvertisingData.MANUFACTURER_SPECIFIC_DATA
             ):
                 assert isinstance(manufacturer_data, tuple)
                 company_id = cast(int, manufacturer_data[0])
                 data = cast(bytes, manufacturer_data[1])
                 self.manufacturer_data = (
-                    bumble.company_ids.COMPANY_IDENTIFIERS.get(
+                    company_ids.COMPANY_IDENTIFIERS.get(
                         company_id, f'0x{company_id:04X}'
                     ),
                     data,
@@ -232,15 +231,15 @@ class BroadcastScanner(pyee.EventEmitter):
                 return
 
             for service_data in advertisement.data.get_all(
-                bumble.core.AdvertisingData.SERVICE_DATA
+                core.AdvertisingData.SERVICE_DATA
             ):
                 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 +261,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 +276,44 @@ 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.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 isinstance(ad, tuple)
+                    and 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(core.AdvertisingData.BROADCAST_NAME)
         assert isinstance(broadcast_name, str) or broadcast_name is None
+        assert isinstance(broadcast_audio_announcement[1], bytes)
 
         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,
+                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 +321,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 +333,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,24 +472,26 @@ 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):
+        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}"
                     )
                 )
-            except bumble.core.ProtocolError as error:
+            except core.ProtocolError as error:
                 print(
                     color(
                         f'!!! Failed to subscribe to Broadcast Receive State characteristic:',
@@ -497,7 +510,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 +530,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 +548,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 +559,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 +582,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 +603,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 +623,228 @@ async def run_pair(transport: str, address: str) -> None:
             print("+++ Paired")
 
 
+async def run_receive(
+    transport: str,
+    broadcast_id: int,
+    broadcast_code: str | None,
+    sync_timeout: float,
+    subgroup_index: int,
+) -> None:
+    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.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,
+        )
+        sdus = [b''] * num_bis
+        subprocess = await asyncio.create_subprocess_shell(
+            f'stdbuf -i0 ffplay -ar {sampling_frequency.hz} -ac {num_bis} -f f32le pipe:0',
+            stdin=asyncio.subprocess.PIPE,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+        )
+        for i, bis_link in enumerate(big_sync.bis_links):
+            print(f'Setup ISO for BIS {bis_link.handle}')
+
+            def sink(index: int, packet: hci.HCI_IsoDataPacket):
+                nonlocal sdus
+                sdus[index] = packet.iso_sdu_fragment
+                if all(sdus) and subprocess.stdin:
+                    subprocess.stdin.write(decoder.decode(b''.join(sdus)).tobytes())
+                    sdus = [b''] * num_bis
+
+            bis_link.sink = functools.partial(sink, 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()
+
+
+async def run_broadcast(
+    transport: str, broadcast_id: int, broadcast_code: str | None, wav_file_path: str
+) -> None:
+    async with create_device(transport) as device:
+        if not device.supports_le_periodic_advertising:
+            print(color('Periodic advertising not supported', 'red'))
+            return
+
+        with wave.open(wav_file_path, 'rb') as wav:
+            print('Encoding wav file into lc3...')
+            encoder = lc3.Encoder(
+                frame_duration_us=10000,
+                sample_rate_hz=48000,
+                num_channels=2,
+                input_sample_rate_hz=wav.getframerate(),
+            )
+            frames = list[bytes]()
+            while pcm := wav.readframes(encoder.get_frame_samples()):
+                frames.append(
+                    encoder.encode(pcm, num_bytes=200, bit_depth=wav.getsampwidth() * 8)
+                )
+            del encoder
+            print('Encoding complete.')
+
+        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)
+        print('Start Advertising')
+        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, b'Bumble Auracast')]
+                    )
+                )
+            ),
+            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()
+        print('Setup BIG')
+        big = await device.create_big(
+            advertising_set,
+            parameters=bumble.device.BigParameters(
+                num_bis=2,
+                sdu_interval=10000,
+                max_sdu=100,
+                max_transport_latency=65,
+                rtn=4,
+                broadcast_code=(
+                    bytes.fromhex(broadcast_code) if broadcast_code else None
+                ),
+            ),
+        )
+        print('Setup ISO Data Path')
+        for bis_link in big.bis_links:
+            await bis_link.setup_data_path(
+                direction=bis_link.Direction.HOST_TO_CONTROLLER
+            )
+
+        for frame in itertools.cycle(frames):
+            mid = len(frame) // 2
+            big.bis_links[0].write(frame[:mid])
+            big.bis_links[1].write(frame[mid:])
+            await asyncio.sleep(0.009)
+
+
 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 +858,7 @@ def run_async(async_command: Coroutine) -> None:
 # -----------------------------------------------------------------------------
 @click.group()
 @click.pass_context
-def auracast(
-    ctx,
-):
+def auracast(ctx):
     ctx.ensure_object(dict)
 
 
@@ -691,6 +916,66 @@ def pair(ctx, transport, address):
     run_async(run_pair(transport, address))
 
 
+@auracast.command('receive')
+@click.argument('transport')
+@click.argument('broadcast_id', type=int)
+@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, broadcast_code, sync_timeout, subgroup):
+    """Receive a broadcast source"""
+    run_async(
+        run_receive(transport, broadcast_id, broadcast_code, sync_timeout, subgroup)
+    )
+
+
+@auracast.command('broadcast')
+@click.argument('transport')
+@click.argument('wav_file_path', type=str)
+@click.option(
+    '--broadcast-id',
+    metavar='BROADCAST_ID',
+    type=int,
+    default=123456,
+    help='Broadcast ID',
+)
+@click.option(
+    '--broadcast-code',
+    metavar='BROADCAST_CODE',
+    type=str,
+    help='Broadcast encryption code in hex format',
+)
+@click.pass_context
+def broadcast(ctx, transport, broadcast_id, broadcast_code, wav_file_path):
+    """Start a broadcast as a source."""
+    run_async(
+        run_broadcast(
+            transport=transport,
+            broadcast_id=broadcast_id,
+            broadcast_code=broadcast_code,
+            wav_file_path=wav_file_path,
+        )
+    )
+
+
 def main():
     logging.basicConfig(level=os.environ.get('BUMBLE_LOGLEVEL', 'INFO').upper())
     auracast()

apps/bench.py

@@ -199,7 +199,7 @@ def log_stats(title, stats, precision=2):
     stats_min = min(stats)
     stats_max = max(stats)
     stats_avg = statistics.mean(stats)
-    stats_stdev = statistics.stdev(stats)
+    stats_stdev = statistics.stdev(stats) if len(stats) >= 2 else 0
     logging.info(
         color(
             (
@@ -468,6 +468,7 @@ class Ping:
 
         for run in range(self.repeat + 1):
             self.done.clear()
+            self.ping_times = []
 
             if run > 0 and self.repeat and self.repeat_delay:
                 logging.info(color(f'*** Repeat delay: {self.repeat_delay}', 'green'))

apps/controller_info.py

@@ -75,7 +75,7 @@ async def get_classic_info(host: Host) -> None:
         if command_succeeded(response):
             print()
             print(
-                color('Classic Address:', 'yellow'),
+                color('Public Address:', 'yellow'),
                 response.return_parameters.bd_addr.to_string(False),
             )
 

apps/lea_unicast/app.py

@@ -16,23 +16,22 @@
 # Imports
 # -----------------------------------------------------------------------------
 from __future__ import annotations
+
 import asyncio
 import datetime
-import enum
 import functools
 from importlib import resources
 import json
 import os
 import logging
 import pathlib
-from typing import Optional, List, cast
 import weakref
-import struct
+import wave
 
-import ctypes
-import wasmtime
-import wasmtime.loader
-import liblc3  # type: ignore
+try:
+    import lc3  # type: ignore  # pylint: disable=E0401
+except ImportError as e:
+    raise ImportError("Try `python -m pip install \".[lc3]\"`.") from e
 
 import click
 import aiohttp.web
@@ -40,11 +39,12 @@ 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
 
+
 # -----------------------------------------------------------------------------
 # Logging
 # -----------------------------------------------------------------------------
@@ -54,6 +54,7 @@ logger = logging.getLogger(__name__)
 # Constants
 # -----------------------------------------------------------------------------
 DEFAULT_UI_PORT = 7654
+DEFAULT_PCM_BYTES_PER_SAMPLE = 2
 
 
 def _sink_pac_record() -> pacs.PacRecord:
@@ -100,153 +101,8 @@ def _source_pac_record() -> pacs.PacRecord:
     )
 
 
-# -----------------------------------------------------------------------------
-# WASM - liblc3
-# -----------------------------------------------------------------------------
-store = wasmtime.loader.store
-_memory = cast(wasmtime.Memory, liblc3.memory)
-STACK_POINTER = _memory.data_len(store)
-_memory.grow(store, 1)
-# Mapping wasmtime memory to linear address
-memory = (ctypes.c_ubyte * _memory.data_len(store)).from_address(
-    ctypes.addressof(_memory.data_ptr(store).contents)  # type: ignore
-)
-
-
-class Liblc3PcmFormat(enum.IntEnum):
-    S16 = 0
-    S24 = 1
-    S24_3LE = 2
-    FLOAT = 3
-
-
-MAX_DECODER_SIZE = liblc3.lc3_decoder_size(10000, 48000)
-MAX_ENCODER_SIZE = liblc3.lc3_encoder_size(10000, 48000)
-
-DECODER_STACK_POINTER = STACK_POINTER
-ENCODER_STACK_POINTER = DECODER_STACK_POINTER + MAX_DECODER_SIZE * 2
-DECODE_BUFFER_STACK_POINTER = ENCODER_STACK_POINTER + MAX_ENCODER_SIZE * 2
-ENCODE_BUFFER_STACK_POINTER = DECODE_BUFFER_STACK_POINTER + 8192
-DEFAULT_PCM_SAMPLE_RATE = 48000
-DEFAULT_PCM_FORMAT = Liblc3PcmFormat.S16
-DEFAULT_PCM_BYTES_PER_SAMPLE = 2
-
-
-encoders: List[int] = []
-decoders: List[int] = []
-
-
-def setup_encoders(
-    sample_rate_hz: int, frame_duration_us: int, num_channels: int
-) -> None:
-    logger.info(
-        f"setup_encoders {sample_rate_hz}Hz {frame_duration_us}us {num_channels}channels"
-    )
-    encoders[:num_channels] = [
-        liblc3.lc3_setup_encoder(
-            frame_duration_us,
-            sample_rate_hz,
-            DEFAULT_PCM_SAMPLE_RATE,  # Input sample rate
-            ENCODER_STACK_POINTER + MAX_ENCODER_SIZE * i,
-        )
-        for i in range(num_channels)
-    ]
-
-
-def setup_decoders(
-    sample_rate_hz: int, frame_duration_us: int, num_channels: int
-) -> None:
-    logger.info(
-        f"setup_decoders {sample_rate_hz}Hz {frame_duration_us}us {num_channels}channels"
-    )
-    decoders[:num_channels] = [
-        liblc3.lc3_setup_decoder(
-            frame_duration_us,
-            sample_rate_hz,
-            DEFAULT_PCM_SAMPLE_RATE,  # Output sample rate
-            DECODER_STACK_POINTER + MAX_DECODER_SIZE * i,
-        )
-        for i in range(num_channels)
-    ]
-
-
-def decode(
-    frame_duration_us: int,
-    num_channels: int,
-    input_bytes: bytes,
-) -> bytes:
-    if not input_bytes:
-        return b''
-
-    input_buffer_offset = DECODE_BUFFER_STACK_POINTER
-    input_buffer_size = len(input_bytes)
-    input_bytes_per_frame = input_buffer_size // num_channels
-
-    # Copy into wasm
-    memory[input_buffer_offset : input_buffer_offset + input_buffer_size] = input_bytes  # type: ignore
-
-    output_buffer_offset = input_buffer_offset + input_buffer_size
-    output_buffer_size = (
-        liblc3.lc3_frame_samples(frame_duration_us, DEFAULT_PCM_SAMPLE_RATE)
-        * DEFAULT_PCM_BYTES_PER_SAMPLE
-        * num_channels
-    )
-
-    for i in range(num_channels):
-        res = liblc3.lc3_decode(
-            decoders[i],
-            input_buffer_offset + input_bytes_per_frame * i,
-            input_bytes_per_frame,
-            DEFAULT_PCM_FORMAT,
-            output_buffer_offset + i * DEFAULT_PCM_BYTES_PER_SAMPLE,
-            num_channels,  # Stride
-        )
-
-        if res != 0:
-            logging.error(f"Parsing failed, res={res}")
-
-    # Extract decoded data from the output buffer
-    return bytes(
-        memory[output_buffer_offset : output_buffer_offset + output_buffer_size]
-    )
-
-
-def encode(
-    sdu_length: int,
-    num_channels: int,
-    stride: int,
-    input_bytes: bytes,
-) -> bytes:
-    if not input_bytes:
-        return b''
-
-    input_buffer_offset = ENCODE_BUFFER_STACK_POINTER
-    input_buffer_size = len(input_bytes)
-
-    # Copy into wasm
-    memory[input_buffer_offset : input_buffer_offset + input_buffer_size] = input_bytes  # type: ignore
-
-    output_buffer_offset = input_buffer_offset + input_buffer_size
-    output_buffer_size = sdu_length
-    output_frame_size = output_buffer_size // num_channels
-
-    for i in range(num_channels):
-        res = liblc3.lc3_encode(
-            encoders[i],
-            DEFAULT_PCM_FORMAT,
-            input_buffer_offset + DEFAULT_PCM_BYTES_PER_SAMPLE * i,
-            stride,
-            output_frame_size,
-            output_buffer_offset + output_frame_size * i,
-        )
-
-        if res != 0:
-            logging.error(f"Parsing failed, res={res}")
-
-    # Extract decoded data from the output buffer
-    return bytes(
-        memory[output_buffer_offset : output_buffer_offset + output_buffer_size]
-    )
+decoder: lc3.Decoder | None = None
+encoding_config: bap.CodecSpecificConfiguration | None = None
 
 
 async def lc3_source_task(
@@ -254,44 +110,49 @@ async def lc3_source_task(
     sdu_length: int,
     frame_duration_us: int,
     device: Device,
-    cis_handle: int,
+    cis_link: CisLink,
 ) -> None:
-    with open(filename, 'rb') as f:
-        header = f.read(44)
-        assert header[8:12] == b'WAVE'
+    logger.info(
+        "lc3_source_task filename=%s, sdu_length=%d, frame_duration=%.1f",
+        filename,
+        sdu_length,
+        frame_duration_us / 1000,
+    )
+    with wave.open(filename, 'rb') as wav:
+        bits_per_sample = wav.getsampwidth() * 8
 
-        pcm_num_channel, pcm_sample_rate, _byte_rate, _block_align, bits_per_sample = (
-            struct.unpack("<HIIHH", header[22:36])
-        )
-        assert pcm_sample_rate == DEFAULT_PCM_SAMPLE_RATE
-        assert bits_per_sample == DEFAULT_PCM_BYTES_PER_SAMPLE * 8
-
-        frame_bytes = (
-            liblc3.lc3_frame_samples(frame_duration_us, DEFAULT_PCM_SAMPLE_RATE)
-            * DEFAULT_PCM_BYTES_PER_SAMPLE
-        )
-        packet_sequence_number = 0
+        encoder: lc3.Encoder | None = None
 
         while True:
             next_round = datetime.datetime.now() + datetime.timedelta(
                 microseconds=frame_duration_us
             )
-            pcm_data = f.read(frame_bytes)
-            sdu = encode(sdu_length, pcm_num_channel, pcm_num_channel, pcm_data)
+            if not encoder:
+                if (
+                    encoding_config
+                    and (frame_duration := encoding_config.frame_duration)
+                    and (sampling_frequency := encoding_config.sampling_frequency)
+                    and (
+                        audio_channel_allocation := encoding_config.audio_channel_allocation
+                    )
+                ):
+                    logger.info("Use %s", encoding_config)
+                    encoder = lc3.Encoder(
+                        frame_duration_us=frame_duration.us,
+                        sample_rate_hz=sampling_frequency.hz,
+                        num_channels=audio_channel_allocation.channel_count,
+                        input_sample_rate_hz=wav.getframerate(),
+                    )
+            else:
+                sdu = encoder.encode(
+                    pcm=wav.readframes(encoder.get_frame_samples()),
+                    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())
+            await asyncio.sleep(sleep_time.total_seconds() * 0.9)
 
 
 # -----------------------------------------------------------------------------
@@ -410,7 +271,7 @@ class Speaker:
 
     def __init__(
         self,
-        device_config_path: Optional[str],
+        device_config_path: str | None,
         ui_port: int,
         transport: str,
         lc3_input_file_path: str,
@@ -437,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
@@ -490,12 +352,12 @@ class Speaker:
                     not isinstance(codec_config, bap.CodecSpecificConfiguration)
                     or codec_config.frame_duration is None
                     or codec_config.audio_channel_allocation is None
+                    or decoder is None
+                    or not pdu.iso_sdu_fragment
                 ):
                     return
-                pcm = decode(
-                    codec_config.frame_duration.us,
-                    codec_config.audio_channel_allocation.channel_count,
-                    pdu.iso_sdu_fragment,
+                pcm = decoder.decode(
+                    pdu.iso_sdu_fragment, bit_depth=DEFAULT_PCM_BYTES_PER_SAMPLE * 8
                 )
                 self.device.abort_on('disconnection', self.ui_server.send_audio(pcm))
 
@@ -521,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:
@@ -537,16 +399,14 @@ class Speaker:
                     ):
                         return
                     if ase.role == ascs.AudioRole.SOURCE:
-                        setup_encoders(
-                            codec_config.sampling_frequency.hz,
-                            codec_config.frame_duration.us,
-                            codec_config.audio_channel_allocation.channel_count,
-                        )
+                        global encoding_config
+                        encoding_config = codec_config
                     else:
-                        setup_decoders(
-                            codec_config.sampling_frequency.hz,
-                            codec_config.frame_duration.us,
-                            codec_config.audio_channel_allocation.channel_count,
+                        global decoder
+                        decoder = lc3.Decoder(
+                            frame_duration_us=codec_config.frame_duration.us,
+                            sample_rate_hz=codec_config.sampling_frequency.hz,
+                            num_channels=codec_config.audio_channel_allocation.channel_count,
                         )
 
             for ase in ascs_service.ase_state_machines.values():
@@ -585,7 +445,7 @@ def speaker(ui_port: int, device_config: str, transport: str, lc3_file: str) ->
 
 # -----------------------------------------------------------------------------
 def main():
-    logging.basicConfig(level=os.environ.get('BUMBLE_LOGLEVEL', 'WARNING').upper())
+    logging.basicConfig(level=os.environ.get('BUMBLE_LOGLEVEL', 'INFO').upper())
     speaker()
 
 

apps/pair.py

@@ -373,7 +373,9 @@ async def pair(
             shared_data = (
                 None
                 if oob == '-'
-                else OobData.from_ad(AdvertisingData.from_bytes(bytes.fromhex(oob)))
+                else OobData.from_ad(
+                    AdvertisingData.from_bytes(bytes.fromhex(oob))
+                ).shared_data
             )
             legacy_context = OobLegacyContext()
             oob_contexts = PairingConfig.OobConfig(
@@ -381,16 +383,19 @@ async def pair(
                 peer_data=shared_data,
                 legacy_context=legacy_context,
             )
-            oob_data = OobData(
-                address=device.random_address,
-                shared_data=shared_data,
-                legacy_context=legacy_context,
-            )
             print(color('@@@-----------------------------------', 'yellow'))
             print(color('@@@ OOB Data:', 'yellow'))
-            print(color(f'@@@   {our_oob_context.share()}', 'yellow'))
+            if shared_data is None:
+                oob_data = OobData(
+                    address=device.random_address, shared_data=our_oob_context.share()
+                )
+                print(
+                    color(
+                        f'@@@   SHARE: {bytes(oob_data.to_ad()).hex()}',
+                        'yellow',
+                    )
+                )
             print(color(f'@@@   TK={legacy_context.tk.hex()}', 'yellow'))
-            print(color(f'@@@   HEX: ({bytes(oob_data.to_ad()).hex()})', 'yellow'))
             print(color('@@@-----------------------------------', 'yellow'))
         else:
             oob_contexts = None

apps/show.py

@@ -144,18 +144,18 @@ class Printer:
     help='Format of the input file',
 )
 @click.option(
-    '--vendors',
+    '--vendor',
     type=click.Choice(['android', 'zephyr']),
     multiple=True,
     help='Support vendor-specific commands (list one or more)',
 )
 @click.argument('filename')
 # pylint: disable=redefined-builtin
-def main(format, vendors, filename):
-    for vendor in vendors:
-        if vendor == 'android':
+def main(format, vendor, filename):
+    for vendor_name in vendor:
+        if vendor_name == 'android':
             import bumble.vendor.android.hci
-        elif vendor == 'zephyr':
+        elif vendor_name == 'zephyr':
             import bumble.vendor.zephyr.hci
 
     input = open(filename, 'rb')
@@ -180,7 +180,7 @@ def main(format, vendors, filename):
             else:
                 printer.print(color("[TRUNCATED]", "red"))
         except Exception as error:
-            logger.exception()
+            logger.exception('')
             print(color(f'!!! {error}', 'red'))
 
 

bumble/att.py

@@ -57,6 +57,7 @@ if TYPE_CHECKING:
 # pylint: disable=line-too-long
 
 ATT_CID = 0x04
+ATT_PSM = 0x001F
 
 ATT_ERROR_RESPONSE              = 0x01
 ATT_EXCHANGE_MTU_REQUEST        = 0x02
@@ -756,13 +757,13 @@ class AttributeValue:
     def __init__(
         self,
         read: Union[
-            Callable[[Optional[Connection]], bytes],
-            Callable[[Optional[Connection]], Awaitable[bytes]],
+            Callable[[Optional[Connection]], Any],
+            Callable[[Optional[Connection]], Awaitable[Any]],
             None,
         ] = None,
         write: Union[
-            Callable[[Optional[Connection], bytes], None],
-            Callable[[Optional[Connection], bytes], Awaitable[None]],
+            Callable[[Optional[Connection], Any], None],
+            Callable[[Optional[Connection], Any], Awaitable[None]],
             None,
         ] = None,
     ):
@@ -821,13 +822,13 @@ class Attribute(EventEmitter):
     READ_REQUIRES_AUTHORIZATION = Permissions.READ_REQUIRES_AUTHORIZATION
     WRITE_REQUIRES_AUTHORIZATION = Permissions.WRITE_REQUIRES_AUTHORIZATION
 
-    value: Union[bytes, AttributeValue]
+    value: Any
 
     def __init__(
         self,
         attribute_type: Union[str, bytes, UUID],
         permissions: Union[str, Attribute.Permissions],
-        value: Union[str, bytes, AttributeValue] = b'',
+        value: Any = b'',
     ) -> None:
         EventEmitter.__init__(self)
         self.handle = 0
@@ -845,11 +846,7 @@ class Attribute(EventEmitter):
         else:
             self.type = attribute_type
 
-        # Convert the value to a byte array
-        if isinstance(value, str):
-            self.value = bytes(value, 'utf-8')
-        else:
-            self.value = value
+        self.value = value
 
     def encode_value(self, value: Any) -> bytes:
         return value
@@ -892,6 +889,8 @@ class Attribute(EventEmitter):
         else:
             value = self.value
 
+        self.emit('read', connection, value)
+
         return self.encode_value(value)
 
     async def write_value(self, connection: Connection, value_bytes: bytes) -> None:

bumble/core.py

@@ -1501,7 +1501,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])

bumble/device.py

@@ -17,7 +17,7 @@
 # -----------------------------------------------------------------------------
 from __future__ import annotations
 import asyncio
-from collections.abc import Iterable
+from collections.abc import Iterable, Sequence
 from contextlib import (
     asynccontextmanager,
     AsyncExitStack,
@@ -37,9 +37,7 @@ from typing import (
     Callable,
     ClassVar,
     Dict,
-    List,
     Optional,
-    Tuple,
     Type,
     TypeVar,
     Union,
@@ -119,6 +117,8 @@ DEVICE_MIN_LE_RSSI                            = -127
 DEVICE_MAX_LE_RSSI                            = 20
 DEVICE_MIN_EXTENDED_ADVERTISING_SET_HANDLE    = 0x00
 DEVICE_MAX_EXTENDED_ADVERTISING_SET_HANDLE    = 0xEF
+DEVICE_MIN_BIG_HANDLE                         = 0x00
+DEVICE_MAX_BIG_HANDLE                         = 0xEF
 
 DEVICE_DEFAULT_ADDRESS                        = '00:00:00:00:00:00'
 DEVICE_DEFAULT_ADVERTISING_INTERVAL           = 1000  # ms
@@ -992,6 +992,130 @@ class PeriodicAdvertisingSync(EventEmitter):
         )
 
 
+# -----------------------------------------------------------------------------
+@dataclass
+class BigParameters:
+    num_bis: int
+    sdu_interval: int
+    max_sdu: int
+    max_transport_latency: int
+    rtn: int
+    phy: hci.PhyBit = hci.PhyBit.LE_2M
+    packing: int = 0
+    framing: int = 0
+    broadcast_code: bytes | None = None
+
+
+# -----------------------------------------------------------------------------
+@dataclass
+class Big(EventEmitter):
+    class State(IntEnum):
+        PENDING = 0
+        ACTIVE = 1
+        TERMINATED = 2
+
+    class Event(str, Enum):
+        ESTABLISHMENT = 'establishment'
+        ESTABLISHMENT_FAILURE = 'establishment_failure'
+        TERMINATION = 'termination'
+
+    big_handle: int
+    advertising_set: AdvertisingSet
+    parameters: BigParameters
+    state: State = State.PENDING
+
+    # Attributes provided by BIG Create Complete event
+    big_sync_delay: int = 0
+    transport_latency_big: int = 0
+    phy: int = 0
+    nse: int = 0
+    bn: int = 0
+    pto: int = 0
+    irc: int = 0
+    max_pdu: int = 0
+    iso_interval: int = 0
+    bis_links: Sequence[BisLink] = ()
+
+    def __post_init__(self) -> None:
+        super().__init__()
+        self.device = self.advertising_set.device
+
+    async def terminate(
+        self,
+        reason: int = hci.HCI_REMOTE_USER_TERMINATED_CONNECTION_ERROR,
+    ) -> None:
+        if self.state != Big.State.ACTIVE:
+            logger.error('BIG %d is not active.', self.big_handle)
+            return
+
+        with closing(EventWatcher()) as watcher:
+            terminated = asyncio.Event()
+            watcher.once(self, Big.Event.TERMINATION, lambda _: terminated.set())
+            await self.device.send_command(
+                hci.HCI_LE_Terminate_BIG_Command(
+                    big_handle=self.big_handle, reason=reason
+                ),
+                check_result=True,
+            )
+            await terminated.wait()
+
+
+# -----------------------------------------------------------------------------
+@dataclass
+class BigSyncParameters:
+    big_sync_timeout: int
+    bis: Sequence[int]
+    mse: int = 0
+    broadcast_code: bytes | None = None
+
+
+# -----------------------------------------------------------------------------
+@dataclass
+class BigSync(EventEmitter):
+    class State(IntEnum):
+        PENDING = 0
+        ACTIVE = 1
+        TERMINATED = 2
+
+    class Event(str, Enum):
+        ESTABLISHMENT = 'establishment'
+        ESTABLISHMENT_FAILURE = 'establishment_failure'
+        TERMINATION = 'termination'
+
+    big_handle: int
+    pa_sync: PeriodicAdvertisingSync
+    parameters: BigSyncParameters
+    state: State = State.PENDING
+
+    # Attributes provided by BIG Create Sync Complete event
+    transport_latency_big: int = 0
+    nse: int = 0
+    bn: int = 0
+    pto: int = 0
+    irc: int = 0
+    max_pdu: int = 0
+    iso_interval: int = 0
+    bis_links: Sequence[BisLink] = ()
+
+    def __post_init__(self) -> None:
+        super().__init__()
+        self.device = self.pa_sync.device
+
+    async def terminate(self) -> None:
+        if self.state != BigSync.State.ACTIVE:
+            logger.error('BIG Sync %d is not active.', self.big_handle)
+            return
+
+        with closing(EventWatcher()) as watcher:
+            terminated = asyncio.Event()
+            watcher.once(self, BigSync.Event.TERMINATION, lambda _: terminated.set())
+            await self.device.send_command(
+                hci.HCI_LE_BIG_Terminate_Sync_Command(big_handle=self.big_handle),
+                check_result=True,
+            )
+            await terminated.wait()
+
+
 # -----------------------------------------------------------------------------
 class LePhyOptions:
     # Coded PHY preference
@@ -1019,7 +1143,7 @@ class Peer:
         connection.gatt_client = self.gatt_client
 
     @property
-    def services(self) -> List[gatt_client.ServiceProxy]:
+    def services(self) -> list[gatt_client.ServiceProxy]:
         return self.gatt_client.services
 
     async def request_mtu(self, mtu: int) -> int:
@@ -1029,24 +1153,24 @@ class Peer:
 
     async def discover_service(
         self, uuid: Union[core.UUID, str]
-    ) -> List[gatt_client.ServiceProxy]:
+    ) -> list[gatt_client.ServiceProxy]:
         return await self.gatt_client.discover_service(uuid)
 
     async def discover_services(
         self, uuids: Iterable[core.UUID] = ()
-    ) -> List[gatt_client.ServiceProxy]:
+    ) -> list[gatt_client.ServiceProxy]:
         return await self.gatt_client.discover_services(uuids)
 
     async def discover_included_services(
         self, service: gatt_client.ServiceProxy
-    ) -> List[gatt_client.ServiceProxy]:
+    ) -> list[gatt_client.ServiceProxy]:
         return await self.gatt_client.discover_included_services(service)
 
     async def discover_characteristics(
         self,
         uuids: Iterable[Union[core.UUID, str]] = (),
         service: Optional[gatt_client.ServiceProxy] = None,
-    ) -> List[gatt_client.CharacteristicProxy]:
+    ) -> list[gatt_client.CharacteristicProxy]:
         return await self.gatt_client.discover_characteristics(
             uuids=uuids, service=service
         )
@@ -1061,7 +1185,7 @@ class Peer:
             characteristic, start_handle, end_handle
         )
 
-    async def discover_attributes(self) -> List[gatt_client.AttributeProxy]:
+    async def discover_attributes(self) -> list[gatt_client.AttributeProxy]:
         return await self.gatt_client.discover_attributes()
 
     async def discover_all(self):
@@ -1105,17 +1229,17 @@ class Peer:
 
     async def read_characteristics_by_uuid(
         self, uuid: core.UUID, service: Optional[gatt_client.ServiceProxy] = None
-    ) -> List[bytes]:
+    ) -> list[bytes]:
         return await self.gatt_client.read_characteristics_by_uuid(uuid, service)
 
-    def get_services_by_uuid(self, uuid: core.UUID) -> List[gatt_client.ServiceProxy]:
+    def get_services_by_uuid(self, uuid: core.UUID) -> list[gatt_client.ServiceProxy]:
         return self.gatt_client.get_services_by_uuid(uuid)
 
     def get_characteristics_by_uuid(
         self,
         uuid: core.UUID,
         service: Optional[Union[gatt_client.ServiceProxy, core.UUID]] = None,
-    ) -> List[gatt_client.CharacteristicProxy]:
+    ) -> list[gatt_client.CharacteristicProxy]:
         if isinstance(service, core.UUID):
             return list(
                 itertools.chain(
@@ -1201,9 +1325,93 @@ class ScoLink(CompositeEventEmitter):
         await self.device.disconnect(self, reason)
 
 
+# -----------------------------------------------------------------------------
+class _IsoLink:
+    handle: int
+    device: Device
+    packet_sequence_number: int
+    sink: Callable[[hci.HCI_IsoDataPacket], Any] | None = None
+
+    class Direction(IntEnum):
+        HOST_TO_CONTROLLER = (
+            hci.HCI_LE_Setup_ISO_Data_Path_Command.Direction.HOST_TO_CONTROLLER
+        )
+        CONTROLLER_TO_HOST = (
+            hci.HCI_LE_Setup_ISO_Data_Path_Command.Direction.CONTROLLER_TO_HOST
+        )
+
+    async def setup_data_path(
+        self,
+        direction: _IsoLink.Direction,
+        data_path_id: int = 0,
+        codec_id: hci.CodingFormat | None = None,
+        controller_delay: int = 0,
+        codec_configuration: bytes = b'',
+    ) -> None:
+        """Create a data path between controller and given entry.
+
+        Args:
+            direction: Direction of data path.
+            data_path_id: ID of data path. Default is 0 (HCI).
+            codec_id: Codec ID. Default is Transparent.
+            controller_delay: Controller delay in microseconds. Default is 0.
+            codec_configuration: Codec-specific configuration.
+
+        Raises:
+            HCI_Error: When command complete status is not HCI_SUCCESS.
+        """
+        await self.device.send_command(
+            hci.HCI_LE_Setup_ISO_Data_Path_Command(
+                connection_handle=self.handle,
+                data_path_direction=direction,
+                data_path_id=data_path_id,
+                codec_id=codec_id or hci.CodingFormat(hci.CodecID.TRANSPARENT),
+                controller_delay=controller_delay,
+                codec_configuration=codec_configuration,
+            ),
+            check_result=True,
+        )
+
+    async def remove_data_path(self, direction: _IsoLink.Direction) -> int:
+        """Remove a data path with controller on given direction.
+
+        Args:
+            direction: Direction of data path.
+
+        Returns:
+            Command status.
+        """
+        response = await self.device.send_command(
+            hci.HCI_LE_Remove_ISO_Data_Path_Command(
+                connection_handle=self.handle,
+                data_path_direction=direction,
+            ),
+            check_result=False,
+        )
+        return response.return_parameters.status
+
+    def write(self, sdu: bytes) -> None:
+        """Write an ISO SDU.
+
+        This will automatically increase the packet sequence number.
+        """
+        self.device.host.send_hci_packet(
+            hci.HCI_IsoDataPacket(
+                connection_handle=self.handle,
+                data_total_length=len(sdu) + 4,
+                packet_sequence_number=self.packet_sequence_number,
+                pb_flag=0b10,
+                packet_status_flag=0,
+                iso_sdu_length=len(sdu),
+                iso_sdu_fragment=sdu,
+            )
+        )
+        self.packet_sequence_number += 1
+
+
 # -----------------------------------------------------------------------------
 @dataclass
-class CisLink(CompositeEventEmitter):
+class CisLink(CompositeEventEmitter, _IsoLink):
     class State(IntEnum):
         PENDING = 0
         ESTABLISHED = 1
@@ -1214,10 +1422,11 @@ class CisLink(CompositeEventEmitter):
     cis_id: int  # CIS ID assigned by Central device
     cig_id: int  # CIG ID assigned by Central device
     state: State = State.PENDING
-    sink: Optional[Callable[[hci.HCI_IsoDataPacket], Any]] = None
+    sink: Callable[[hci.HCI_IsoDataPacket], Any] | None = None
 
     def __post_init__(self) -> None:
         super().__init__()
+        self.packet_sequence_number = 0
 
     async def disconnect(
         self, reason: int = hci.HCI_REMOTE_USER_TERMINATED_CONNECTION_ERROR
@@ -1225,6 +1434,18 @@ class CisLink(CompositeEventEmitter):
         await self.device.disconnect(self, reason)
 
 
+# -----------------------------------------------------------------------------
+@dataclass
+class BisLink(_IsoLink):
+    handle: int
+    big: Big | BigSync
+    sink: Callable[[hci.HCI_IsoDataPacket], Any] | None = None
+
+    def __post_init__(self) -> None:
+        self.device = self.big.device
+        self.packet_sequence_number = 0
+
+
 # -----------------------------------------------------------------------------
 class Connection(CompositeEventEmitter):
     device: Device
@@ -1537,7 +1758,7 @@ class DeviceConfiguration:
     io_capability: int = pairing.PairingDelegate.IoCapability.NO_OUTPUT_NO_INPUT
 
     def __post_init__(self) -> None:
-        self.gatt_services: List[Dict[str, Any]] = []
+        self.gatt_services: list[Dict[str, Any]] = []
 
     def load_from_dict(self, config: Dict[str, Any]) -> None:
         config = copy.deepcopy(config)
@@ -1684,7 +1905,7 @@ def host_event_handler(function):
 # List of host event handlers for the Device class.
 # (we define this list outside the class, because referencing a class in method
 #  decorators is not straightforward)
-device_host_event_handlers: List[str] = []
+device_host_event_handlers: list[str] = []
 
 
 # -----------------------------------------------------------------------------
@@ -1705,15 +1926,18 @@ class Device(CompositeEventEmitter):
     pending_connections: Dict[hci.Address, Connection]
     classic_pending_accepts: Dict[
         hci.Address,
-        List[asyncio.Future[Union[Connection, Tuple[hci.Address, int, int]]]],
+        list[asyncio.Future[Union[Connection, tuple[hci.Address, int, int]]]],
     ]
     advertisement_accumulators: Dict[hci.Address, AdvertisementDataAccumulator]
-    periodic_advertising_syncs: List[PeriodicAdvertisingSync]
+    periodic_advertising_syncs: list[PeriodicAdvertisingSync]
     config: DeviceConfiguration
     legacy_advertiser: Optional[LegacyAdvertiser]
     sco_links: Dict[int, ScoLink]
     cis_links: Dict[int, CisLink]
-    _pending_cis: Dict[int, Tuple[int, int]]
+    bigs = dict[int, Big]()
+    bis_links = dict[int, BisLink]()
+    big_syncs = dict[int, BigSync]()
+    _pending_cis: Dict[int, tuple[int, int]]
 
     @composite_listener
     class Listener:
@@ -2009,6 +2233,17 @@ class Device(CompositeEventEmitter):
             None,
         )
 
+    def next_big_handle(self) -> int | None:
+        return next(
+            (
+                handle
+                for handle in range(DEVICE_MIN_BIG_HANDLE, DEVICE_MAX_BIG_HANDLE + 1)
+                if handle
+                not in itertools.chain(self.bigs.keys(), self.big_syncs.keys())
+            ),
+            None,
+        )
+
     @deprecated("Please use create_l2cap_server()")
     def register_l2cap_server(self, psm, server) -> int:
         return self.l2cap_channel_manager.register_server(psm, server)
@@ -2627,7 +2862,7 @@ class Device(CompositeEventEmitter):
         scan_window: int = DEVICE_DEFAULT_SCAN_WINDOW,  # Scan window in ms
         own_address_type: int = hci.OwnAddressType.RANDOM,
         filter_duplicates: bool = False,
-        scanning_phys: List[int] = [hci.HCI_LE_1M_PHY, hci.HCI_LE_CODED_PHY],
+        scanning_phys: Sequence[int] = (hci.HCI_LE_1M_PHY, hci.HCI_LE_CODED_PHY),
     ) -> None:
         # Check that the arguments are legal
         if scan_interval < scan_window:
@@ -3958,13 +4193,13 @@ class Device(CompositeEventEmitter):
     async def setup_cig(
         self,
         cig_id: int,
-        cis_id: List[int],
-        sdu_interval: Tuple[int, int],
+        cis_id: Sequence[int],
+        sdu_interval: tuple[int, int],
         framing: int,
-        max_sdu: Tuple[int, int],
+        max_sdu: tuple[int, int],
         retransmission_number: int,
-        max_transport_latency: Tuple[int, int],
-    ) -> List[int]:
+        max_transport_latency: tuple[int, int],
+    ) -> list[int]:
         """Sends hci.HCI_LE_Set_CIG_Parameters_Command.
 
         Args:
@@ -4013,7 +4248,9 @@ class Device(CompositeEventEmitter):
 
     # [LE only]
     @experimental('Only for testing.')
-    async def create_cis(self, cis_acl_pairs: List[Tuple[int, int]]) -> List[CisLink]:
+    async def create_cis(
+        self, cis_acl_pairs: Sequence[tuple[int, int]]
+    ) -> list[CisLink]:
         for cis_handle, acl_handle in cis_acl_pairs:
             acl_connection = self.lookup_connection(acl_handle)
             assert acl_connection
@@ -4112,6 +4349,106 @@ class Device(CompositeEventEmitter):
             check_result=True,
         )
 
+    # [LE only]
+    @experimental('Only for testing.')
+    async def create_big(
+        self, advertising_set: AdvertisingSet, parameters: BigParameters
+    ) -> Big:
+        if (big_handle := self.next_big_handle()) is None:
+            raise core.OutOfResourcesError("All valid BIG handles already in use")
+
+        with closing(EventWatcher()) as watcher:
+            big = Big(
+                big_handle=big_handle,
+                parameters=parameters,
+                advertising_set=advertising_set,
+            )
+            self.bigs[big_handle] = big
+            established = asyncio.get_running_loop().create_future()
+            watcher.once(
+                big, big.Event.ESTABLISHMENT, lambda: established.set_result(None)
+            )
+            watcher.once(
+                big,
+                big.Event.ESTABLISHMENT_FAILURE,
+                lambda status: established.set_exception(hci.HCI_Error(status)),
+            )
+
+            try:
+                await self.send_command(
+                    hci.HCI_LE_Create_BIG_Command(
+                        big_handle=big_handle,
+                        advertising_handle=advertising_set.advertising_handle,
+                        num_bis=parameters.num_bis,
+                        sdu_interval=parameters.sdu_interval,
+                        max_sdu=parameters.max_sdu,
+                        max_transport_latency=parameters.max_transport_latency,
+                        rtn=parameters.rtn,
+                        phy=parameters.phy,
+                        packing=parameters.packing,
+                        framing=parameters.framing,
+                        encryption=1 if parameters.broadcast_code else 0,
+                        broadcast_code=parameters.broadcast_code or bytes(16),
+                    ),
+                    check_result=True,
+                )
+                await established
+            except hci.HCI_Error:
+                del self.bigs[big_handle]
+                raise
+
+        return big
+
+    # [LE only]
+    @experimental('Only for testing.')
+    async def create_big_sync(
+        self, pa_sync: PeriodicAdvertisingSync, parameters: BigSyncParameters
+    ) -> BigSync:
+        if (big_handle := self.next_big_handle()) is None:
+            raise core.OutOfResourcesError("All valid BIG handles already in use")
+
+        if (pa_sync_handle := pa_sync.sync_handle) is None:
+            raise core.InvalidStateError("PA Sync is not established")
+
+        with closing(EventWatcher()) as watcher:
+            big_sync = BigSync(
+                big_handle=big_handle,
+                parameters=parameters,
+                pa_sync=pa_sync,
+            )
+            self.big_syncs[big_handle] = big_sync
+            established = asyncio.get_running_loop().create_future()
+            watcher.once(
+                big_sync,
+                big_sync.Event.ESTABLISHMENT,
+                lambda: established.set_result(None),
+            )
+            watcher.once(
+                big_sync,
+                big_sync.Event.ESTABLISHMENT_FAILURE,
+                lambda status: established.set_exception(hci.HCI_Error(status)),
+            )
+
+            try:
+                await self.send_command(
+                    hci.HCI_LE_BIG_Create_Sync_Command(
+                        big_handle=big_handle,
+                        sync_handle=pa_sync_handle,
+                        encryption=1 if parameters.broadcast_code else 0,
+                        broadcast_code=parameters.broadcast_code or bytes(16),
+                        mse=parameters.mse,
+                        big_sync_timeout=parameters.big_sync_timeout,
+                        bis=parameters.bis,
+                    ),
+                    check_result=True,
+                )
+                await established
+            except hci.HCI_Error:
+                del self.big_syncs[big_handle]
+                raise
+
+        return big_sync
+
     async def get_remote_le_features(self, connection: Connection) -> hci.LeFeatureMask:
         """[LE Only] Reads remote LE supported features.
 
@@ -4233,6 +4570,112 @@ class Device(CompositeEventEmitter):
         )
         self.connecting_extended_advertising_sets[connection_handle] = advertising_set
 
+    @host_event_handler
+    def on_big_establishment(
+        self,
+        status: int,
+        big_handle: int,
+        bis_handles: list[int],
+        big_sync_delay: int,
+        transport_latency_big: int,
+        phy: int,
+        nse: int,
+        bn: int,
+        pto: int,
+        irc: int,
+        max_pdu: int,
+        iso_interval: int,
+    ) -> None:
+        if not (big := self.bigs.get(big_handle)):
+            logger.warning('BIG %d not found', big_handle)
+            return
+
+        if status != hci.HCI_SUCCESS:
+            del self.bigs[big_handle]
+            logger.debug('Unable to create BIG %d', big_handle)
+            big.state = Big.State.TERMINATED
+            big.emit(Big.Event.ESTABLISHMENT_FAILURE, status)
+            return
+
+        big.bis_links = [BisLink(handle=handle, big=big) for handle in bis_handles]
+        big.big_sync_delay = big_sync_delay
+        big.transport_latency_big = transport_latency_big
+        big.phy = phy
+        big.nse = nse
+        big.bn = bn
+        big.pto = pto
+        big.irc = irc
+        big.max_pdu = max_pdu
+        big.iso_interval = iso_interval
+        big.state = Big.State.ACTIVE
+
+        for bis_link in big.bis_links:
+            self.bis_links[bis_link.handle] = bis_link
+        big.emit(Big.Event.ESTABLISHMENT)
+
+    @host_event_handler
+    def on_big_termination(self, reason: int, big_handle: int) -> None:
+        if not (big := self.bigs.pop(big_handle, None)):
+            logger.warning('BIG %d not found', big_handle)
+            return
+
+        big.state = Big.State.TERMINATED
+        for bis_link in big.bis_links:
+            self.bis_links.pop(bis_link.handle, None)
+        big.emit(Big.Event.TERMINATION, reason)
+
+    @host_event_handler
+    def on_big_sync_establishment(
+        self,
+        status: int,
+        big_handle: int,
+        transport_latency_big: int,
+        nse: int,
+        bn: int,
+        pto: int,
+        irc: int,
+        max_pdu: int,
+        iso_interval: int,
+        bis_handles: list[int],
+    ) -> None:
+        if not (big_sync := self.big_syncs.get(big_handle)):
+            logger.warning('BIG Sync %d not found', big_handle)
+            return
+
+        if status != hci.HCI_SUCCESS:
+            del self.big_syncs[big_handle]
+            logger.debug('Unable to create BIG Sync %d', big_handle)
+            big_sync.state = BigSync.State.TERMINATED
+            big_sync.emit(BigSync.Event.ESTABLISHMENT_FAILURE, status)
+            return
+
+        big_sync.transport_latency_big = transport_latency_big
+        big_sync.nse = nse
+        big_sync.bn = bn
+        big_sync.pto = pto
+        big_sync.irc = irc
+        big_sync.max_pdu = max_pdu
+        big_sync.iso_interval = iso_interval
+        big_sync.bis_links = [
+            BisLink(handle=handle, big=big_sync) for handle in bis_handles
+        ]
+        big_sync.state = BigSync.State.ACTIVE
+
+        for bis_link in big_sync.bis_links:
+            self.bis_links[bis_link.handle] = bis_link
+        big_sync.emit(BigSync.Event.ESTABLISHMENT)
+
+    @host_event_handler
+    def on_big_sync_lost(self, big_handle: int, reason: int) -> None:
+        if not (big_sync := self.big_syncs.pop(big_handle, None)):
+            logger.warning('BIG %d not found', big_handle)
+            return
+
+        for bis_link in big_sync.bis_links:
+            self.bis_links.pop(bis_link.handle, None)
+        big_sync.state = BigSync.State.TERMINATED
+        big_sync.emit(BigSync.Event.TERMINATION, reason)
+
     def _complete_le_extended_advertising_connection(
         self, connection: Connection, advertising_set: AdvertisingSet
     ) -> None:
@@ -4879,6 +5322,8 @@ class Device(CompositeEventEmitter):
     def on_iso_packet(self, handle: int, packet: hci.HCI_IsoDataPacket) -> None:
         if (cis_link := self.cis_links.get(handle)) and cis_link.sink:
             cis_link.sink(packet)
+        elif (bis_link := self.bis_links.get(handle)) and bis_link.sink:
+            bis_link.sink(packet)
 
     @host_event_handler
     @with_connection_from_handle

bumble/drivers/common.py

@@ -20,6 +20,8 @@ Common types for drivers.
 # -----------------------------------------------------------------------------
 import abc
 
+from bumble import core
+
 
 # -----------------------------------------------------------------------------
 # Classes

bumble/drivers/intel.py

@@ -11,18 +11,33 @@
 # 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.
+"""
+Support for Intel USB controllers.
+Loosely based on the Fuchsia OS implementation.
+"""
 
 # -----------------------------------------------------------------------------
 # Imports
 # -----------------------------------------------------------------------------
+from __future__ import annotations
+import asyncio
+import collections
+import dataclasses
 import logging
+import os
+import pathlib
+import platform
+import struct
+from typing import Any, Deque, Optional, TYPE_CHECKING
 
+from bumble import core
 from bumble.drivers import common
-from bumble.hci import (
-    hci_vendor_command_op_code,  # type: ignore
-    HCI_Command,
-    HCI_Reset_Command,
-)
+from bumble import hci
+from bumble import utils
+
+if TYPE_CHECKING:
+    from bumble.host import Host
+
 
 # -----------------------------------------------------------------------------
 # Logging
@@ -34,39 +49,328 @@ logger = logging.getLogger(__name__)
 # -----------------------------------------------------------------------------
 
 INTEL_USB_PRODUCTS = {
-    # Intel AX210
-    (0x8087, 0x0032),
-    # Intel BE200
-    (0x8087, 0x0036),
+    (0x8087, 0x0032),  # AX210
+    (0x8087, 0x0036),  # BE200
 }
 
+INTEL_FW_IMAGE_NAMES = [
+    "ibt-0040-0041",
+    "ibt-0040-1020",
+    "ibt-0040-1050",
+    "ibt-0040-2120",
+    "ibt-0040-4150",
+    "ibt-0041-0041",
+    "ibt-0180-0041",
+    "ibt-0180-1050",
+    "ibt-0180-4150",
+    "ibt-0291-0291",
+    "ibt-1040-0041",
+    "ibt-1040-1020",
+    "ibt-1040-1050",
+    "ibt-1040-2120",
+    "ibt-1040-4150",
+]
+
+INTEL_FIRMWARE_DIR_ENV = "BUMBLE_INTEL_FIRMWARE_DIR"
+INTEL_LINUX_FIRMWARE_DIR = "/lib/firmware/intel"
+
+_MAX_FRAGMENT_SIZE = 252
+_POST_RESET_DELAY = 0.2
+
 # -----------------------------------------------------------------------------
 # HCI Commands
 # -----------------------------------------------------------------------------
-HCI_INTEL_DDC_CONFIG_WRITE_COMMAND = hci_vendor_command_op_code(0xFC8B)  # type: ignore
-HCI_INTEL_DDC_CONFIG_WRITE_PAYLOAD = [0x03, 0xE4, 0x02, 0x00]
+HCI_INTEL_WRITE_DEVICE_CONFIG_COMMAND = hci.hci_vendor_command_op_code(0x008B)
+HCI_INTEL_READ_VERSION_COMMAND = hci.hci_vendor_command_op_code(0x0005)
+HCI_INTEL_RESET_COMMAND = hci.hci_vendor_command_op_code(0x0001)
+HCI_INTEL_SECURE_SEND_COMMAND = hci.hci_vendor_command_op_code(0x0009)
+HCI_INTEL_WRITE_BOOT_PARAMS_COMMAND = hci.hci_vendor_command_op_code(0x000E)
 
-HCI_Command.register_commands(globals())
+hci.HCI_Command.register_commands(globals())
 
 
-@HCI_Command.command(  # type: ignore
-    fields=[("params", "*")],
+@hci.HCI_Command.command(
+    fields=[
+        ("param0", 1),
+    ],
     return_parameters_fields=[
-        ("params", "*"),
+        ("status", hci.STATUS_SPEC),
+        ("tlv", "*"),
     ],
 )
-class Hci_Intel_DDC_Config_Write_Command(HCI_Command):
+class HCI_Intel_Read_Version_Command(hci.HCI_Command):
     pass
 
 
+@hci.HCI_Command.command(
+    fields=[("data_type", 1), ("data", "*")],
+    return_parameters_fields=[
+        ("status", 1),
+    ],
+)
+class Hci_Intel_Secure_Send_Command(hci.HCI_Command):
+    pass
+
+
+@hci.HCI_Command.command(
+    fields=[
+        ("reset_type", 1),
+        ("patch_enable", 1),
+        ("ddc_reload", 1),
+        ("boot_option", 1),
+        ("boot_address", 4),
+    ],
+    return_parameters_fields=[
+        ("data", "*"),
+    ],
+)
+class HCI_Intel_Reset_Command(hci.HCI_Command):
+    pass
+
+
+@hci.HCI_Command.command(
+    fields=[("data", "*")],
+    return_parameters_fields=[
+        ("status", hci.STATUS_SPEC),
+        ("params", "*"),
+    ],
+)
+class Hci_Intel_Write_Device_Config_Command(hci.HCI_Command):
+    pass
+
+
+# -----------------------------------------------------------------------------
+# Functions
+# -----------------------------------------------------------------------------
+def intel_firmware_dir() -> pathlib.Path:
+    """
+    Returns:
+        A path to a subdir of the project data dir for Intel firmware.
+         The directory is created if it doesn't exist.
+    """
+    from bumble.drivers import project_data_dir
+
+    p = project_data_dir() / "firmware" / "intel"
+    p.mkdir(parents=True, exist_ok=True)
+    return p
+
+
+def _find_binary_path(file_name: str) -> pathlib.Path | None:
+    # First check if an environment variable is set
+    if INTEL_FIRMWARE_DIR_ENV in os.environ:
+        if (
+            path := pathlib.Path(os.environ[INTEL_FIRMWARE_DIR_ENV]) / file_name
+        ).is_file():
+            logger.debug(f"{file_name} found in env dir")
+            return path
+
+        # When the environment variable is set, don't look elsewhere
+        return None
+
+    # Then, look where the firmware download tool writes by default
+    if (path := intel_firmware_dir() / file_name).is_file():
+        logger.debug(f"{file_name} found in project data dir")
+        return path
+
+    # Then, look in the package's driver directory
+    if (path := pathlib.Path(__file__).parent / "intel_fw" / file_name).is_file():
+        logger.debug(f"{file_name} found in package dir")
+        return path
+
+    # On Linux, check the system's FW directory
+    if (
+        platform.system() == "Linux"
+        and (path := pathlib.Path(INTEL_LINUX_FIRMWARE_DIR) / file_name).is_file()
+    ):
+        logger.debug(f"{file_name} found in Linux system FW dir")
+        return path
+
+    # Finally look in the current directory
+    if (path := pathlib.Path.cwd() / file_name).is_file():
+        logger.debug(f"{file_name} found in CWD")
+        return path
+
+    return None
+
+
+def _parse_tlv(data: bytes) -> list[tuple[ValueType, Any]]:
+    result: list[tuple[ValueType, Any]] = []
+    while len(data) >= 2:
+        value_type = ValueType(data[0])
+        value_length = data[1]
+        value = data[2 : 2 + value_length]
+        typed_value: Any
+
+        if value_type == ValueType.END:
+            break
+
+        if value_type in (ValueType.CNVI, ValueType.CNVR):
+            (v,) = struct.unpack("<I", value)
+            typed_value = (
+                (((v >> 0) & 0xF) << 12)
+                | (((v >> 4) & 0xF) << 0)
+                | (((v >> 8) & 0xF) << 4)
+                | (((v >> 24) & 0xF) << 8)
+            )
+        elif value_type == ValueType.HARDWARE_INFO:
+            (v,) = struct.unpack("<I", value)
+            typed_value = HardwareInfo(
+                HardwarePlatform((v >> 8) & 0xFF), HardwareVariant((v >> 16) & 0x3F)
+            )
+        elif value_type in (
+            ValueType.USB_VENDOR_ID,
+            ValueType.USB_PRODUCT_ID,
+            ValueType.DEVICE_REVISION,
+        ):
+            (typed_value,) = struct.unpack("<H", value)
+        elif value_type == ValueType.CURRENT_MODE_OF_OPERATION:
+            typed_value = ModeOfOperation(value[0])
+        elif value_type in (
+            ValueType.BUILD_TYPE,
+            ValueType.BUILD_NUMBER,
+            ValueType.SECURE_BOOT,
+            ValueType.OTP_LOCK,
+            ValueType.API_LOCK,
+            ValueType.DEBUG_LOCK,
+            ValueType.SECURE_BOOT_ENGINE_TYPE,
+        ):
+            typed_value = value[0]
+        elif value_type == ValueType.TIMESTAMP:
+            typed_value = Timestamp(value[0], value[1])
+        elif value_type == ValueType.FIRMWARE_BUILD:
+            typed_value = FirmwareBuild(value[0], Timestamp(value[1], value[2]))
+        elif value_type == ValueType.BLUETOOTH_ADDRESS:
+            typed_value = hci.Address(
+                value, address_type=hci.Address.PUBLIC_DEVICE_ADDRESS
+            )
+        else:
+            typed_value = value
+
+        result.append((value_type, typed_value))
+        data = data[2 + value_length :]
+
+    return result
+
+
+# -----------------------------------------------------------------------------
+# Classes
+# -----------------------------------------------------------------------------
+class DriverError(core.BaseBumbleError):
+    def __init__(self, message: str) -> None:
+        super().__init__(message)
+        self.message = message
+
+    def __str__(self) -> str:
+        return f"IntelDriverError({self.message})"
+
+
+class ValueType(utils.OpenIntEnum):
+    END = 0x00
+    CNVI = 0x10
+    CNVR = 0x11
+    HARDWARE_INFO = 0x12
+    DEVICE_REVISION = 0x16
+    CURRENT_MODE_OF_OPERATION = 0x1C
+    USB_VENDOR_ID = 0x17
+    USB_PRODUCT_ID = 0x18
+    TIMESTAMP = 0x1D
+    BUILD_TYPE = 0x1E
+    BUILD_NUMBER = 0x1F
+    SECURE_BOOT = 0x28
+    OTP_LOCK = 0x2A
+    API_LOCK = 0x2B
+    DEBUG_LOCK = 0x2C
+    FIRMWARE_BUILD = 0x2D
+    SECURE_BOOT_ENGINE_TYPE = 0x2F
+    BLUETOOTH_ADDRESS = 0x30
+
+
+class HardwarePlatform(utils.OpenIntEnum):
+    INTEL_37 = 0x37
+
+
+class HardwareVariant(utils.OpenIntEnum):
+    # This is a just a partial list.
+    # Add other constants here as new hardware is encountered and tested.
+    TYPHOON_PEAK = 0x17
+    GALE_PEAK = 0x1C
+
+
+@dataclasses.dataclass
+class HardwareInfo:
+    platform: HardwarePlatform
+    variant: HardwareVariant
+
+
+@dataclasses.dataclass
+class Timestamp:
+    week: int
+    year: int
+
+
+@dataclasses.dataclass
+class FirmwareBuild:
+    build_number: int
+    timestamp: Timestamp
+
+
+class ModeOfOperation(utils.OpenIntEnum):
+    BOOTLOADER = 0x01
+    INTERMEDIATE = 0x02
+    OPERATIONAL = 0x03
+
+
+class SecureBootEngineType(utils.OpenIntEnum):
+    RSA = 0x00
+    ECDSA = 0x01
+
+
+@dataclasses.dataclass
+class BootParams:
+    css_header_offset: int
+    css_header_size: int
+    pki_offset: int
+    pki_size: int
+    sig_offset: int
+    sig_size: int
+    write_offset: int
+
+
+_BOOT_PARAMS = {
+    SecureBootEngineType.RSA: BootParams(0, 128, 128, 256, 388, 256, 964),
+    SecureBootEngineType.ECDSA: BootParams(644, 128, 772, 96, 868, 96, 964),
+}
+
+
 class Driver(common.Driver):
-    def __init__(self, host):
+    def __init__(self, host: Host) -> None:
         self.host = host
+        self.max_in_flight_firmware_load_commands = 1
+        self.pending_firmware_load_commands: Deque[hci.HCI_Command] = (
+            collections.deque()
+        )
+        self.can_send_firmware_load_command = asyncio.Event()
+        self.can_send_firmware_load_command.set()
+        self.firmware_load_complete = asyncio.Event()
+        self.reset_complete = asyncio.Event()
+
+        # Parse configuration options from the driver name.
+        self.ddc_addon: Optional[bytes] = None
+        self.ddc_override: Optional[bytes] = None
+        driver = host.hci_metadata.get("driver")
+        if driver is not None and driver.startswith("intel/"):
+            for key, value in [
+                key_eq_value.split(":") for key_eq_value in driver[6:].split("+")
+            ]:
+                if key == "ddc_addon":
+                    self.ddc_addon = bytes.fromhex(value)
+                elif key == "ddc_override":
+                    self.ddc_override = bytes.fromhex(value)
 
     @staticmethod
-    def check(host):
+    def check(host: Host) -> bool:
         driver = host.hci_metadata.get("driver")
-        if driver == "intel":
+        if driver == "intel" or driver is not None and driver.startswith("intel/"):
             return True
 
         vendor_id = host.hci_metadata.get("vendor_id")
@@ -85,18 +389,283 @@ class Driver(common.Driver):
         return True
 
     @classmethod
-    async def for_host(cls, host, force=False):  # type: ignore
+    async def for_host(cls, host: Host, force: bool = False):
         # Only instantiate this driver if explicitly selected
         if not force and not cls.check(host):
             return None
 
         return cls(host)
 
-    async def init_controller(self):
+    def on_packet(self, packet: bytes) -> None:
+        """Handler for event packets that are received from an ACL channel"""
+        event = hci.HCI_Event.from_bytes(packet)
+
+        if not isinstance(event, hci.HCI_Command_Complete_Event):
+            self.host.on_hci_event_packet(event)
+            return
+
+        if not event.return_parameters == hci.HCI_SUCCESS:
+            raise DriverError("HCI_Command_Complete_Event error")
+
+        if self.max_in_flight_firmware_load_commands != event.num_hci_command_packets:
+            logger.debug(
+                "max_in_flight_firmware_load_commands update: "
+                f"{event.num_hci_command_packets}"
+            )
+            self.max_in_flight_firmware_load_commands = event.num_hci_command_packets
+        logger.debug(f"event: {event}")
+        self.pending_firmware_load_commands.popleft()
+        in_flight = len(self.pending_firmware_load_commands)
+        logger.debug(f"event received, {in_flight} still in flight")
+        if in_flight < self.max_in_flight_firmware_load_commands:
+            self.can_send_firmware_load_command.set()
+
+    async def send_firmware_load_command(self, command: hci.HCI_Command) -> None:
+        # Wait until we can send.
+        await self.can_send_firmware_load_command.wait()
+
+        # Send the command and adjust counters.
+        self.host.send_hci_packet(command)
+        self.pending_firmware_load_commands.append(command)
+        in_flight = len(self.pending_firmware_load_commands)
+        if in_flight >= self.max_in_flight_firmware_load_commands:
+            logger.debug(f"max commands in flight reached [{in_flight}]")
+            self.can_send_firmware_load_command.clear()
+
+    async def send_firmware_data(self, data_type: int, data: bytes) -> None:
+        while data:
+            fragment_size = min(len(data), _MAX_FRAGMENT_SIZE)
+            fragment = data[:fragment_size]
+            data = data[fragment_size:]
+
+            await self.send_firmware_load_command(
+                Hci_Intel_Secure_Send_Command(data_type=data_type, data=fragment)
+            )
+
+    async def load_firmware(self) -> None:
         self.host.ready = True
-        await self.host.send_command(HCI_Reset_Command(), check_result=True)
-        await self.host.send_command(
-            Hci_Intel_DDC_Config_Write_Command(
-                params=HCI_INTEL_DDC_CONFIG_WRITE_PAYLOAD
+        device_info = await self.read_device_info()
+        logger.debug(
+            "device info: \n%s",
+            "\n".join(
+                [
+                    f"  {value_type.name}: {value}"
+                    for value_type, value in device_info.items()
+                ]
+            ),
+        )
+
+        # Check if the firmware is already loaded.
+        if (
+            device_info.get(ValueType.CURRENT_MODE_OF_OPERATION)
+            == ModeOfOperation.OPERATIONAL
+        ):
+            logger.debug("firmware already loaded")
+            return
+
+        # We only support some platforms and variants.
+        hardware_info = device_info.get(ValueType.HARDWARE_INFO)
+        if hardware_info is None:
+            raise DriverError("hardware info missing")
+        if hardware_info.platform != HardwarePlatform.INTEL_37:
+            raise DriverError("hardware platform not supported")
+        if hardware_info.variant not in (
+            HardwareVariant.TYPHOON_PEAK,
+            HardwareVariant.GALE_PEAK,
+        ):
+            raise DriverError("hardware variant not supported")
+
+        # Compute the firmware name.
+        if ValueType.CNVI not in device_info or ValueType.CNVR not in device_info:
+            raise DriverError("insufficient device info, missing CNVI or CNVR")
+
+        firmware_base_name = (
+            "ibt-"
+            f"{device_info[ValueType.CNVI]:04X}-"
+            f"{device_info[ValueType.CNVR]:04X}"
+        )
+        logger.debug(f"FW base name: {firmware_base_name}")
+
+        firmware_name = f"{firmware_base_name}.sfi"
+        firmware_path = _find_binary_path(firmware_name)
+        if not firmware_path:
+            logger.warning(f"Firmware file {firmware_name} not found")
+            logger.warning("See https://google.github.io/bumble/drivers/intel.html")
+            return None
+        logger.debug(f"loading firmware from {firmware_path}")
+        firmware_image = firmware_path.read_bytes()
+
+        engine_type = device_info.get(ValueType.SECURE_BOOT_ENGINE_TYPE)
+        if engine_type is None:
+            raise DriverError("secure boot engine type missing")
+        if engine_type not in _BOOT_PARAMS:
+            raise DriverError("secure boot engine type not supported")
+
+        boot_params = _BOOT_PARAMS[engine_type]
+        if len(firmware_image) < boot_params.write_offset:
+            raise DriverError("firmware image too small")
+
+        # Register to receive vendor events.
+        def on_vendor_event(event: hci.HCI_Vendor_Event):
+            logger.debug(f"vendor event: {event}")
+            event_type = event.parameters[0]
+            if event_type == 0x02:
+                # Boot event
+                logger.debug("boot complete")
+                self.reset_complete.set()
+            elif event_type == 0x06:
+                # Firmware load event
+                logger.debug("download complete")
+                self.firmware_load_complete.set()
+            else:
+                logger.debug(f"ignoring vendor event type {event_type}")
+
+        self.host.on("vendor_event", on_vendor_event)
+
+        # We need to temporarily intercept packets from the controller,
+        # because they are formatted as HCI event packets but are received
+        # on the ACL channel, so the host parser would get confused.
+        saved_on_packet = self.host.on_packet
+        self.host.on_packet = self.on_packet  # type: ignore
+        self.firmware_load_complete.clear()
+
+        # Send the CSS header
+        data = firmware_image[
+            boot_params.css_header_offset : boot_params.css_header_offset
+            + boot_params.css_header_size
+        ]
+        await self.send_firmware_data(0x00, data)
+
+        # Send the PKI header
+        data = firmware_image[
+            boot_params.pki_offset : boot_params.pki_offset + boot_params.pki_size
+        ]
+        await self.send_firmware_data(0x03, data)
+
+        # Send the Signature header
+        data = firmware_image[
+            boot_params.sig_offset : boot_params.sig_offset + boot_params.sig_size
+        ]
+        await self.send_firmware_data(0x02, data)
+
+        # Send the rest of the image.
+        # The payload consists of command objects, which are sent when they add up
+        # to a multiple of 4 bytes.
+        boot_address = 0
+        offset = boot_params.write_offset
+        fragment_size = 0
+        while offset + 3 < len(firmware_image):
+            (command_opcode,) = struct.unpack_from(
+                "<H", firmware_image, offset + fragment_size
+            )
+            command_size = firmware_image[offset + fragment_size + 2]
+            if command_opcode == HCI_INTEL_WRITE_BOOT_PARAMS_COMMAND:
+                (boot_address,) = struct.unpack_from(
+                    "<I", firmware_image, offset + fragment_size + 3
+                )
+                logger.debug(
+                    "found HCI_INTEL_WRITE_BOOT_PARAMS_COMMAND, "
+                    f"boot_address={boot_address}"
+                )
+            fragment_size += 3 + command_size
+            if fragment_size % 4 == 0:
+                await self.send_firmware_data(
+                    0x01, firmware_image[offset : offset + fragment_size]
+                )
+                logger.debug(f"sent {fragment_size} bytes")
+                offset += fragment_size
+                fragment_size = 0
+
+        # Wait for the firmware loading to be complete.
+        logger.debug("waiting for firmware to be loaded")
+        await self.firmware_load_complete.wait()
+        logger.debug("firmware loaded")
+
+        # Restore the original packet handler.
+        self.host.on_packet = saved_on_packet  # type: ignore
+
+        # Reset
+        self.reset_complete.clear()
+        self.host.send_hci_packet(
+            HCI_Intel_Reset_Command(
+                reset_type=0x00,
+                patch_enable=0x01,
+                ddc_reload=0x00,
+                boot_option=0x01,
+                boot_address=boot_address,
             )
         )
+        logger.debug("waiting for reset completion")
+        await self.reset_complete.wait()
+        logger.debug("reset complete")
+
+        # Load the device config if there is one.
+        if self.ddc_override:
+            logger.debug("loading overridden DDC")
+            await self.load_device_config(self.ddc_override)
+        else:
+            ddc_name = f"{firmware_base_name}.ddc"
+            ddc_path = _find_binary_path(ddc_name)
+            if ddc_path:
+                logger.debug(f"loading DDC from {ddc_path}")
+                ddc_data = ddc_path.read_bytes()
+                await self.load_device_config(ddc_data)
+        if self.ddc_addon:
+            logger.debug("loading DDC addon")
+            await self.load_device_config(self.ddc_addon)
+
+    async def load_device_config(self, ddc_data: bytes) -> None:
+        while ddc_data:
+            ddc_len = 1 + ddc_data[0]
+            ddc_payload = ddc_data[:ddc_len]
+            await self.host.send_command(
+                Hci_Intel_Write_Device_Config_Command(data=ddc_payload)
+            )
+            ddc_data = ddc_data[ddc_len:]
+
+    async def reboot_bootloader(self) -> None:
+        self.host.send_hci_packet(
+            HCI_Intel_Reset_Command(
+                reset_type=0x01,
+                patch_enable=0x01,
+                ddc_reload=0x01,
+                boot_option=0x00,
+                boot_address=0,
+            )
+        )
+        await asyncio.sleep(_POST_RESET_DELAY)
+
+    async def read_device_info(self) -> dict[ValueType, Any]:
+        self.host.ready = True
+        response = await self.host.send_command(hci.HCI_Reset_Command())
+        if not (
+            isinstance(response, hci.HCI_Command_Complete_Event)
+            and response.return_parameters
+            in (hci.HCI_UNKNOWN_HCI_COMMAND_ERROR, hci.HCI_SUCCESS)
+        ):
+            # When the controller is in operational mode, the response is a
+            # successful response.
+            # When the controller is in bootloader mode,
+            # HCI_UNKNOWN_HCI_COMMAND_ERROR is the expected response. Anything
+            # else is a failure.
+            logger.warning(f"unexpected response: {response}")
+            raise DriverError("unexpected HCI response")
+
+        # Read the firmware version.
+        response = await self.host.send_command(
+            HCI_Intel_Read_Version_Command(param0=0xFF)
+        )
+        if not isinstance(response, hci.HCI_Command_Complete_Event):
+            raise DriverError("unexpected HCI response")
+
+        if response.return_parameters.status != 0:  # type: ignore
+            raise DriverError("HCI_Intel_Read_Version_Command error")
+
+        tlvs = _parse_tlv(response.return_parameters.tlv)  # type: ignore
+
+        # Convert the list to a dict. That's Ok here because we only expect each type
+        # to appear just once.
+        return dict(tlvs)
+
+    async def init_controller(self):
+        await self.load_firmware()

bumble/gatt.py

@@ -28,12 +28,15 @@ import functools
 import logging
 import struct
 from typing import (
+    Any,
     Callable,
     Dict,
     Iterable,
     List,
     Optional,
     Sequence,
+    SupportsBytes,
+    Type,
     Union,
     TYPE_CHECKING,
 )
@@ -41,6 +44,7 @@ from typing import (
 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
@@ -275,6 +279,13 @@ GATT_SOURCE_AUDIO_LOCATION_CHARACTERISTIC       = UUID.from_16_bits(0x2BCC, 'Sou
 GATT_AVAILABLE_AUDIO_CONTEXTS_CHARACTERISTIC    = UUID.from_16_bits(0x2BCD, 'Available Audio Contexts')
 GATT_SUPPORTED_AUDIO_CONTEXTS_CHARACTERISTIC    = UUID.from_16_bits(0x2BCE, 'Supported Audio Contexts')
 
+# Gaming Audio Service (GMAS)
+GATT_GMAP_ROLE_CHARACTERISTIC    = UUID.from_16_bits(0x2C00, 'GMAP Role')
+GATT_UGG_FEATURES_CHARACTERISTIC = UUID.from_16_bits(0x2C01, 'UGG Features')
+GATT_UGT_FEATURES_CHARACTERISTIC = UUID.from_16_bits(0x2C02, 'UGT Features')
+GATT_BGS_FEATURES_CHARACTERISTIC = UUID.from_16_bits(0x2C03, 'BGS Features')
+GATT_BGR_FEATURES_CHARACTERISTIC = UUID.from_16_bits(0x2C04, 'BGR Features')
+
 # Hearing Access Service
 GATT_HEARING_AID_FEATURES_CHARACTERISTIC             = UUID.from_16_bits(0x2BDA, 'Hearing Aid Features')
 GATT_HEARING_AID_PRESET_CONTROL_POINT_CHARACTERISTIC = UUID.from_16_bits(0x2BDB, 'Hearing Aid Preset Control Point')
@@ -343,7 +354,7 @@ class Service(Attribute):
     def __init__(
         self,
         uuid: Union[str, UUID],
-        characteristics: List[Characteristic],
+        characteristics: Iterable[Characteristic],
         primary=True,
         included_services: Iterable[Service] = (),
     ) -> None:
@@ -362,7 +373,7 @@ class Service(Attribute):
         )
         self.uuid = uuid
         self.included_services = list(included_services)
-        self.characteristics = characteristics[:]
+        self.characteristics = list(characteristics)
         self.primary = primary
 
     def get_advertising_data(self) -> Optional[bytes]:
@@ -393,7 +404,7 @@ class TemplateService(Service):
 
     def __init__(
         self,
-        characteristics: List[Characteristic],
+        characteristics: Iterable[Characteristic],
         primary: bool = True,
         included_services: Iterable[Service] = (),
     ) -> None:
@@ -490,7 +501,7 @@ class Characteristic(Attribute):
         uuid: Union[str, bytes, UUID],
         properties: Characteristic.Properties,
         permissions: Union[str, Attribute.Permissions],
-        value: Union[str, bytes, CharacteristicValue] = b'',
+        value: Any = b'',
         descriptors: Sequence[Descriptor] = (),
     ):
         super().__init__(uuid, permissions, value)
@@ -525,7 +536,11 @@ class CharacteristicDeclaration(Attribute):
 
     characteristic: Characteristic
 
-    def __init__(self, characteristic: Characteristic, value_handle: int) -> None:
+    def __init__(
+        self,
+        characteristic: Characteristic,
+        value_handle: int,
+    ) -> None:
         declaration_bytes = (
             struct.pack('<BH', characteristic.properties, value_handle)
             + characteristic.uuid.to_pdu_bytes()
@@ -705,7 +720,7 @@ class MappedCharacteristicAdapter(PackedCharacteristicAdapter):
     '''
     Adapter that packs/unpacks characteristic values according to a standard
     Python `struct` format.
-    The adapted `read_value` and `write_value` methods return/accept aa dictionary which
+    The adapted `read_value` and `write_value` methods return/accept a dictionary which
     is packed/unpacked according to format, with the arguments extracted from the
     dictionary by key, in the same order as they occur in the `keys` parameter.
     '''
@@ -735,6 +750,24 @@ class UTF8CharacteristicAdapter(CharacteristicAdapter):
         return value.decode('utf-8')
 
 
+# -----------------------------------------------------------------------------
+class SerializableCharacteristicAdapter(CharacteristicAdapter):
+    '''
+    Adapter that converts any class to/from bytes using the class'
+    `to_bytes` and `__bytes__` methods, respectively.
+    '''
+
+    def __init__(self, characteristic, cls: Type[ByteSerializable]):
+        super().__init__(characteristic)
+        self.cls = cls
+
+    def encode_value(self, value: SupportsBytes) -> bytes:
+        return bytes(value)
+
+    def decode_value(self, value: bytes) -> Any:
+        return self.cls.from_bytes(value)
+
+
 # -----------------------------------------------------------------------------
 class Descriptor(Attribute):
     '''

bumble/gatt_server.py

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

bumble/hci.py

@@ -129,6 +129,7 @@ HCI_VERSION_BLUETOOTH_CORE_5_1     = 10
 HCI_VERSION_BLUETOOTH_CORE_5_2     = 11
 HCI_VERSION_BLUETOOTH_CORE_5_3     = 12
 HCI_VERSION_BLUETOOTH_CORE_5_4     = 13
+HCI_VERSION_BLUETOOTH_CORE_6_0     = 14
 
 HCI_VERSION_NAMES = {
     HCI_VERSION_BLUETOOTH_CORE_1_0B:    'HCI_VERSION_BLUETOOTH_CORE_1_0B',
@@ -145,6 +146,7 @@ HCI_VERSION_NAMES = {
     HCI_VERSION_BLUETOOTH_CORE_5_2:     'HCI_VERSION_BLUETOOTH_CORE_5_2',
     HCI_VERSION_BLUETOOTH_CORE_5_3:     'HCI_VERSION_BLUETOOTH_CORE_5_3',
     HCI_VERSION_BLUETOOTH_CORE_5_4:     'HCI_VERSION_BLUETOOTH_CORE_5_4',
+    HCI_VERSION_BLUETOOTH_CORE_6_0:     'HCI_VERSION_BLUETOOTH_CORE_6_0',
 }
 
 # LMP Version
@@ -4934,7 +4936,7 @@ class HCI_LE_Create_BIG_Command(HCI_Command):
     packing: int
     framing: int
     encryption: int
-    broadcast_code: int
+    broadcast_code: bytes
 
 
 # -----------------------------------------------------------------------------
@@ -5068,6 +5070,7 @@ class HCI_Event(HCI_Packet):
     hci_packet_type = HCI_EVENT_PACKET
     event_names: Dict[int, str] = {}
     event_classes: Dict[int, Type[HCI_Event]] = {}
+    vendor_factories: list[Callable[[bytes], Optional[HCI_Event]]] = []
 
     @staticmethod
     def event(fields=()):
@@ -5125,37 +5128,54 @@ class HCI_Event(HCI_Packet):
 
         return event_class
 
-    @staticmethod
-    def from_bytes(packet: bytes) -> HCI_Event:
+    @classmethod
+    def add_vendor_factory(
+        cls, factory: Callable[[bytes], Optional[HCI_Event]]
+    ) -> None:
+        cls.vendor_factories.append(factory)
+
+    @classmethod
+    def remove_vendor_factory(
+        cls, factory: Callable[[bytes], Optional[HCI_Event]]
+    ) -> None:
+        if factory in cls.vendor_factories:
+            cls.vendor_factories.remove(factory)
+
+    @classmethod
+    def from_bytes(cls, packet: bytes) -> HCI_Event:
         event_code = packet[1]
         length = packet[2]
         parameters = packet[3:]
         if len(parameters) != length:
             raise InvalidPacketError('invalid packet length')
 
-        cls: Any
+        subclass: Any
         if event_code == HCI_LE_META_EVENT:
             # We do this dispatch here and not in the subclass in order to avoid call
             # loops
             subevent_code = parameters[0]
-            cls = HCI_LE_Meta_Event.subevent_classes.get(subevent_code)
-            if cls is None:
+            subclass = HCI_LE_Meta_Event.subevent_classes.get(subevent_code)
+            if subclass is None:
                 # No class registered, just use a generic class instance
                 return HCI_LE_Meta_Event(subevent_code, parameters)
         elif event_code == HCI_VENDOR_EVENT:
-            subevent_code = parameters[0]
-            cls = HCI_Vendor_Event.subevent_classes.get(subevent_code)
-            if cls is None:
-                # No class registered, just use a generic class instance
-                return HCI_Vendor_Event(subevent_code, parameters)
+            # Invoke all the registered factories to see if any of them can handle
+            # the event
+            for vendor_factory in cls.vendor_factories:
+                if event := vendor_factory(parameters):
+                    return event
+
+            # No factory, or the factory could not create an instance,
+            # return a generic vendor event
+            return HCI_Vendor_Event(data=parameters)
         else:
-            cls = HCI_Event.event_classes.get(event_code)
-            if cls is None:
+            subclass = HCI_Event.event_classes.get(event_code)
+            if subclass is None:
                 # No class registered, just use a generic class instance
                 return HCI_Event(event_code, parameters)
 
         # Invoke the factory to create a new instance
-        return cls.from_parameters(parameters)  # type: ignore
+        return subclass.from_parameters(parameters)  # type: ignore
 
     @classmethod
     def from_parameters(cls, parameters):
@@ -5198,11 +5218,11 @@ HCI_Event.register_events(globals())
 # -----------------------------------------------------------------------------
 class HCI_Extended_Event(HCI_Event):
     '''
-    HCI_Event subclass for events that has a subevent code.
+    HCI_Event subclass for events that have a subevent code.
     '''
 
     subevent_names: Dict[int, str] = {}
-    subevent_classes: Dict[int, Type[HCI_Extended_Event]]
+    subevent_classes: Dict[int, Type[HCI_Extended_Event]] = {}
 
     @classmethod
     def event(cls, fields=()):
@@ -5253,7 +5273,22 @@ class HCI_Extended_Event(HCI_Event):
         cls.subevent_names.update(cls.subevent_map(symbols))
 
     @classmethod
-    def from_parameters(cls, parameters):
+    def subclass_from_parameters(
+        cls, parameters: bytes
+    ) -> Optional[HCI_Extended_Event]:
+        """
+        Factory method that parses the subevent code, finds a registered subclass,
+        and creates an instance if found.
+        """
+        subevent_code = parameters[0]
+        if subclass := cls.subevent_classes.get(subevent_code):
+            return subclass.from_parameters(parameters)
+
+        return None
+
+    @classmethod
+    def from_parameters(cls, parameters: bytes) -> HCI_Extended_Event:
+        """Factory method for subclasses (the subevent code has already been parsed)"""
         self = cls.__new__(cls)
         HCI_Extended_Event.__init__(self, self.subevent_code, parameters)
         if fields := getattr(self, 'fields', None):
@@ -5294,12 +5329,6 @@ class HCI_LE_Meta_Event(HCI_Extended_Event):
 HCI_LE_Meta_Event.register_subevents(globals())
 
 
-# -----------------------------------------------------------------------------
-class HCI_Vendor_Event(HCI_Extended_Event):
-    event_code: int = HCI_VENDOR_EVENT
-    subevent_classes = {}
-
-
 # -----------------------------------------------------------------------------
 @HCI_LE_Meta_Event.event(
     [
@@ -5809,7 +5838,7 @@ class HCI_LE_Periodic_Advertising_Sync_Lost_Event(HCI_LE_Meta_Event):
 # -----------------------------------------------------------------------------
 @HCI_LE_Meta_Event.event(
     [
-        ('status', 1),
+        ('status', STATUS_SPEC),
         ('advertising_handle', 1),
         ('connection_handle', 2),
         ('num_completed_extended_advertising_events', 1),
@@ -5892,6 +5921,70 @@ class HCI_LE_CIS_Request_Event(HCI_LE_Meta_Event):
     '''
 
 
+# -----------------------------------------------------------------------------
+@HCI_LE_Meta_Event.event(
+    [
+        ('status', STATUS_SPEC),
+        ('big_handle', 1),
+        ('big_sync_delay', 3),
+        ('transport_latency_big', 3),
+        ('phy', 1),
+        ('nse', 1),
+        ('bn', 1),
+        ('pto', 1),
+        ('irc', 1),
+        ('max_pdu', 2),
+        ('iso_interval', 2),
+        [('connection_handle', 2)],
+    ]
+)
+class HCI_LE_Create_BIG_Complete_Event(HCI_LE_Meta_Event):
+    '''
+    See Bluetooth spec @ 7.7.65.27 LE Create BIG Complete Event
+    '''
+
+
+# -----------------------------------------------------------------------------
+@HCI_LE_Meta_Event.event([('big_handle', 1), ('reason', 1)])
+class HCI_LE_Terminate_BIG_Complete_Event(HCI_LE_Meta_Event):
+    '''
+    See Bluetooth spec @ 7.7.65.28 LE Terminate BIG Complete Event
+    '''
+
+
+# -----------------------------------------------------------------------------
+
+
+@HCI_LE_Meta_Event.event(
+    [
+        ('status', STATUS_SPEC),
+        ('big_handle', 1),
+        ('transport_latency_big', 3),
+        ('nse', 1),
+        ('bn', 1),
+        ('pto', 1),
+        ('irc', 1),
+        ('max_pdu', 2),
+        ('iso_interval', 2),
+        [('connection_handle', 2)],
+    ]
+)
+class HCI_LE_BIG_Sync_Established_Event(HCI_LE_Meta_Event):
+    '''
+    See Bluetooth spec @ 7.7.65.29 LE BIG Sync Established event
+    '''
+
+
+# -----------------------------------------------------------------------------
+
+
+@HCI_LE_Meta_Event.event([('big_handle', 1), ('reason', 1)])
+class HCI_LE_BIG_Sync_Lost_Event(HCI_LE_Meta_Event):
+    '''
+    See Bluetooth spec @ 7.7.65.30 LE BIG Sync Lost event
+    '''
+
+
 # -----------------------------------------------------------------------------
 @HCI_LE_Meta_Event.event(
     [
@@ -6173,8 +6266,9 @@ class HCI_Command_Complete_Event(HCI_Event):
     See Bluetooth spec @ 7.7.14 Command Complete Event
     '''
 
-    return_parameters = b''
+    num_hci_command_packets: int
     command_opcode: int
+    return_parameters = b''
 
     def map_return_parameters(self, return_parameters):
         '''Map simple 'status' return parameters to their named constant form'''
@@ -6710,6 +6804,14 @@ class HCI_Remote_Host_Supported_Features_Notification_Event(HCI_Event):
     '''
 
 
+# -----------------------------------------------------------------------------
+@HCI_Event.event([('data', "*")])
+class HCI_Vendor_Event(HCI_Event):
+    '''
+    See Bluetooth spec @ 5.4.4 HCI Event packet
+    '''
+
+
 # -----------------------------------------------------------------------------
 class HCI_AclDataPacket(HCI_Packet):
     '''

bumble/host.py

@@ -21,6 +21,7 @@ import collections
 import dataclasses
 import logging
 import struct
+import itertools
 
 from typing import (
     Any,
@@ -149,6 +150,7 @@ class Host(AbortableEventEmitter):
     connections: Dict[int, Connection]
     cis_links: Dict[int, CisLink]
     sco_links: Dict[int, ScoLink]
+    bigs: dict[int, set[int]] = {}  # BIG Handle to BIS Handles
     acl_packet_queue: Optional[AclPacketQueue] = None
     le_acl_packet_queue: Optional[AclPacketQueue] = None
     hci_sink: Optional[TransportSink] = None
@@ -552,7 +554,7 @@ class Host(AbortableEventEmitter):
 
                 return response
             except Exception as error:
-                logger.warning(
+                logger.exception(
                     f'{color("!!! Exception while sending command:", "red")} {error}'
                 )
                 raise error
@@ -733,9 +735,10 @@ class Host(AbortableEventEmitter):
         ):
             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)
+            elif connection_handle not in itertools.chain(
+                self.cis_links.keys(),
+                self.sco_links.keys(),
+                itertools.chain.from_iterable(self.bigs.values()),
             ):
                 logger.warning(
                     'received packet completion event for unknown handle '
@@ -953,6 +956,50 @@ 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)
+        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.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.emit(
+            'big_sync_lost',
+            event.big_handle,
+            event.reason,
+        )
+
+    def on_hci_le_terminate_big_complete_event(self, event):
+        self.bigs.pop(event.big_handle)
+        self.emit('big_termination', event.reason, event.big_handle)
+
     def on_hci_le_cis_established_event(self, event):
         # The remaining parameters are unused for now.
         if event.status == hci.HCI_SUCCESS:
@@ -1248,3 +1295,6 @@ class Host(AbortableEventEmitter):
                 event.connection_handle,
                 int.from_bytes(event.le_features, 'little'),
             )
+
+    def on_hci_vendor_event(self, event):
+        self.emit('vendor_event', event)

bumble/pairing.py

@@ -139,16 +139,19 @@ class PairingDelegate:
     io_capability: IoCapability
     local_initiator_key_distribution: KeyDistribution
     local_responder_key_distribution: KeyDistribution
+    maximum_encryption_key_size: int
 
     def __init__(
         self,
         io_capability: IoCapability = NO_OUTPUT_NO_INPUT,
         local_initiator_key_distribution: KeyDistribution = DEFAULT_KEY_DISTRIBUTION,
         local_responder_key_distribution: KeyDistribution = DEFAULT_KEY_DISTRIBUTION,
+        maximum_encryption_key_size: int = 16,
     ) -> None:
         self.io_capability = io_capability
         self.local_initiator_key_distribution = local_initiator_key_distribution
         self.local_responder_key_distribution = local_responder_key_distribution
+        self.maximum_encryption_key_size = maximum_encryption_key_size
 
     @property
     def classic_io_capability(self) -> int:

bumble/profiles/aics.py

@@ -17,6 +17,7 @@
 # -----------------------------------------------------------------------------
 # Imports
 # -----------------------------------------------------------------------------
+from __future__ import annotations
 import logging
 import struct
 
@@ -28,10 +29,11 @@ from bumble.device import Connection
 from bumble.att import ATT_Error
 from bumble.gatt import (
     Characteristic,
-    DelegatedCharacteristicAdapter,
+    SerializableCharacteristicAdapter,
+    PackedCharacteristicAdapter,
     TemplateService,
     CharacteristicValue,
-    PackedCharacteristicAdapter,
+    UTF8CharacteristicAdapter,
     GATT_AUDIO_INPUT_CONTROL_SERVICE,
     GATT_AUDIO_INPUT_STATE_CHARACTERISTIC,
     GATT_GAIN_SETTINGS_ATTRIBUTE_CHARACTERISTIC,
@@ -154,9 +156,6 @@ class AudioInputState:
             attribute=self.attribute_value, value=bytes(self)
         )
 
-    def on_read(self, _connection: Optional[Connection]) -> bytes:
-        return bytes(self)
-
 
 @dataclass
 class GainSettingsProperties:
@@ -173,7 +172,7 @@ class GainSettingsProperties:
         (gain_settings_unit, gain_settings_minimum, gain_settings_maximum) = (
             struct.unpack('BBB', data)
         )
-        GainSettingsProperties(
+        return GainSettingsProperties(
             gain_settings_unit, gain_settings_minimum, gain_settings_maximum
         )
 
@@ -186,9 +185,6 @@ class GainSettingsProperties:
             ]
         )
 
-    def on_read(self, _connection: Optional[Connection]) -> bytes:
-        return bytes(self)
-
 
 @dataclass
 class AudioInputControlPoint:
@@ -321,21 +317,14 @@ class AudioInputDescription:
     audio_input_description: str = "Bluetooth"
     attribute_value: Optional[CharacteristicValue] = None
 
-    @classmethod
-    def from_bytes(cls, data: bytes):
-        return cls(audio_input_description=data.decode('utf-8'))
+    def on_read(self, _connection: Optional[Connection]) -> str:
+        return self.audio_input_description
 
-    def __bytes__(self) -> bytes:
-        return self.audio_input_description.encode('utf-8')
-
-    def on_read(self, _connection: Optional[Connection]) -> bytes:
-        return self.audio_input_description.encode('utf-8')
-
-    async def on_write(self, connection: Optional[Connection], value: bytes) -> None:
+    async def on_write(self, connection: Optional[Connection], value: str) -> None:
         assert connection
         assert self.attribute_value
 
-        self.audio_input_description = value.decode('utf-8')
+        self.audio_input_description = value
         await connection.device.notify_subscribers(
             attribute=self.attribute_value, value=value
         )
@@ -375,26 +364,29 @@ class AICSService(TemplateService):
             self.audio_input_state, self.gain_settings_properties
         )
 
-        self.audio_input_state_characteristic = DelegatedCharacteristicAdapter(
+        self.audio_input_state_characteristic = SerializableCharacteristicAdapter(
             Characteristic(
                 uuid=GATT_AUDIO_INPUT_STATE_CHARACTERISTIC,
                 properties=Characteristic.Properties.READ
                 | Characteristic.Properties.NOTIFY,
                 permissions=Characteristic.Permissions.READ_REQUIRES_ENCRYPTION,
-                value=CharacteristicValue(read=self.audio_input_state.on_read),
+                value=self.audio_input_state,
             ),
-            encode=lambda value: bytes(value),
+            AudioInputState,
         )
         self.audio_input_state.attribute_value = (
             self.audio_input_state_characteristic.value
         )
 
-        self.gain_settings_properties_characteristic = DelegatedCharacteristicAdapter(
-            Characteristic(
-                uuid=GATT_GAIN_SETTINGS_ATTRIBUTE_CHARACTERISTIC,
-                properties=Characteristic.Properties.READ,
-                permissions=Characteristic.Permissions.READ_REQUIRES_ENCRYPTION,
-                value=CharacteristicValue(read=self.gain_settings_properties.on_read),
+        self.gain_settings_properties_characteristic = (
+            SerializableCharacteristicAdapter(
+                Characteristic(
+                    uuid=GATT_GAIN_SETTINGS_ATTRIBUTE_CHARACTERISTIC,
+                    properties=Characteristic.Properties.READ,
+                    permissions=Characteristic.Permissions.READ_REQUIRES_ENCRYPTION,
+                    value=self.gain_settings_properties,
+                ),
+                GainSettingsProperties,
             )
         )
 
@@ -402,7 +394,7 @@ class AICSService(TemplateService):
             uuid=GATT_AUDIO_INPUT_TYPE_CHARACTERISTIC,
             properties=Characteristic.Properties.READ,
             permissions=Characteristic.Permissions.READ_REQUIRES_ENCRYPTION,
-            value=audio_input_type,
+            value=bytes(audio_input_type, 'utf-8'),
         )
 
         self.audio_input_status_characteristic = Characteristic(
@@ -412,18 +404,14 @@ class AICSService(TemplateService):
             value=bytes([self.audio_input_status]),
         )
 
-        self.audio_input_control_point_characteristic = DelegatedCharacteristicAdapter(
-            Characteristic(
-                uuid=GATT_AUDIO_INPUT_CONTROL_POINT_CHARACTERISTIC,
-                properties=Characteristic.Properties.WRITE,
-                permissions=Characteristic.Permissions.WRITE_REQUIRES_ENCRYPTION,
-                value=CharacteristicValue(
-                    write=self.audio_input_control_point.on_write
-                ),
-            )
+        self.audio_input_control_point_characteristic = Characteristic(
+            uuid=GATT_AUDIO_INPUT_CONTROL_POINT_CHARACTERISTIC,
+            properties=Characteristic.Properties.WRITE,
+            permissions=Characteristic.Permissions.WRITE_REQUIRES_ENCRYPTION,
+            value=CharacteristicValue(write=self.audio_input_control_point.on_write),
         )
 
-        self.audio_input_description_characteristic = DelegatedCharacteristicAdapter(
+        self.audio_input_description_characteristic = UTF8CharacteristicAdapter(
             Characteristic(
                 uuid=GATT_AUDIO_INPUT_DESCRIPTION_CHARACTERISTIC,
                 properties=Characteristic.Properties.READ
@@ -469,8 +457,8 @@ class AICSServiceProxy(ProfileServiceProxy):
             )
         ):
             raise gatt.InvalidServiceError("Audio Input State Characteristic not found")
-        self.audio_input_state = DelegatedCharacteristicAdapter(
-            characteristic=characteristics[0], decode=AudioInputState.from_bytes
+        self.audio_input_state = SerializableCharacteristicAdapter(
+            characteristics[0], AudioInputState
         )
 
         if not (
@@ -481,9 +469,8 @@ class AICSServiceProxy(ProfileServiceProxy):
             raise gatt.InvalidServiceError(
                 "Gain Settings Attribute Characteristic not found"
             )
-        self.gain_settings_properties = PackedCharacteristicAdapter(
-            characteristics[0],
-            'BBB',
+        self.gain_settings_properties = SerializableCharacteristicAdapter(
+            characteristics[0], GainSettingsProperties
         )
 
         if not (
@@ -494,10 +481,7 @@ class AICSServiceProxy(ProfileServiceProxy):
             raise gatt.InvalidServiceError(
                 "Audio Input Status Characteristic not found"
             )
-        self.audio_input_status = PackedCharacteristicAdapter(
-            characteristics[0],
-            'B',
-        )
+        self.audio_input_status = PackedCharacteristicAdapter(characteristics[0], 'B')
 
         if not (
             characteristics := service_proxy.get_characteristics_by_uuid(
@@ -517,4 +501,4 @@ class AICSServiceProxy(ProfileServiceProxy):
             raise gatt.InvalidServiceError(
                 "Audio Input Description Characteristic not found"
             )
-        self.audio_input_description = characteristics[0]
+        self.audio_input_description = UTF8CharacteristicAdapter(characteristics[0])

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
 
 
 # -----------------------------------------------------------------------------
@@ -354,16 +355,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 +503,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/bass.py

@@ -276,10 +276,7 @@ class BroadcastReceiveState:
     subgroups: List[SubgroupInfo]
 
     @classmethod
-    def from_bytes(cls, data: bytes) -> Optional[BroadcastReceiveState]:
-        if not data:
-            return None
-
+    def from_bytes(cls, data: bytes) -> BroadcastReceiveState:
         source_id = data[0]
         _, source_address = hci.Address.parse_address_preceded_by_type(data, 2)
         source_adv_sid = data[8]
@@ -357,7 +354,7 @@ class BroadcastAudioScanServiceProxy(gatt_client.ProfileServiceProxy):
     SERVICE_CLASS = BroadcastAudioScanService
 
     broadcast_audio_scan_control_point: gatt_client.CharacteristicProxy
-    broadcast_receive_states: List[gatt.DelegatedCharacteristicAdapter]
+    broadcast_receive_states: List[gatt.SerializableCharacteristicAdapter]
 
     def __init__(self, service_proxy: gatt_client.ServiceProxy):
         self.service_proxy = service_proxy
@@ -381,8 +378,8 @@ class BroadcastAudioScanServiceProxy(gatt_client.ProfileServiceProxy):
                 "Broadcast Receive State characteristic not found"
             )
         self.broadcast_receive_states = [
-            gatt.DelegatedCharacteristicAdapter(
-                characteristic, decode=BroadcastReceiveState.from_bytes
+            gatt.SerializableCharacteristicAdapter(
+                characteristic, BroadcastReceiveState
             )
             for characteristic in characteristics
         ]

bumble/profiles/device_information_service.py

@@ -64,7 +64,10 @@ class DeviceInformationService(TemplateService):
     ):
         characteristics = [
             Characteristic(
-                uuid, Characteristic.Properties.READ, Characteristic.READABLE, field
+                uuid,
+                Characteristic.Properties.READ,
+                Characteristic.READABLE,
+                bytes(field, 'utf-8'),
             )
             for (field, uuid) in (
                 (manufacturer_name, GATT_MANUFACTURER_NAME_STRING_CHARACTERISTIC),

bumble/profiles/gmap.py

@@ -0,0 +1,198 @@
+# 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.
+
+"""LE Audio - Gaming Audio Profile"""
+
+# -----------------------------------------------------------------------------
+# Imports
+# -----------------------------------------------------------------------------
+import struct
+from typing import Optional
+
+from bumble.gatt import (
+    TemplateService,
+    DelegatedCharacteristicAdapter,
+    Characteristic,
+    GATT_GAMING_AUDIO_SERVICE,
+    GATT_GMAP_ROLE_CHARACTERISTIC,
+    GATT_UGG_FEATURES_CHARACTERISTIC,
+    GATT_UGT_FEATURES_CHARACTERISTIC,
+    GATT_BGS_FEATURES_CHARACTERISTIC,
+    GATT_BGR_FEATURES_CHARACTERISTIC,
+    InvalidServiceError,
+)
+from bumble.gatt_client import ProfileServiceProxy, ServiceProxy
+from enum import IntFlag
+
+
+# -----------------------------------------------------------------------------
+# Classes
+# -----------------------------------------------------------------------------
+class GmapRole(IntFlag):
+    UNICAST_GAME_GATEWAY = 1 << 0
+    UNICAST_GAME_TERMINAL = 1 << 1
+    BROADCAST_GAME_SENDER = 1 << 2
+    BROADCAST_GAME_RECEIVER = 1 << 3
+
+
+class UggFeatures(IntFlag):
+    UGG_MULTIPLEX = 1 << 0
+    UGG_96_KBPS_SOURCE = 1 << 1
+    UGG_MULTISINK = 1 << 2
+
+
+class UgtFeatures(IntFlag):
+    UGT_SOURCE = 1 << 0
+    UGT_80_KBPS_SOURCE = 1 << 1
+    UGT_SINK = 1 << 2
+    UGT_64_KBPS_SINK = 1 << 3
+    UGT_MULTIPLEX = 1 << 4
+    UGT_MULTISINK = 1 << 5
+    UGT_MULTISOURCE = 1 << 6
+
+
+class BgsFeatures(IntFlag):
+    BGS_96_KBPS = 1 << 0
+
+
+class BgrFeatures(IntFlag):
+    BGR_MULTISINK = 1 << 0
+    BGR_MULTIPLEX = 1 << 1
+
+
+# -----------------------------------------------------------------------------
+# Server
+# -----------------------------------------------------------------------------
+class GamingAudioService(TemplateService):
+    UUID = GATT_GAMING_AUDIO_SERVICE
+
+    gmap_role: Characteristic
+    ugg_features: Optional[Characteristic] = None
+    ugt_features: Optional[Characteristic] = None
+    bgs_features: Optional[Characteristic] = None
+    bgr_features: Optional[Characteristic] = None
+
+    def __init__(
+        self,
+        gmap_role: GmapRole,
+        ugg_features: Optional[UggFeatures] = None,
+        ugt_features: Optional[UgtFeatures] = None,
+        bgs_features: Optional[BgsFeatures] = None,
+        bgr_features: Optional[BgrFeatures] = None,
+    ) -> None:
+        characteristics = []
+
+        ugg_features = UggFeatures(0) if ugg_features is None else ugg_features
+        ugt_features = UgtFeatures(0) if ugt_features is None else ugt_features
+        bgs_features = BgsFeatures(0) if bgs_features is None else bgs_features
+        bgr_features = BgrFeatures(0) if bgr_features is None else bgr_features
+
+        self.gmap_role = Characteristic(
+            uuid=GATT_GMAP_ROLE_CHARACTERISTIC,
+            properties=Characteristic.Properties.READ,
+            permissions=Characteristic.Permissions.READABLE,
+            value=struct.pack('B', gmap_role),
+        )
+        characteristics.append(self.gmap_role)
+
+        if gmap_role & GmapRole.UNICAST_GAME_GATEWAY:
+            self.ugg_features = Characteristic(
+                uuid=GATT_UGG_FEATURES_CHARACTERISTIC,
+                properties=Characteristic.Properties.READ,
+                permissions=Characteristic.Permissions.READABLE,
+                value=struct.pack('B', ugg_features),
+            )
+            characteristics.append(self.ugg_features)
+
+        if gmap_role & GmapRole.UNICAST_GAME_TERMINAL:
+            self.ugt_features = Characteristic(
+                uuid=GATT_UGT_FEATURES_CHARACTERISTIC,
+                properties=Characteristic.Properties.READ,
+                permissions=Characteristic.Permissions.READABLE,
+                value=struct.pack('B', ugt_features),
+            )
+            characteristics.append(self.ugt_features)
+
+        if gmap_role & GmapRole.BROADCAST_GAME_SENDER:
+            self.bgs_features = Characteristic(
+                uuid=GATT_BGS_FEATURES_CHARACTERISTIC,
+                properties=Characteristic.Properties.READ,
+                permissions=Characteristic.Permissions.READABLE,
+                value=struct.pack('B', bgs_features),
+            )
+            characteristics.append(self.bgs_features)
+
+        if gmap_role & GmapRole.BROADCAST_GAME_RECEIVER:
+            self.bgr_features = Characteristic(
+                uuid=GATT_BGR_FEATURES_CHARACTERISTIC,
+                properties=Characteristic.Properties.READ,
+                permissions=Characteristic.Permissions.READABLE,
+                value=struct.pack('B', bgr_features),
+            )
+            characteristics.append(self.bgr_features)
+
+        super().__init__(characteristics)
+
+
+# -----------------------------------------------------------------------------
+# Client
+# -----------------------------------------------------------------------------
+class GamingAudioServiceProxy(ProfileServiceProxy):
+    SERVICE_CLASS = GamingAudioService
+
+    def __init__(self, service_proxy: ServiceProxy) -> None:
+        self.service_proxy = service_proxy
+
+        if not (
+            characteristics := service_proxy.get_characteristics_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],
+                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],
+                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],
+                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],
+                decode=lambda value: BgrFeatures(value[0]),
+            )

bumble/profiles/heart_rate_service.py

@@ -30,6 +30,7 @@ from ..gatt import (
     TemplateService,
     Characteristic,
     CharacteristicValue,
+    SerializableCharacteristicAdapter,
     DelegatedCharacteristicAdapter,
     PackedCharacteristicAdapter,
 )
@@ -150,15 +151,14 @@ class HeartRateService(TemplateService):
         body_sensor_location=None,
         reset_energy_expended=None,
     ):
-        self.heart_rate_measurement_characteristic = DelegatedCharacteristicAdapter(
+        self.heart_rate_measurement_characteristic = SerializableCharacteristicAdapter(
             Characteristic(
                 GATT_HEART_RATE_MEASUREMENT_CHARACTERISTIC,
                 Characteristic.Properties.NOTIFY,
                 0,
                 CharacteristicValue(read=read_heart_rate_measurement),
             ),
-            # pylint: disable=unnecessary-lambda
-            encode=lambda value: bytes(value),
+            HeartRateService.HeartRateMeasurement,
         )
         characteristics = [self.heart_rate_measurement_characteristic]
 
@@ -204,9 +204,8 @@ class HeartRateServiceProxy(ProfileServiceProxy):
         if characteristics := service_proxy.get_characteristics_by_uuid(
             GATT_HEART_RATE_MEASUREMENT_CHARACTERISTIC
         ):
-            self.heart_rate_measurement = DelegatedCharacteristicAdapter(
-                characteristics[0],
-                decode=HeartRateService.HeartRateMeasurement.from_bytes,
+            self.heart_rate_measurement = SerializableCharacteristicAdapter(
+                characteristics[0], HeartRateService.HeartRateMeasurement
             )
         else:
             self.heart_rate_measurement = None

bumble/profiles/vocs.py

@@ -0,0 +1,330 @@
+# 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
+# -----------------------------------------------------------------------------
+import struct
+from dataclasses import dataclass
+from typing import Optional
+
+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_client import ProfileServiceProxy, ServiceProxy
+from bumble.utils import OpenIntEnum
+from bumble.profiles.bap import AudioLocation
+
+# -----------------------------------------------------------------------------
+# Constants
+# -----------------------------------------------------------------------------
+
+MIN_VOLUME_OFFSET = -255
+MAX_VOLUME_OFFSET = 255
+CHANGE_COUNTER_MAX_VALUE = 0xFF
+
+
+class SetVolumeOffsetOpCode(OpenIntEnum):
+    SET_VOLUME_OFFSET = 0x01
+
+
+class ErrorCode(OpenIntEnum):
+    """
+    See Volume Offset Control Service 1.6. Application error codes.
+    """
+
+    INVALID_CHANGE_COUNTER = 0x80
+    OPCODE_NOT_SUPPORTED = 0x81
+    VALUE_OUT_OF_RANGE = 0x82
+
+
+# -----------------------------------------------------------------------------
+@dataclass
+class VolumeOffsetState:
+    volume_offset: int = 0
+    change_counter: int = 0
+    attribute_value: Optional[CharacteristicValue] = None
+
+    def __bytes__(self) -> bytes:
+        return struct.pack('<hB', self.volume_offset, self.change_counter)
+
+    @classmethod
+    def from_bytes(cls, data: bytes):
+        volume_offset, change_counter = struct.unpack('<hB', data)
+        return cls(volume_offset, change_counter)
+
+    def increment_change_counter(self) -> None:
+        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)
+        )
+
+    def on_read(self, _connection: Optional[Connection]) -> bytes:
+        return bytes(self)
+
+
+@dataclass
+class VocsAudioLocation:
+    audio_location: AudioLocation = AudioLocation.NOT_ALLOWED
+    attribute_value: Optional[CharacteristicValue] = None
+
+    def __bytes__(self) -> bytes:
+        return struct.pack('<I', self.audio_location)
+
+    @classmethod
+    def from_bytes(cls, data: bytes):
+        audio_location = AudioLocation(struct.unpack('<I', data)[0])
+        return cls(audio_location)
+
+    def on_read(self, _connection: Optional[Connection]) -> bytes:
+        return bytes(self)
+
+    async def on_write(self, connection: Optional[Connection], value: bytes) -> None:
+        assert connection
+        assert self.attribute_value
+
+        self.audio_location = AudioLocation(int.from_bytes(value, 'little'))
+        await connection.device.notify_subscribers(
+            attribute=self.attribute_value, value=value
+        )
+
+
+@dataclass
+class VolumeOffsetControlPoint:
+    volume_offset_state: VolumeOffsetState
+
+    async def on_write(self, connection: Optional[Connection], value: bytes) -> None:
+        assert connection
+
+        opcode = value[0]
+        if opcode != SetVolumeOffsetOpCode.SET_VOLUME_OFFSET:
+            raise ATT_Error(ErrorCode.OPCODE_NOT_SUPPORTED)
+
+        change_counter, volume_offset = struct.unpack('<Bh', value[1:])
+        await self._set_volume_offset(connection, change_counter, volume_offset)
+
+    async def _set_volume_offset(
+        self,
+        connection: Connection,
+        change_counter_operand: int,
+        volume_offset_operand: int,
+    ) -> None:
+        change_counter = self.volume_offset_state.change_counter
+
+        if change_counter != change_counter_operand:
+            raise ATT_Error(ErrorCode.INVALID_CHANGE_COUNTER)
+
+        if not MIN_VOLUME_OFFSET <= volume_offset_operand <= MAX_VOLUME_OFFSET:
+            raise ATT_Error(ErrorCode.VALUE_OUT_OF_RANGE)
+
+        self.volume_offset_state.volume_offset = volume_offset_operand
+        self.volume_offset_state.increment_change_counter()
+        await self.volume_offset_state.notify_subscribers_via_connection(connection)
+
+
+@dataclass
+class AudioOutputDescription:
+    audio_output_description: str = ''
+    attribute_value: Optional[CharacteristicValue] = None
+
+    @classmethod
+    def from_bytes(cls, data: bytes):
+        return cls(audio_output_description=data.decode('utf-8'))
+
+    def __bytes__(self) -> bytes:
+        return self.audio_output_description.encode('utf-8')
+
+    def on_read(self, _connection: Optional[Connection]) -> bytes:
+        return bytes(self)
+
+    async def on_write(self, connection: Optional[Connection], value: bytes) -> None:
+        assert connection
+        assert self.attribute_value
+
+        self.audio_output_description = value.decode('utf-8')
+        await connection.device.notify_subscribers(
+            attribute=self.attribute_value, value=value
+        )
+
+
+# -----------------------------------------------------------------------------
+class VolumeOffsetControlService(TemplateService):
+    UUID = GATT_VOLUME_OFFSET_CONTROL_SERVICE
+
+    def __init__(
+        self,
+        volume_offset_state: Optional[VolumeOffsetState] = None,
+        audio_location: Optional[VocsAudioLocation] = None,
+        audio_output_description: Optional[AudioOutputDescription] = None,
+    ) -> None:
+
+        self.volume_offset_state = (
+            VolumeOffsetState() if volume_offset_state is None else volume_offset_state
+        )
+
+        self.audio_location = (
+            VocsAudioLocation() if audio_location is None else audio_location
+        )
+
+        self.audio_output_description = (
+            AudioOutputDescription()
+            if audio_output_description is None
+            else audio_output_description
+        )
+
+        self.volume_offset_control_point: VolumeOffsetControlPoint = (
+            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),
+            ),
+            encode=lambda value: bytes(value),
+        )
+
+        self.audio_location_characteristic = DelegatedCharacteristicAdapter(
+            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,
+                ),
+            ),
+            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(
+            Characteristic(
+                uuid=GATT_AUDIO_OUTPUT_DESCRIPTION_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_output_description.on_read,
+                    write=self.audio_output_description.on_write,
+                ),
+            )
+        )
+
+        self.audio_output_description.attribute_value = (
+            self.audio_output_description_characteristic.value
+        )
+
+        super().__init__(
+            characteristics=[
+                self.volume_offset_state_characteristic,  # type: ignore
+                self.audio_location_characteristic,  # type: ignore
+                self.volume_offset_control_point_characteristic,  # type: ignore
+                self.audio_output_description_characteristic,  # type: ignore
+            ],
+            primary=False,
+        )
+
+
+# -----------------------------------------------------------------------------
+# Client
+# -----------------------------------------------------------------------------
+class VolumeOffsetControlServiceProxy(ProfileServiceProxy):
+    SERVICE_CLASS = VolumeOffsetControlService
+
+    def __init__(self, service_proxy: ServiceProxy) -> None:
+        self.service_proxy = service_proxy
+
+        if not (
+            characteristics := service_proxy.get_characteristics_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
+        )
+
+        if not (
+            characteristics := service_proxy.get_characteristics_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,
+        )
+
+        if not (
+            characteristics := service_proxy.get_characteristics_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(
+                GATT_AUDIO_OUTPUT_DESCRIPTION_CHARACTERISTIC
+            )
+        ):
+            raise InvalidServiceError(
+                "Audio Output Description characteristic not found"
+            )
+        self.audio_output_description = UTF8CharacteristicAdapter(characteristics[0])

bumble/smp.py

@@ -695,6 +695,7 @@ class Session:
         self.ltk_ediv = 0
         self.ltk_rand = bytes(8)
         self.link_key: Optional[bytes] = None
+        self.maximum_encryption_key_size: int = 0
         self.initiator_key_distribution: int = 0
         self.responder_key_distribution: int = 0
         self.peer_random_value: Optional[bytes] = None
@@ -741,6 +742,10 @@ class Session:
         else:
             self.pairing_result = None
 
+        self.maximum_encryption_key_size = (
+            pairing_config.delegate.maximum_encryption_key_size
+        )
+
         # Key Distribution (default values before negotiation)
         self.initiator_key_distribution = (
             pairing_config.delegate.local_initiator_key_distribution
@@ -993,7 +998,7 @@ class Session:
             io_capability=self.io_capability,
             oob_data_flag=self.oob_data_flag,
             auth_req=self.auth_req,
-            maximum_encryption_key_size=16,
+            maximum_encryption_key_size=self.maximum_encryption_key_size,
             initiator_key_distribution=self.initiator_key_distribution,
             responder_key_distribution=self.responder_key_distribution,
         )
@@ -1005,7 +1010,7 @@ class Session:
             io_capability=self.io_capability,
             oob_data_flag=self.oob_data_flag,
             auth_req=self.auth_req,
-            maximum_encryption_key_size=16,
+            maximum_encryption_key_size=self.maximum_encryption_key_size,
             initiator_key_distribution=self.initiator_key_distribution,
             responder_key_distribution=self.responder_key_distribution,
         )

bumble/transport/usb.py

@@ -149,7 +149,10 @@ async def open_usb_transport(spec: str) -> Transport:
 
             if status != usb1.TRANSFER_COMPLETED:
                 logger.warning(
-                    color(f'!!! OUT transfer not completed: status={status}', 'red')
+                    color(
+                        f'!!! OUT transfer not completed: status={status}',
+                        'red',
+                    )
                 )
 
         async def process_queue(self):
@@ -275,7 +278,10 @@ async def open_usb_transport(spec: str) -> Transport:
                 )
             else:
                 logger.warning(
-                    color(f'!!! IN transfer not completed: status={status}', 'red')
+                    color(
+                        f'!!! IN[{packet_type}] transfer not completed: status={status}',
+                        'red',
+                    )
                 )
                 self.loop.call_soon_threadsafe(self.on_transport_lost)
 

bumble/utils.py

@@ -24,17 +24,19 @@ import logging
 import sys
 import warnings
 from typing import (
-    Awaitable,
-    Set,
-    TypeVar,
-    List,
-    Tuple,
-    Callable,
     Any,
+    Awaitable,
+    Callable,
+    List,
     Optional,
+    Protocol,
+    Set,
+    Tuple,
+    TypeVar,
     Union,
     overload,
 )
+from typing_extensions import Self
 
 from pyee import EventEmitter
 
@@ -487,3 +489,16 @@ class OpenIntEnum(enum.IntEnum):
         obj._value_ = value
         obj._name_ = f"{cls.__name__}[{value}]"
         return obj
+
+
+# -----------------------------------------------------------------------------
+class ByteSerializable(Protocol):
+    """
+    Type protocol for classes that can be instantiated from bytes and serialized
+    to bytes.
+    """
+
+    @classmethod
+    def from_bytes(cls, data: bytes) -> Self: ...
+
+    def __bytes__(self) -> bytes: ...

bumble/vendor/android/hci.py

@@ -16,6 +16,7 @@
 # Imports
 # -----------------------------------------------------------------------------
 import struct
+from typing import Dict, Optional, Type
 
 from bumble.hci import (
     name_or_number,
@@ -24,7 +25,9 @@ from bumble.hci import (
     HCI_Constant,
     HCI_Object,
     HCI_Command,
-    HCI_Vendor_Event,
+    HCI_Event,
+    HCI_Extended_Event,
+    HCI_VENDOR_EVENT,
     STATUS_SPEC,
 )
 
@@ -48,7 +51,6 @@ HCI_DYNAMIC_AUDIO_BUFFER_COMMAND = hci_vendor_command_op_code(0x15F)
 HCI_BLUETOOTH_QUALITY_REPORT_EVENT = 0x58
 
 HCI_Command.register_commands(globals())
-HCI_Vendor_Event.register_subevents(globals())
 
 
 # -----------------------------------------------------------------------------
@@ -279,7 +281,29 @@ class HCI_Dynamic_Audio_Buffer_Command(HCI_Command):
 
 
 # -----------------------------------------------------------------------------
-@HCI_Vendor_Event.event(
+class HCI_Android_Vendor_Event(HCI_Extended_Event):
+    event_code: int = HCI_VENDOR_EVENT
+    subevent_classes: Dict[int, Type[HCI_Extended_Event]] = {}
+
+    @classmethod
+    def subclass_from_parameters(
+        cls, parameters: bytes
+    ) -> Optional[HCI_Extended_Event]:
+        subevent_code = parameters[0]
+        if subevent_code == HCI_BLUETOOTH_QUALITY_REPORT_EVENT:
+            quality_report_id = parameters[1]
+            if quality_report_id in (0x01, 0x02, 0x03, 0x04, 0x07, 0x08, 0x09):
+                return HCI_Bluetooth_Quality_Report_Event.from_parameters(parameters)
+
+        return None
+
+
+HCI_Android_Vendor_Event.register_subevents(globals())
+HCI_Event.add_vendor_factory(HCI_Android_Vendor_Event.subclass_from_parameters)
+
+
+# -----------------------------------------------------------------------------
+@HCI_Extended_Event.event(
     fields=[
         ('quality_report_id', 1),
         ('packet_types', 1),
@@ -308,10 +332,11 @@ class HCI_Dynamic_Audio_Buffer_Command(HCI_Command):
         ('tx_last_subevent_packets', 4),
         ('crc_error_packets', 4),
         ('rx_duplicate_packets', 4),
+        ('rx_unreceived_packets', 4),
         ('vendor_specific_parameters', '*'),
     ]
 )
-class HCI_Bluetooth_Quality_Report_Event(HCI_Vendor_Event):
+class HCI_Bluetooth_Quality_Report_Event(HCI_Android_Vendor_Event):
     # pylint: disable=line-too-long
     '''
     See https://source.android.com/docs/core/connect/bluetooth/hci_requirements#bluetooth-quality-report-sub-event

docs/mkdocs/src/drivers/index.md

@@ -16,4 +16,5 @@ USB vendor ID and product ID.
 
 Drivers included in the module are:
 
-  * [Realtek](realtek.md): Loading of Firmware and Config for Realtek USB dongles.
+  * [Realtek](realtek.md): Loading of Firmware and Config for Realtek USB dongles.
+  * [Intel](intel.md): Loading of Firmware and Config for Intel USB controllers.

docs/mkdocs/src/drivers/intel.md

@@ -0,0 +1,73 @@
+INTEL DRIVER
+==============
+
+This driver supports loading firmware images and optional config data to
+Intel USB controllers.
+A number of USB dongles are supported, but likely not all.
+The initial implementation has been tested on BE200 and AX210 controllers.
+When using a USB controller, the USB product ID and vendor ID are used
+to find whether a matching set of firmware image and config data
+is needed for that specific model. If a match exists, the driver will try
+load the firmware image and, if needed, config data.
+Alternatively, the metadata property ``driver=intel`` may be specified in a transport
+name to force that driver to be used (ex: ``usb:[driver=intel]0`` instead of just
+``usb:0`` for the first USB device).
+The driver will look for the firmware and config files by name, in order, in:
+
+  * The directory specified by the environment variable `BUMBLE_INTEL_FIRMWARE_DIR`
+    if set.
+  * The directory `<package-dir>/drivers/intel_fw` where `<package-dir>` is the directory
+    where the `bumble` package is installed.
+  * The current directory.
+
+It is also possible to override or extend the config data with parameters passed via the
+transport name. The driver name `intel` may be suffixed with `/<param:value>[+<param:value>]...`
+The supported params are:
+  * `ddc_addon`: configuration data to add to the data loaded from the config data file
+  * `ddc_override`: configuration data to use instead of the data loaded from the config data file.
+
+With both `dcc_addon` and `dcc_override`, the param value is a hex-encoded byte array containing
+the config data (same format as the config file).
+Example transport name:
+`usb:[driver=intel/dcc_addon:03E40200]0`
+
+
+Obtaining Firmware Images and Config Data
+-----------------------------------------
+
+Firmware images and config data may be obtained from a variety of online
+sources.
+To facilitate finding a downloading the, the utility program `bumble-intel-fw-download`
+may be used.
+
+```
+Usage: bumble-intel-fw-download [OPTIONS]
+
+  Download Intel firmware images and configs.
+
+Options:
+  --output-dir TEXT        Output directory where the files will be saved.
+                           Defaults to the OS-specific app data dir, which the
+                           driver will check when trying to find firmware
+  --source [linux-kernel]  [default: linux-kernel]
+  --single TEXT            Only download a single image set, by its base name
+  --force                  Overwrite files if they already exist
+  --help                   Show this message and exit.
+```
+
+Utility
+-------
+
+The `bumble-intel-util` utility may be used to interact with an Intel USB controller.
+
+```
+Usage: bumble-intel-util [OPTIONS] COMMAND [ARGS]...
+
+Options:
+  --help  Show this message and exit.
+
+Commands:
+  bootloader  Reboot in bootloader mode.
+  info        Get the firmware info.
+  load        Load a firmware image.
+```

examples/keyboard.py

@@ -282,7 +282,7 @@ async def keyboard_device(device, command):
                         GATT_MANUFACTURER_NAME_STRING_CHARACTERISTIC,
                         Characteristic.Properties.READ,
                         Characteristic.READABLE,
-                        'Bumble',
+                        bytes('Bumble', 'utf-8'),
                     )
                 ],
             ),

examples/run_gatt_server.py

@@ -127,7 +127,7 @@ async def main() -> None:
                     '486F64C6-4B5F-4B3B-8AFF-EDE134A8446A',
                     Characteristic.Properties.READ | Characteristic.Properties.NOTIFY,
                     Characteristic.READABLE,
-                    'hello',
+                    bytes('hello', 'utf-8'),
                 ),
             ],
         )

examples/run_gatt_with_adapters.py

@@ -0,0 +1,319 @@
+# 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 dataclasses
+import logging
+import os
+import random
+import struct
+import sys
+from typing import Any, List, Union
+
+from bumble.device import Connection, Device, Peer
+from bumble import transport
+from bumble import gatt
+from bumble import hci
+from bumble import core
+
+
+# -----------------------------------------------------------------------------
+SERVICE_UUID = core.UUID("50DB505C-8AC4-4738-8448-3B1D9CC09CC5")
+CHARACTERISTIC_UUID_BASE = "D901B45B-4916-412E-ACCA-0000000000"
+
+
+# -----------------------------------------------------------------------------
+@dataclasses.dataclass
+class CustomSerializableClass:
+    x: int
+    y: int
+
+    @classmethod
+    def from_bytes(cls, data: bytes) -> CustomSerializableClass:
+        return cls(*struct.unpack(">II", data))
+
+    def __bytes__(self) -> bytes:
+        return struct.pack(">II", self.x, self.y)
+
+
+# -----------------------------------------------------------------------------
+@dataclasses.dataclass
+class CustomClass:
+    a: int
+    b: int
+
+    @classmethod
+    def decode(cls, data: bytes) -> CustomClass:
+        return cls(*struct.unpack(">II", data))
+
+    def encode(self) -> bytes:
+        return struct.pack(">II", self.a, self.b)
+
+
+# -----------------------------------------------------------------------------
+async def client(device: Device, address: hci.Address) -> None:
+    print(f'=== Connecting to {address}...')
+    connection = await device.connect(address)
+    print('=== Connected')
+
+    # Discover all characteristics.
+    peer = Peer(connection)
+    print("*** Discovering services and characteristics...")
+    await peer.discover_all()
+    print("*** Discovery complete")
+
+    service = peer.get_services_by_uuid(SERVICE_UUID)[0]
+    characteristics = []
+    for index in range(1, 9):
+        characteristics.append(
+            service.get_characteristics_by_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()})")
+
+    # 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)})")
+    await c1.write_value("happy π day".encode("utf-8"))
+
+    # Static characteristic with a string value.
+    c2 = gatt.UTF8CharacteristicAdapter(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")
+
+    # Static characteristic with a tuple value.
+    c3 = gatt.PackedCharacteristicAdapter(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))
+
+    # Static characteristic with a named tuple value.
+    c4 = gatt.MappedCharacteristicAdapter(
+        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})
+
+    # Static characteristic with a serializable value.
+    c5 = gatt.SerializableCharacteristicAdapter(
+        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))
+
+    # Static characteristic with a delegated value.
+    c6 = gatt.DelegatedCharacteristicAdapter(
+        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))
+
+    # 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)})")
+    await c7.write_value(bytes.fromhex("01020304"))
+
+    # Dynamic characteristic with a string value.
+    c8 = gatt.UTF8CharacteristicAdapter(characteristics[7])
+    c8_value = await c8.read_value()
+    print(f"@@@ C8 {c8} value = {c8_value} (type={type(c8_value)})")
+    await c8.write_value("howdy")
+
+
+# -----------------------------------------------------------------------------
+def dynamic_read(selector: str) -> Union[bytes, str]:
+    if selector == "bytes":
+        print("$$$ Returning random bytes")
+        return random.randbytes(7)
+    elif selector == "string":
+        print("$$$ Returning random string")
+        return random.randbytes(7).hex()
+
+    raise ValueError("invalid selector")
+
+
+# -----------------------------------------------------------------------------
+def dynamic_write(selector: str, value: Any) -> None:
+    print(f"$$$ Received[{selector}]: {value} (type={type(value)})")
+
+
+# -----------------------------------------------------------------------------
+def on_characteristic_read(characteristic: gatt.Characteristic, value: Any) -> None:
+    """Event listener invoked when a characteristic is read."""
+    print(f"<<< READ: {characteristic} -> {value} ({type(value)})")
+
+
+# -----------------------------------------------------------------------------
+def on_characteristic_write(characteristic: gatt.Characteristic, value: Any) -> None:
+    """Event listener invoked when a characteristic is written."""
+    print(f"<<< WRITE: {characteristic} <- {value}  ({type(value)})")
+
+
+# -----------------------------------------------------------------------------
+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")
+        return
+
+    async with await transport.open_transport(sys.argv[1]) as hci_transport:
+        # Create a device to manage the host
+        device = Device.with_hci(
+            "Bumble",
+            hci.Address("F0:F1:F2:F3:F4:F5"),
+            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]))
+        else:
+            await device.start_advertising(auto_restart=True)
+
+        await hci_transport.source.wait_for_termination()
+
+
+# -----------------------------------------------------------------------------
+logging.basicConfig(level=os.environ.get('BUMBLE_LOGLEVEL', 'INFO').upper())
+asyncio.run(main())

pyproject.toml

@@ -1,21 +1,133 @@
 [build-system]
-requires = ["setuptools>=52", "wheel", "setuptools_scm>=6.2"]
+requires = ["setuptools>=61", "wheel", "setuptools_scm>=8"]
 build-backend = "setuptools.build_meta"
 
+[project]
+name = "bumble"
+dynamic = ["version"]
+description = "Bluetooth Stack for Apps, Emulation, Test and Experimentation"
+readme = "README.md"
+authors = [{ name = "Google", email = "bumble-dev@google.com" }]
+requires-python = ">=3.8"
+dependencies = [
+    "aiohttp ~= 3.8; platform_system!='Emscripten'",
+    "appdirs >= 1.4; platform_system!='Emscripten'",
+    "click >= 8.1.3; platform_system!='Emscripten'",
+    "cryptography >= 39; platform_system!='Emscripten'",
+    # Pyodide bundles a version of cryptography that is built for wasm, which may not match the
+    # versions available on PyPI. Relax the version requirement since it's better than being
+    # completely unable to import the package in case of version mismatch.
+    "cryptography >= 39.0; platform_system=='Emscripten'",
+    "grpcio >= 1.62.1; platform_system!='Emscripten'",
+    "humanize >= 4.6.0; platform_system!='Emscripten'",
+    "libusb1 >= 2.0.1; platform_system!='Emscripten'",
+    "libusb-package == 1.0.26.1; platform_system!='Emscripten'",
+    "platformdirs >= 3.10.0; platform_system!='Emscripten'",
+    "prompt_toolkit >= 3.0.16; platform_system!='Emscripten'",
+    "prettytable >= 3.6.0; platform_system!='Emscripten'",
+    "protobuf >= 3.12.4; platform_system!='Emscripten'",
+    "pyee >= 8.2.2",
+    "pyserial-asyncio >= 0.5; platform_system!='Emscripten'",
+    "pyserial >= 3.5; platform_system!='Emscripten'",
+    "pyusb >= 1.2; platform_system!='Emscripten'",
+    "websockets == 13.1; platform_system!='Emscripten'",
+]
+
+[project.optional-dependencies]
+build = ["build >= 0.7"]
+test = [
+    "pytest >= 8.2",
+    "pytest-asyncio >= 0.23.5",
+    "pytest-html >= 3.2.0",
+    "coverage >= 6.4",
+]
+development = [
+    "black == 24.3",
+    "bt-test-interfaces >= 0.0.6",
+    "grpcio-tools >= 1.62.1",
+    "invoke >= 1.7.3",
+    "mobly >= 1.12.2",
+    "mypy == 1.12.0",
+    "nox >= 2022",
+    "pylint == 3.3.1",
+    "pyyaml >= 6.0",
+    "types-appdirs >= 1.4.3",
+    "types-invoke >= 1.7.3",
+    "types-protobuf >= 4.21.0",
+]
+avatar = [
+    "pandora-avatar == 0.0.10",
+    "rootcanal == 1.10.0 ; 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",
+]
+lc3 = [
+    "lc3 @ git+https://github.com/google/liblc3.git",
+]
+
+[project.scripts]
+bumble-ble-rpa-tool = "bumble.apps.ble_rpa_tool:main"
+bumble-console = "bumble.apps.console:main"
+bumble-controller-info = "bumble.apps.controller_info:main"
+bumble-controller-loopback = "bumble.apps.controller_loopback:main"
+bumble-gatt-dump = "bumble.apps.gatt_dump:main"
+bumble-hci-bridge = "bumble.apps.hci_bridge:main"
+bumble-l2cap-bridge = "bumble.apps.l2cap_bridge:main"
+bumble-rfcomm-bridge = "bumble.apps.rfcomm_bridge:main"
+bumble-pair = "bumble.apps.pair:main"
+bumble-scan = "bumble.apps.scan:main"
+bumble-show = "bumble.apps.show:main"
+bumble-unbond = "bumble.apps.unbond:main"
+bumble-usb-probe = "bumble.apps.usb_probe:main"
+bumble-link-relay = "bumble.apps.link_relay.link_relay:main"
+bumble-bench = "bumble.apps.bench:main"
+bumble-player = "bumble.apps.player.player:main"
+bumble-speaker = "bumble.apps.speaker.speaker:main"
+bumble-pandora-server = "bumble.apps.pandora_server:main"
+bumble-rtk-util = "bumble.tools.rtk_util:main"
+bumble-rtk-fw-download = "bumble.tools.rtk_fw_download:main"
+bumble-intel-util = "bumble.tools.intel_util:main"
+bumble-intel-fw-download = "bumble.tools.intel_fw_download:main"
+
+
+[project.urls]
+Homepage = "https://github.com/google/bumble"
+
+[tool.setuptools]
+packages = [
+    "bumble",
+    "bumble.transport",
+    "bumble.transport.grpc_protobuf",
+    "bumble.drivers",
+    "bumble.profiles",
+    "bumble.apps",
+    "bumble.apps.link_relay",
+    "bumble.pandora",
+    "bumble.tools",
+]
+
+[tool.setuptools.package-dir]
+"bumble" = "bumble"
+"bumble.apps" = "apps"
+"bumble.tools" = "tools"
+
 [tool.setuptools_scm]
 write_to = "bumble/_version.py"
 
+[tool.setuptools.package-data]
+"*" = ["*.pyi", "py.typed"]
+
 [tool.pytest.ini_options]
 pythonpath = "."
-testpaths = [
-    "tests"
-]
+testpaths = ["tests"]
 
 [tool.pylint.master]
 init-hook = 'import sys; sys.path.append(".")'
-ignore-paths = [
-    '.*_pb2(_grpc)?.py'
-]
+ignore-paths = ['.*_pb2(_grpc)?.py']
 
 [tool.pylint.messages_control]
 max-line-length = "88"
@@ -25,8 +137,8 @@ disable = [
     "fixme",
     "logging-fstring-interpolation",
     "logging-not-lazy",
-    "no-member", # Temporary until pylint works better with class/method decorators
-    "no-value-for-parameter", # Temporary until pylint works better with class/method decorators
+    "no-member",                     # Temporary until pylint works better with class/method decorators
+    "no-value-for-parameter",        # Temporary until pylint works better with class/method decorators
     "missing-class-docstring",
     "missing-function-docstring",
     "missing-module-docstring",
@@ -41,11 +153,11 @@ disable = [
 ]
 
 [tool.pylint.main]
-ignore="pandora" # FIXME: pylint does not support stubs yet:
+ignore = "pandora" # FIXME: pylint does not support stubs yet:
 
 [tool.pylint.typecheck]
-signature-mutators="AsyncRunner.run_in_task"
-disable="not-callable"
+signature-mutators = "AsyncRunner.run_in_task"
+disable = "not-callable"
 
 [tool.black]
 skip-string-normalization = true
@@ -85,4 +197,3 @@ ignore_missing_imports = true
 [[tool.mypy.overrides]]
 module = "usb1.*"
 ignore_missing_imports = true
-

setup.cfg

@@ -1,111 +0,0 @@
-# Copyright 2021-2023 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.
-
-[metadata]
-name = bumble
-use_scm_version = True
-description = Bluetooth Stack for Apps, Emulation, Test and Experimentation
-long_description = file: README.md
-long_description_content_type = text/markdown
-author = Google
-author_email = tbd@tbd.com
-url = https://github.com/google/bumble
-
-[options]
-python_requires = >=3.8
-packages = bumble, bumble.transport, bumble.transport.grpc_protobuf, bumble.drivers, bumble.profiles, bumble.apps, bumble.apps.link_relay, bumble.pandora, bumble.tools
-package_dir =
-    bumble = bumble
-    bumble.apps = apps
-    bumble.tools = tools
-include_package_data = True
-install_requires =
-    aiohttp ~= 3.8; platform_system!='Emscripten'
-    appdirs >= 1.4; platform_system!='Emscripten'
-    click >= 8.1.3; platform_system!='Emscripten'
-    cryptography == 39; platform_system!='Emscripten'
-    # Pyodide bundles a version of cryptography that is built for wasm, which may not match the
-    # versions available on PyPI. Relax the version requirement since it's better than being
-    # completely unable to import the package in case of version mismatch.
-    cryptography >= 39.0; platform_system=='Emscripten'
-    grpcio >= 1.62.1; platform_system!='Emscripten'
-    humanize >= 4.6.0; platform_system!='Emscripten'
-    libusb1 >= 2.0.1; platform_system!='Emscripten'
-    libusb-package == 1.0.26.1; platform_system!='Emscripten'
-    platformdirs >= 3.10.0; platform_system!='Emscripten'
-    prompt_toolkit >= 3.0.16; platform_system!='Emscripten'
-    prettytable >= 3.6.0; platform_system!='Emscripten'
-    protobuf >= 3.12.4; platform_system!='Emscripten'
-    pyee >= 8.2.2
-    pyserial-asyncio >= 0.5; platform_system!='Emscripten'
-    pyserial >= 3.5; platform_system!='Emscripten'
-    pyusb >= 1.2; platform_system!='Emscripten'
-    websockets == 13.1; platform_system!='Emscripten'
-
-[options.entry_points]
-console_scripts =
-    bumble-ble-rpa-tool = bumble.apps.ble_rpa_tool:main
-    bumble-console = bumble.apps.console:main
-    bumble-controller-info = bumble.apps.controller_info:main
-    bumble-controller-loopback = bumble.apps.controller_loopback:main
-    bumble-gatt-dump = bumble.apps.gatt_dump:main
-    bumble-hci-bridge = bumble.apps.hci_bridge:main
-    bumble-l2cap-bridge = bumble.apps.l2cap_bridge:main
-    bumble-rfcomm-bridge = bumble.apps.rfcomm_bridge:main
-    bumble-pair = bumble.apps.pair:main
-    bumble-scan = bumble.apps.scan:main
-    bumble-show = bumble.apps.show:main
-    bumble-unbond = bumble.apps.unbond:main
-    bumble-usb-probe = bumble.apps.usb_probe:main
-    bumble-link-relay = bumble.apps.link_relay.link_relay:main
-    bumble-bench = bumble.apps.bench:main
-    bumble-player = bumble.apps.player.player:main
-    bumble-speaker = bumble.apps.speaker.speaker:main
-    bumble-pandora-server = bumble.apps.pandora_server:main
-    bumble-rtk-util = bumble.tools.rtk_util:main
-    bumble-rtk-fw-download = bumble.tools.rtk_fw_download:main
-
-[options.package_data]
-* = py.typed, *.pyi
-
-[options.extras_require]
-build =
-    build >= 0.7
-test =
-    pytest >= 8.2
-    pytest-asyncio >= 0.23.5
-    pytest-html >= 3.2.0
-    coverage >= 6.4
-development =
-    black == 24.3
-    grpcio-tools >= 1.62.1
-    invoke >= 1.7.3
-    mobly >= 1.12.2
-    mypy == 1.12.0
-    nox >= 2022
-    pylint == 3.3.1
-    pyyaml >= 6.0
-    types-appdirs >= 1.4.3
-    types-invoke >= 1.7.3
-    types-protobuf >= 4.21.0
-    wasmtime == 20.0.0
-avatar =
-    pandora-avatar == 0.0.10
-    rootcanal == 1.10.0 ; 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

setup.py

@@ -1,17 +0,0 @@
-# Copyright 2021-2022 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 setuptools import setup
-
-setup()

tests/aics_test.py

@@ -28,6 +28,7 @@ from bumble.profiles.aics import (
     AudioInputState,
     AICSServiceProxy,
     GainMode,
+    GainSettingsProperties,
     AudioInputStatus,
     AudioInputControlPointOpCode,
     ErrorCode,
@@ -82,7 +83,12 @@ async def test_init_service(aics_client: AICSServiceProxy):
         gain_mode=GainMode.MANUAL,
         change_counter=0,
     )
-    assert await aics_client.gain_settings_properties.read_value() == (1, 0, 255)
+    assert (
+        await aics_client.gain_settings_properties.read_value()
+        == GainSettingsProperties(
+            gain_settings_unit=1, gain_settings_minimum=0, gain_settings_maximum=255
+        )
+    )
     assert await aics_client.audio_input_status.read_value() == (
         AudioInputStatus.ACTIVE
     )
@@ -481,12 +487,12 @@ async def test_set_automatic_gain_mode_when_automatic_only(
 @pytest.mark.asyncio
 async def test_audio_input_description_initial_value(aics_client: AICSServiceProxy):
     description = await aics_client.audio_input_description.read_value()
-    assert description.decode('utf-8') == "Bluetooth"
+    assert description == "Bluetooth"
 
 
 @pytest.mark.asyncio
 async def test_audio_input_description_write_and_read(aics_client: AICSServiceProxy):
-    new_description = "Line Input".encode('utf-8')
+    new_description = "Line Input"
 
     await aics_client.audio_input_description.write_value(new_description)
 

tests/gatt_test.py

@@ -15,11 +15,13 @@
 # -----------------------------------------------------------------------------
 # Imports
 # -----------------------------------------------------------------------------
+from __future__ import annotations
 import asyncio
 import logging
 import os
 import struct
 import pytest
+from typing_extensions import Self
 from unittest.mock import AsyncMock, Mock, ANY
 
 from bumble.controller import Controller
@@ -31,6 +33,7 @@ from bumble.gatt import (
     GATT_BATTERY_LEVEL_CHARACTERISTIC,
     GATT_CLIENT_CHARACTERISTIC_CONFIGURATION_DESCRIPTOR,
     CharacteristicAdapter,
+    SerializableCharacteristicAdapter,
     DelegatedCharacteristicAdapter,
     PackedCharacteristicAdapter,
     MappedCharacteristicAdapter,
@@ -310,7 +313,7 @@ async def test_attribute_getters():
 
 # -----------------------------------------------------------------------------
 @pytest.mark.asyncio
-async def test_CharacteristicAdapter():
+async def test_CharacteristicAdapter() -> None:
     # Check that the CharacteristicAdapter base class is transparent
     v = bytes([1, 2, 3])
     c = Characteristic(
@@ -329,67 +332,94 @@ async def test_CharacteristicAdapter():
     assert c.value == v
 
     # Simple delegated adapter
-    a = DelegatedCharacteristicAdapter(
+    delegated = DelegatedCharacteristicAdapter(
         c, lambda x: bytes(reversed(x)), lambda x: bytes(reversed(x))
     )
 
-    value = await a.read_value(None)
-    assert value == bytes(reversed(v))
+    delegated_value = await delegated.read_value(None)
+    assert delegated_value == bytes(reversed(v))
 
-    v = bytes([3, 4, 5])
-    await a.write_value(None, v)
-    assert a.value == bytes(reversed(v))
+    delegated_value2 = bytes([3, 4, 5])
+    await delegated.write_value(None, delegated_value2)
+    assert delegated.value == bytes(reversed(delegated_value2))
 
     # Packed adapter with single element format
-    v = 1234
-    pv = struct.pack('>H', v)
-    c.value = v
-    a = PackedCharacteristicAdapter(c, '>H')
+    packed_value_ref = 1234
+    packed_value_bytes = struct.pack('>H', packed_value_ref)
+    c.value = packed_value_ref
+    packed = PackedCharacteristicAdapter(c, '>H')
 
-    value = await a.read_value(None)
-    assert value == pv
-    c.value = None
-    await a.write_value(None, pv)
-    assert a.value == v
+    packed_value_read = await packed.read_value(None)
+    assert packed_value_read == packed_value_bytes
+    c.value = b''
+    await packed.write_value(None, packed_value_bytes)
+    assert packed.value == packed_value_ref
 
     # Packed adapter with multi-element format
     v1 = 1234
     v2 = 5678
-    pv = struct.pack('>HH', v1, v2)
+    packed_multi_value_bytes = struct.pack('>HH', v1, v2)
     c.value = (v1, v2)
-    a = PackedCharacteristicAdapter(c, '>HH')
+    packed_multi = PackedCharacteristicAdapter(c, '>HH')
 
-    value = await a.read_value(None)
-    assert value == pv
-    c.value = None
-    await a.write_value(None, pv)
-    assert a.value == (v1, v2)
+    packed_multi_read_value = await packed_multi.read_value(None)
+    assert packed_multi_read_value == packed_multi_value_bytes
+    packed_multi.value = b''
+    await packed_multi.write_value(None, packed_multi_value_bytes)
+    assert packed_multi.value == (v1, v2)
 
     # Mapped adapter
     v1 = 1234
     v2 = 5678
-    pv = struct.pack('>HH', v1, v2)
+    packed_mapped_value_bytes = struct.pack('>HH', v1, v2)
     mapped = {'v1': v1, 'v2': v2}
     c.value = mapped
-    a = MappedCharacteristicAdapter(c, '>HH', ('v1', 'v2'))
+    packed_mapped = MappedCharacteristicAdapter(c, '>HH', ('v1', 'v2'))
 
-    value = await a.read_value(None)
-    assert value == pv
-    c.value = None
-    await a.write_value(None, pv)
-    assert a.value == mapped
+    packed_mapped_read_value = await packed_mapped.read_value(None)
+    assert packed_mapped_read_value == packed_mapped_value_bytes
+    c.value = b''
+    await packed_mapped.write_value(None, packed_mapped_value_bytes)
+    assert packed_mapped.value == mapped
 
     # UTF-8 adapter
-    v = 'Hello π'
-    ev = v.encode('utf-8')
-    c.value = v
-    a = UTF8CharacteristicAdapter(c)
+    string_value = 'Hello π'
+    string_value_bytes = string_value.encode('utf-8')
+    c.value = string_value
+    string_c = UTF8CharacteristicAdapter(c)
 
-    value = await a.read_value(None)
-    assert value == ev
-    c.value = None
-    await a.write_value(None, ev)
-    assert a.value == v
+    string_read_value = await string_c.read_value(None)
+    assert string_read_value == string_value_bytes
+    c.value = b''
+    await string_c.write_value(None, string_value_bytes)
+    assert string_c.value == string_value
+
+    # 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
+    class_c = SerializableCharacteristicAdapter(c, BlaBla)
+
+    class_read_value = await class_c.read_value(None)
+    assert class_read_value == class_value_bytes
+    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
 
 
 # -----------------------------------------------------------------------------

tests/gmap_test.py

@@ -0,0 +1,84 @@
+# 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
+# -----------------------------------------------------------------------------
+import pytest
+import pytest_asyncio
+
+from bumble import device
+from bumble.profiles.gmap import (
+    GamingAudioService,
+    GamingAudioServiceProxy,
+    GmapRole,
+    UggFeatures,
+    UgtFeatures,
+    BgrFeatures,
+    BgsFeatures,
+)
+
+from .test_utils import TwoDevices
+
+# -----------------------------------------------------------------------------
+# Tests
+# -----------------------------------------------------------------------------
+gmas_service = GamingAudioService(
+    gmap_role=GmapRole.UNICAST_GAME_GATEWAY
+    | GmapRole.UNICAST_GAME_TERMINAL
+    | GmapRole.BROADCAST_GAME_RECEIVER
+    | GmapRole.BROADCAST_GAME_SENDER,
+    ugg_features=UggFeatures.UGG_MULTISINK,
+    ugt_features=UgtFeatures.UGT_SOURCE,
+    bgr_features=BgrFeatures.BGR_MULTISINK,
+    bgs_features=BgsFeatures.BGS_96_KBPS,
+)
+
+
+@pytest_asyncio.fixture
+async def gmap_client():
+    devices = TwoDevices()
+    devices[0].add_service(gmas_service)
+
+    await devices.setup_connection()
+
+    assert devices.connections[0]
+    assert devices.connections[1]
+
+    devices.connections[0].encryption = 1
+    devices.connections[1].encryption = 1
+
+    peer = device.Peer(devices.connections[1])
+
+    gmap_client = await peer.discover_service_and_create_proxy(GamingAudioServiceProxy)
+
+    assert gmap_client
+    yield gmap_client
+
+
+# -----------------------------------------------------------------------------
+@pytest.mark.asyncio
+async def test_init_service(gmap_client: GamingAudioServiceProxy):
+    assert (
+        await gmap_client.gmap_role.read_value()
+        == GmapRole.UNICAST_GAME_GATEWAY
+        | GmapRole.UNICAST_GAME_TERMINAL
+        | GmapRole.BROADCAST_GAME_RECEIVER
+        | GmapRole.BROADCAST_GAME_SENDER
+    )
+    assert await gmap_client.ugg_features.read_value() == UggFeatures.UGG_MULTISINK
+    assert await gmap_client.ugt_features.read_value() == UgtFeatures.UGT_SOURCE
+    assert await gmap_client.bgr_features.read_value() == BgrFeatures.BGR_MULTISINK
+    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,
 )
 
 
@@ -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/vocs_test.py

@@ -0,0 +1,184 @@
+# 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
+# -----------------------------------------------------------------------------
+import pytest
+import pytest_asyncio
+import struct
+
+from bumble import device
+
+from bumble.att import ATT_Error
+
+from bumble.profiles.vocs import (
+    VolumeOffsetControlService,
+    ErrorCode,
+    MIN_VOLUME_OFFSET,
+    MAX_VOLUME_OFFSET,
+    SetVolumeOffsetOpCode,
+    VolumeOffsetControlServiceProxy,
+    VolumeOffsetState,
+    VocsAudioLocation,
+)
+from bumble.profiles.vcp import VolumeControlService, VolumeControlServiceProxy
+from bumble.profiles.bap import AudioLocation
+
+from .test_utils import TwoDevices
+
+
+# -----------------------------------------------------------------------------
+# Tests
+# -----------------------------------------------------------------------------
+vocs_service = VolumeOffsetControlService()
+vcp_service = VolumeControlService(included_services=[vocs_service])
+
+
+@pytest_asyncio.fixture
+async def vocs_client():
+    devices = TwoDevices()
+    devices[0].add_service(vcp_service)
+
+    await devices.setup_connection()
+
+    assert devices.connections[0]
+    assert devices.connections[1]
+
+    devices.connections[0].encryption = 1
+    devices.connections[1].encryption = 1
+
+    peer = device.Peer(devices.connections[1])
+
+    vcp_client = await peer.discover_service_and_create_proxy(VolumeControlServiceProxy)
+
+    assert vcp_client
+    included_services = await peer.discover_included_services(vcp_client.service_proxy)
+    assert included_services
+    vocs_service_discovered = included_services[0]
+    await peer.discover_characteristics(service=vocs_service_discovered)
+    vocs_client = VolumeOffsetControlServiceProxy(vocs_service_discovered)
+
+    yield vocs_client
+
+
+# -----------------------------------------------------------------------------
+@pytest.mark.asyncio
+async def test_init_service(vocs_client: VolumeOffsetControlServiceProxy):
+    assert await vocs_client.volume_offset_state.read_value() == VolumeOffsetState(
+        volume_offset=0,
+        change_counter=0,
+    )
+    assert await vocs_client.audio_location.read_value() == VocsAudioLocation(
+        audio_location=AudioLocation.NOT_ALLOWED
+    )
+    description = await vocs_client.audio_output_description.read_value()
+    assert description == ''
+
+
+@pytest.mark.asyncio
+async def test_wrong_opcode_raise_error(vocs_client: VolumeOffsetControlServiceProxy):
+    with pytest.raises(ATT_Error) as e:
+        await vocs_client.volume_offset_control_point.write_value(
+            bytes(
+                [
+                    0xFF,
+                ]
+            ),
+            with_response=True,
+        )
+
+    assert e.value.error_code == ErrorCode.OPCODE_NOT_SUPPORTED
+
+
+@pytest.mark.asyncio
+async def test_wrong_change_counter_raise_error(
+    vocs_client: VolumeOffsetControlServiceProxy,
+):
+    initial_offset = vocs_service.volume_offset_state.volume_offset
+    initial_counter = vocs_service.volume_offset_state.change_counter
+    wrong_counter = initial_counter + 1
+
+    with pytest.raises(ATT_Error) as e:
+        await vocs_client.volume_offset_control_point.write_value(
+            struct.pack(
+                '<BBh', SetVolumeOffsetOpCode.SET_VOLUME_OFFSET, wrong_counter, 0
+            ),
+            with_response=True,
+        )
+    assert e.value.error_code == ErrorCode.INVALID_CHANGE_COUNTER
+
+    counter = await vocs_client.volume_offset_state.read_value()
+    assert counter == VolumeOffsetState(initial_offset, initial_counter)
+
+
+@pytest.mark.asyncio
+async def test_wrong_volume_offset_raise_error(
+    vocs_client: VolumeOffsetControlServiceProxy,
+):
+    invalid_offset_low = MIN_VOLUME_OFFSET - 1
+    invalid_offset_high = MAX_VOLUME_OFFSET + 1
+
+    with pytest.raises(ATT_Error) as e_low:
+        await vocs_client.volume_offset_control_point.write_value(
+            struct.pack(
+                '<BBh', SetVolumeOffsetOpCode.SET_VOLUME_OFFSET, 0, invalid_offset_low
+            ),
+            with_response=True,
+        )
+    assert e_low.value.error_code == ErrorCode.VALUE_OUT_OF_RANGE
+
+    with pytest.raises(ATT_Error) as e_high:
+        await vocs_client.volume_offset_control_point.write_value(
+            struct.pack(
+                '<BBh', SetVolumeOffsetOpCode.SET_VOLUME_OFFSET, 0, invalid_offset_high
+            ),
+            with_response=True,
+        )
+    assert e_high.value.error_code == ErrorCode.VALUE_OUT_OF_RANGE
+
+
+@pytest.mark.asyncio
+async def test_set_volume_offset(vocs_client: VolumeOffsetControlServiceProxy):
+    await vocs_client.volume_offset_control_point.write_value(
+        struct.pack('<BBh', SetVolumeOffsetOpCode.SET_VOLUME_OFFSET, 0, -255),
+    )
+    assert await vocs_client.volume_offset_state.read_value() == VolumeOffsetState(
+        -255, 1
+    )
+
+
+@pytest.mark.asyncio
+async def test_set_audio_channel_location(vocs_client: VolumeOffsetControlServiceProxy):
+    new_audio_location = VocsAudioLocation(audio_location=AudioLocation.FRONT_LEFT)
+
+    await vocs_client.audio_location.write_value(
+        struct.pack('<I', new_audio_location.audio_location)
+    )
+
+    location = await vocs_client.audio_location.read_value()
+    assert location == new_audio_location
+
+
+@pytest.mark.asyncio
+async def test_set_audio_output_description(
+    vocs_client: VolumeOffsetControlServiceProxy,
+):
+    new_description = 'Left Speaker'
+
+    await vocs_client.audio_output_description.write_value(new_description)
+
+    description = await vocs_client.audio_output_description.read_value()
+    assert description == new_description

tools/intel_fw_download.py

@@ -0,0 +1,130 @@
+# 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
+# -----------------------------------------------------------------------------
+import logging
+import pathlib
+import urllib.request
+import urllib.error
+
+import click
+
+from bumble.colors import color
+from bumble.drivers import intel
+
+
+# -----------------------------------------------------------------------------
+# Logging
+# -----------------------------------------------------------------------------
+logger = logging.getLogger(__name__)
+
+
+# -----------------------------------------------------------------------------
+# Constants
+# -----------------------------------------------------------------------------
+LINUX_KERNEL_GIT_SOURCE = "https://git.kernel.org/pub/scm/linux/kernel/git/firmware/linux-firmware.git/plain/intel"
+
+
+# -----------------------------------------------------------------------------
+# Functions
+# -----------------------------------------------------------------------------
+def download_file(base_url, name):
+    url = f"{base_url}/{name}"
+    with urllib.request.urlopen(url) as file:
+        data = file.read()
+        print(f"Downloaded {name}: {len(data)} bytes")
+        return data
+
+
+# -----------------------------------------------------------------------------
+@click.command
+@click.option(
+    "--output-dir",
+    default="",
+    help="Output directory where the files will be saved. Defaults to the OS-specific"
+    "app data dir, which the driver will check when trying to find firmware",
+    show_default=True,
+)
+@click.option(
+    "--source",
+    type=click.Choice(["linux-kernel"]),
+    default="linux-kernel",
+    show_default=True,
+)
+@click.option("--single", help="Only download a single image set, by its base name")
+@click.option("--force", is_flag=True, help="Overwrite files if they already exist")
+def main(output_dir, source, single, force):
+    """Download Intel firmware images and configs."""
+
+    # Check that the output dir exists
+    if output_dir == '':
+        output_dir = intel.intel_firmware_dir()
+    else:
+        output_dir = pathlib.Path(output_dir)
+    if not output_dir.is_dir():
+        print("Output dir does not exist or is not a directory")
+        return
+
+    base_url = {
+        "linux-kernel": LINUX_KERNEL_GIT_SOURCE,
+    }[source]
+
+    print("Downloading")
+    print(color("FROM:", "green"), base_url)
+    print(color("TO:", "green"), output_dir)
+
+    if single:
+        images = [(f"{single}.sfi", f"{single}.ddc")]
+    else:
+        images = [
+            (f"{base_name}.sfi", f"{base_name}.ddc")
+            for base_name in intel.INTEL_FW_IMAGE_NAMES
+        ]
+
+    for fw_name, config_name in images:
+        print(color("---", "yellow"))
+        fw_image_out = output_dir / fw_name
+        if not force and fw_image_out.exists():
+            print(color(f"{fw_image_out} already exists, skipping", "red"))
+            continue
+        if config_name:
+            config_image_out = output_dir / config_name
+            if not force and config_image_out.exists():
+                print(color("f{config_image_out} already exists, skipping", "red"))
+                continue
+
+        try:
+            fw_image = download_file(base_url, fw_name)
+        except urllib.error.HTTPError as error:
+            print(f"Failed to download {fw_name}: {error}")
+            continue
+
+        config_image = None
+        if config_name:
+            try:
+                config_image = download_file(base_url, config_name)
+            except urllib.error.HTTPError as error:
+                print(f"Failed to download {config_name}: {error}")
+                continue
+
+        fw_image_out.write_bytes(fw_image)
+        if config_image:
+            config_image_out.write_bytes(config_image)
+
+
+# -----------------------------------------------------------------------------
+if __name__ == '__main__':
+    main()

tools/intel_util.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
+# -----------------------------------------------------------------------------
+import logging
+import asyncio
+import os
+from typing import Any, Optional
+
+import click
+
+from bumble.colors import color
+from bumble import transport
+from bumble.drivers import intel
+from bumble.host import Host
+
+# -----------------------------------------------------------------------------
+# Logging
+# -----------------------------------------------------------------------------
+logger = logging.getLogger(__name__)
+
+
+# -----------------------------------------------------------------------------
+def print_device_info(device_info: dict[intel.ValueType, Any]) -> None:
+    if (mode := device_info.get(intel.ValueType.CURRENT_MODE_OF_OPERATION)) is not None:
+        print(
+            color("MODE:", "yellow"),
+            mode.name,
+        )
+    print(color("DETAILS:", "yellow"))
+    for key, value in device_info.items():
+        print(f"  {color(key.name, 'green')}: {value}")
+
+
+# -----------------------------------------------------------------------------
+async def get_driver(host: Host, force: bool) -> Optional[intel.Driver]:
+    # Create a driver
+    driver = await intel.Driver.for_host(host, force)
+    if driver is None:
+        print("Device does not appear to be an Intel device")
+        return None
+
+    return driver
+
+
+# -----------------------------------------------------------------------------
+async def do_info(usb_transport, force):
+    async with await transport.open_transport(usb_transport) as (
+        hci_source,
+        hci_sink,
+    ):
+        host = Host(hci_source, hci_sink)
+        driver = await get_driver(host, force)
+        if driver is None:
+            return
+
+        # Get and print the device info
+        print_device_info(await driver.read_device_info())
+
+
+# -----------------------------------------------------------------------------
+async def do_load(usb_transport: str, force: bool) -> None:
+    async with await transport.open_transport(usb_transport) as (
+        hci_source,
+        hci_sink,
+    ):
+        host = Host(hci_source, hci_sink)
+        driver = await get_driver(host, force)
+        if driver is None:
+            return
+
+        # Reboot in bootloader mode
+        await driver.load_firmware()
+
+        # Get and print the device info
+        print_device_info(await driver.read_device_info())
+
+
+# -----------------------------------------------------------------------------
+async def do_bootloader(usb_transport: str, force: bool) -> None:
+    async with await transport.open_transport(usb_transport) as (
+        hci_source,
+        hci_sink,
+    ):
+        host = Host(hci_source, hci_sink)
+        driver = await get_driver(host, force)
+        if driver is None:
+            return
+
+        # Reboot in bootloader mode
+        await driver.reboot_bootloader()
+
+
+# -----------------------------------------------------------------------------
+@click.group()
+def main():
+    logging.basicConfig(level=os.environ.get('BUMBLE_LOGLEVEL', 'INFO').upper())
+
+
+@main.command
+@click.argument("usb_transport")
+@click.option(
+    "--force",
+    is_flag=True,
+    default=False,
+    help="Try to get the device info even if the USB info doesn't match",
+)
+def info(usb_transport, force):
+    """Get the firmware info."""
+    asyncio.run(do_info(usb_transport, force))
+
+
+@main.command
+@click.argument("usb_transport")
+@click.option(
+    "--force",
+    is_flag=True,
+    default=False,
+    help="Load even if the USB info doesn't match",
+)
+def load(usb_transport, force):
+    """Load a firmware image."""
+    asyncio.run(do_load(usb_transport, force))
+
+
+@main.command
+@click.argument("usb_transport")
+@click.option(
+    "--force",
+    is_flag=True,
+    default=False,
+    help="Attempt to reboot event if the USB info doesn't match",
+)
+def bootloader(usb_transport, force):
+    """Reboot in bootloader mode."""
+    asyncio.run(do_bootloader(usb_transport, force))
+
+
+# -----------------------------------------------------------------------------
+if __name__ == '__main__':
+    main()