Create inv web.build

This command will build a wheel, copy it in the web directory, and create a file `packageFile` with the name of the wheel. If the correct override param is given, bumble.js will read `packageFile` and load that package.

.github/workflows/code-check.yml

@@ -16,7 +16,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.8", "3.9", "3.10", "3.11"]
+        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
       fail-fast: false
 
     steps:
@@ -29,11 +29,11 @@ jobs:
     - name: Set up Python
       uses: actions/setup-python@v3
       with:
-        python-version: '3.10'
+        python-version: ${{ matrix.python-version }}
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
-        python -m pip install ".[build,test,development]"
+        python -m pip install ".[build,test,development,pandora]"
     - 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]
+          python -m pip install .[avatar,pandora]
       - name: Rootcanal
         run: nohup python -m rootcanal > rootcanal.log &
       - name: Test

.github/workflows/python-build-test.yml

@@ -16,7 +16,7 @@ jobs:
     strategy:
       matrix:
         os: ['ubuntu-latest', 'macos-latest', 'windows-latest']
-        python-version: ["3.8", "3.9", "3.10", "3.11"]
+        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
       fail-fast: false
 
     steps:
@@ -46,8 +46,8 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: [ "3.8", "3.9", "3.10", "3.11" ]
-        rust-version: [ "1.70.0", "stable" ]
+        python-version: [ "3.8", "3.9", "3.10", "3.11", "3.12" ]
+        rust-version: [ "1.76.0", "stable" ]
       fail-fast: false
     steps:
       - name: Check out from Git

.gitignore

@@ -6,7 +6,14 @@ dist/
 docs/mkdocs/site
 test-results.xml
 __pycache__
+# Vim
+.*.sw*
 # generated by setuptools_scm
 bumble/_version.py
 .vscode/launch.json
+.vscode/settings.json
 /.idea
+venv/
+.venv/
+# snoop logs
+out/

.vscode/settings.json

@@ -1,6 +1,7 @@
 {
     "cSpell.words": [
         "Abortable",
+        "aiohttp",
         "altsetting",
         "ansiblue",
         "ansicyan",
@@ -9,10 +10,13 @@
         "ansired",
         "ansiyellow",
         "appendleft",
+        "ascs",
         "ASHA",
         "asyncio",
         "ATRAC",
+        "avctp",
         "avdtp",
+        "avrcp",
         "bitpool",
         "bitstruct",
         "BSCP",
@@ -22,6 +26,7 @@
         "cmac",
         "CONNECTIONLESS",
         "csip",
+        "csis",
         "csrcs",
         "CVSD",
         "datagram",
@@ -32,6 +37,7 @@
         "dhkey",
         "diversifier",
         "endianness",
+        "ESCO",
         "Fitbit",
         "GATTLINK",
         "HANDSFREE",
@@ -39,6 +45,7 @@
         "keyup",
         "levelname",
         "libc",
+        "liblc",
         "libusb",
         "MITM",
         "MSBC",
@@ -70,8 +77,11 @@
         "substates",
         "tobytes",
         "tsep",
+        "UNMUTE",
+        "unmuted",
         "usbmodem",
         "vhci",
+        "wasmtime",
         "websockets",
         "xcursor",
         "ycursor"

apps/auracast.py

@@ -0,0 +1,407 @@
+# 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
+from typing import cast, Dict, Optional, Tuple
+
+import click
+import pyee
+
+from bumble.colors import color
+import bumble.company_ids
+import bumble.core
+import bumble.device
+import bumble.gatt
+import bumble.hci
+import bumble.profiles.bap
+import bumble.profiles.pbp
+import bumble.transport
+import bumble.utils
+
+
+# -----------------------------------------------------------------------------
+# Logging
+# -----------------------------------------------------------------------------
+logger = logging.getLogger(__name__)
+
+
+# -----------------------------------------------------------------------------
+# Constants
+# -----------------------------------------------------------------------------
+AURACAST_DEFAULT_DEVICE_NAME = "Bumble Auracast"
+AURACAST_DEFAULT_DEVICE_ADDRESS = bumble.hci.Address("F0:F1:F2:F3:F4:F5")
+
+
+# -----------------------------------------------------------------------------
+# Discover Broadcasts
+# -----------------------------------------------------------------------------
+class BroadcastDiscoverer:
+    @dataclasses.dataclass
+    class Broadcast(pyee.EventEmitter):
+        name: str
+        sync: bumble.device.PeriodicAdvertisingSync
+        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
+        biginfo: Optional[bumble.device.BIGInfoAdvertisement] = None
+        manufacturer_data: Optional[Tuple[str, bytes]] = None
+
+        def __post_init__(self) -> None:
+            super().__init__()
+            self.sync.on('establishment', self.on_sync_establishment)
+            self.sync.on('loss', self.on_sync_loss)
+            self.sync.on('periodic_advertisement', self.on_periodic_advertisement)
+            self.sync.on('biginfo_advertisement', self.on_biginfo_advertisement)
+
+            self.establishment_timeout_task = asyncio.create_task(
+                self.wait_for_establishment()
+            )
+
+        async def wait_for_establishment(self) -> None:
+            await asyncio.sleep(5.0)
+            if self.sync.state == bumble.device.PeriodicAdvertisingSync.State.PENDING:
+                print(
+                    color(
+                        '!!! Periodic advertisement sync not established in time, '
+                        'canceling',
+                        'red',
+                    )
+                )
+                await self.sync.terminate()
+
+        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
+            ):
+                assert isinstance(service_data, tuple)
+                service_uuid, data = service_data
+                assert isinstance(data, bytes)
+
+                if (
+                    service_uuid
+                    == bumble.gatt.GATT_PUBLIC_BROADCAST_ANNOUNCEMENT_SERVICE
+                ):
+                    self.public_broadcast_announcement = (
+                        bumble.profiles.pbp.PublicBroadcastAnnouncement.from_bytes(data)
+                    )
+                    continue
+
+                if (
+                    service_uuid
+                    == bumble.gatt.GATT_BROADCAST_AUDIO_ANNOUNCEMENT_SERVICE
+                ):
+                    self.broadcast_audio_announcement = (
+                        bumble.profiles.bap.BroadcastAudioAnnouncement.from_bytes(data)
+                    )
+                    continue
+
+            self.appearance = advertisement.data.get(  # type: ignore[assignment]
+                bumble.core.AdvertisingData.APPEARANCE
+            )
+
+            if manufacturer_data := advertisement.data.get(
+                bumble.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_id, f'0x{company_id:04X}'
+                    ),
+                    data,
+                )
+
+        def print(self) -> None:
+            print(
+                color('Broadcast:', 'yellow'),
+                self.sync.advertiser_address,
+                color(self.sync.state.name, 'green'),
+            )
+            print(f'  {color("Name", "cyan")}:         {self.name}')
+            if self.appearance:
+                print(f'  {color("Appearance", "cyan")}:   {str(self.appearance)}')
+            print(f'  {color("RSSI", "cyan")}:         {self.rssi}')
+            print(f'  {color("SID", "cyan")}:          {self.sync.sid}')
+
+            if self.manufacturer_data:
+                print(
+                    f'  {color("Manufacturer Data", "cyan")}: '
+                    f'{self.manufacturer_data[0]} -> {self.manufacturer_data[1].hex()}'
+                )
+
+            if self.broadcast_audio_announcement:
+                print(
+                    f'  {color("Broadcast ID", "cyan")}: '
+                    f'{self.broadcast_audio_announcement.broadcast_id}'
+                )
+
+            if self.public_broadcast_announcement:
+                print(
+                    f'  {color("Features", "cyan")}:     '
+                    f'{self.public_broadcast_announcement.features}'
+                )
+                print(
+                    f'  {color("Metadata", "cyan")}:     '
+                    f'{self.public_broadcast_announcement.metadata}'
+                )
+
+            if self.basic_audio_announcement:
+                print(color('  Audio:', 'cyan'))
+                print(
+                    color('    Presentation Delay:', 'magenta'),
+                    self.basic_audio_announcement.presentation_delay,
+                )
+                for subgroup in self.basic_audio_announcement.subgroups:
+                    print(color('    Subgroup:', 'magenta'))
+                    print(color('      Codec ID:', 'yellow'))
+                    print(
+                        color('        Coding Format:           ', 'green'),
+                        subgroup.codec_id.coding_format.name,
+                    )
+                    print(
+                        color('        Company ID:              ', 'green'),
+                        subgroup.codec_id.company_id,
+                    )
+                    print(
+                        color('        Vendor Specific Codec ID:', 'green'),
+                        subgroup.codec_id.vendor_specific_codec_id,
+                    )
+                    print(
+                        color('      Codec Config:', 'yellow'),
+                        subgroup.codec_specific_configuration,
+                    )
+                    print(color('      Metadata:    ', 'yellow'), subgroup.metadata)
+
+                    for bis in subgroup.bis:
+                        print(color(f'      BIS [{bis.index}]:', 'yellow'))
+                        print(
+                            color('       Codec Config:', 'green'),
+                            bis.codec_specific_configuration,
+                        )
+
+            if self.biginfo:
+                print(color('  BIG:', 'cyan'))
+                print(
+                    color('    Number of BIS:', 'magenta'),
+                    self.biginfo.num_bis,
+                )
+                print(
+                    color('    PHY:          ', 'magenta'),
+                    self.biginfo.phy.name,
+                )
+                print(
+                    color('    Framed:       ', 'magenta'),
+                    self.biginfo.framed,
+                )
+                print(
+                    color('    Encrypted:    ', 'magenta'),
+                    self.biginfo.encrypted,
+                )
+
+        def on_sync_establishment(self) -> None:
+            self.establishment_timeout_task.cancel()
+            self.emit('change')
+
+        def on_sync_loss(self) -> None:
+            self.basic_audio_announcement = None
+            self.biginfo = None
+            self.emit('change')
+
+        def on_periodic_advertisement(
+            self, advertisement: bumble.device.PeriodicAdvertisement
+        ) -> None:
+            if advertisement.data is None:
+                return
+
+            for service_data in advertisement.data.get_all(
+                bumble.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:
+                    self.basic_audio_announcement = (
+                        bumble.profiles.bap.BasicAudioAnnouncement.from_bytes(data)
+                    )
+                    break
+
+            self.emit('change')
+
+        def on_biginfo_advertisement(
+            self, advertisement: bumble.device.BIGInfoAdvertisement
+        ) -> None:
+            self.biginfo = advertisement
+            self.emit('change')
+
+    def __init__(
+        self,
+        device: bumble.device.Device,
+        filter_duplicates: bool,
+        sync_timeout: float,
+    ):
+        self.device = device
+        self.filter_duplicates = filter_duplicates
+        self.sync_timeout = sync_timeout
+        self.broadcasts: Dict[bumble.hci.Address, BroadcastDiscoverer.Broadcast] = {}
+        self.status_message = ''
+        device.on('advertisement', self.on_advertisement)
+
+    async def run(self) -> None:
+        self.status_message = color('Scanning...', 'green')
+        await self.device.start_scanning(
+            active=False,
+            filter_duplicates=False,
+        )
+
+    def refresh(self) -> None:
+        # Clear the screen from the top
+        print('\033[H')
+        print('\033[0J')
+        print('\033[H')
+
+        # Print the status message
+        print(self.status_message)
+        print("==========================================")
+
+        # Print all broadcasts
+        for broadcast in self.broadcasts.values():
+            broadcast.print()
+            print('------------------------------------------')
+
+        # Clear the screen to the bottom
+        print('\033[0J')
+
+    def on_advertisement(self, advertisement: bumble.device.Advertisement) -> None:
+        if (
+            broadcast_name := advertisement.data.get(
+                bumble.core.AdvertisingData.BROADCAST_NAME
+            )
+        ) is None:
+            return
+        assert isinstance(broadcast_name, str)
+
+        if broadcast := self.broadcasts.get(advertisement.address):
+            broadcast.update(advertisement)
+            self.refresh()
+            return
+
+        bumble.utils.AsyncRunner.spawn(
+            self.on_new_broadcast(broadcast_name, advertisement)
+        )
+
+    async def on_new_broadcast(
+        self, name: str, advertisement: bumble.device.Advertisement
+    ) -> None:
+        periodic_advertising_sync = await self.device.create_periodic_advertising_sync(
+            advertiser_address=advertisement.address,
+            sid=advertisement.sid,
+            sync_timeout=self.sync_timeout,
+            filter_duplicates=self.filter_duplicates,
+        )
+        broadcast = self.Broadcast(
+            name,
+            periodic_advertising_sync,
+        )
+        broadcast.on('change', self.refresh)
+        broadcast.update(advertisement)
+        self.broadcasts[advertisement.address] = broadcast
+        periodic_advertising_sync.on('loss', lambda: self.on_broadcast_loss(broadcast))
+        self.status_message = color(
+            f'+Found {len(self.broadcasts)} broadcasts', 'green'
+        )
+        self.refresh()
+
+    def on_broadcast_loss(self, broadcast: Broadcast) -> None:
+        del self.broadcasts[broadcast.sync.advertiser_address]
+        bumble.utils.AsyncRunner.spawn(broadcast.sync.terminate())
+        self.status_message = color(
+            f'-Found {len(self.broadcasts)} broadcasts', 'green'
+        )
+        self.refresh()
+
+
+async def run_discover_broadcasts(
+    filter_duplicates: bool, sync_timeout: float, transport: str
+) -> None:
+    async with await bumble.transport.open_transport(transport) as (
+        hci_source,
+        hci_sink,
+    ):
+        device = bumble.device.Device.with_hci(
+            AURACAST_DEFAULT_DEVICE_NAME,
+            AURACAST_DEFAULT_DEVICE_ADDRESS,
+            hci_source,
+            hci_sink,
+        )
+        await device.power_on()
+        discoverer = BroadcastDiscoverer(device, filter_duplicates, sync_timeout)
+        await discoverer.run()
+        await hci_source.terminated
+
+
+# -----------------------------------------------------------------------------
+# Main
+# -----------------------------------------------------------------------------
+@click.group()
+@click.pass_context
+def auracast(
+    ctx,
+):
+    ctx.ensure_object(dict)
+
+
+@auracast.command('discover-broadcasts')
+@click.option(
+    '--filter-duplicates', is_flag=True, default=False, help='Filter duplicates'
+)
+@click.option(
+    '--sync-timeout',
+    metavar='SYNC_TIMEOUT',
+    type=float,
+    default=5.0,
+    help='Sync timeout (in seconds)',
+)
+@click.argument('transport')
+@click.pass_context
+def discover_broadcasts(ctx, filter_duplicates, sync_timeout, transport):
+    """Discover public broadcasts"""
+    asyncio.run(run_discover_broadcasts(filter_duplicates, sync_timeout, transport))
+
+
+def main():
+    logging.basicConfig(level=os.environ.get('BUMBLE_LOGLEVEL', 'INFO').upper())
+    auracast()
+
+
+# -----------------------------------------------------------------------------
+if __name__ == "__main__":
+    main()  # pylint: disable=no-value-for-parameter

apps/ble_rpa_tool.py

@@ -0,0 +1,63 @@
+# Copyright 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.
+
+import click
+from bumble.colors import color
+from bumble.hci import Address
+from bumble.helpers import generate_irk, verify_rpa_with_irk
+
+
+@click.group()
+def cli():
+    '''
+    This is a tool for generating IRK, RPA,
+    and verifying IRK/RPA pairs
+    '''
+
+
+@click.command()
+def gen_irk() -> None:
+    print(generate_irk().hex())
+
+
+@click.command()
+@click.argument("irk", type=str)
+def gen_rpa(irk: str) -> None:
+    irk_bytes = bytes.fromhex(irk)
+    rpa = Address.generate_private_address(irk_bytes)
+    print(rpa.to_string(with_type_qualifier=False))
+
+
+@click.command()
+@click.argument("irk", type=str)
+@click.argument("rpa", type=str)
+def verify_rpa(irk: str, rpa: str) -> None:
+    address = Address(rpa)
+    irk_bytes = bytes.fromhex(irk)
+    if verify_rpa_with_irk(address, irk_bytes):
+        print(color("Verified", "green"))
+    else:
+        print(color("Not Verified", "red"))
+
+
+def main():
+    cli.add_command(gen_irk)
+    cli.add_command(gen_rpa)
+    cli.add_command(verify_rpa)
+    cli()
+
+
+# -----------------------------------------------------------------------------
+if __name__ == '__main__':
+    main()

apps/console.py

@@ -777,7 +777,7 @@ class ConsoleApp:
                 if not service:
                     continue
                 values = [
-                    attribute.read_value(connection)
+                    await attribute.read_value(connection)
                     for connection in self.device.connections.values()
                 ]
                 if not values:
@@ -796,11 +796,11 @@ class ConsoleApp:
                 if not characteristic:
                     continue
                 values = [
-                    attribute.read_value(connection)
+                    await attribute.read_value(connection)
                     for connection in self.device.connections.values()
                 ]
                 if not values:
-                    values = [attribute.read_value(None)]
+                    values = [await attribute.read_value(None)]
 
                 # TODO: future optimization: convert CCCD value to human readable string
 
@@ -944,7 +944,7 @@ class ConsoleApp:
 
         # send data to any subscribers
         if isinstance(attribute, Characteristic):
-            attribute.write_value(None, value)
+            await attribute.write_value(None, value)
             if attribute.has_properties(Characteristic.NOTIFY):
                 await self.device.gatt_server.notify_subscribers(attribute)
             if attribute.has_properties(Characteristic.INDICATE):

apps/controller_info.py

@@ -18,24 +18,30 @@
 import asyncio
 import os
 import logging
-import click
-from bumble.company_ids import COMPANY_IDENTIFIERS
+import time
 
+import click
+
+from bumble.company_ids import COMPANY_IDENTIFIERS
 from bumble.colors import color
 from bumble.core import name_or_number
 from bumble.hci import (
     map_null_terminated_utf8_string,
+    LeFeature,
     HCI_SUCCESS,
-    HCI_LE_SUPPORTED_FEATURES_NAMES,
     HCI_VERSION_NAMES,
     LMP_VERSION_NAMES,
     HCI_Command,
     HCI_Command_Complete_Event,
     HCI_Command_Status_Event,
+    HCI_READ_BUFFER_SIZE_COMMAND,
+    HCI_Read_Buffer_Size_Command,
     HCI_READ_BD_ADDR_COMMAND,
     HCI_Read_BD_ADDR_Command,
     HCI_READ_LOCAL_NAME_COMMAND,
     HCI_Read_Local_Name_Command,
+    HCI_LE_READ_BUFFER_SIZE_COMMAND,
+    HCI_LE_Read_Buffer_Size_Command,
     HCI_LE_READ_MAXIMUM_DATA_LENGTH_COMMAND,
     HCI_LE_Read_Maximum_Data_Length_Command,
     HCI_LE_READ_NUMBER_OF_SUPPORTED_ADVERTISING_SETS_COMMAND,
@@ -44,6 +50,7 @@ from bumble.hci import (
     HCI_LE_Read_Maximum_Advertising_Data_Length_Command,
     HCI_LE_READ_SUGGESTED_DEFAULT_DATA_LENGTH_COMMAND,
     HCI_LE_Read_Suggested_Default_Data_Length_Command,
+    HCI_Read_Local_Version_Information_Command,
 )
 from bumble.host import Host
 from bumble.transport import open_transport_or_link
@@ -59,7 +66,7 @@ def command_succeeded(response):
 
 
 # -----------------------------------------------------------------------------
-async def get_classic_info(host):
+async def get_classic_info(host: Host) -> None:
     if host.supports_command(HCI_READ_BD_ADDR_COMMAND):
         response = await host.send_command(HCI_Read_BD_ADDR_Command())
         if command_succeeded(response):
@@ -80,7 +87,7 @@ async def get_classic_info(host):
 
 
 # -----------------------------------------------------------------------------
-async def get_le_info(host):
+async def get_le_info(host: Host) -> None:
     print()
 
     if host.supports_command(HCI_LE_READ_NUMBER_OF_SUPPORTED_ADVERTISING_SETS_COMMAND):
@@ -133,11 +140,36 @@ async def get_le_info(host):
 
     print(color('LE Features:', 'yellow'))
     for feature in host.supported_le_features:
-        print('  ', name_or_number(HCI_LE_SUPPORTED_FEATURES_NAMES, feature))
+        print(f'  {LeFeature(feature).name}')
 
 
 # -----------------------------------------------------------------------------
-async def async_main(transport):
+async def get_acl_flow_control_info(host: Host) -> None:
+    print()
+
+    if host.supports_command(HCI_READ_BUFFER_SIZE_COMMAND):
+        response = await host.send_command(
+            HCI_Read_Buffer_Size_Command(), check_result=True
+        )
+        print(
+            color('ACL Flow Control:', 'yellow'),
+            f'{response.return_parameters.hc_total_num_acl_data_packets} '
+            f'packets of size {response.return_parameters.hc_acl_data_packet_length}',
+        )
+
+    if host.supports_command(HCI_LE_READ_BUFFER_SIZE_COMMAND):
+        response = await host.send_command(
+            HCI_LE_Read_Buffer_Size_Command(), check_result=True
+        )
+        print(
+            color('LE ACL Flow Control:', 'yellow'),
+            f'{response.return_parameters.hc_total_num_le_acl_data_packets} '
+            f'packets of size {response.return_parameters.hc_le_acl_data_packet_length}',
+        )
+
+
+# -----------------------------------------------------------------------------
+async def async_main(latency_probes, transport):
     print('<<< connecting to HCI...')
     async with await open_transport_or_link(transport) as (hci_source, hci_sink):
         print('<<< connected')
@@ -145,6 +177,23 @@ async def async_main(transport):
         host = Host(hci_source, hci_sink)
         await host.reset()
 
+        # Measure the latency if requested
+        latencies = []
+        if latency_probes:
+            for _ in range(latency_probes):
+                start = time.time()
+                await host.send_command(HCI_Read_Local_Version_Information_Command())
+                latencies.append(1000 * (time.time() - start))
+            print(
+                color('HCI Command Latency:', 'yellow'),
+                (
+                    f'min={min(latencies):.2f}, '
+                    f'max={max(latencies):.2f}, '
+                    f'average={sum(latencies)/len(latencies):.2f}'
+                ),
+                '\n',
+            )
+
         # Print version
         print(color('Version:', 'yellow'))
         print(
@@ -168,19 +217,28 @@ async def async_main(transport):
         # Get the LE info
         await get_le_info(host)
 
+        # Print the ACL flow control info
+        await get_acl_flow_control_info(host)
+
         # Print the list of commands supported by the controller
         print()
         print(color('Supported Commands:', 'yellow'))
         for command in host.supported_commands:
-            print('  ', HCI_Command.command_name(command))
+            print(f'  {HCI_Command.command_name(command)}')
 
 
 # -----------------------------------------------------------------------------
 @click.command()
+@click.option(
+    '--latency-probes',
+    metavar='N',
+    type=int,
+    help='Send N commands to measure HCI transport latency statistics',
+)
 @click.argument('transport')
-def main(transport):
+def main(latency_probes, transport):
     logging.basicConfig(level=os.environ.get('BUMBLE_LOGLEVEL', 'WARNING').upper())
-    asyncio.run(async_main(transport))
+    asyncio.run(async_main(latency_probes, transport))
 
 
 # -----------------------------------------------------------------------------

apps/controller_loopback.py

@@ -0,0 +1,205 @@
+# 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 asyncio
+import logging
+import os
+import time
+from typing import Optional
+from bumble.colors import color
+from bumble.hci import (
+    HCI_READ_LOOPBACK_MODE_COMMAND,
+    HCI_Read_Loopback_Mode_Command,
+    HCI_WRITE_LOOPBACK_MODE_COMMAND,
+    HCI_Write_Loopback_Mode_Command,
+    LoopbackMode,
+)
+from bumble.host import Host
+from bumble.transport import open_transport_or_link
+import click
+
+
+class Loopback:
+    """Send and receive ACL data packets in local loopback mode"""
+
+    def __init__(self, packet_size: int, packet_count: int, transport: str):
+        self.transport = transport
+        self.packet_size = packet_size
+        self.packet_count = packet_count
+        self.connection_handle: Optional[int] = None
+        self.connection_event = asyncio.Event()
+        self.done = asyncio.Event()
+        self.expected_cid = 0
+        self.bytes_received = 0
+        self.start_timestamp = 0.0
+        self.last_timestamp = 0.0
+
+    def on_connection(self, connection_handle: int, *args):
+        """Retrieve connection handle from new connection event"""
+        if not self.connection_event.is_set():
+            # save first connection handle for ACL
+            # subsequent connections are SCO
+            self.connection_handle = connection_handle
+            self.connection_event.set()
+
+    def on_l2cap_pdu(self, connection_handle: int, cid: int, pdu: bytes):
+        """Calculate packet receive speed"""
+        now = time.time()
+        print(f'<<< Received packet {cid}: {len(pdu)} bytes')
+        assert connection_handle == self.connection_handle
+        assert cid == self.expected_cid
+        self.expected_cid += 1
+        if cid == 0:
+            self.start_timestamp = now
+        else:
+            elapsed_since_start = now - self.start_timestamp
+            elapsed_since_last = now - self.last_timestamp
+            self.bytes_received += len(pdu)
+            instant_rx_speed = len(pdu) / elapsed_since_last
+            average_rx_speed = self.bytes_received / elapsed_since_start
+            print(
+                color(
+                    f'@@@ RX speed: instant={instant_rx_speed:.4f},'
+                    f' average={average_rx_speed:.4f}',
+                    'cyan',
+                )
+            )
+
+        self.last_timestamp = now
+
+        if self.expected_cid == self.packet_count:
+            print(color('@@@ Received last packet', 'green'))
+            self.done.set()
+
+    async def run(self):
+        """Run a loopback throughput test"""
+        print(color('>>> Connecting to HCI...', 'green'))
+        async with await open_transport_or_link(self.transport) as (
+            hci_source,
+            hci_sink,
+        ):
+            print(color('>>> Connected', 'green'))
+
+            host = Host(hci_source, hci_sink)
+            await host.reset()
+
+            # make sure data can fit in one l2cap pdu
+            l2cap_header_size = 4
+
+            max_packet_size = (
+                host.acl_packet_queue
+                if host.acl_packet_queue
+                else host.le_acl_packet_queue
+            ).max_packet_size - l2cap_header_size
+            if self.packet_size > max_packet_size:
+                print(
+                    color(
+                        f'!!! Packet size ({self.packet_size}) larger than max supported'
+                        f' size ({max_packet_size})',
+                        'red',
+                    )
+                )
+                return
+
+            if not host.supports_command(
+                HCI_WRITE_LOOPBACK_MODE_COMMAND
+            ) or not host.supports_command(HCI_READ_LOOPBACK_MODE_COMMAND):
+                print(color('!!! Loopback mode not supported', 'red'))
+                return
+
+            # set event callbacks
+            host.on('connection', self.on_connection)
+            host.on('l2cap_pdu', self.on_l2cap_pdu)
+
+            loopback_mode = LoopbackMode.LOCAL
+
+            print(color('### Setting loopback mode', 'blue'))
+            await host.send_command(
+                HCI_Write_Loopback_Mode_Command(loopback_mode=LoopbackMode.LOCAL),
+                check_result=True,
+            )
+
+            print(color('### Checking loopback mode', 'blue'))
+            response = await host.send_command(
+                HCI_Read_Loopback_Mode_Command(), check_result=True
+            )
+            if response.return_parameters.loopback_mode != loopback_mode:
+                print(color('!!! Loopback mode mismatch', 'red'))
+                return
+
+            await self.connection_event.wait()
+            print(color('### Connected', 'cyan'))
+
+            print(color('=== Start sending', 'magenta'))
+            start_time = time.time()
+            bytes_sent = 0
+            for cid in range(0, self.packet_count):
+                # using the cid as an incremental index
+                host.send_l2cap_pdu(
+                    self.connection_handle, cid, bytes(self.packet_size)
+                )
+                print(
+                    color(
+                        f'>>> Sending packet {cid}: {self.packet_size} bytes', 'yellow'
+                    )
+                )
+                bytes_sent += self.packet_size  # don't count L2CAP or HCI header sizes
+                await asyncio.sleep(0)  # yield to allow packet receive
+
+            await self.done.wait()
+            print(color('=== Done!', 'magenta'))
+
+            elapsed = time.time() - start_time
+            average_tx_speed = bytes_sent / elapsed
+            print(
+                color(
+                    f'@@@ TX speed: average={average_tx_speed:.4f} ({bytes_sent} bytes'
+                    f' in {elapsed:.2f} seconds)',
+                    'green',
+                )
+            )
+
+
+# -----------------------------------------------------------------------------
+@click.command()
+@click.option(
+    '--packet-size',
+    '-s',
+    metavar='SIZE',
+    type=click.IntRange(8, 4096),
+    default=500,
+    help='Packet size',
+)
+@click.option(
+    '--packet-count',
+    '-c',
+    metavar='COUNT',
+    type=click.IntRange(1, 65535),
+    default=10,
+    help='Packet count',
+)
+@click.argument('transport')
+def main(packet_size, packet_count, transport):
+    logging.basicConfig(level=os.environ.get('BUMBLE_LOGLEVEL', 'WARNING').upper())
+
+    loopback = Loopback(packet_size, packet_count, transport)
+    asyncio.run(loopback.run())
+
+
+# -----------------------------------------------------------------------------
+if __name__ == '__main__':
+    main()

apps/l2cap_bridge.py

@@ -49,14 +49,16 @@ class ServerBridge:
         self.tcp_port = tcp_port
 
     async def start(self, device: Device) -> None:
-        # Listen for incoming L2CAP CoC connections
+        # Listen for incoming L2CAP channel connections
         device.create_l2cap_server(
             spec=l2cap.LeCreditBasedChannelSpec(
                 psm=self.psm, mtu=self.mtu, mps=self.mps, max_credits=self.max_credits
             ),
-            handler=self.on_coc,
+            handler=self.on_channel,
+        )
+        print(
+            color(f'### Listening for channel connection on PSM {self.psm}', 'yellow')
         )
-        print(color(f'### Listening for CoC connection on PSM {self.psm}', 'yellow'))
 
         def on_ble_connection(connection):
             def on_ble_disconnection(reason):
@@ -73,7 +75,7 @@ class ServerBridge:
         await device.start_advertising(auto_restart=True)
 
     # Called when a new L2CAP connection is established
-    def on_coc(self, l2cap_channel):
+    def on_channel(self, l2cap_channel):
         print(color('*** L2CAP channel:', 'cyan'), l2cap_channel)
 
         class Pipe:
@@ -83,7 +85,7 @@ class ServerBridge:
                 self.l2cap_channel = l2cap_channel
 
                 l2cap_channel.on('close', self.on_l2cap_close)
-                l2cap_channel.sink = self.on_coc_sdu
+                l2cap_channel.sink = self.on_channel_sdu
 
             async def connect_to_tcp(self):
                 # Connect to the TCP server
@@ -128,7 +130,7 @@ class ServerBridge:
                 if self.tcp_transport is not None:
                     self.tcp_transport.close()
 
-            def on_coc_sdu(self, sdu):
+            def on_channel_sdu(self, sdu):
                 print(color(f'<<< [L2CAP SDU]: {len(sdu)} bytes', 'cyan'))
                 if self.tcp_transport is None:
                     print(color('!!! TCP socket not open, dropping', 'red'))
@@ -183,7 +185,7 @@ class ClientBridge:
             peer_name = writer.get_extra_info('peer_name')
             print(color(f'<<< TCP connection from {peer_name}', 'magenta'))
 
-            def on_coc_sdu(sdu):
+            def on_channel_sdu(sdu):
                 print(color(f'<<< [L2CAP SDU]: {len(sdu)} bytes', 'cyan'))
                 l2cap_to_tcp_pipe.write(sdu)
 
@@ -209,7 +211,7 @@ class ClientBridge:
                 writer.close()
                 return
 
-            l2cap_channel.sink = on_coc_sdu
+            l2cap_channel.sink = on_channel_sdu
             l2cap_channel.on('close', on_l2cap_close)
 
             # Start a flow control pipe from L2CAP to TCP
@@ -274,23 +276,29 @@ async def run(device_config, hci_transport, bridge):
 @click.pass_context
 @click.option('--device-config', help='Device configuration file', required=True)
 @click.option('--hci-transport', help='HCI transport', required=True)
-@click.option('--psm', help='PSM for L2CAP CoC', type=int, default=1234)
+@click.option('--psm', help='PSM for L2CAP', type=int, default=1234)
 @click.option(
-    '--l2cap-coc-max-credits',
-    help='Maximum L2CAP CoC Credits',
+    '--l2cap-max-credits',
+    help='Maximum L2CAP Credits',
     type=click.IntRange(1, 65535),
     default=128,
 )
 @click.option(
-    '--l2cap-coc-mtu',
-    help='L2CAP CoC MTU',
-    type=click.IntRange(23, 65535),
-    default=1022,
+    '--l2cap-mtu',
+    help='L2CAP MTU',
+    type=click.IntRange(
+        l2cap.L2CAP_LE_CREDIT_BASED_CONNECTION_MIN_MTU,
+        l2cap.L2CAP_LE_CREDIT_BASED_CONNECTION_MAX_MTU,
+    ),
+    default=1024,
 )
 @click.option(
-    '--l2cap-coc-mps',
-    help='L2CAP CoC MPS',
-    type=click.IntRange(23, 65533),
+    '--l2cap-mps',
+    help='L2CAP MPS',
+    type=click.IntRange(
+        l2cap.L2CAP_LE_CREDIT_BASED_CONNECTION_MIN_MPS,
+        l2cap.L2CAP_LE_CREDIT_BASED_CONNECTION_MAX_MPS,
+    ),
     default=1024,
 )
 def cli(
@@ -298,17 +306,17 @@ def cli(
     device_config,
     hci_transport,
     psm,
-    l2cap_coc_max_credits,
-    l2cap_coc_mtu,
-    l2cap_coc_mps,
+    l2cap_max_credits,
+    l2cap_mtu,
+    l2cap_mps,
 ):
     context.ensure_object(dict)
     context.obj['device_config'] = device_config
     context.obj['hci_transport'] = hci_transport
     context.obj['psm'] = psm
-    context.obj['max_credits'] = l2cap_coc_max_credits
-    context.obj['mtu'] = l2cap_coc_mtu
-    context.obj['mps'] = l2cap_coc_mps
+    context.obj['max_credits'] = l2cap_max_credits
+    context.obj['mtu'] = l2cap_mtu
+    context.obj['mps'] = l2cap_mps
 
 
 # -----------------------------------------------------------------------------

apps/lea_unicast/app.py

@@ -0,0 +1,577 @@
+# Copyright 2021-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 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 ctypes
+import wasmtime
+import wasmtime.loader
+import liblc3  # type: ignore
+import logging
+
+import click
+import aiohttp.web
+
+import bumble
+from bumble.core import AdvertisingData
+from bumble.colors import color
+from bumble.device import Device, DeviceConfiguration, AdvertisingParameters
+from bumble.transport import open_transport
+from bumble.profiles import bap
+from bumble.hci import Address, CodecID, CodingFormat, HCI_IsoDataPacket
+
+# -----------------------------------------------------------------------------
+# Logging
+# -----------------------------------------------------------------------------
+logger = logging.getLogger(__name__)
+
+# -----------------------------------------------------------------------------
+# Constants
+# -----------------------------------------------------------------------------
+DEFAULT_UI_PORT = 7654
+
+
+def _sink_pac_record() -> bap.PacRecord:
+    return bap.PacRecord(
+        coding_format=CodingFormat(CodecID.LC3),
+        codec_specific_capabilities=bap.CodecSpecificCapabilities(
+            supported_sampling_frequencies=(
+                bap.SupportedSamplingFrequency.FREQ_8000
+                | bap.SupportedSamplingFrequency.FREQ_16000
+                | bap.SupportedSamplingFrequency.FREQ_24000
+                | bap.SupportedSamplingFrequency.FREQ_32000
+                | bap.SupportedSamplingFrequency.FREQ_48000
+            ),
+            supported_frame_durations=(
+                bap.SupportedFrameDuration.DURATION_10000_US_SUPPORTED
+            ),
+            supported_audio_channel_count=[1, 2],
+            min_octets_per_codec_frame=26,
+            max_octets_per_codec_frame=240,
+            supported_max_codec_frames_per_sdu=2,
+        ),
+    )
+
+
+def _source_pac_record() -> bap.PacRecord:
+    return bap.PacRecord(
+        coding_format=CodingFormat(CodecID.LC3),
+        codec_specific_capabilities=bap.CodecSpecificCapabilities(
+            supported_sampling_frequencies=(
+                bap.SupportedSamplingFrequency.FREQ_8000
+                | bap.SupportedSamplingFrequency.FREQ_16000
+                | bap.SupportedSamplingFrequency.FREQ_24000
+                | bap.SupportedSamplingFrequency.FREQ_32000
+                | bap.SupportedSamplingFrequency.FREQ_48000
+            ),
+            supported_frame_durations=(
+                bap.SupportedFrameDuration.DURATION_10000_US_SUPPORTED
+            ),
+            supported_audio_channel_count=[1],
+            min_octets_per_codec_frame=30,
+            max_octets_per_codec_frame=100,
+            supported_max_codec_frames_per_sdu=1,
+        ),
+    )
+
+
+# -----------------------------------------------------------------------------
+# 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]
+    )
+
+
+async def lc3_source_task(
+    filename: str,
+    sdu_length: int,
+    frame_duration_us: int,
+    device: Device,
+    cis_handle: int,
+) -> None:
+    with open(filename, 'rb') as f:
+        header = f.read(44)
+        assert header[8:12] == b'WAVE'
+
+        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
+
+        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)
+
+            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())
+
+
+# -----------------------------------------------------------------------------
+class UiServer:
+    speaker: weakref.ReferenceType[Speaker]
+    port: int
+
+    def __init__(self, speaker: Speaker, port: int) -> None:
+        self.speaker = weakref.ref(speaker)
+        self.port = port
+        self.channel_socket = None
+
+    async def start_http(self) -> None:
+        """Start the UI HTTP server."""
+
+        app = aiohttp.web.Application()
+        app.add_routes(
+            [
+                aiohttp.web.get('/', self.get_static),
+                aiohttp.web.get('/index.html', self.get_static),
+                aiohttp.web.get('/channel', self.get_channel),
+            ]
+        )
+
+        runner = aiohttp.web.AppRunner(app)
+        await runner.setup()
+        site = aiohttp.web.TCPSite(runner, 'localhost', self.port)
+        print('UI HTTP server at ' + color(f'http://127.0.0.1:{self.port}', 'green'))
+        await site.start()
+
+    async def get_static(self, request):
+        path = request.path
+        if path == '/':
+            path = '/index.html'
+        if path.endswith('.html'):
+            content_type = 'text/html'
+        elif path.endswith('.js'):
+            content_type = 'text/javascript'
+        elif path.endswith('.css'):
+            content_type = 'text/css'
+        elif path.endswith('.svg'):
+            content_type = 'image/svg+xml'
+        else:
+            content_type = 'text/plain'
+        text = (
+            resources.files("bumble.apps.lea_unicast")
+            .joinpath(pathlib.Path(path).relative_to('/'))
+            .read_text(encoding="utf-8")
+        )
+        return aiohttp.web.Response(text=text, content_type=content_type)
+
+    async def get_channel(self, request):
+        ws = aiohttp.web.WebSocketResponse()
+        await ws.prepare(request)
+
+        # Process messages until the socket is closed.
+        self.channel_socket = ws
+        async for message in ws:
+            if message.type == aiohttp.WSMsgType.TEXT:
+                logger.debug(f'<<< received message: {message.data}')
+                await self.on_message(message.data)
+            elif message.type == aiohttp.WSMsgType.ERROR:
+                logger.debug(
+                    f'channel connection closed with exception {ws.exception()}'
+                )
+
+        self.channel_socket = None
+        logger.debug('--- channel connection closed')
+
+        return ws
+
+    async def on_message(self, message_str: str):
+        # Parse the message as JSON
+        message = json.loads(message_str)
+
+        # Dispatch the message
+        message_type = message['type']
+        message_params = message.get('params', {})
+        handler = getattr(self, f'on_{message_type}_message')
+        if handler:
+            await handler(**message_params)
+
+    async def on_hello_message(self):
+        await self.send_message(
+            'hello',
+            bumble_version=bumble.__version__,
+            codec=self.speaker().codec,
+            streamState=self.speaker().stream_state.name,
+        )
+        if connection := self.speaker().connection:
+            await self.send_message(
+                'connection',
+                peer_address=connection.peer_address.to_string(False),
+                peer_name=connection.peer_name,
+            )
+
+    async def send_message(self, message_type: str, **kwargs) -> None:
+        if self.channel_socket is None:
+            return
+
+        message = {'type': message_type, 'params': kwargs}
+        await self.channel_socket.send_json(message)
+
+    async def send_audio(self, data: bytes) -> None:
+        if self.channel_socket is None:
+            return
+
+        try:
+            await self.channel_socket.send_bytes(data)
+        except Exception as error:
+            logger.warning(f'exception while sending audio packet: {error}')
+
+
+# -----------------------------------------------------------------------------
+class Speaker:
+
+    def __init__(
+        self,
+        device_config_path: Optional[str],
+        ui_port: int,
+        transport: str,
+        lc3_input_file_path: str,
+    ):
+        self.device_config_path = device_config_path
+        self.transport = transport
+        self.lc3_input_file_path = lc3_input_file_path
+
+        # Create an HTTP server for the UI
+        self.ui_server = UiServer(speaker=self, port=ui_port)
+
+    async def run(self) -> None:
+        await self.ui_server.start_http()
+
+        async with await open_transport(self.transport) as hci_transport:
+            # Create a device
+            if self.device_config_path:
+                device_config = DeviceConfiguration.from_file(self.device_config_path)
+            else:
+                device_config = DeviceConfiguration(
+                    name="Bumble LE Headphone",
+                    class_of_device=0x244418,
+                    keystore="JsonKeyStore",
+                    advertising_interval_min=25,
+                    advertising_interval_max=25,
+                    address=Address('F1:F2:F3:F4:F5:F6'),
+                )
+
+            device_config.le_enabled = True
+            device_config.cis_enabled = True
+            self.device = Device.from_config_with_hci(
+                device_config, hci_transport.source, hci_transport.sink
+            )
+
+            self.device.add_service(
+                bap.PublishedAudioCapabilitiesService(
+                    supported_source_context=bap.ContextType(0xFFFF),
+                    available_source_context=bap.ContextType(0xFFFF),
+                    supported_sink_context=bap.ContextType(0xFFFF),  # All context types
+                    available_sink_context=bap.ContextType(0xFFFF),  # All context types
+                    sink_audio_locations=(
+                        bap.AudioLocation.FRONT_LEFT | bap.AudioLocation.FRONT_RIGHT
+                    ),
+                    sink_pac=[_sink_pac_record()],
+                    source_audio_locations=bap.AudioLocation.FRONT_LEFT,
+                    source_pac=[_source_pac_record()],
+                )
+            )
+
+            ascs = bap.AudioStreamControlService(
+                self.device, sink_ase_id=[1], source_ase_id=[2]
+            )
+            self.device.add_service(ascs)
+
+            advertising_data = bytes(
+                AdvertisingData(
+                    [
+                        (
+                            AdvertisingData.COMPLETE_LOCAL_NAME,
+                            bytes(device_config.name, 'utf-8'),
+                        ),
+                        (
+                            AdvertisingData.FLAGS,
+                            bytes([AdvertisingData.LE_GENERAL_DISCOVERABLE_MODE_FLAG]),
+                        ),
+                        (
+                            AdvertisingData.INCOMPLETE_LIST_OF_16_BIT_SERVICE_CLASS_UUIDS,
+                            bytes(bap.PublishedAudioCapabilitiesService.UUID),
+                        ),
+                    ]
+                )
+            ) + bytes(bap.UnicastServerAdvertisingData())
+
+            def on_pdu(pdu: HCI_IsoDataPacket, ase: bap.AseStateMachine):
+                codec_config = ase.codec_specific_configuration
+                assert isinstance(codec_config, bap.CodecSpecificConfiguration)
+                pcm = decode(
+                    codec_config.frame_duration.us,
+                    codec_config.audio_channel_allocation.channel_count,
+                    pdu.iso_sdu_fragment,
+                )
+                self.device.abort_on('disconnection', self.ui_server.send_audio(pcm))
+
+            def on_ase_state_change(ase: bap.AseStateMachine) -> None:
+                if ase.state == bap.AseStateMachine.State.STREAMING:
+                    codec_config = ase.codec_specific_configuration
+                    assert isinstance(codec_config, bap.CodecSpecificConfiguration)
+                    assert ase.cis_link
+                    if ase.role == bap.AudioRole.SOURCE:
+                        ase.cis_link.abort_on(
+                            'disconnection',
+                            lc3_source_task(
+                                filename=self.lc3_input_file_path,
+                                sdu_length=(
+                                    codec_config.codec_frames_per_sdu
+                                    * codec_config.octets_per_codec_frame
+                                ),
+                                frame_duration_us=codec_config.frame_duration.us,
+                                device=self.device,
+                                cis_handle=ase.cis_link.handle,
+                            ),
+                        )
+                    else:
+                        ase.cis_link.sink = functools.partial(on_pdu, ase=ase)
+                elif ase.state == bap.AseStateMachine.State.CODEC_CONFIGURED:
+                    codec_config = ase.codec_specific_configuration
+                    assert isinstance(codec_config, bap.CodecSpecificConfiguration)
+                    if ase.role == bap.AudioRole.SOURCE:
+                        setup_encoders(
+                            codec_config.sampling_frequency.hz,
+                            codec_config.frame_duration.us,
+                            codec_config.audio_channel_allocation.channel_count,
+                        )
+                    else:
+                        setup_decoders(
+                            codec_config.sampling_frequency.hz,
+                            codec_config.frame_duration.us,
+                            codec_config.audio_channel_allocation.channel_count,
+                        )
+
+            for ase in ascs.ase_state_machines.values():
+                ase.on('state_change', functools.partial(on_ase_state_change, ase=ase))
+
+            await self.device.power_on()
+            await self.device.create_advertising_set(
+                advertising_data=advertising_data,
+                auto_restart=True,
+                advertising_parameters=AdvertisingParameters(
+                    primary_advertising_interval_min=100,
+                    primary_advertising_interval_max=100,
+                ),
+            )
+
+            await hci_transport.source.terminated
+
+
+@click.command()
+@click.option(
+    '--ui-port',
+    'ui_port',
+    metavar='HTTP_PORT',
+    default=DEFAULT_UI_PORT,
+    show_default=True,
+    help='HTTP port for the UI server',
+)
+@click.option('--device-config', metavar='FILENAME', help='Device configuration file')
+@click.argument('transport')
+@click.argument('lc3_file')
+def speaker(ui_port: int, device_config: str, transport: str, lc3_file: str) -> None:
+    """Run the speaker."""
+
+    asyncio.run(Speaker(device_config, ui_port, transport, lc3_file).run())
+
+
+# -----------------------------------------------------------------------------
+def main():
+    logging.basicConfig(level=os.environ.get('BUMBLE_LOGLEVEL', 'WARNING').upper())
+    speaker()
+
+
+# -----------------------------------------------------------------------------
+if __name__ == "__main__":
+    main()  # pylint: disable=no-value-for-parameter

apps/lea_unicast/index.html

@@ -0,0 +1,68 @@
+<html data-bs-theme="dark">
+
+<head>
+    <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.2/dist/css/bootstrap.min.css" rel="stylesheet"
+        integrity="sha384-T3c6CoIi6uLrA9TneNEoa7RxnatzjcDSCmG1MXxSR1GAsXEV/Dwwykc2MPK8M2HN" crossorigin="anonymous">
+    <script src="https://unpkg.com/pcm-player"></script>
+</head>
+
+<body>
+    <nav class="navbar navbar-dark bg-primary">
+        <div class="container">
+            <span class="navbar-brand mb-0 h1">Bumble Unicast Server</span>
+        </div>
+    </nav>
+    <br>
+
+    <div class="container">
+        <button type="button" class="btn btn-danger" id="connect-audio" onclick="connectAudio()">Connect Audio</button>
+        <button class="btn btn-primary" type="button" disabled>
+            <span class="spinner-border spinner-border-sm" id="ws-status-spinner" aria-hidden="true"></span>
+            <span role="status" id="ws-status">WebSocket Connecting...</span>
+        </button>
+    </div>
+
+
+    <script>
+        let player = null;
+        const wsStatus = document.getElementById("ws-status");
+        const wsStatusSpinner = document.getElementById("ws-status-spinner");
+
+        const socket = new WebSocket('ws://127.0.0.1:7654/channel');
+        socket.binaryType = "arraybuffer";
+        socket.onmessage = function (message) {
+            if (typeof message.data === 'string' || message.data instanceof String) {
+                console.log(`channel MESSAGE: ${message.data}`);
+            } else {
+                console.log(typeof (message.data))
+                // BINARY audio data.
+                if (player == null) return;
+                player.feed(message.data);
+            }
+        };
+
+        socket.onopen = (message) => {
+            wsStatusSpinner.remove();
+            wsStatus.textContent = "WebSocket Connected";
+        }
+
+        socket.onclose = (message) => {
+            wsStatus.textContent = "WebSocket Disconnected";
+        }
+
+        function connectAudio() {
+            player = new PCMPlayer({
+                inputCodec: 'Int16',
+                channels: 2,
+                sampleRate: 48000,
+                flushTime: 10,
+            });
+            const button = document.getElementById("connect-audio")
+            button.disabled = true;
+            button.textContent = "Audio Connected";
+        }
+    </script>
+    </div>
+</body>
+
+</html>

apps/pair.py

@@ -52,11 +52,13 @@ from bumble.att import (
 class Waiter:
     instance = None
 
-    def __init__(self):
+    def __init__(self, linger=False):
         self.done = asyncio.get_running_loop().create_future()
+        self.linger = linger
 
     def terminate(self):
-        self.done.set_result(None)
+        if not self.linger:
+            self.done.set_result(None)
 
     async def wait_until_terminated(self):
         return await self.done
@@ -302,7 +304,7 @@ async def pair(
     hci_transport,
     address_or_name,
 ):
-    Waiter.instance = Waiter()
+    Waiter.instance = Waiter(linger=linger)
 
     print('<<< connecting to HCI...')
     async with await open_transport_or_link(hci_transport) as (hci_source, hci_sink):
@@ -396,7 +398,6 @@ async def pair(
                 address_or_name,
                 transport=BT_LE_TRANSPORT if mode == 'le' else BT_BR_EDR_TRANSPORT,
             )
-            pairing_failure = False
 
             if not request:
                 try:
@@ -405,11 +406,8 @@ async def pair(
                     else:
                         await connection.authenticate()
                 except ProtocolError as error:
-                    pairing_failure = True
                     print(color(f'Pairing failed: {error}', 'red'))
 
-            if not linger or pairing_failure:
-                return
         else:
             if mode == 'le':
                 # Advertise so that peers can find us and connect
@@ -459,7 +457,7 @@ class LogHandler(logging.Handler):
     help='Enable CTKD',
     show_default=True,
 )
-@click.option('--linger', default=True, is_flag=True, help='Linger after pairing')
+@click.option('--linger', default=False, is_flag=True, help='Linger after pairing')
 @click.option(
     '--io',
     type=click.Choice(

apps/rfcomm_bridge.py

@@ -0,0 +1,511 @@
+# 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 asyncio
+import logging
+import os
+import time
+from typing import Optional
+
+import click
+
+from bumble.colors import color
+from bumble.device import Device, DeviceConfiguration, Connection
+from bumble import core
+from bumble import hci
+from bumble import rfcomm
+from bumble import transport
+from bumble import utils
+
+
+# -----------------------------------------------------------------------------
+# Constants
+# -----------------------------------------------------------------------------
+DEFAULT_RFCOMM_UUID = "E6D55659-C8B4-4B85-96BB-B1143AF6D3AE"
+DEFAULT_MTU = 4096
+DEFAULT_CLIENT_TCP_PORT = 9544
+DEFAULT_SERVER_TCP_PORT = 9545
+
+TRACE_MAX_SIZE = 48
+
+
+# -----------------------------------------------------------------------------
+class Tracer:
+    """
+    Trace data buffers transmitted from one endpoint to another, with stats.
+    """
+
+    def __init__(self, channel_name: str) -> None:
+        self.channel_name = channel_name
+        self.last_ts: float = 0.0
+
+    def trace_data(self, data: bytes) -> None:
+        now = time.time()
+        elapsed_s = now - self.last_ts if self.last_ts else 0
+        elapsed_ms = int(elapsed_s * 1000)
+        instant_throughput_kbps = ((len(data) / elapsed_s) / 1000) if elapsed_s else 0.0
+
+        hex_str = data[:TRACE_MAX_SIZE].hex() + (
+            "..." if len(data) > TRACE_MAX_SIZE else ""
+        )
+        print(
+            f"[{self.channel_name}] {len(data):4} bytes "
+            f"(+{elapsed_ms:4}ms, {instant_throughput_kbps: 7.2f}kB/s) "
+            f" {hex_str}"
+        )
+
+        self.last_ts = now
+
+
+# -----------------------------------------------------------------------------
+class ServerBridge:
+    """
+    RFCOMM server bridge: waits for a peer to connect an RFCOMM channel.
+    The RFCOMM channel may be associated with a UUID published in an SDP service
+    description, or simply be on a system-assigned channel number.
+    When the connection is made, the bridge connects a TCP socket to a remote host and
+    bridges the data in both directions, with flow control.
+    When the RFCOMM channel is closed, the bridge disconnects the TCP socket
+    and waits for a new channel to be connected.
+    """
+
+    READ_CHUNK_SIZE = 4096
+
+    def __init__(
+        self, channel: int, uuid: str, trace: bool, tcp_host: str, tcp_port: int
+    ) -> None:
+        self.device: Optional[Device] = None
+        self.channel = channel
+        self.uuid = uuid
+        self.tcp_host = tcp_host
+        self.tcp_port = tcp_port
+        self.rfcomm_channel: Optional[rfcomm.DLC] = None
+        self.tcp_tracer: Optional[Tracer]
+        self.rfcomm_tracer: Optional[Tracer]
+
+        if trace:
+            self.tcp_tracer = Tracer(color("RFCOMM->TCP", "cyan"))
+            self.rfcomm_tracer = Tracer(color("TCP->RFCOMM", "magenta"))
+        else:
+            self.rfcomm_tracer = None
+            self.tcp_tracer = None
+
+    async def start(self, device: Device) -> None:
+        self.device = device
+
+        # Create and register a server
+        rfcomm_server = rfcomm.Server(self.device)
+
+        # Listen for incoming DLC connections
+        self.channel = rfcomm_server.listen(self.on_rfcomm_channel, self.channel)
+
+        # Setup the SDP to advertise this channel
+        service_record_handle = 0x00010001
+        self.device.sdp_service_records = {
+            service_record_handle: rfcomm.make_service_sdp_records(
+                service_record_handle, self.channel, core.UUID(self.uuid)
+            )
+        }
+
+        # We're ready for a connection
+        self.device.on("connection", self.on_connection)
+        await self.set_available(True)
+
+        print(
+            color(
+                (
+                    f"### Listening for RFCOMM connection on {device.public_address}, "
+                    f"channel {self.channel}"
+                ),
+                "yellow",
+            )
+        )
+
+    async def set_available(self, available: bool):
+        # Become discoverable and connectable
+        assert self.device
+        await self.device.set_connectable(available)
+        await self.device.set_discoverable(available)
+
+    def on_connection(self, connection):
+        print(color(f"@@@ Bluetooth connection: {connection}", "blue"))
+        connection.on("disconnection", self.on_disconnection)
+
+        # Don't accept new connections until we're disconnected
+        utils.AsyncRunner.spawn(self.set_available(False))
+
+    def on_disconnection(self, reason: int):
+        print(
+            color("@@@ Bluetooth disconnection:", "red"),
+            hci.HCI_Constant.error_name(reason),
+        )
+
+        # We're ready for a new connection
+        utils.AsyncRunner.spawn(self.set_available(True))
+
+    # Called when an RFCOMM channel is established
+    @utils.AsyncRunner.run_in_task()
+    async def on_rfcomm_channel(self, rfcomm_channel):
+        print(color("*** RFCOMM channel:", "cyan"), rfcomm_channel)
+
+        # Connect to the TCP server
+        print(
+            color(
+                f"### Connecting to TCP {self.tcp_host}:{self.tcp_port}",
+                "yellow",
+            )
+        )
+        try:
+            reader, writer = await asyncio.open_connection(self.tcp_host, self.tcp_port)
+        except OSError:
+            print(color("!!! Connection failed", "red"))
+            await rfcomm_channel.disconnect()
+            return
+
+        # Pipe data from RFCOMM to TCP
+        def on_rfcomm_channel_closed():
+            print(color("*** RFCOMM channel closed", "cyan"))
+            writer.close()
+
+        def write_rfcomm_data(data):
+            if self.rfcomm_tracer:
+                self.rfcomm_tracer.trace_data(data)
+
+            writer.write(data)
+
+        rfcomm_channel.sink = write_rfcomm_data
+        rfcomm_channel.on("close", on_rfcomm_channel_closed)
+
+        # Pipe data from TCP to RFCOMM
+        while True:
+            try:
+                data = await reader.read(self.READ_CHUNK_SIZE)
+
+                if len(data) == 0:
+                    print(color("### TCP end of stream", "yellow"))
+                    if rfcomm_channel.state == rfcomm.DLC.State.CONNECTED:
+                        await rfcomm_channel.disconnect()
+                    return
+
+                if self.tcp_tracer:
+                    self.tcp_tracer.trace_data(data)
+
+                rfcomm_channel.write(data)
+                await rfcomm_channel.drain()
+            except Exception as error:
+                print(f"!!! Exception: {error}")
+                break
+
+        writer.close()
+        await writer.wait_closed()
+        print(color("~~~ Bye bye", "magenta"))
+
+
+# -----------------------------------------------------------------------------
+class ClientBridge:
+    """
+    RFCOMM client bridge: connects to a BR/EDR device, then waits for an inbound
+    TCP connection on a specified port number. When a TCP client connects, an
+    RFCOMM connection to the device is established, and the data is bridged in both
+    directions, with flow control.
+    When the TCP connection is closed by the client, the RFCOMM channel is
+    disconnected, but the connection to the device remains, ready for a new TCP client
+    to connect.
+    """
+
+    READ_CHUNK_SIZE = 4096
+
+    def __init__(
+        self,
+        channel: int,
+        uuid: str,
+        trace: bool,
+        address: str,
+        tcp_host: str,
+        tcp_port: int,
+        encrypt: bool,
+    ):
+        self.channel = channel
+        self.uuid = uuid
+        self.trace = trace
+        self.address = address
+        self.tcp_host = tcp_host
+        self.tcp_port = tcp_port
+        self.encrypt = encrypt
+        self.device: Optional[Device] = None
+        self.connection: Optional[Connection] = None
+        self.rfcomm_client: Optional[rfcomm.Client]
+        self.rfcomm_mux: Optional[rfcomm.Multiplexer]
+        self.tcp_connected: bool = False
+
+        self.tcp_tracer: Optional[Tracer]
+        self.rfcomm_tracer: Optional[Tracer]
+
+        if trace:
+            self.tcp_tracer = Tracer(color("RFCOMM->TCP", "cyan"))
+            self.rfcomm_tracer = Tracer(color("TCP->RFCOMM", "magenta"))
+        else:
+            self.rfcomm_tracer = None
+            self.tcp_tracer = None
+
+    async def connect(self) -> None:
+        if self.connection:
+            return
+
+        print(color(f"@@@ Connecting to Bluetooth {self.address}", "blue"))
+        assert self.device
+        self.connection = await self.device.connect(
+            self.address, transport=core.BT_BR_EDR_TRANSPORT
+        )
+        print(color(f"@@@ Bluetooth connection: {self.connection}", "blue"))
+        self.connection.on("disconnection", self.on_disconnection)
+
+        if self.encrypt:
+            print(color("@@@ Encrypting Bluetooth connection", "blue"))
+            await self.connection.encrypt()
+            print(color("@@@ Bluetooth connection encrypted", "blue"))
+
+        self.rfcomm_client = rfcomm.Client(self.connection)
+        try:
+            self.rfcomm_mux = await self.rfcomm_client.start()
+        except BaseException as e:
+            print(color("!!! Failed to setup RFCOMM connection", "red"), e)
+            raise
+
+    async def start(self, device: Device) -> None:
+        self.device = device
+        await device.set_connectable(False)
+        await device.set_discoverable(False)
+
+        # Called when a TCP connection is established
+        async def on_tcp_connection(reader, writer):
+            print(color("<<< TCP connection", "magenta"))
+            if self.tcp_connected:
+                print(
+                    color("!!! TCP connection already active, rejecting new one", "red")
+                )
+                writer.close()
+                return
+            self.tcp_connected = True
+
+            try:
+                await self.pipe(reader, writer)
+            except BaseException as error:
+                print(color("!!! Exception while piping data:", "red"), error)
+                return
+            finally:
+                writer.close()
+                await writer.wait_closed()
+                self.tcp_connected = False
+
+        await asyncio.start_server(
+            on_tcp_connection,
+            host=self.tcp_host if self.tcp_host != "_" else None,
+            port=self.tcp_port,
+        )
+        print(
+            color(
+                f"### Listening for TCP connections on port {self.tcp_port}", "magenta"
+            )
+        )
+
+    async def pipe(
+        self, reader: asyncio.StreamReader, writer: asyncio.StreamWriter
+    ) -> None:
+        # Resolve the channel number from the UUID if needed
+        if self.channel == 0:
+            await self.connect()
+            assert self.connection
+            channel = await rfcomm.find_rfcomm_channel_with_uuid(
+                self.connection, self.uuid
+            )
+            if channel:
+                print(color(f"### Found RFCOMM channel {channel}", "yellow"))
+            else:
+                print(color(f"!!! RFCOMM channel with UUID {self.uuid} not found"))
+                return
+        else:
+            channel = self.channel
+
+        # Connect a new RFCOMM channel
+        await self.connect()
+        assert self.rfcomm_mux
+        print(color(f"*** Opening RFCOMM channel {channel}", "green"))
+        try:
+            rfcomm_channel = await self.rfcomm_mux.open_dlc(channel)
+            print(color(f"*** RFCOMM channel open: {rfcomm_channel}", "green"))
+        except Exception as error:
+            print(color(f"!!! RFCOMM open failed: {error}", "red"))
+            return
+
+        # Pipe data from RFCOMM to TCP
+        def on_rfcomm_channel_closed():
+            print(color("*** RFCOMM channel closed", "green"))
+
+        def write_rfcomm_data(data):
+            if self.trace:
+                self.rfcomm_tracer.trace_data(data)
+
+            writer.write(data)
+
+        rfcomm_channel.on("close", on_rfcomm_channel_closed)
+        rfcomm_channel.sink = write_rfcomm_data
+
+        # Pipe data from TCP to RFCOMM
+        while True:
+            try:
+                data = await reader.read(self.READ_CHUNK_SIZE)
+
+                if len(data) == 0:
+                    print(color("### TCP end of stream", "yellow"))
+                    if rfcomm_channel.state == rfcomm.DLC.State.CONNECTED:
+                        await rfcomm_channel.disconnect()
+                    self.tcp_connected = False
+                    return
+
+                if self.tcp_tracer:
+                    self.tcp_tracer.trace_data(data)
+
+                rfcomm_channel.write(data)
+                await rfcomm_channel.drain()
+            except Exception as error:
+                print(f"!!! Exception: {error}")
+                break
+
+        print(color("~~~ Bye bye", "magenta"))
+
+    def on_disconnection(self, reason: int) -> None:
+        print(
+            color("@@@ Bluetooth disconnection:", "red"),
+            hci.HCI_Constant.error_name(reason),
+        )
+        self.connection = None
+
+
+# -----------------------------------------------------------------------------
+async def run(device_config, hci_transport, bridge):
+    print("<<< connecting to HCI...")
+    async with await transport.open_transport_or_link(hci_transport) as (
+        hci_source,
+        hci_sink,
+    ):
+        print("<<< connected")
+
+        if device_config:
+            device = Device.from_config_file_with_hci(
+                device_config, hci_source, hci_sink
+            )
+        else:
+            device = Device.from_config_with_hci(
+                DeviceConfiguration(), hci_source, hci_sink
+            )
+        device.classic_enabled = True
+
+        # Let's go
+        await device.power_on()
+        try:
+            await bridge.start(device)
+
+            # Wait until the transport terminates
+            await hci_source.wait_for_termination()
+        except core.ConnectionError as error:
+            print(color(f"!!! Bluetooth connection failed: {error}", "red"))
+        except Exception as error:
+            print(f"Exception while running bridge: {error}")
+
+
+# -----------------------------------------------------------------------------
+@click.group()
+@click.pass_context
+@click.option(
+    "--device-config",
+    metavar="CONFIG_FILE",
+    help="Device configuration file",
+)
+@click.option(
+    "--hci-transport", metavar="TRANSPORT_NAME", help="HCI transport", required=True
+)
+@click.option("--trace", is_flag=True, help="Trace bridged data to stdout")
+@click.option(
+    "--channel",
+    metavar="CHANNEL_NUMER",
+    help="RFCOMM channel number",
+    type=int,
+    default=0,
+)
+@click.option(
+    "--uuid",
+    metavar="UUID",
+    help="UUID for the RFCOMM channel",
+    default=DEFAULT_RFCOMM_UUID,
+)
+def cli(
+    context,
+    device_config,
+    hci_transport,
+    trace,
+    channel,
+    uuid,
+):
+    context.ensure_object(dict)
+    context.obj["device_config"] = device_config
+    context.obj["hci_transport"] = hci_transport
+    context.obj["trace"] = trace
+    context.obj["channel"] = channel
+    context.obj["uuid"] = uuid
+
+
+# -----------------------------------------------------------------------------
+@cli.command()
+@click.pass_context
+@click.option("--tcp-host", help="TCP host", default="localhost")
+@click.option("--tcp-port", help="TCP port", default=DEFAULT_SERVER_TCP_PORT)
+def server(context, tcp_host, tcp_port):
+    bridge = ServerBridge(
+        context.obj["channel"],
+        context.obj["uuid"],
+        context.obj["trace"],
+        tcp_host,
+        tcp_port,
+    )
+    asyncio.run(run(context.obj["device_config"], context.obj["hci_transport"], bridge))
+
+
+# -----------------------------------------------------------------------------
+@cli.command()
+@click.pass_context
+@click.argument("bluetooth-address")
+@click.option("--tcp-host", help="TCP host", default="_")
+@click.option("--tcp-port", help="TCP port", default=DEFAULT_CLIENT_TCP_PORT)
+@click.option("--encrypt", is_flag=True, help="Encrypt the connection")
+def client(context, bluetooth_address, tcp_host, tcp_port, encrypt):
+    bridge = ClientBridge(
+        context.obj["channel"],
+        context.obj["uuid"],
+        context.obj["trace"],
+        bluetooth_address,
+        tcp_host,
+        tcp_port,
+        encrypt,
+    )
+    asyncio.run(run(context.obj["device_config"], context.obj["hci_transport"], bridge))
+
+
+# -----------------------------------------------------------------------------
+logging.basicConfig(level=os.environ.get("BUMBLE_LOGLEVEL", "WARNING").upper())
+if __name__ == "__main__":
+    cli(obj={})  # pylint: disable=no-value-for-parameter

apps/scan.py

@@ -26,7 +26,7 @@ from bumble.transport import open_transport_or_link
 from bumble.keys import JsonKeyStore
 from bumble.smp import AddressResolver
 from bumble.device import Advertisement
-from bumble.hci import HCI_Constant, HCI_LE_1M_PHY, HCI_LE_CODED_PHY
+from bumble.hci import Address, HCI_Constant, HCI_LE_1M_PHY, HCI_LE_CODED_PHY
 
 
 # -----------------------------------------------------------------------------
@@ -66,10 +66,15 @@ class AdvertisementPrinter:
         address_type_string = ('PUBLIC', 'RANDOM', 'PUBLIC_ID', 'RANDOM_ID')[
             address.address_type
         ]
-        if address.is_public:
-            type_color = 'cyan'
+        if address.address_type in (
+            Address.RANDOM_IDENTITY_ADDRESS,
+            Address.PUBLIC_IDENTITY_ADDRESS,
+        ):
+            type_color = 'yellow'
         else:
-            if address.is_static:
+            if address.is_public:
+                type_color = 'cyan'
+            elif address.is_static:
                 type_color = 'green'
                 address_qualifier = '(static)'
             elif address.is_resolvable:
@@ -116,6 +121,7 @@ async def scan(
     phy,
     filter_duplicates,
     raw,
+    irks,
     keystore_file,
     device_config,
     transport,
@@ -140,9 +146,21 @@ async def scan(
 
         if device.keystore:
             resolving_keys = await device.keystore.get_resolving_keys()
-            resolver = AddressResolver(resolving_keys)
         else:
-            resolver = None
+            resolving_keys = []
+
+        for irk_and_address in irks:
+            if ':' not in irk_and_address:
+                raise ValueError('invalid IRK:ADDRESS value')
+            irk_hex, address_str = irk_and_address.split(':', 1)
+            resolving_keys.append(
+                (
+                    bytes.fromhex(irk_hex),
+                    Address(address_str, Address.RANDOM_DEVICE_ADDRESS),
+                )
+            )
+
+        resolver = AddressResolver(resolving_keys) if resolving_keys else None
 
         printer = AdvertisementPrinter(min_rssi, resolver)
         if raw:
@@ -187,8 +205,24 @@ async def scan(
     default=False,
     help='Listen for raw advertising reports instead of processed ones',
 )
-@click.option('--keystore-file', help='Keystore file to use when resolving addresses')
-@click.option('--device-config', help='Device config file for the scanning device')
+@click.option(
+    '--irk',
+    metavar='<IRK_HEX>:<ADDRESS>',
+    help=(
+        'Use this IRK for resolving private addresses ' '(may be used more than once)'
+    ),
+    multiple=True,
+)
+@click.option(
+    '--keystore-file',
+    metavar='FILE_PATH',
+    help='Keystore file to use when resolving addresses',
+)
+@click.option(
+    '--device-config',
+    metavar='FILE_PATH',
+    help='Device config file for the scanning device',
+)
 @click.argument('transport')
 def main(
     min_rssi,
@@ -198,6 +232,7 @@ def main(
     phy,
     filter_duplicates,
     raw,
+    irk,
     keystore_file,
     device_config,
     transport,
@@ -212,6 +247,7 @@ def main(
             phy,
             filter_duplicates,
             raw,
+            irk,
             keystore_file,
             device_config,
             transport,

apps/show.py

@@ -15,7 +15,11 @@
 # -----------------------------------------------------------------------------
 # Imports
 # -----------------------------------------------------------------------------
+import datetime
+import logging
+import os
 import struct
+
 import click
 
 from bumble.colors import color
@@ -24,6 +28,14 @@ from bumble.transport.common import PacketReader
 from bumble.helpers import PacketTracer
 
 
+# -----------------------------------------------------------------------------
+# Logging
+# -----------------------------------------------------------------------------
+logger = logging.getLogger(__name__)
+
+
+# -----------------------------------------------------------------------------
+# Classes
 # -----------------------------------------------------------------------------
 class SnoopPacketReader:
     '''
@@ -36,12 +48,18 @@ class SnoopPacketReader:
     DATALINK_BSCP = 1003
     DATALINK_H5 = 1004
 
+    IDENTIFICATION_PATTERN = b'btsnoop\0'
+    TIMESTAMP_ANCHOR = datetime.datetime(2000, 1, 1)
+    TIMESTAMP_DELTA = 0x00E03AB44A676000
+    ONE_MICROSECOND = datetime.timedelta(microseconds=1)
+
     def __init__(self, source):
         self.source = source
+        self.at_end = False
 
         # Read the header
         identification_pattern = source.read(8)
-        if identification_pattern.hex().lower() != '6274736e6f6f7000':
+        if identification_pattern != self.IDENTIFICATION_PATTERN:
             raise ValueError(
                 'not a valid snoop file, unexpected identification pattern'
             )
@@ -55,19 +73,32 @@ class SnoopPacketReader:
         # Read the record header
         header = self.source.read(24)
         if len(header) < 24:
-            return (0, None)
+            self.at_end = True
+            return (None, 0, None)
+
+        # Parse the header
         (
             original_length,
             included_length,
             packet_flags,
             _cumulative_drops,
-            _timestamp_seconds,
-            _timestamp_microsecond,
-        ) = struct.unpack('>IIIIII', header)
+            timestamp,
+        ) = struct.unpack('>IIIIQ', header)
 
-        # Abort on truncated packets
+        # Skip truncated packets
         if original_length != included_length:
-            return (0, None)
+            print(
+                color(
+                    f"!!! truncated packet ({included_length}/{original_length})", "red"
+                )
+            )
+            self.source.read(included_length)
+            return (None, 0, None)
+
+        # Convert the timestamp to a datetime object.
+        ts_dt = self.TIMESTAMP_ANCHOR + datetime.timedelta(
+            microseconds=timestamp - self.TIMESTAMP_DELTA
+        )
 
         if self.data_link_type == self.DATALINK_H1:
             # The packet is un-encapsulated, look at the flags to figure out its type
@@ -89,7 +120,17 @@ class SnoopPacketReader:
                 bytes([packet_type]) + self.source.read(included_length),
             )
 
-        return (packet_flags & 1, self.source.read(included_length))
+        return (ts_dt, packet_flags & 1, self.source.read(included_length))
+
+
+# -----------------------------------------------------------------------------
+class Printer:
+    def __init__(self):
+        self.index = 0
+
+    def print(self, message: str) -> None:
+        self.index += 1
+        print(f"[{self.index:8}]{message}")
 
 
 # -----------------------------------------------------------------------------
@@ -122,24 +163,28 @@ def main(format, vendors, filename):
         packet_reader = PacketReader(input)
 
         def read_next_packet():
-            return (0, packet_reader.next_packet())
+            return (None, 0, packet_reader.next_packet())
 
     else:
         packet_reader = SnoopPacketReader(input)
         read_next_packet = packet_reader.next_packet
 
-    tracer = PacketTracer(emit_message=print)
+    printer = Printer()
+    tracer = PacketTracer(emit_message=printer.print)
 
-    while True:
+    while not packet_reader.at_end:
         try:
-            (direction, packet) = read_next_packet()
-            if packet is None:
-                break
-            tracer.trace(hci.HCI_Packet.from_bytes(packet), direction)
+            (timestamp, direction, packet) = read_next_packet()
+            if packet:
+                tracer.trace(hci.HCI_Packet.from_bytes(packet), direction, timestamp)
+            else:
+                printer.print(color("[TRUNCATED]", "red"))
         except Exception as error:
+            logger.exception()
             print(color(f'!!! {error}', 'red'))
 
 
 # -----------------------------------------------------------------------------
 if __name__ == '__main__':
+    logging.basicConfig(level=os.environ.get('BUMBLE_LOGLEVEL', 'WARNING').upper())
     main()  # pylint: disable=no-value-for-parameter

apps/speaker/speaker.py

@@ -76,6 +76,7 @@ logger = logging.getLogger(__name__)
 # -----------------------------------------------------------------------------
 DEFAULT_UI_PORT = 7654
 
+
 # -----------------------------------------------------------------------------
 class AudioExtractor:
     @staticmethod

apps/unbond.py

@@ -24,6 +24,7 @@ from bumble.device import Device
 from bumble.keys import JsonKeyStore
 from bumble.transport import open_transport
 
+
 # -----------------------------------------------------------------------------
 async def unbond_with_keystore(keystore, address):
     if address is None:

bumble/a2dp.py

@@ -184,8 +184,12 @@ def make_audio_source_service_sdp_records(service_record_handle, version=(1, 3))
             SDP_BLUETOOTH_PROFILE_DESCRIPTOR_LIST_ATTRIBUTE_ID,
             DataElement.sequence(
                 [
-                    DataElement.uuid(BT_ADVANCED_AUDIO_DISTRIBUTION_SERVICE),
-                    DataElement.unsigned_integer_16(version_int),
+                    DataElement.sequence(
+                        [
+                            DataElement.uuid(BT_ADVANCED_AUDIO_DISTRIBUTION_SERVICE),
+                            DataElement.unsigned_integer_16(version_int),
+                        ]
+                    )
                 ]
             ),
         ),
@@ -234,8 +238,12 @@ def make_audio_sink_service_sdp_records(service_record_handle, version=(1, 3)):
             SDP_BLUETOOTH_PROFILE_DESCRIPTOR_LIST_ATTRIBUTE_ID,
             DataElement.sequence(
                 [
-                    DataElement.uuid(BT_ADVANCED_AUDIO_DISTRIBUTION_SERVICE),
-                    DataElement.unsigned_integer_16(version_int),
+                    DataElement.sequence(
+                        [
+                            DataElement.uuid(BT_ADVANCED_AUDIO_DISTRIBUTION_SERVICE),
+                            DataElement.unsigned_integer_16(version_int),
+                        ]
+                    )
                 ]
             ),
         ),
@@ -644,7 +652,9 @@ class SbcPacketSource:
 
                     # Prepare for next packets
                     sequence_number += 1
+                    sequence_number &= 0xFFFF
                     timestamp += sum((frame.sample_count for frame in frames))
+                    timestamp &= 0xFFFFFFFF
                     frames = [frame]
                     frames_size = len(frame.payload)
                 else:

bumble/att.py

@@ -25,9 +25,21 @@
 from __future__ import annotations
 import enum
 import functools
+import inspect
 import struct
+from typing import (
+    Any,
+    Awaitable,
+    Callable,
+    Dict,
+    List,
+    Optional,
+    Type,
+    Union,
+    TYPE_CHECKING,
+)
+
 from pyee import EventEmitter
-from typing import Dict, Type, List, Protocol, Union, Optional, Any, TYPE_CHECKING
 
 from bumble.core import UUID, name_or_number, ProtocolError
 from bumble.hci import HCI_Object, key_with_value
@@ -643,7 +655,7 @@ class ATT_Write_Command(ATT_PDU):
 @ATT_PDU.subclass(
     [
         ('attribute_handle', HANDLE_FIELD_SPEC),
-        ('attribute_value', '*')
+        ('attribute_value', '*'),
         # ('authentication_signature', 'TODO')
     ]
 )
@@ -722,12 +734,38 @@ class ATT_Handle_Value_Confirmation(ATT_PDU):
 
 
 # -----------------------------------------------------------------------------
-class ConnectionValue(Protocol):
-    def read(self, connection) -> bytes:
-        ...
+class AttributeValue:
+    '''
+    Attribute value where reading and/or writing is delegated to functions
+    passed as arguments to the constructor.
+    '''
 
-    def write(self, connection, value: bytes) -> None:
-        ...
+    def __init__(
+        self,
+        read: Union[
+            Callable[[Optional[Connection]], bytes],
+            Callable[[Optional[Connection]], Awaitable[bytes]],
+            None,
+        ] = None,
+        write: Union[
+            Callable[[Optional[Connection], bytes], None],
+            Callable[[Optional[Connection], bytes], Awaitable[None]],
+            None,
+        ] = None,
+    ):
+        self._read = read
+        self._write = write
+
+    def read(self, connection: Optional[Connection]) -> Union[bytes, Awaitable[bytes]]:
+        return self._read(connection) if self._read else b''
+
+    def write(
+        self, connection: Optional[Connection], value: bytes
+    ) -> Union[Awaitable[None], None]:
+        if self._write:
+            return self._write(connection, value)
+
+        return None
 
 
 # -----------------------------------------------------------------------------
@@ -770,13 +808,13 @@ class Attribute(EventEmitter):
     READ_REQUIRES_AUTHORIZATION = Permissions.READ_REQUIRES_AUTHORIZATION
     WRITE_REQUIRES_AUTHORIZATION = Permissions.WRITE_REQUIRES_AUTHORIZATION
 
-    value: Union[str, bytes, ConnectionValue]
+    value: Union[bytes, AttributeValue]
 
     def __init__(
         self,
         attribute_type: Union[str, bytes, UUID],
         permissions: Union[str, Attribute.Permissions],
-        value: Union[str, bytes, ConnectionValue] = b'',
+        value: Union[str, bytes, AttributeValue] = b'',
     ) -> None:
         EventEmitter.__init__(self)
         self.handle = 0
@@ -806,7 +844,7 @@ class Attribute(EventEmitter):
     def decode_value(self, value_bytes: bytes) -> Any:
         return value_bytes
 
-    def read_value(self, connection: Optional[Connection]) -> bytes:
+    async def read_value(self, connection: Optional[Connection]) -> bytes:
         if (
             (self.permissions & self.READ_REQUIRES_ENCRYPTION)
             and connection is not None
@@ -832,6 +870,8 @@ class Attribute(EventEmitter):
         if hasattr(self.value, 'read'):
             try:
                 value = self.value.read(connection)
+                if inspect.isawaitable(value):
+                    value = await value
             except ATT_Error as error:
                 raise ATT_Error(
                     error_code=error.error_code, att_handle=self.handle
@@ -841,7 +881,7 @@ class Attribute(EventEmitter):
 
         return self.encode_value(value)
 
-    def write_value(self, connection: Connection, value_bytes: bytes) -> None:
+    async def write_value(self, connection: Connection, value_bytes: bytes) -> None:
         if (
             self.permissions & self.WRITE_REQUIRES_ENCRYPTION
         ) and not connection.encryption:
@@ -864,7 +904,9 @@ class Attribute(EventEmitter):
 
         if hasattr(self.value, 'write'):
             try:
-                self.value.write(connection, value)  # pylint: disable=not-callable
+                result = self.value.write(connection, value)
+                if inspect.isawaitable(result):
+                    await result
             except ATT_Error as error:
                 raise ATT_Error(
                     error_code=error.error_code, att_handle=self.handle

bumble/avc.py

@@ -0,0 +1,520 @@
+# 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.
+
+# -----------------------------------------------------------------------------
+# Imports
+# -----------------------------------------------------------------------------
+from __future__ import annotations
+import enum
+import struct
+from typing import Dict, Type, Union, Tuple
+
+from bumble.utils import OpenIntEnum
+
+
+# -----------------------------------------------------------------------------
+class Frame:
+    class SubunitType(enum.IntEnum):
+        # AV/C Digital Interface Command Set General Specification Version 4.1
+        # Table 7.4
+        MONITOR = 0x00
+        AUDIO = 0x01
+        PRINTER = 0x02
+        DISC = 0x03
+        TAPE_RECORDER_OR_PLAYER = 0x04
+        TUNER = 0x05
+        CA = 0x06
+        CAMERA = 0x07
+        PANEL = 0x09
+        BULLETIN_BOARD = 0x0A
+        VENDOR_UNIQUE = 0x1C
+        EXTENDED = 0x1E
+        UNIT = 0x1F
+
+    class OperationCode(OpenIntEnum):
+        # 0x00 - 0x0F: Unit and subunit commands
+        VENDOR_DEPENDENT = 0x00
+        RESERVE = 0x01
+        PLUG_INFO = 0x02
+
+        # 0x10 - 0x3F: Unit commands
+        DIGITAL_OUTPUT = 0x10
+        DIGITAL_INPUT = 0x11
+        CHANNEL_USAGE = 0x12
+        OUTPUT_PLUG_SIGNAL_FORMAT = 0x18
+        INPUT_PLUG_SIGNAL_FORMAT = 0x19
+        GENERAL_BUS_SETUP = 0x1F
+        CONNECT_AV = 0x20
+        DISCONNECT_AV = 0x21
+        CONNECTIONS = 0x22
+        CONNECT = 0x24
+        DISCONNECT = 0x25
+        UNIT_INFO = 0x30
+        SUBUNIT_INFO = 0x31
+
+        # 0x40 - 0x7F: Subunit commands
+        PASS_THROUGH = 0x7C
+        GUI_UPDATE = 0x7D
+        PUSH_GUI_DATA = 0x7E
+        USER_ACTION = 0x7F
+
+        # 0xA0 - 0xBF: Unit and subunit commands
+        VERSION = 0xB0
+        POWER = 0xB2
+
+    subunit_type: SubunitType
+    subunit_id: int
+    opcode: OperationCode
+    operands: bytes
+
+    @staticmethod
+    def subclass(subclass):
+        # Infer the opcode from the class name
+        if subclass.__name__.endswith("CommandFrame"):
+            short_name = subclass.__name__.replace("CommandFrame", "")
+            category_class = CommandFrame
+        elif subclass.__name__.endswith("ResponseFrame"):
+            short_name = subclass.__name__.replace("ResponseFrame", "")
+            category_class = ResponseFrame
+        else:
+            raise ValueError(f"invalid subclass name {subclass.__name__}")
+
+        uppercase_indexes = [
+            i for i in range(len(short_name)) if short_name[i].isupper()
+        ]
+        uppercase_indexes.append(len(short_name))
+        words = [
+            short_name[uppercase_indexes[i] : uppercase_indexes[i + 1]].upper()
+            for i in range(len(uppercase_indexes) - 1)
+        ]
+        opcode_name = "_".join(words)
+        opcode = Frame.OperationCode[opcode_name]
+        category_class.subclasses[opcode] = subclass
+        return subclass
+
+    @staticmethod
+    def from_bytes(data: bytes) -> Frame:
+        if data[0] >> 4 != 0:
+            raise ValueError("first 4 bits must be 0s")
+
+        ctype_or_response = data[0] & 0xF
+        subunit_type = Frame.SubunitType(data[1] >> 3)
+        subunit_id = data[1] & 7
+
+        if subunit_type == Frame.SubunitType.EXTENDED:
+            # Not supported
+            raise NotImplementedError("extended subunit types not supported")
+
+        if subunit_id < 5:
+            opcode_offset = 2
+        elif subunit_id == 5:
+            # Extended to the next byte
+            extension = data[2]
+            if extension == 0:
+                raise ValueError("extended subunit ID value reserved")
+            if extension == 0xFF:
+                subunit_id = 5 + 254 + data[3]
+                opcode_offset = 4
+            else:
+                subunit_id = 5 + extension
+                opcode_offset = 3
+
+        elif subunit_id == 6:
+            raise ValueError("reserved subunit ID")
+
+        opcode = Frame.OperationCode(data[opcode_offset])
+        operands = data[opcode_offset + 1 :]
+
+        # Look for a registered subclass
+        if ctype_or_response < 8:
+            # Command
+            ctype = CommandFrame.CommandType(ctype_or_response)
+            if c_subclass := CommandFrame.subclasses.get(opcode):
+                return c_subclass(
+                    ctype,
+                    subunit_type,
+                    subunit_id,
+                    *c_subclass.parse_operands(operands),
+                )
+            return CommandFrame(ctype, subunit_type, subunit_id, opcode, operands)
+        else:
+            # Response
+            response = ResponseFrame.ResponseCode(ctype_or_response)
+            if r_subclass := ResponseFrame.subclasses.get(opcode):
+                return r_subclass(
+                    response,
+                    subunit_type,
+                    subunit_id,
+                    *r_subclass.parse_operands(operands),
+                )
+            return ResponseFrame(response, subunit_type, subunit_id, opcode, operands)
+
+    def to_bytes(
+        self,
+        ctype_or_response: Union[CommandFrame.CommandType, ResponseFrame.ResponseCode],
+    ) -> bytes:
+        # TODO: support extended subunit types and ids.
+        return (
+            bytes(
+                [
+                    ctype_or_response,
+                    self.subunit_type << 3 | self.subunit_id,
+                    self.opcode,
+                ]
+            )
+            + self.operands
+        )
+
+    def to_string(self, extra: str) -> str:
+        return (
+            f"{self.__class__.__name__}({extra}"
+            f"subunit_type={self.subunit_type.name}, "
+            f"subunit_id=0x{self.subunit_id:02X}, "
+            f"opcode={self.opcode.name}, "
+            f"operands={self.operands.hex()})"
+        )
+
+    def __init__(
+        self,
+        subunit_type: SubunitType,
+        subunit_id: int,
+        opcode: OperationCode,
+        operands: bytes,
+    ) -> None:
+        self.subunit_type = subunit_type
+        self.subunit_id = subunit_id
+        self.opcode = opcode
+        self.operands = operands
+
+
+# -----------------------------------------------------------------------------
+class CommandFrame(Frame):
+    class CommandType(OpenIntEnum):
+        # AV/C Digital Interface Command Set General Specification Version 4.1
+        # Table 7.1
+        CONTROL = 0x00
+        STATUS = 0x01
+        SPECIFIC_INQUIRY = 0x02
+        NOTIFY = 0x03
+        GENERAL_INQUIRY = 0x04
+
+    subclasses: Dict[Frame.OperationCode, Type[CommandFrame]] = {}
+    ctype: CommandType
+
+    @staticmethod
+    def parse_operands(operands: bytes) -> Tuple:
+        raise NotImplementedError
+
+    def __init__(
+        self,
+        ctype: CommandType,
+        subunit_type: Frame.SubunitType,
+        subunit_id: int,
+        opcode: Frame.OperationCode,
+        operands: bytes,
+    ) -> None:
+        super().__init__(subunit_type, subunit_id, opcode, operands)
+        self.ctype = ctype
+
+    def __bytes__(self):
+        return self.to_bytes(self.ctype)
+
+    def __str__(self):
+        return self.to_string(f"ctype={self.ctype.name}, ")
+
+
+# -----------------------------------------------------------------------------
+class ResponseFrame(Frame):
+    class ResponseCode(OpenIntEnum):
+        # AV/C Digital Interface Command Set General Specification Version 4.1
+        # Table 7.2
+        NOT_IMPLEMENTED = 0x08
+        ACCEPTED = 0x09
+        REJECTED = 0x0A
+        IN_TRANSITION = 0x0B
+        IMPLEMENTED_OR_STABLE = 0x0C
+        CHANGED = 0x0D
+        INTERIM = 0x0F
+
+    subclasses: Dict[Frame.OperationCode, Type[ResponseFrame]] = {}
+    response: ResponseCode
+
+    @staticmethod
+    def parse_operands(operands: bytes) -> Tuple:
+        raise NotImplementedError
+
+    def __init__(
+        self,
+        response: ResponseCode,
+        subunit_type: Frame.SubunitType,
+        subunit_id: int,
+        opcode: Frame.OperationCode,
+        operands: bytes,
+    ) -> None:
+        super().__init__(subunit_type, subunit_id, opcode, operands)
+        self.response = response
+
+    def __bytes__(self):
+        return self.to_bytes(self.response)
+
+    def __str__(self):
+        return self.to_string(f"response={self.response.name}, ")
+
+
+# -----------------------------------------------------------------------------
+class VendorDependentFrame:
+    company_id: int
+    vendor_dependent_data: bytes
+
+    @staticmethod
+    def parse_operands(operands: bytes) -> Tuple:
+        return (
+            struct.unpack(">I", b"\x00" + operands[:3])[0],
+            operands[3:],
+        )
+
+    def make_operands(self) -> bytes:
+        return struct.pack(">I", self.company_id)[1:] + self.vendor_dependent_data
+
+    def __init__(self, company_id: int, vendor_dependent_data: bytes):
+        self.company_id = company_id
+        self.vendor_dependent_data = vendor_dependent_data
+
+
+# -----------------------------------------------------------------------------
+@Frame.subclass
+class VendorDependentCommandFrame(VendorDependentFrame, CommandFrame):
+    def __init__(
+        self,
+        ctype: CommandFrame.CommandType,
+        subunit_type: Frame.SubunitType,
+        subunit_id: int,
+        company_id: int,
+        vendor_dependent_data: bytes,
+    ) -> None:
+        VendorDependentFrame.__init__(self, company_id, vendor_dependent_data)
+        CommandFrame.__init__(
+            self,
+            ctype,
+            subunit_type,
+            subunit_id,
+            Frame.OperationCode.VENDOR_DEPENDENT,
+            self.make_operands(),
+        )
+
+    def __str__(self):
+        return (
+            f"VendorDependentCommandFrame(ctype={self.ctype.name}, "
+            f"subunit_type={self.subunit_type.name}, "
+            f"subunit_id=0x{self.subunit_id:02X}, "
+            f"company_id=0x{self.company_id:06X}, "
+            f"vendor_dependent_data={self.vendor_dependent_data.hex()})"
+        )
+
+
+# -----------------------------------------------------------------------------
+@Frame.subclass
+class VendorDependentResponseFrame(VendorDependentFrame, ResponseFrame):
+    def __init__(
+        self,
+        response: ResponseFrame.ResponseCode,
+        subunit_type: Frame.SubunitType,
+        subunit_id: int,
+        company_id: int,
+        vendor_dependent_data: bytes,
+    ) -> None:
+        VendorDependentFrame.__init__(self, company_id, vendor_dependent_data)
+        ResponseFrame.__init__(
+            self,
+            response,
+            subunit_type,
+            subunit_id,
+            Frame.OperationCode.VENDOR_DEPENDENT,
+            self.make_operands(),
+        )
+
+    def __str__(self):
+        return (
+            f"VendorDependentResponseFrame(response={self.response.name}, "
+            f"subunit_type={self.subunit_type.name}, "
+            f"subunit_id=0x{self.subunit_id:02X}, "
+            f"company_id=0x{self.company_id:06X}, "
+            f"vendor_dependent_data={self.vendor_dependent_data.hex()})"
+        )
+
+
+# -----------------------------------------------------------------------------
+class PassThroughFrame:
+    """
+    See AV/C Panel Subunit Specification 1.1 - 9.4 PASS THROUGH control command
+    """
+
+    class StateFlag(enum.IntEnum):
+        PRESSED = 0
+        RELEASED = 1
+
+    class OperationId(OpenIntEnum):
+        SELECT = 0x00
+        UP = 0x01
+        DOWN = 0x01
+        LEFT = 0x03
+        RIGHT = 0x04
+        RIGHT_UP = 0x05
+        RIGHT_DOWN = 0x06
+        LEFT_UP = 0x07
+        LEFT_DOWN = 0x08
+        ROOT_MENU = 0x09
+        SETUP_MENU = 0x0A
+        CONTENTS_MENU = 0x0B
+        FAVORITE_MENU = 0x0C
+        EXIT = 0x0D
+        NUMBER_0 = 0x20
+        NUMBER_1 = 0x21
+        NUMBER_2 = 0x22
+        NUMBER_3 = 0x23
+        NUMBER_4 = 0x24
+        NUMBER_5 = 0x25
+        NUMBER_6 = 0x26
+        NUMBER_7 = 0x27
+        NUMBER_8 = 0x28
+        NUMBER_9 = 0x29
+        DOT = 0x2A
+        ENTER = 0x2B
+        CLEAR = 0x2C
+        CHANNEL_UP = 0x30
+        CHANNEL_DOWN = 0x31
+        PREVIOUS_CHANNEL = 0x32
+        SOUND_SELECT = 0x33
+        INPUT_SELECT = 0x34
+        DISPLAY_INFORMATION = 0x35
+        HELP = 0x36
+        PAGE_UP = 0x37
+        PAGE_DOWN = 0x38
+        POWER = 0x40
+        VOLUME_UP = 0x41
+        VOLUME_DOWN = 0x42
+        MUTE = 0x43
+        PLAY = 0x44
+        STOP = 0x45
+        PAUSE = 0x46
+        RECORD = 0x47
+        REWIND = 0x48
+        FAST_FORWARD = 0x49
+        EJECT = 0x4A
+        FORWARD = 0x4B
+        BACKWARD = 0x4C
+        ANGLE = 0x50
+        SUBPICTURE = 0x51
+        F1 = 0x71
+        F2 = 0x72
+        F3 = 0x73
+        F4 = 0x74
+        F5 = 0x75
+        VENDOR_UNIQUE = 0x7E
+
+    state_flag: StateFlag
+    operation_id: OperationId
+    operation_data: bytes
+
+    @staticmethod
+    def parse_operands(operands: bytes) -> Tuple:
+        return (
+            PassThroughFrame.StateFlag(operands[0] >> 7),
+            PassThroughFrame.OperationId(operands[0] & 0x7F),
+            operands[1 : 1 + operands[1]],
+        )
+
+    def make_operands(self):
+        return (
+            bytes([self.state_flag << 7 | self.operation_id, len(self.operation_data)])
+            + self.operation_data
+        )
+
+    def __init__(
+        self,
+        state_flag: StateFlag,
+        operation_id: OperationId,
+        operation_data: bytes,
+    ) -> None:
+        if len(operation_data) > 255:
+            raise ValueError("operation data must be <= 255 bytes")
+        self.state_flag = state_flag
+        self.operation_id = operation_id
+        self.operation_data = operation_data
+
+
+# -----------------------------------------------------------------------------
+@Frame.subclass
+class PassThroughCommandFrame(PassThroughFrame, CommandFrame):
+    def __init__(
+        self,
+        ctype: CommandFrame.CommandType,
+        subunit_type: Frame.SubunitType,
+        subunit_id: int,
+        state_flag: PassThroughFrame.StateFlag,
+        operation_id: PassThroughFrame.OperationId,
+        operation_data: bytes,
+    ) -> None:
+        PassThroughFrame.__init__(self, state_flag, operation_id, operation_data)
+        CommandFrame.__init__(
+            self,
+            ctype,
+            subunit_type,
+            subunit_id,
+            Frame.OperationCode.PASS_THROUGH,
+            self.make_operands(),
+        )
+
+    def __str__(self):
+        return (
+            f"PassThroughCommandFrame(ctype={self.ctype.name}, "
+            f"subunit_type={self.subunit_type.name}, "
+            f"subunit_id=0x{self.subunit_id:02X}, "
+            f"state_flag={self.state_flag.name}, "
+            f"operation_id={self.operation_id.name}, "
+            f"operation_data={self.operation_data.hex()})"
+        )
+
+
+# -----------------------------------------------------------------------------
+@Frame.subclass
+class PassThroughResponseFrame(PassThroughFrame, ResponseFrame):
+    def __init__(
+        self,
+        response: ResponseFrame.ResponseCode,
+        subunit_type: Frame.SubunitType,
+        subunit_id: int,
+        state_flag: PassThroughFrame.StateFlag,
+        operation_id: PassThroughFrame.OperationId,
+        operation_data: bytes,
+    ) -> None:
+        PassThroughFrame.__init__(self, state_flag, operation_id, operation_data)
+        ResponseFrame.__init__(
+            self,
+            response,
+            subunit_type,
+            subunit_id,
+            Frame.OperationCode.PASS_THROUGH,
+            self.make_operands(),
+        )
+
+    def __str__(self):
+        return (
+            f"PassThroughResponseFrame(response={self.response.name}, "
+            f"subunit_type={self.subunit_type.name}, "
+            f"subunit_id=0x{self.subunit_id:02X}, "
+            f"state_flag={self.state_flag.name}, "
+            f"operation_id={self.operation_id.name}, "
+            f"operation_data={self.operation_data.hex()})"
+        )

bumble/avctp.py

@@ -0,0 +1,291 @@
+# 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.
+
+# -----------------------------------------------------------------------------
+# Imports
+# -----------------------------------------------------------------------------
+from __future__ import annotations
+from enum import IntEnum
+import logging
+import struct
+from typing import Callable, cast, Dict, Optional
+
+from bumble.colors import color
+from bumble import avc
+from bumble import l2cap
+
+# -----------------------------------------------------------------------------
+# Logging
+# -----------------------------------------------------------------------------
+logger = logging.getLogger(__name__)
+
+
+# -----------------------------------------------------------------------------
+# Constants
+# -----------------------------------------------------------------------------
+AVCTP_PSM = 0x0017
+AVCTP_BROWSING_PSM = 0x001B
+
+
+# -----------------------------------------------------------------------------
+class MessageAssembler:
+    Callback = Callable[[int, bool, bool, int, bytes], None]
+
+    transaction_label: int
+    pid: int
+    c_r: int
+    ipid: int
+    payload: bytes
+    number_of_packets: int
+    packets_received: int
+
+    def __init__(self, callback: Callback) -> None:
+        self.callback = callback
+        self.reset()
+
+    def reset(self) -> None:
+        self.packets_received = 0
+        self.transaction_label = -1
+        self.pid = -1
+        self.c_r = -1
+        self.ipid = -1
+        self.payload = b''
+        self.number_of_packets = 0
+        self.packet_count = 0
+
+    def on_pdu(self, pdu: bytes) -> None:
+        self.packets_received += 1
+
+        transaction_label = pdu[0] >> 4
+        packet_type = Protocol.PacketType((pdu[0] >> 2) & 3)
+        c_r = (pdu[0] >> 1) & 1
+        ipid = pdu[0] & 1
+
+        if c_r == 0 and ipid != 0:
+            logger.warning("invalid IPID in command frame")
+            self.reset()
+            return
+
+        pid_offset = 1
+        if packet_type in (Protocol.PacketType.SINGLE, Protocol.PacketType.START):
+            if self.transaction_label >= 0:
+                # We are already in a transaction
+                logger.warning("received START or SINGLE fragment while in transaction")
+                self.reset()
+                self.packets_received = 1
+
+            if packet_type == Protocol.PacketType.START:
+                self.number_of_packets = pdu[1]
+                pid_offset = 2
+
+        pid = struct.unpack_from(">H", pdu, pid_offset)[0]
+        self.payload += pdu[pid_offset + 2 :]
+
+        if packet_type in (Protocol.PacketType.CONTINUE, Protocol.PacketType.END):
+            if transaction_label != self.transaction_label:
+                logger.warning("transaction label does not match")
+                self.reset()
+                return
+
+            if pid != self.pid:
+                logger.warning("PID does not match")
+                self.reset()
+                return
+
+            if c_r != self.c_r:
+                logger.warning("C/R does not match")
+                self.reset()
+                return
+
+            if self.packets_received > self.number_of_packets:
+                logger.warning("too many fragments in transaction")
+                self.reset()
+                return
+
+            if packet_type == Protocol.PacketType.END:
+                if self.packets_received != self.number_of_packets:
+                    logger.warning("premature END")
+                    self.reset()
+                    return
+        else:
+            self.transaction_label = transaction_label
+            self.c_r = c_r
+            self.ipid = ipid
+            self.pid = pid
+
+        if packet_type in (Protocol.PacketType.SINGLE, Protocol.PacketType.END):
+            self.on_message_complete()
+
+    def on_message_complete(self):
+        try:
+            self.callback(
+                self.transaction_label,
+                self.c_r == 0,
+                self.ipid != 0,
+                self.pid,
+                self.payload,
+            )
+        except Exception as error:
+            logger.exception(color(f"!!! exception in callback: {error}", "red"))
+
+        self.reset()
+
+
+# -----------------------------------------------------------------------------
+class Protocol:
+    CommandHandler = Callable[[int, avc.CommandFrame], None]
+    command_handlers: Dict[int, CommandHandler]  # Command handlers, by PID
+    ResponseHandler = Callable[[int, Optional[avc.ResponseFrame]], None]
+    response_handlers: Dict[int, ResponseHandler]  # Response handlers, by PID
+    next_transaction_label: int
+    message_assembler: MessageAssembler
+
+    class PacketType(IntEnum):
+        SINGLE = 0b00
+        START = 0b01
+        CONTINUE = 0b10
+        END = 0b11
+
+    def __init__(self, l2cap_channel: l2cap.ClassicChannel) -> None:
+        self.command_handlers = {}
+        self.response_handlers = {}
+        self.l2cap_channel = l2cap_channel
+        self.message_assembler = MessageAssembler(self.on_message)
+
+        # Register to receive PDUs from the channel
+        l2cap_channel.sink = self.on_pdu
+        l2cap_channel.on("open", self.on_l2cap_channel_open)
+        l2cap_channel.on("close", self.on_l2cap_channel_close)
+
+    def on_l2cap_channel_open(self):
+        logger.debug(color("<<< AVCTP channel open", "magenta"))
+
+    def on_l2cap_channel_close(self):
+        logger.debug(color("<<< AVCTP channel closed", "magenta"))
+
+    def on_pdu(self, pdu: bytes) -> None:
+        self.message_assembler.on_pdu(pdu)
+
+    def on_message(
+        self,
+        transaction_label: int,
+        is_command: bool,
+        ipid: bool,
+        pid: int,
+        payload: bytes,
+    ) -> None:
+        logger.debug(
+            f"<<< AVCTP Message: pid={pid}, "
+            f"transaction_label={transaction_label}, "
+            f"is_command={is_command}, "
+            f"ipid={ipid}, "
+            f"payload={payload.hex()}"
+        )
+
+        # Check for invalid PID responses.
+        if ipid:
+            logger.debug(f"received IPID for PID={pid}")
+
+        # Find the appropriate handler.
+        if is_command:
+            if pid not in self.command_handlers:
+                logger.warning(f"no command handler for PID {pid}")
+                self.send_ipid(transaction_label, pid)
+                return
+
+            command_frame = cast(avc.CommandFrame, avc.Frame.from_bytes(payload))
+            self.command_handlers[pid](transaction_label, command_frame)
+        else:
+            if pid not in self.response_handlers:
+                logger.warning(f"no response handler for PID {pid}")
+                return
+
+            # By convention, for an ipid, send a None payload to the response handler.
+            if ipid:
+                response_frame = None
+            else:
+                response_frame = cast(avc.ResponseFrame, avc.Frame.from_bytes(payload))
+
+            self.response_handlers[pid](transaction_label, response_frame)
+
+    def send_message(
+        self,
+        transaction_label: int,
+        is_command: bool,
+        ipid: bool,
+        pid: int,
+        payload: bytes,
+    ):
+        # TODO: fragment large messages
+        packet_type = Protocol.PacketType.SINGLE
+        pdu = (
+            struct.pack(
+                ">BH",
+                transaction_label << 4
+                | packet_type << 2
+                | (0 if is_command else 1) << 1
+                | (1 if ipid else 0),
+                pid,
+            )
+            + payload
+        )
+        self.l2cap_channel.send_pdu(pdu)
+
+    def send_command(self, transaction_label: int, pid: int, payload: bytes) -> None:
+        logger.debug(
+            ">>> AVCTP command: "
+            f"transaction_label={transaction_label}, "
+            f"pid={pid}, "
+            f"payload={payload.hex()}"
+        )
+        self.send_message(transaction_label, True, False, pid, payload)
+
+    def send_response(self, transaction_label: int, pid: int, payload: bytes):
+        logger.debug(
+            ">>> AVCTP response: "
+            f"transaction_label={transaction_label}, "
+            f"pid={pid}, "
+            f"payload={payload.hex()}"
+        )
+        self.send_message(transaction_label, False, False, pid, payload)
+
+    def send_ipid(self, transaction_label: int, pid: int) -> None:
+        logger.debug(
+            ">>> AVCTP ipid: " f"transaction_label={transaction_label}, " f"pid={pid}"
+        )
+        self.send_message(transaction_label, False, True, pid, b'')
+
+    def register_command_handler(
+        self, pid: int, handler: Protocol.CommandHandler
+    ) -> None:
+        self.command_handlers[pid] = handler
+
+    def unregister_command_handler(
+        self, pid: int, handler: Protocol.CommandHandler
+    ) -> None:
+        if pid not in self.command_handlers or self.command_handlers[pid] != handler:
+            raise ValueError("command handler not registered")
+        del self.command_handlers[pid]
+
+    def register_response_handler(
+        self, pid: int, handler: Protocol.ResponseHandler
+    ) -> None:
+        self.response_handlers[pid] = handler
+
+    def unregister_response_handler(
+        self, pid: int, handler: Protocol.ResponseHandler
+    ) -> None:
+        if pid not in self.response_handlers or self.response_handlers[pid] != handler:
+            raise ValueError("response handler not registered")
+        del self.response_handlers[pid]

bumble/avdtp.py

@@ -241,7 +241,10 @@ async def find_avdtp_service_with_sdp_client(
         )
         if profile_descriptor_list:
             for profile_descriptor in profile_descriptor_list.value:
-                if len(profile_descriptor.value) >= 2:
+                if (
+                    profile_descriptor.type == sdp.DataElement.SEQUENCE
+                    and len(profile_descriptor.value) >= 2
+                ):
                     avdtp_version_major = profile_descriptor.value[1].value >> 8
                     avdtp_version_minor = profile_descriptor.value[1].value & 0xFF
                     return (avdtp_version_major, avdtp_version_minor)
@@ -322,8 +325,8 @@ class MediaPacket:
         self.padding = padding
         self.extension = extension
         self.marker = marker
-        self.sequence_number = sequence_number
-        self.timestamp = timestamp
+        self.sequence_number = sequence_number & 0xFFFF
+        self.timestamp = timestamp & 0xFFFFFFFF
         self.ssrc = ssrc
         self.csrc_list = csrc_list
         self.payload_type = payload_type
@@ -338,7 +341,12 @@ class MediaPacket:
                 | len(self.csrc_list),
                 self.marker << 7 | self.payload_type,
             ]
-        ) + struct.pack('>HII', self.sequence_number, self.timestamp, self.ssrc)
+        ) + struct.pack(
+            '>HII',
+            self.sequence_number,
+            self.timestamp,
+            self.ssrc,
+        )
         for csrc in self.csrc_list:
             header += struct.pack('>I', csrc)
         return header + self.payload
@@ -511,7 +519,8 @@ class MessageAssembler:
         try:
             self.callback(self.transaction_label, message)
         except Exception as error:
-            logger.warning(color(f'!!! exception in callback: {error}'))
+            logger.exception(color(f'!!! exception in callback: {error}', 'red'))
+
         self.reset()
 
 
@@ -1466,10 +1475,10 @@ class Protocol(EventEmitter):
             f'[{transaction_label}] {message}'
         )
         max_fragment_size = (
-            self.l2cap_channel.mtu - 3
+            self.l2cap_channel.peer_mtu - 3
         )  # Enough space for a 3-byte start packet header
         payload = message.payload
-        if len(payload) + 2 <= self.l2cap_channel.mtu:
+        if len(payload) + 2 <= self.l2cap_channel.peer_mtu:
             # Fits in a single packet
             packet_type = self.PacketType.SINGLE_PACKET
         else:
@@ -1541,9 +1550,10 @@ class Protocol(EventEmitter):
 
         assert False  # Should never reach this
 
-    async def get_capabilities(
-        self, seid: int
-    ) -> Union[Get_Capabilities_Response, Get_All_Capabilities_Response,]:
+    async def get_capabilities(self, seid: int) -> Union[
+        Get_Capabilities_Response,
+        Get_All_Capabilities_Response,
+    ]:
         if self.version > (1, 2):
             return await self.send_command(Get_All_Capabilities_Command(seid))
 

bumble/controller.py

@@ -19,6 +19,7 @@ from __future__ import annotations
 
 import logging
 import asyncio
+import dataclasses
 import itertools
 import random
 import struct
@@ -42,6 +43,7 @@ from bumble.hci import (
     HCI_LE_1M_PHY,
     HCI_SUCCESS,
     HCI_UNKNOWN_HCI_COMMAND_ERROR,
+    HCI_UNKNOWN_CONNECTION_IDENTIFIER_ERROR,
     HCI_REMOTE_USER_TERMINATED_CONNECTION_ERROR,
     HCI_VERSION_BLUETOOTH_CORE_5_0,
     Address,
@@ -53,17 +55,21 @@ from bumble.hci import (
     HCI_Connection_Request_Event,
     HCI_Disconnection_Complete_Event,
     HCI_Encryption_Change_Event,
+    HCI_Synchronous_Connection_Complete_Event,
     HCI_LE_Advertising_Report_Event,
+    HCI_LE_CIS_Established_Event,
+    HCI_LE_CIS_Request_Event,
     HCI_LE_Connection_Complete_Event,
     HCI_LE_Read_Remote_Features_Complete_Event,
     HCI_Number_Of_Completed_Packets_Event,
     HCI_Packet,
     HCI_Role_Change_Event,
 )
-from typing import Optional, Union, Dict, TYPE_CHECKING
+from typing import Optional, Union, Dict, Any, TYPE_CHECKING
 
 if TYPE_CHECKING:
-    from bumble.transport.common import TransportSink, TransportSource
+    from bumble.link import LocalLink
+    from bumble.transport.common import TransportSink
 
 # -----------------------------------------------------------------------------
 # Logging
@@ -79,15 +85,27 @@ class DataObject:
 
 
 # -----------------------------------------------------------------------------
+@dataclasses.dataclass
+class CisLink:
+    handle: int
+    cis_id: int
+    cig_id: int
+    acl_connection: Optional[Connection] = None
+
+
+# -----------------------------------------------------------------------------
+@dataclasses.dataclass
 class Connection:
-    def __init__(self, controller, handle, role, peer_address, link, transport):
-        self.controller = controller
-        self.handle = handle
-        self.role = role
-        self.peer_address = peer_address
-        self.link = link
+    controller: Controller
+    handle: int
+    role: int
+    peer_address: Address
+    link: Any
+    transport: int
+    link_type: int
+
+    def __post_init__(self):
         self.assembler = HCI_AclDataPacketAssembler(self.on_acl_pdu)
-        self.transport = transport
 
     def on_hci_acl_data_packet(self, packet):
         self.assembler.feed_packet(packet)
@@ -106,25 +124,27 @@ class Connection:
 class Controller:
     def __init__(
         self,
-        name,
+        name: str,
         host_source=None,
         host_sink: Optional[TransportSink] = None,
-        link=None,
+        link: Optional[LocalLink] = None,
         public_address: Optional[Union[bytes, str, Address]] = None,
     ):
         self.name = name
         self.hci_sink = None
         self.link = link
 
-        self.central_connections: Dict[
-            Address, Connection
-        ] = {}  # Connections where this controller is the central
-        self.peripheral_connections: Dict[
-            Address, Connection
-        ] = {}  # Connections where this controller is the peripheral
-        self.classic_connections: Dict[
-            Address, Connection
-        ] = {}  # Connections in BR/EDR
+        self.central_connections: Dict[Address, Connection] = (
+            {}
+        )  # Connections where this controller is the central
+        self.peripheral_connections: Dict[Address, Connection] = (
+            {}
+        )  # Connections where this controller is the peripheral
+        self.classic_connections: Dict[Address, Connection] = (
+            {}
+        )  # Connections in BR/EDR
+        self.central_cis_links: Dict[int, CisLink] = {}  # CIS links by handle
+        self.peripheral_cis_links: Dict[int, CisLink] = {}  # CIS links by handle
 
         self.hci_version = HCI_VERSION_BLUETOOTH_CORE_5_0
         self.hci_revision = 0
@@ -134,12 +154,14 @@ class Controller:
             '0000000060000000'
         )  # BR/EDR Not Supported, LE Supported (Controller)
         self.manufacturer_name = 0xFFFF
+        self.hc_data_packet_length = 27
+        self.hc_total_num_data_packets = 64
         self.hc_le_data_packet_length = 27
         self.hc_total_num_le_data_packets = 64
         self.event_mask = 0
         self.event_mask_page_2 = 0
         self.supported_commands = bytes.fromhex(
-            '2000800000c000000000e40000002822000000000000040000f7ffff7f000000'
+            '2000800000c000000000e4000000a822000000000000040000f7ffff7f000000'
             '30f0f9ff01008004000000000000000000000000000000000000000000000000'
         )
         self.le_event_mask = 0
@@ -301,7 +323,7 @@ class Controller:
     ############################################################
     # Link connections
     ############################################################
-    def allocate_connection_handle(self):
+    def allocate_connection_handle(self) -> int:
         handle = 0
         max_handle = 0
         for connection in itertools.chain(
@@ -313,6 +335,13 @@ class Controller:
             if connection.handle == handle:
                 # Already used, continue searching after the current max
                 handle = max_handle + 1
+        for cis_handle in itertools.chain(
+            self.central_cis_links.keys(), self.peripheral_cis_links.keys()
+        ):
+            max_handle = max(max_handle, cis_handle)
+            if cis_handle == handle:
+                # Already used, continue searching after the current max
+                handle = max_handle + 1
         return handle
 
     def find_le_connection_by_address(self, address):
@@ -357,12 +386,13 @@ class Controller:
         if connection is None:
             connection_handle = self.allocate_connection_handle()
             connection = Connection(
-                self,
-                connection_handle,
-                BT_PERIPHERAL_ROLE,
-                peer_address,
-                self.link,
-                BT_LE_TRANSPORT,
+                controller=self,
+                handle=connection_handle,
+                role=BT_PERIPHERAL_ROLE,
+                peer_address=peer_address,
+                link=self.link,
+                transport=BT_LE_TRANSPORT,
+                link_type=HCI_Connection_Complete_Event.ACL_LINK_TYPE,
             )
             self.peripheral_connections[peer_address] = connection
             logger.debug(f'New PERIPHERAL connection handle: 0x{connection_handle:04X}')
@@ -416,12 +446,13 @@ class Controller:
             if connection is None:
                 connection_handle = self.allocate_connection_handle()
                 connection = Connection(
-                    self,
-                    connection_handle,
-                    BT_CENTRAL_ROLE,
-                    peer_address,
-                    self.link,
-                    BT_LE_TRANSPORT,
+                    controller=self,
+                    handle=connection_handle,
+                    role=BT_CENTRAL_ROLE,
+                    peer_address=peer_address,
+                    link=self.link,
+                    transport=BT_LE_TRANSPORT,
+                    link_type=HCI_Connection_Complete_Event.ACL_LINK_TYPE,
                 )
                 self.central_connections[peer_address] = connection
                 logger.debug(
@@ -538,6 +569,104 @@ class Controller:
         )
         self.send_hci_packet(HCI_LE_Advertising_Report_Event([report]))
 
+    def on_link_cis_request(
+        self, central_address: Address, cig_id: int, cis_id: int
+    ) -> None:
+        '''
+        Called when an incoming CIS request occurs from a central on the link
+        '''
+
+        connection = self.peripheral_connections.get(central_address)
+        assert connection
+
+        pending_cis_link = CisLink(
+            handle=self.allocate_connection_handle(),
+            cis_id=cis_id,
+            cig_id=cig_id,
+            acl_connection=connection,
+        )
+        self.peripheral_cis_links[pending_cis_link.handle] = pending_cis_link
+
+        self.send_hci_packet(
+            HCI_LE_CIS_Request_Event(
+                acl_connection_handle=connection.handle,
+                cis_connection_handle=pending_cis_link.handle,
+                cig_id=cig_id,
+                cis_id=cis_id,
+            )
+        )
+
+    def on_link_cis_established(self, cig_id: int, cis_id: int) -> None:
+        '''
+        Called when an incoming CIS established.
+        '''
+
+        cis_link = next(
+            cis_link
+            for cis_link in itertools.chain(
+                self.central_cis_links.values(), self.peripheral_cis_links.values()
+            )
+            if cis_link.cis_id == cis_id and cis_link.cig_id == cig_id
+        )
+
+        self.send_hci_packet(
+            HCI_LE_CIS_Established_Event(
+                status=HCI_SUCCESS,
+                connection_handle=cis_link.handle,
+                # CIS parameters are ignored.
+                cig_sync_delay=0,
+                cis_sync_delay=0,
+                transport_latency_c_to_p=0,
+                transport_latency_p_to_c=0,
+                phy_c_to_p=0,
+                phy_p_to_c=0,
+                nse=0,
+                bn_c_to_p=0,
+                bn_p_to_c=0,
+                ft_c_to_p=0,
+                ft_p_to_c=0,
+                max_pdu_c_to_p=0,
+                max_pdu_p_to_c=0,
+                iso_interval=0,
+            )
+        )
+
+    def on_link_cis_disconnected(self, cig_id: int, cis_id: int) -> None:
+        '''
+        Called when a CIS disconnected.
+        '''
+
+        if cis_link := next(
+            (
+                cis_link
+                for cis_link in self.peripheral_cis_links.values()
+                if cis_link.cis_id == cis_id and cis_link.cig_id == cig_id
+            ),
+            None,
+        ):
+            # Remove peripheral CIS on disconnection.
+            self.peripheral_cis_links.pop(cis_link.handle)
+        elif cis_link := next(
+            (
+                cis_link
+                for cis_link in self.central_cis_links.values()
+                if cis_link.cis_id == cis_id and cis_link.cig_id == cig_id
+            ),
+            None,
+        ):
+            # Keep central CIS on disconnection. They should be removed by HCI_LE_Remove_CIG_Command.
+            cis_link.acl_connection = None
+        else:
+            return
+
+        self.send_hci_packet(
+            HCI_Disconnection_Complete_Event(
+                status=HCI_SUCCESS,
+                connection_handle=cis_link.handle,
+                reason=HCI_REMOTE_USER_TERMINATED_CONNECTION_ERROR,
+            )
+        )
+
     ############################################################
     # Classic link connections
     ############################################################
@@ -566,6 +695,7 @@ class Controller:
                     peer_address=peer_address,
                     link=self.link,
                     transport=BT_BR_EDR_TRANSPORT,
+                    link_type=HCI_Connection_Complete_Event.ACL_LINK_TYPE,
                 )
                 self.classic_connections[peer_address] = connection
                 logger.debug(
@@ -619,6 +749,42 @@ class Controller:
             )
         )
 
+    def on_classic_sco_connection_complete(
+        self, peer_address: Address, status: int, link_type: int
+    ):
+        if status == HCI_SUCCESS:
+            # Allocate (or reuse) a connection handle
+            connection_handle = self.allocate_connection_handle()
+            connection = Connection(
+                controller=self,
+                handle=connection_handle,
+                # Role doesn't matter in SCO.
+                role=BT_CENTRAL_ROLE,
+                peer_address=peer_address,
+                link=self.link,
+                transport=BT_BR_EDR_TRANSPORT,
+                link_type=link_type,
+            )
+            self.classic_connections[peer_address] = connection
+            logger.debug(f'New SCO connection handle: 0x{connection_handle:04X}')
+        else:
+            connection_handle = 0
+
+        self.send_hci_packet(
+            HCI_Synchronous_Connection_Complete_Event(
+                status=status,
+                connection_handle=connection_handle,
+                bd_addr=peer_address,
+                link_type=link_type,
+                # TODO: Provide SCO connection parameters.
+                transmission_interval=0,
+                retransmission_window=0,
+                rx_packet_length=0,
+                tx_packet_length=0,
+                air_mode=0,
+            )
+        )
+
     ############################################################
     # Advertising support
     ############################################################
@@ -721,6 +887,17 @@ class Controller:
             else:
                 # Remove the connection
                 del self.classic_connections[connection.peer_address]
+        elif cis_link := (
+            self.central_cis_links.get(handle) or self.peripheral_cis_links.get(handle)
+        ):
+            if self.link:
+                self.link.disconnect_cis(
+                    initiator_controller=self,
+                    peer_address=cis_link.acl_connection.peer_address,
+                    cig_id=cis_link.cig_id,
+                    cis_id=cis_link.cis_id,
+                )
+            # Spec requires handle to be kept after disconnection.
 
     def on_hci_accept_connection_request_command(self, command):
         '''
@@ -738,6 +915,68 @@ class Controller:
         )
         self.link.classic_accept_connection(self, command.bd_addr, command.role)
 
+    def on_hci_enhanced_setup_synchronous_connection_command(self, command):
+        '''
+        See Bluetooth spec Vol 4, Part E - 7.1.45 Enhanced Setup Synchronous Connection command
+        '''
+
+        if self.link is None:
+            return
+
+        if not (
+            connection := self.find_classic_connection_by_handle(
+                command.connection_handle
+            )
+        ):
+            self.send_hci_packet(
+                HCI_Command_Status_Event(
+                    status=HCI_UNKNOWN_CONNECTION_IDENTIFIER_ERROR,
+                    num_hci_command_packets=1,
+                    command_opcode=command.op_code,
+                )
+            )
+            return
+
+        self.send_hci_packet(
+            HCI_Command_Status_Event(
+                status=HCI_SUCCESS,
+                num_hci_command_packets=1,
+                command_opcode=command.op_code,
+            )
+        )
+        self.link.classic_sco_connect(
+            self, connection.peer_address, HCI_Connection_Complete_Event.ESCO_LINK_TYPE
+        )
+
+    def on_hci_enhanced_accept_synchronous_connection_request_command(self, command):
+        '''
+        See Bluetooth spec Vol 4, Part E - 7.1.46 Enhanced Accept Synchronous Connection Request command
+        '''
+
+        if self.link is None:
+            return
+
+        if not (connection := self.find_classic_connection_by_address(command.bd_addr)):
+            self.send_hci_packet(
+                HCI_Command_Status_Event(
+                    status=HCI_UNKNOWN_CONNECTION_IDENTIFIER_ERROR,
+                    num_hci_command_packets=1,
+                    command_opcode=command.op_code,
+                )
+            )
+            return
+
+        self.send_hci_packet(
+            HCI_Command_Status_Event(
+                status=HCI_SUCCESS,
+                num_hci_command_packets=1,
+                command_opcode=command.op_code,
+            )
+        )
+        self.link.classic_accept_sco_connection(
+            self, connection.peer_address, HCI_Connection_Complete_Event.ESCO_LINK_TYPE
+        )
+
     def on_hci_switch_role_command(self, command):
         '''
         See Bluetooth spec Vol 4, Part E - 7.2.8 Switch Role command
@@ -912,7 +1151,41 @@ class Controller:
         '''
         See Bluetooth spec Vol 4, Part E - 7.4.3 Read Local Supported Features Command
         '''
-        return bytes([HCI_SUCCESS]) + self.lmp_features
+        return bytes([HCI_SUCCESS]) + self.lmp_features[:8]
+
+    def on_hci_read_local_extended_features_command(self, command):
+        '''
+        See Bluetooth spec Vol 4, Part E - 7.4.4 Read Local Extended Features Command
+        '''
+        if command.page_number * 8 > len(self.lmp_features):
+            return bytes([HCI_INVALID_HCI_COMMAND_PARAMETERS_ERROR])
+        return (
+            bytes(
+                [
+                    # Status
+                    HCI_SUCCESS,
+                    # Page number
+                    command.page_number,
+                    # Max page number
+                    len(self.lmp_features) // 8 - 1,
+                ]
+            )
+            # Features of the current page
+            + self.lmp_features[command.page_number * 8 : (command.page_number + 1) * 8]
+        )
+
+    def on_hci_read_buffer_size_command(self, _command):
+        '''
+        See Bluetooth spec Vol 4, Part E - 7.4.5 Read Buffer Size Command
+        '''
+        return struct.pack(
+            '<BHBHH',
+            HCI_SUCCESS,
+            self.hc_data_packet_length,
+            0,
+            self.hc_total_num_data_packets,
+            0,
+        )
 
     def on_hci_read_bd_addr_command(self, _command):
         '''
@@ -1089,6 +1362,18 @@ class Controller:
         See Bluetooth spec Vol 4, Part E - 7.8.21 LE Read Remote Features Command
         '''
 
+        handle = command.connection_handle
+
+        if not self.find_connection_by_handle(handle):
+            self.send_hci_packet(
+                HCI_Command_Status_Event(
+                    status=HCI_INVALID_HCI_COMMAND_PARAMETERS_ERROR,
+                    num_hci_command_packets=1,
+                    command_opcode=command.op_code,
+                )
+            )
+            return
+
         # First, say that the command is pending
         self.send_hci_packet(
             HCI_Command_Status_Event(
@@ -1102,7 +1387,7 @@ class Controller:
         self.send_hci_packet(
             HCI_LE_Read_Remote_Features_Complete_Event(
                 status=HCI_SUCCESS,
-                connection_handle=0,
+                connection_handle=handle,
                 le_features=bytes.fromhex('dd40000000000000'),
             )
         )
@@ -1258,8 +1543,135 @@ class Controller:
         }
         return bytes([HCI_SUCCESS])
 
+    def on_hci_le_read_maximum_advertising_data_length_command(self, _command):
+        '''
+        See Bluetooth spec Vol 4, Part E - 7.8.57 LE Read Maximum Advertising Data
+        Length Command
+        '''
+        return struct.pack('<BH', HCI_SUCCESS, 0x0672)
+
+    def on_hci_le_read_number_of_supported_advertising_sets_command(self, _command):
+        '''
+        See Bluetooth spec Vol 4, Part E - 7.8.58 LE Read Number of Supported
+        Advertising Set Command
+        '''
+        return struct.pack('<BB', HCI_SUCCESS, 0xF0)
+
     def on_hci_le_read_transmit_power_command(self, _command):
         '''
         See Bluetooth spec Vol 4, Part E - 7.8.74 LE Read Transmit Power Command
         '''
         return struct.pack('<BBB', HCI_SUCCESS, 0, 0)
+
+    def on_hci_le_set_cig_parameters_command(self, command):
+        '''
+        See Bluetooth spec Vol 4, Part E - 7.8.97 LE Set CIG Parameter Command
+        '''
+
+        # Remove old CIG implicitly.
+        for handle, cis_link in self.central_cis_links.items():
+            if cis_link.cig_id == command.cig_id:
+                self.central_cis_links.pop(handle)
+
+        handles = []
+        for cis_id in command.cis_id:
+            handle = self.allocate_connection_handle()
+            handles.append(handle)
+            self.central_cis_links[handle] = CisLink(
+                cis_id=cis_id,
+                cig_id=command.cig_id,
+                handle=handle,
+            )
+        return struct.pack(
+            '<BBB', HCI_SUCCESS, command.cig_id, len(handles)
+        ) + b''.join([struct.pack('<H', handle) for handle in handles])
+
+    def on_hci_le_create_cis_command(self, command):
+        '''
+        See Bluetooth spec Vol 4, Part E - 7.8.99 LE Create CIS Command
+        '''
+        if not self.link:
+            return
+
+        for cis_handle, acl_handle in zip(
+            command.cis_connection_handle, command.acl_connection_handle
+        ):
+            if not (connection := self.find_connection_by_handle(acl_handle)):
+                logger.error(f'Cannot find connection with handle={acl_handle}')
+                return bytes([HCI_INVALID_HCI_COMMAND_PARAMETERS_ERROR])
+
+            if not (cis_link := self.central_cis_links.get(cis_handle)):
+                logger.error(f'Cannot find CIS with handle={cis_handle}')
+                return bytes([HCI_INVALID_HCI_COMMAND_PARAMETERS_ERROR])
+
+            cis_link.acl_connection = connection
+
+            self.link.create_cis(
+                self,
+                peripheral_address=connection.peer_address,
+                cig_id=cis_link.cig_id,
+                cis_id=cis_link.cis_id,
+            )
+
+        self.send_hci_packet(
+            HCI_Command_Status_Event(
+                status=HCI_COMMAND_STATUS_PENDING,
+                num_hci_command_packets=1,
+                command_opcode=command.op_code,
+            )
+        )
+
+    def on_hci_le_remove_cig_command(self, command):
+        '''
+        See Bluetooth spec Vol 4, Part E - 7.8.100 LE Remove CIG Command
+        '''
+
+        status = HCI_UNKNOWN_CONNECTION_IDENTIFIER_ERROR
+
+        for cis_handle, cis_link in self.central_cis_links.items():
+            if cis_link.cig_id == command.cig_id:
+                self.central_cis_links.pop(cis_handle)
+                status = HCI_SUCCESS
+
+        return struct.pack('<BH', status, command.cig_id)
+
+    def on_hci_le_accept_cis_request_command(self, command):
+        '''
+        See Bluetooth spec Vol 4, Part E - 7.8.101 LE Accept CIS Request Command
+        '''
+        if not self.link:
+            return
+
+        if not (
+            pending_cis_link := self.peripheral_cis_links.get(command.connection_handle)
+        ):
+            logger.error(f'Cannot find CIS with handle={command.connection_handle}')
+            return bytes([HCI_INVALID_HCI_COMMAND_PARAMETERS_ERROR])
+
+        assert pending_cis_link.acl_connection
+        self.link.accept_cis(
+            peripheral_controller=self,
+            central_address=pending_cis_link.acl_connection.peer_address,
+            cig_id=pending_cis_link.cig_id,
+            cis_id=pending_cis_link.cis_id,
+        )
+
+        self.send_hci_packet(
+            HCI_Command_Status_Event(
+                status=HCI_COMMAND_STATUS_PENDING,
+                num_hci_command_packets=1,
+                command_opcode=command.op_code,
+            )
+        )
+
+    def on_hci_le_setup_iso_data_path_command(self, command):
+        '''
+        See Bluetooth spec Vol 4, Part E - 7.8.109 LE Setup ISO Data Path Command
+        '''
+        return struct.pack('<BH', HCI_SUCCESS, command.connection_handle)
+
+    def on_hci_le_remove_iso_data_path_command(self, command):
+        '''
+        See Bluetooth spec Vol 4, Part E - 7.8.110 LE Remove ISO Data Path Command
+        '''
+        return struct.pack('<BH', HCI_SUCCESS, command.connection_handle)

bumble/core.py

@@ -16,11 +16,14 @@
 # Imports
 # -----------------------------------------------------------------------------
 from __future__ import annotations
+import dataclasses
 import enum
 import struct
 from typing import List, Optional, Tuple, Union, cast, Dict
+from typing_extensions import Self
 
-from .company_ids import COMPANY_IDENTIFIERS
+from bumble.company_ids import COMPANY_IDENTIFIERS
+from bumble.utils import OpenIntEnum
 
 
 # -----------------------------------------------------------------------------
@@ -97,12 +100,16 @@ class BaseError(Exception):
             namespace = f'{self.error_namespace}/'
         else:
             namespace = ''
-        error_text = {
-            (True, True): f'{self.error_name} [0x{self.error_code:X}]',
-            (True, False): self.error_name,
-            (False, True): f'0x{self.error_code:X}',
-            (False, False): '',
-        }[(self.error_name != '', self.error_code is not None)]
+        have_name = self.error_name != ''
+        have_code = self.error_code is not None
+        if have_name and have_code:
+            error_text = f'{self.error_name} [0x{self.error_code:X}]'
+        elif have_name and not have_code:
+            error_text = self.error_name
+        elif not have_name and have_code:
+            error_text = f'0x{self.error_code:X}'
+        else:
+            error_text = '<unspecified>'
 
         return f'{type(self).__name__}({namespace}{error_text})'
 
@@ -319,7 +326,7 @@ BT_HIDP_PROTOCOL_ID                     = UUID.from_16_bits(0x0011, 'HIDP')
 BT_HARDCOPY_CONTROL_CHANNEL_PROTOCOL_ID = UUID.from_16_bits(0x0012, 'HardcopyControlChannel')
 BT_HARDCOPY_DATA_CHANNEL_PROTOCOL_ID    = UUID.from_16_bits(0x0014, 'HardcopyDataChannel')
 BT_HARDCOPY_NOTIFICATION_PROTOCOL_ID    = UUID.from_16_bits(0x0016, 'HardcopyNotification')
-BT_AVTCP_PROTOCOL_ID                    = UUID.from_16_bits(0x0017, 'AVCTP')
+BT_AVCTP_PROTOCOL_ID                    = UUID.from_16_bits(0x0017, 'AVCTP')
 BT_AVDTP_PROTOCOL_ID                    = UUID.from_16_bits(0x0019, 'AVDTP')
 BT_CMTP_PROTOCOL_ID                     = UUID.from_16_bits(0x001B, 'CMTP')
 BT_MCAP_CONTROL_CHANNEL_PROTOCOL_ID     = UUID.from_16_bits(0x001E, 'MCAPControlChannel')
@@ -688,11 +695,569 @@ class DeviceClass:
         return name_or_number(class_names, minor_device_class)
 
 
+# -----------------------------------------------------------------------------
+# Appearance
+# -----------------------------------------------------------------------------
+class Appearance:
+    class Category(OpenIntEnum):
+        UNKNOWN = 0x0000
+        PHONE = 0x0001
+        COMPUTER = 0x0002
+        WATCH = 0x0003
+        CLOCK = 0x0004
+        DISPLAY = 0x0005
+        REMOTE_CONTROL = 0x0006
+        EYE_GLASSES = 0x0007
+        TAG = 0x0008
+        KEYRING = 0x0009
+        MEDIA_PLAYER = 0x000A
+        BARCODE_SCANNER = 0x000B
+        THERMOMETER = 0x000C
+        HEART_RATE_SENSOR = 0x000D
+        BLOOD_PRESSURE = 0x000E
+        HUMAN_INTERFACE_DEVICE = 0x000F
+        GLUCOSE_METER = 0x0010
+        RUNNING_WALKING_SENSOR = 0x0011
+        CYCLING = 0x0012
+        CONTROL_DEVICE = 0x0013
+        NETWORK_DEVICE = 0x0014
+        SENSOR = 0x0015
+        LIGHT_FIXTURES = 0x0016
+        FAN = 0x0017
+        HVAC = 0x0018
+        AIR_CONDITIONING = 0x0019
+        HUMIDIFIER = 0x001A
+        HEATING = 0x001B
+        ACCESS_CONTROL = 0x001C
+        MOTORIZED_DEVICE = 0x001D
+        POWER_DEVICE = 0x001E
+        LIGHT_SOURCE = 0x001F
+        WINDOW_COVERING = 0x0020
+        AUDIO_SINK = 0x0021
+        AUDIO_SOURCE = 0x0022
+        MOTORIZED_VEHICLE = 0x0023
+        DOMESTIC_APPLIANCE = 0x0024
+        WEARABLE_AUDIO_DEVICE = 0x0025
+        AIRCRAFT = 0x0026
+        AV_EQUIPMENT = 0x0027
+        DISPLAY_EQUIPMENT = 0x0028
+        HEARING_AID = 0x0029
+        GAMING = 0x002A
+        SIGNAGE = 0x002B
+        PULSE_OXIMETER = 0x0031
+        WEIGHT_SCALE = 0x0032
+        PERSONAL_MOBILITY_DEVICE = 0x0033
+        CONTINUOUS_GLUCOSE_MONITOR = 0x0034
+        INSULIN_PUMP = 0x0035
+        MEDICATION_DELIVERY = 0x0036
+        SPIROMETER = 0x0037
+        OUTDOOR_SPORTS_ACTIVITY = 0x0051
+
+    class UnknownSubcategory(OpenIntEnum):
+        GENERIC_UNKNOWN = 0x00
+
+    class PhoneSubcategory(OpenIntEnum):
+        GENERIC_PHONE = 0x00
+
+    class ComputerSubcategory(OpenIntEnum):
+        GENERIC_COMPUTER = 0x00
+        DESKTOP_WORKSTATION = 0x01
+        SERVER_CLASS_COMPUTER = 0x02
+        LAPTOP = 0x03
+        HANDHELD_PC_PDA = 0x04
+        PALM_SIZE_PC_PDA = 0x05
+        WEARABLE_COMPUTER = 0x06
+        TABLET = 0x07
+        DOCKING_STATION = 0x08
+        ALL_IN_ONE = 0x09
+        BLADE_SERVER = 0x0A
+        CONVERTIBLE = 0x0B
+        DETACHABLE = 0x0C
+        IOT_GATEWAY = 0x0D
+        MINI_PC = 0x0E
+        STICK_PC = 0x0F
+
+    class WatchSubcategory(OpenIntEnum):
+        GENENERIC_WATCH = 0x00
+        SPORTS_WATCH = 0x01
+        SMARTWATCH = 0x02
+
+    class ClockSubcategory(OpenIntEnum):
+        GENERIC_CLOCK = 0x00
+
+    class DisplaySubcategory(OpenIntEnum):
+        GENERIC_DISPLAY = 0x00
+
+    class RemoteControlSubcategory(OpenIntEnum):
+        GENERIC_REMOTE_CONTROL = 0x00
+
+    class EyeglassesSubcategory(OpenIntEnum):
+        GENERIC_EYEGLASSES = 0x00
+
+    class TagSubcategory(OpenIntEnum):
+        GENERIC_TAG = 0x00
+
+    class KeyringSubcategory(OpenIntEnum):
+        GENERIC_KEYRING = 0x00
+
+    class MediaPlayerSubcategory(OpenIntEnum):
+        GENERIC_MEDIA_PLAYER = 0x00
+
+    class BarcodeScannerSubcategory(OpenIntEnum):
+        GENERIC_BARCODE_SCANNER = 0x00
+
+    class ThermometerSubcategory(OpenIntEnum):
+        GENERIC_THERMOMETER = 0x00
+        EAR_THERMOMETER = 0x01
+
+    class HeartRateSensorSubcategory(OpenIntEnum):
+        GENERIC_HEART_RATE_SENSOR = 0x00
+        HEART_RATE_BELT = 0x01
+
+    class BloodPressureSubcategory(OpenIntEnum):
+        GENERIC_BLOOD_PRESSURE = 0x00
+        ARM_BLOOD_PRESSURE = 0x01
+        WRIST_BLOOD_PRESSURE = 0x02
+
+    class HumanInterfaceDeviceSubcategory(OpenIntEnum):
+        GENERIC_HUMAN_INTERFACE_DEVICE = 0x00
+        KEYBOARD = 0x01
+        MOUSE = 0x02
+        JOYSTICK = 0x03
+        GAMEPAD = 0x04
+        DIGITIZER_TABLET = 0x05
+        CARD_READER = 0x06
+        DIGITAL_PEN = 0x07
+        BARCODE_SCANNER = 0x08
+        TOUCHPAD = 0x09
+        PRESENTATION_REMOTE = 0x0A
+
+    class GlucoseMeterSubcategory(OpenIntEnum):
+        GENERIC_GLUCOSE_METER = 0x00
+
+    class RunningWalkingSensorSubcategory(OpenIntEnum):
+        GENERIC_RUNNING_WALKING_SENSOR = 0x00
+        IN_SHOE_RUNNING_WALKING_SENSOR = 0x01
+        ON_SHOW_RUNNING_WALKING_SENSOR = 0x02
+        ON_HIP_RUNNING_WALKING_SENSOR = 0x03
+
+    class CyclingSubcategory(OpenIntEnum):
+        GENERIC_CYCLING = 0x00
+        CYCLING_COMPUTER = 0x01
+        SPEED_SENSOR = 0x02
+        CADENCE_SENSOR = 0x03
+        POWER_SENSOR = 0x04
+        SPEED_AND_CADENCE_SENSOR = 0x05
+
+    class ControlDeviceSubcategory(OpenIntEnum):
+        GENERIC_CONTROL_DEVICE = 0x00
+        SWITCH = 0x01
+        MULTI_SWITCH = 0x02
+        BUTTON = 0x03
+        SLIDER = 0x04
+        ROTARY_SWITCH = 0x05
+        TOUCH_PANEL = 0x06
+        SINGLE_SWITCH = 0x07
+        DOUBLE_SWITCH = 0x08
+        TRIPLE_SWITCH = 0x09
+        BATTERY_SWITCH = 0x0A
+        ENERGY_HARVESTING_SWITCH = 0x0B
+        PUSH_BUTTON = 0x0C
+
+    class NetworkDeviceSubcategory(OpenIntEnum):
+        GENERIC_NETWORK_DEVICE = 0x00
+        ACCESS_POINT = 0x01
+        MESH_DEVICE = 0x02
+        MESH_NETWORK_PROXY = 0x03
+
+    class SensorSubcategory(OpenIntEnum):
+        GENERIC_SENSOR = 0x00
+        MOTION_SENSOR = 0x01
+        AIR_QUALITY_SENSOR = 0x02
+        TEMPERATURE_SENSOR = 0x03
+        HUMIDITY_SENSOR = 0x04
+        LEAK_SENSOR = 0x05
+        SMOKE_SENSOR = 0x06
+        OCCUPANCY_SENSOR = 0x07
+        CONTACT_SENSOR = 0x08
+        CARBON_MONOXIDE_SENSOR = 0x09
+        CARBON_DIOXIDE_SENSOR = 0x0A
+        AMBIENT_LIGHT_SENSOR = 0x0B
+        ENERGY_SENSOR = 0x0C
+        COLOR_LIGHT_SENSOR = 0x0D
+        RAIN_SENSOR = 0x0E
+        FIRE_SENSOR = 0x0F
+        WIND_SENSOR = 0x10
+        PROXIMITY_SENSOR = 0x11
+        MULTI_SENSOR = 0x12
+        FLUSH_MOUNTED_SENSOR = 0x13
+        CEILING_MOUNTED_SENSOR = 0x14
+        WALL_MOUNTED_SENSOR = 0x15
+        MULTISENSOR = 0x16
+        ENERGY_METER = 0x17
+        FLAME_DETECTOR = 0x18
+        VEHICLE_TIRE_PRESSURE_SENSOR = 0x19
+
+    class LightFixturesSubcategory(OpenIntEnum):
+        GENERIC_LIGHT_FIXTURES = 0x00
+        WALL_LIGHT = 0x01
+        CEILING_LIGHT = 0x02
+        FLOOR_LIGHT = 0x03
+        CABINET_LIGHT = 0x04
+        DESK_LIGHT = 0x05
+        TROFFER_LIGHT = 0x06
+        PENDANT_LIGHT = 0x07
+        IN_GROUND_LIGHT = 0x08
+        FLOOD_LIGHT = 0x09
+        UNDERWATER_LIGHT = 0x0A
+        BOLLARD_WITH_LIGHT = 0x0B
+        PATHWAY_LIGHT = 0x0C
+        GARDEN_LIGHT = 0x0D
+        POLE_TOP_LIGHT = 0x0E
+        SPOTLIGHT = 0x0F
+        LINEAR_LIGHT = 0x10
+        STREET_LIGHT = 0x11
+        SHELVES_LIGHT = 0x12
+        BAY_LIGHT = 0x013
+        EMERGENCY_EXIT_LIGHT = 0x14
+        LIGHT_CONTROLLER = 0x15
+        LIGHT_DRIVER = 0x16
+        BULB = 0x17
+        LOW_BAY_LIGHT = 0x18
+        HIGH_BAY_LIGHT = 0x19
+
+    class FanSubcategory(OpenIntEnum):
+        GENERIC_FAN = 0x00
+        CEILING_FAN = 0x01
+        AXIAL_FAN = 0x02
+        EXHAUST_FAN = 0x03
+        PEDESTAL_FAN = 0x04
+        DESK_FAN = 0x05
+        WALL_FAN = 0x06
+
+    class HvacSubcategory(OpenIntEnum):
+        GENERIC_HVAC = 0x00
+        THERMOSTAT = 0x01
+        HUMIDIFIER = 0x02
+        DEHUMIDIFIER = 0x03
+        HEATER = 0x04
+        RADIATOR = 0x05
+        BOILER = 0x06
+        HEAT_PUMP = 0x07
+        INFRARED_HEATER = 0x08
+        RADIANT_PANEL_HEATER = 0x09
+        FAN_HEATER = 0x0A
+        AIR_CURTAIN = 0x0B
+
+    class AirConditioningSubcategory(OpenIntEnum):
+        GENERIC_AIR_CONDITIONING = 0x00
+
+    class HumidifierSubcategory(OpenIntEnum):
+        GENERIC_HUMIDIFIER = 0x00
+
+    class HeatingSubcategory(OpenIntEnum):
+        GENERIC_HEATING = 0x00
+        RADIATOR = 0x01
+        BOILER = 0x02
+        HEAT_PUMP = 0x03
+        INFRARED_HEATER = 0x04
+        RADIANT_PANEL_HEATER = 0x05
+        FAN_HEATER = 0x06
+        AIR_CURTAIN = 0x07
+
+    class AccessControlSubcategory(OpenIntEnum):
+        GENERIC_ACCESS_CONTROL = 0x00
+        ACCESS_DOOR = 0x01
+        GARAGE_DOOR = 0x02
+        EMERGENCY_EXIT_DOOR = 0x03
+        ACCESS_LOCK = 0x04
+        ELEVATOR = 0x05
+        WINDOW = 0x06
+        ENTRANCE_GATE = 0x07
+        DOOR_LOCK = 0x08
+        LOCKER = 0x09
+
+    class MotorizedDeviceSubcategory(OpenIntEnum):
+        GENERIC_MOTORIZED_DEVICE = 0x00
+        MOTORIZED_GATE = 0x01
+        AWNING = 0x02
+        BLINDS_OR_SHADES = 0x03
+        CURTAINS = 0x04
+        SCREEN = 0x05
+
+    class PowerDeviceSubcategory(OpenIntEnum):
+        GENERIC_POWER_DEVICE = 0x00
+        POWER_OUTLET = 0x01
+        POWER_STRIP = 0x02
+        PLUG = 0x03
+        POWER_SUPPLY = 0x04
+        LED_DRIVER = 0x05
+        FLUORESCENT_LAMP_GEAR = 0x06
+        HID_LAMP_GEAR = 0x07
+        CHARGE_CASE = 0x08
+        POWER_BANK = 0x09
+
+    class LightSourceSubcategory(OpenIntEnum):
+        GENERIC_LIGHT_SOURCE = 0x00
+        INCANDESCENT_LIGHT_BULB = 0x01
+        LED_LAMP = 0x02
+        HID_LAMP = 0x03
+        FLUORESCENT_LAMP = 0x04
+        LED_ARRAY = 0x05
+        MULTI_COLOR_LED_ARRAY = 0x06
+        LOW_VOLTAGE_HALOGEN = 0x07
+        ORGANIC_LIGHT_EMITTING_DIODE = 0x08
+
+    class WindowCoveringSubcategory(OpenIntEnum):
+        GENERIC_WINDOW_COVERING = 0x00
+        WINDOW_SHADES = 0x01
+        WINDOW_BLINDS = 0x02
+        WINDOW_AWNING = 0x03
+        WINDOW_CURTAIN = 0x04
+        EXTERIOR_SHUTTER = 0x05
+        EXTERIOR_SCREEN = 0x06
+
+    class AudioSinkSubcategory(OpenIntEnum):
+        GENERIC_AUDIO_SINK = 0x00
+        STANDALONE_SPEAKER = 0x01
+        SOUNDBAR = 0x02
+        BOOKSHELF_SPEAKER = 0x03
+        STANDMOUNTED_SPEAKER = 0x04
+        SPEAKERPHONE = 0x05
+
+    class AudioSourceSubcategory(OpenIntEnum):
+        GENERIC_AUDIO_SOURCE = 0x00
+        MICROPHONE = 0x01
+        ALARM = 0x02
+        BELL = 0x03
+        HORN = 0x04
+        BROADCASTING_DEVICE = 0x05
+        SERVICE_DESK = 0x06
+        KIOSK = 0x07
+        BROADCASTING_ROOM = 0x08
+        AUDITORIUM = 0x09
+
+    class MotorizedVehicleSubcategory(OpenIntEnum):
+        GENERIC_MOTORIZED_VEHICLE = 0x00
+        CAR = 0x01
+        LARGE_GOODS_VEHICLE = 0x02
+        TWO_WHEELED_VEHICLE = 0x03
+        MOTORBIKE = 0x04
+        SCOOTER = 0x05
+        MOPED = 0x06
+        THREE_WHEELED_VEHICLE = 0x07
+        LIGHT_VEHICLE = 0x08
+        QUAD_BIKE = 0x09
+        MINIBUS = 0x0A
+        BUS = 0x0B
+        TROLLEY = 0x0C
+        AGRICULTURAL_VEHICLE = 0x0D
+        CAMPER_CARAVAN = 0x0E
+        RECREATIONAL_VEHICLE_MOTOR_HOME = 0x0F
+
+    class DomesticApplianceSubcategory(OpenIntEnum):
+        GENERIC_DOMESTIC_APPLIANCE = 0x00
+        REFRIGERATOR = 0x01
+        FREEZER = 0x02
+        OVEN = 0x03
+        MICROWAVE = 0x04
+        TOASTER = 0x05
+        WASHING_MACHINE = 0x06
+        DRYER = 0x07
+        COFFEE_MAKER = 0x08
+        CLOTHES_IRON = 0x09
+        CURLING_IRON = 0x0A
+        HAIR_DRYER = 0x0B
+        VACUUM_CLEANER = 0x0C
+        ROBOTIC_VACUUM_CLEANER = 0x0D
+        RICE_COOKER = 0x0E
+        CLOTHES_STEAMER = 0x0F
+
+    class WearableAudioDeviceSubcategory(OpenIntEnum):
+        GENERIC_WEARABLE_AUDIO_DEVICE = 0x00
+        EARBUD = 0x01
+        HEADSET = 0x02
+        HEADPHONES = 0x03
+        NECK_BAND = 0x04
+
+    class AircraftSubcategory(OpenIntEnum):
+        GENERIC_AIRCRAFT = 0x00
+        LIGHT_AIRCRAFT = 0x01
+        MICROLIGHT = 0x02
+        PARAGLIDER = 0x03
+        LARGE_PASSENGER_AIRCRAFT = 0x04
+
+    class AvEquipmentSubcategory(OpenIntEnum):
+        GENERIC_AV_EQUIPMENT = 0x00
+        AMPLIFIER = 0x01
+        RECEIVER = 0x02
+        RADIO = 0x03
+        TUNER = 0x04
+        TURNTABLE = 0x05
+        CD_PLAYER = 0x06
+        DVD_PLAYER = 0x07
+        BLUERAY_PLAYER = 0x08
+        OPTICAL_DISC_PLAYER = 0x09
+        SET_TOP_BOX = 0x0A
+
+    class DisplayEquipmentSubcategory(OpenIntEnum):
+        GENERIC_DISPLAY_EQUIPMENT = 0x00
+        TELEVISION = 0x01
+        MONITOR = 0x02
+        PROJECTOR = 0x03
+
+    class HearingAidSubcategory(OpenIntEnum):
+        GENERIC_HEARING_AID = 0x00
+        IN_EAR_HEARING_AID = 0x01
+        BEHIND_EAR_HEARING_AID = 0x02
+        COCHLEAR_IMPLANT = 0x03
+
+    class GamingSubcategory(OpenIntEnum):
+        GENERIC_GAMING = 0x00
+        HOME_VIDEO_GAME_CONSOLE = 0x01
+        PORTABLE_HANDHELD_CONSOLE = 0x02
+
+    class SignageSubcategory(OpenIntEnum):
+        GENERIC_SIGNAGE = 0x00
+        DIGITAL_SIGNAGE = 0x01
+        ELECTRONIC_LABEL = 0x02
+
+    class PulseOximeterSubcategory(OpenIntEnum):
+        GENERIC_PULSE_OXIMETER = 0x00
+        FINGERTIP_PULSE_OXIMETER = 0x01
+        WRIST_WORN_PULSE_OXIMETER = 0x02
+
+    class WeightScaleSubcategory(OpenIntEnum):
+        GENERIC_WEIGHT_SCALE = 0x00
+
+    class PersonalMobilityDeviceSubcategory(OpenIntEnum):
+        GENERIC_PERSONAL_MOBILITY_DEVICE = 0x00
+        POWERED_WHEELCHAIR = 0x01
+        MOBILITY_SCOOTER = 0x02
+
+    class ContinuousGlucoseMonitorSubcategory(OpenIntEnum):
+        GENERIC_CONTINUOUS_GLUCOSE_MONITOR = 0x00
+
+    class InsulinPumpSubcategory(OpenIntEnum):
+        GENERIC_INSULIN_PUMP = 0x00
+        INSULIN_PUMP_DURABLE_PUMP = 0x01
+        INSULIN_PUMP_PATCH_PUMP = 0x02
+        INSULIN_PEN = 0x03
+
+    class MedicationDeliverySubcategory(OpenIntEnum):
+        GENERIC_MEDICATION_DELIVERY = 0x00
+
+    class SpirometerSubcategory(OpenIntEnum):
+        GENERIC_SPIROMETER = 0x00
+        HANDHELD_SPIROMETER = 0x01
+
+    class OutdoorSportsActivitySubcategory(OpenIntEnum):
+        GENERIC_OUTDOOR_SPORTS_ACTIVITY = 0x00
+        LOCATION_DISPLAY = 0x01
+        LOCATION_AND_NAVIGATION_DISPLAY = 0x02
+        LOCATION_POD = 0x03
+        LOCATION_AND_NAVIGATION_POD = 0x04
+
+    class _OpenSubcategory(OpenIntEnum):
+        GENERIC = 0x00
+
+    SUBCATEGORY_CLASSES = {
+        Category.UNKNOWN: UnknownSubcategory,
+        Category.PHONE: PhoneSubcategory,
+        Category.COMPUTER: ComputerSubcategory,
+        Category.WATCH: WatchSubcategory,
+        Category.CLOCK: ClockSubcategory,
+        Category.DISPLAY: DisplaySubcategory,
+        Category.REMOTE_CONTROL: RemoteControlSubcategory,
+        Category.EYE_GLASSES: EyeglassesSubcategory,
+        Category.TAG: TagSubcategory,
+        Category.KEYRING: KeyringSubcategory,
+        Category.MEDIA_PLAYER: MediaPlayerSubcategory,
+        Category.BARCODE_SCANNER: BarcodeScannerSubcategory,
+        Category.THERMOMETER: ThermometerSubcategory,
+        Category.HEART_RATE_SENSOR: HeartRateSensorSubcategory,
+        Category.BLOOD_PRESSURE: BloodPressureSubcategory,
+        Category.HUMAN_INTERFACE_DEVICE: HumanInterfaceDeviceSubcategory,
+        Category.GLUCOSE_METER: GlucoseMeterSubcategory,
+        Category.RUNNING_WALKING_SENSOR: RunningWalkingSensorSubcategory,
+        Category.CYCLING: CyclingSubcategory,
+        Category.CONTROL_DEVICE: ControlDeviceSubcategory,
+        Category.NETWORK_DEVICE: NetworkDeviceSubcategory,
+        Category.SENSOR: SensorSubcategory,
+        Category.LIGHT_FIXTURES: LightFixturesSubcategory,
+        Category.FAN: FanSubcategory,
+        Category.HVAC: HvacSubcategory,
+        Category.AIR_CONDITIONING: AirConditioningSubcategory,
+        Category.HUMIDIFIER: HumidifierSubcategory,
+        Category.HEATING: HeatingSubcategory,
+        Category.ACCESS_CONTROL: AccessControlSubcategory,
+        Category.MOTORIZED_DEVICE: MotorizedDeviceSubcategory,
+        Category.POWER_DEVICE: PowerDeviceSubcategory,
+        Category.LIGHT_SOURCE: LightSourceSubcategory,
+        Category.WINDOW_COVERING: WindowCoveringSubcategory,
+        Category.AUDIO_SINK: AudioSinkSubcategory,
+        Category.AUDIO_SOURCE: AudioSourceSubcategory,
+        Category.MOTORIZED_VEHICLE: MotorizedVehicleSubcategory,
+        Category.DOMESTIC_APPLIANCE: DomesticApplianceSubcategory,
+        Category.WEARABLE_AUDIO_DEVICE: WearableAudioDeviceSubcategory,
+        Category.AIRCRAFT: AircraftSubcategory,
+        Category.AV_EQUIPMENT: AvEquipmentSubcategory,
+        Category.DISPLAY_EQUIPMENT: DisplayEquipmentSubcategory,
+        Category.HEARING_AID: HearingAidSubcategory,
+        Category.GAMING: GamingSubcategory,
+        Category.SIGNAGE: SignageSubcategory,
+        Category.PULSE_OXIMETER: PulseOximeterSubcategory,
+        Category.WEIGHT_SCALE: WeightScaleSubcategory,
+        Category.PERSONAL_MOBILITY_DEVICE: PersonalMobilityDeviceSubcategory,
+        Category.CONTINUOUS_GLUCOSE_MONITOR: ContinuousGlucoseMonitorSubcategory,
+        Category.INSULIN_PUMP: InsulinPumpSubcategory,
+        Category.MEDICATION_DELIVERY: MedicationDeliverySubcategory,
+        Category.SPIROMETER: SpirometerSubcategory,
+        Category.OUTDOOR_SPORTS_ACTIVITY: OutdoorSportsActivitySubcategory,
+    }
+
+    category: Category
+    subcategory: enum.IntEnum
+
+    @classmethod
+    def from_int(cls, appearance: int) -> Self:
+        category = cls.Category(appearance >> 6)
+        return cls(category, appearance & 0x3F)
+
+    def __init__(self, category: Category, subcategory: int) -> None:
+        self.category = category
+        if subcategory_class := self.SUBCATEGORY_CLASSES.get(category):
+            self.subcategory = subcategory_class(subcategory)
+        else:
+            self.subcategory = self._OpenSubcategory(subcategory)
+
+    def __int__(self) -> int:
+        return self.category << 6 | self.subcategory
+
+    def __repr__(self) -> str:
+        return (
+            'Appearance('
+            f'category={self.category.name}, '
+            f'subcategory={self.subcategory.name}'
+            ')'
+        )
+
+    def __str__(self) -> str:
+        return f'{self.category.name}/{self.subcategory.name}'
+
+
 # -----------------------------------------------------------------------------
 # Advertising Data
 # -----------------------------------------------------------------------------
-AdvertisingObject = Union[
-    List[UUID], Tuple[UUID, bytes], bytes, str, int, Tuple[int, int], Tuple[int, bytes]
+AdvertisingDataObject = Union[
+    List[UUID],
+    Tuple[UUID, bytes],
+    bytes,
+    str,
+    int,
+    Tuple[int, int],
+    Tuple[int, bytes],
+    Appearance,
 ]
 
 
@@ -700,109 +1265,115 @@ class AdvertisingData:
     # fmt: off
     # pylint: disable=line-too-long
 
-    # This list is only partial, it still needs to be filled in from the spec
-    FLAGS                                          = 0x01
-    INCOMPLETE_LIST_OF_16_BIT_SERVICE_CLASS_UUIDS  = 0x02
-    COMPLETE_LIST_OF_16_BIT_SERVICE_CLASS_UUIDS    = 0x03
-    INCOMPLETE_LIST_OF_32_BIT_SERVICE_CLASS_UUIDS  = 0x04
-    COMPLETE_LIST_OF_32_BIT_SERVICE_CLASS_UUIDS    = 0x05
-    INCOMPLETE_LIST_OF_128_BIT_SERVICE_CLASS_UUIDS = 0x06
-    COMPLETE_LIST_OF_128_BIT_SERVICE_CLASS_UUIDS   = 0x07
-    SHORTENED_LOCAL_NAME                           = 0x08
-    COMPLETE_LOCAL_NAME                            = 0x09
-    TX_POWER_LEVEL                                 = 0x0A
-    CLASS_OF_DEVICE                                = 0x0D
-    SIMPLE_PAIRING_HASH_C                          = 0x0E
-    SIMPLE_PAIRING_HASH_C_192                      = 0x0E
-    SIMPLE_PAIRING_RANDOMIZER_R                    = 0x0F
-    SIMPLE_PAIRING_RANDOMIZER_R_192                = 0x0F
-    DEVICE_ID                                      = 0x10
-    SECURITY_MANAGER_TK_VALUE                      = 0x10
-    SECURITY_MANAGER_OUT_OF_BAND_FLAGS             = 0x11
-    PERIPHERAL_CONNECTION_INTERVAL_RANGE           = 0x12
-    LIST_OF_16_BIT_SERVICE_SOLICITATION_UUIDS      = 0x14
-    LIST_OF_128_BIT_SERVICE_SOLICITATION_UUIDS     = 0x15
-    SERVICE_DATA                                   = 0x16
-    SERVICE_DATA_16_BIT_UUID                       = 0x16
-    PUBLIC_TARGET_ADDRESS                          = 0x17
-    RANDOM_TARGET_ADDRESS                          = 0x18
-    APPEARANCE                                     = 0x19
-    ADVERTISING_INTERVAL                           = 0x1A
-    LE_BLUETOOTH_DEVICE_ADDRESS                    = 0x1B
-    LE_ROLE                                        = 0x1C
-    SIMPLE_PAIRING_HASH_C_256                      = 0x1D
-    SIMPLE_PAIRING_RANDOMIZER_R_256                = 0x1E
-    LIST_OF_32_BIT_SERVICE_SOLICITATION_UUIDS      = 0x1F
-    SERVICE_DATA_32_BIT_UUID                       = 0x20
-    SERVICE_DATA_128_BIT_UUID                      = 0x21
-    LE_SECURE_CONNECTIONS_CONFIRMATION_VALUE       = 0x22
-    LE_SECURE_CONNECTIONS_RANDOM_VALUE             = 0x23
-    URI                                            = 0x24
-    INDOOR_POSITIONING                             = 0x25
-    TRANSPORT_DISCOVERY_DATA                       = 0x26
-    LE_SUPPORTED_FEATURES                          = 0x27
-    CHANNEL_MAP_UPDATE_INDICATION                  = 0x28
-    PB_ADV                                         = 0x29
-    MESH_MESSAGE                                   = 0x2A
-    MESH_BEACON                                    = 0x2B
-    BIGINFO                                        = 0x2C
-    BROADCAST_CODE                                 = 0x2D
-    RESOLVABLE_SET_IDENTIFIER                      = 0x2E
-    ADVERTISING_INTERVAL_LONG                      = 0x2F
-    THREE_D_INFORMATION_DATA                       = 0x3D
-    MANUFACTURER_SPECIFIC_DATA                     = 0xFF
+    FLAGS                                            = 0x01
+    INCOMPLETE_LIST_OF_16_BIT_SERVICE_CLASS_UUIDS    = 0x02
+    COMPLETE_LIST_OF_16_BIT_SERVICE_CLASS_UUIDS      = 0x03
+    INCOMPLETE_LIST_OF_32_BIT_SERVICE_CLASS_UUIDS    = 0x04
+    COMPLETE_LIST_OF_32_BIT_SERVICE_CLASS_UUIDS      = 0x05
+    INCOMPLETE_LIST_OF_128_BIT_SERVICE_CLASS_UUIDS   = 0x06
+    COMPLETE_LIST_OF_128_BIT_SERVICE_CLASS_UUIDS     = 0x07
+    SHORTENED_LOCAL_NAME                             = 0x08
+    COMPLETE_LOCAL_NAME                              = 0x09
+    TX_POWER_LEVEL                                   = 0x0A
+    CLASS_OF_DEVICE                                  = 0x0D
+    SIMPLE_PAIRING_HASH_C                            = 0x0E
+    SIMPLE_PAIRING_HASH_C_192                        = 0x0E
+    SIMPLE_PAIRING_RANDOMIZER_R                      = 0x0F
+    SIMPLE_PAIRING_RANDOMIZER_R_192                  = 0x0F
+    DEVICE_ID                                        = 0x10
+    SECURITY_MANAGER_TK_VALUE                        = 0x10
+    SECURITY_MANAGER_OUT_OF_BAND_FLAGS               = 0x11
+    PERIPHERAL_CONNECTION_INTERVAL_RANGE             = 0x12
+    LIST_OF_16_BIT_SERVICE_SOLICITATION_UUIDS        = 0x14
+    LIST_OF_128_BIT_SERVICE_SOLICITATION_UUIDS       = 0x15
+    SERVICE_DATA                                     = 0x16
+    SERVICE_DATA_16_BIT_UUID                         = 0x16
+    PUBLIC_TARGET_ADDRESS                            = 0x17
+    RANDOM_TARGET_ADDRESS                            = 0x18
+    APPEARANCE                                       = 0x19
+    ADVERTISING_INTERVAL                             = 0x1A
+    LE_BLUETOOTH_DEVICE_ADDRESS                      = 0x1B
+    LE_ROLE                                          = 0x1C
+    SIMPLE_PAIRING_HASH_C_256                        = 0x1D
+    SIMPLE_PAIRING_RANDOMIZER_R_256                  = 0x1E
+    LIST_OF_32_BIT_SERVICE_SOLICITATION_UUIDS        = 0x1F
+    SERVICE_DATA_32_BIT_UUID                         = 0x20
+    SERVICE_DATA_128_BIT_UUID                        = 0x21
+    LE_SECURE_CONNECTIONS_CONFIRMATION_VALUE         = 0x22
+    LE_SECURE_CONNECTIONS_RANDOM_VALUE               = 0x23
+    URI                                              = 0x24
+    INDOOR_POSITIONING                               = 0x25
+    TRANSPORT_DISCOVERY_DATA                         = 0x26
+    LE_SUPPORTED_FEATURES                            = 0x27
+    CHANNEL_MAP_UPDATE_INDICATION                    = 0x28
+    PB_ADV                                           = 0x29
+    MESH_MESSAGE                                     = 0x2A
+    MESH_BEACON                                      = 0x2B
+    BIGINFO                                          = 0x2C
+    BROADCAST_CODE                                   = 0x2D
+    RESOLVABLE_SET_IDENTIFIER                        = 0x2E
+    ADVERTISING_INTERVAL_LONG                        = 0x2F
+    BROADCAST_NAME                                   = 0x30
+    ENCRYPTED_ADVERTISING_DATA                       = 0X31
+    PERIODIC_ADVERTISING_RESPONSE_TIMING_INFORMATION = 0X32
+    ELECTRONIC_SHELF_LABEL                           = 0X34
+    THREE_D_INFORMATION_DATA                         = 0x3D
+    MANUFACTURER_SPECIFIC_DATA                       = 0xFF
 
     AD_TYPE_NAMES = {
-        FLAGS:                                          'FLAGS',
-        INCOMPLETE_LIST_OF_16_BIT_SERVICE_CLASS_UUIDS:  'INCOMPLETE_LIST_OF_16_BIT_SERVICE_CLASS_UUIDS',
-        COMPLETE_LIST_OF_16_BIT_SERVICE_CLASS_UUIDS:    'COMPLETE_LIST_OF_16_BIT_SERVICE_CLASS_UUIDS',
-        INCOMPLETE_LIST_OF_32_BIT_SERVICE_CLASS_UUIDS:  'INCOMPLETE_LIST_OF_32_BIT_SERVICE_CLASS_UUIDS',
-        COMPLETE_LIST_OF_32_BIT_SERVICE_CLASS_UUIDS:    'COMPLETE_LIST_OF_32_BIT_SERVICE_CLASS_UUIDS',
-        INCOMPLETE_LIST_OF_128_BIT_SERVICE_CLASS_UUIDS: 'INCOMPLETE_LIST_OF_128_BIT_SERVICE_CLASS_UUIDS',
-        COMPLETE_LIST_OF_128_BIT_SERVICE_CLASS_UUIDS:   'COMPLETE_LIST_OF_128_BIT_SERVICE_CLASS_UUIDS',
-        SHORTENED_LOCAL_NAME:                           'SHORTENED_LOCAL_NAME',
-        COMPLETE_LOCAL_NAME:                            'COMPLETE_LOCAL_NAME',
-        TX_POWER_LEVEL:                                 'TX_POWER_LEVEL',
-        CLASS_OF_DEVICE:                                'CLASS_OF_DEVICE',
-        SIMPLE_PAIRING_HASH_C:                          'SIMPLE_PAIRING_HASH_C',
-        SIMPLE_PAIRING_HASH_C_192:                      'SIMPLE_PAIRING_HASH_C_192',
-        SIMPLE_PAIRING_RANDOMIZER_R:                    'SIMPLE_PAIRING_RANDOMIZER_R',
-        SIMPLE_PAIRING_RANDOMIZER_R_192:                'SIMPLE_PAIRING_RANDOMIZER_R_192',
-        DEVICE_ID:                                      'DEVICE_ID',
-        SECURITY_MANAGER_TK_VALUE:                      'SECURITY_MANAGER_TK_VALUE',
-        SECURITY_MANAGER_OUT_OF_BAND_FLAGS:             'SECURITY_MANAGER_OUT_OF_BAND_FLAGS',
-        PERIPHERAL_CONNECTION_INTERVAL_RANGE:           'PERIPHERAL_CONNECTION_INTERVAL_RANGE',
-        LIST_OF_16_BIT_SERVICE_SOLICITATION_UUIDS:      'LIST_OF_16_BIT_SERVICE_SOLICITATION_UUIDS',
-        LIST_OF_128_BIT_SERVICE_SOLICITATION_UUIDS:     'LIST_OF_128_BIT_SERVICE_SOLICITATION_UUIDS',
-        SERVICE_DATA:                                   'SERVICE_DATA',
-        SERVICE_DATA_16_BIT_UUID:                       'SERVICE_DATA_16_BIT_UUID',
-        PUBLIC_TARGET_ADDRESS:                          'PUBLIC_TARGET_ADDRESS',
-        RANDOM_TARGET_ADDRESS:                          'RANDOM_TARGET_ADDRESS',
-        APPEARANCE:                                     'APPEARANCE',
-        ADVERTISING_INTERVAL:                           'ADVERTISING_INTERVAL',
-        LE_BLUETOOTH_DEVICE_ADDRESS:                    'LE_BLUETOOTH_DEVICE_ADDRESS',
-        LE_ROLE:                                        'LE_ROLE',
-        SIMPLE_PAIRING_HASH_C_256:                      'SIMPLE_PAIRING_HASH_C_256',
-        SIMPLE_PAIRING_RANDOMIZER_R_256:                'SIMPLE_PAIRING_RANDOMIZER_R_256',
-        LIST_OF_32_BIT_SERVICE_SOLICITATION_UUIDS:      'LIST_OF_32_BIT_SERVICE_SOLICITATION_UUIDS',
-        SERVICE_DATA_32_BIT_UUID:                       'SERVICE_DATA_32_BIT_UUID',
-        SERVICE_DATA_128_BIT_UUID:                      'SERVICE_DATA_128_BIT_UUID',
-        LE_SECURE_CONNECTIONS_CONFIRMATION_VALUE:       'LE_SECURE_CONNECTIONS_CONFIRMATION_VALUE',
-        LE_SECURE_CONNECTIONS_RANDOM_VALUE:             'LE_SECURE_CONNECTIONS_RANDOM_VALUE',
-        URI:                                            'URI',
-        INDOOR_POSITIONING:                             'INDOOR_POSITIONING',
-        TRANSPORT_DISCOVERY_DATA:                       'TRANSPORT_DISCOVERY_DATA',
-        LE_SUPPORTED_FEATURES:                          'LE_SUPPORTED_FEATURES',
-        CHANNEL_MAP_UPDATE_INDICATION:                  'CHANNEL_MAP_UPDATE_INDICATION',
-        PB_ADV:                                         'PB_ADV',
-        MESH_MESSAGE:                                   'MESH_MESSAGE',
-        MESH_BEACON:                                    'MESH_BEACON',
-        BIGINFO:                                        'BIGINFO',
-        BROADCAST_CODE:                                 'BROADCAST_CODE',
-        RESOLVABLE_SET_IDENTIFIER:                      'RESOLVABLE_SET_IDENTIFIER',
-        ADVERTISING_INTERVAL_LONG:                      'ADVERTISING_INTERVAL_LONG',
-        THREE_D_INFORMATION_DATA:                       'THREE_D_INFORMATION_DATA',
-        MANUFACTURER_SPECIFIC_DATA:                     'MANUFACTURER_SPECIFIC_DATA'
+        FLAGS:                                            'FLAGS',
+        INCOMPLETE_LIST_OF_16_BIT_SERVICE_CLASS_UUIDS:    'INCOMPLETE_LIST_OF_16_BIT_SERVICE_CLASS_UUIDS',
+        COMPLETE_LIST_OF_16_BIT_SERVICE_CLASS_UUIDS:      'COMPLETE_LIST_OF_16_BIT_SERVICE_CLASS_UUIDS',
+        INCOMPLETE_LIST_OF_32_BIT_SERVICE_CLASS_UUIDS:    'INCOMPLETE_LIST_OF_32_BIT_SERVICE_CLASS_UUIDS',
+        COMPLETE_LIST_OF_32_BIT_SERVICE_CLASS_UUIDS:      'COMPLETE_LIST_OF_32_BIT_SERVICE_CLASS_UUIDS',
+        INCOMPLETE_LIST_OF_128_BIT_SERVICE_CLASS_UUIDS:   'INCOMPLETE_LIST_OF_128_BIT_SERVICE_CLASS_UUIDS',
+        COMPLETE_LIST_OF_128_BIT_SERVICE_CLASS_UUIDS:     'COMPLETE_LIST_OF_128_BIT_SERVICE_CLASS_UUIDS',
+        SHORTENED_LOCAL_NAME:                             'SHORTENED_LOCAL_NAME',
+        COMPLETE_LOCAL_NAME:                              'COMPLETE_LOCAL_NAME',
+        TX_POWER_LEVEL:                                   'TX_POWER_LEVEL',
+        CLASS_OF_DEVICE:                                  'CLASS_OF_DEVICE',
+        SIMPLE_PAIRING_HASH_C:                            'SIMPLE_PAIRING_HASH_C',
+        SIMPLE_PAIRING_HASH_C_192:                        'SIMPLE_PAIRING_HASH_C_192',
+        SIMPLE_PAIRING_RANDOMIZER_R:                      'SIMPLE_PAIRING_RANDOMIZER_R',
+        SIMPLE_PAIRING_RANDOMIZER_R_192:                  'SIMPLE_PAIRING_RANDOMIZER_R_192',
+        DEVICE_ID:                                        'DEVICE_ID',
+        SECURITY_MANAGER_TK_VALUE:                        'SECURITY_MANAGER_TK_VALUE',
+        SECURITY_MANAGER_OUT_OF_BAND_FLAGS:               'SECURITY_MANAGER_OUT_OF_BAND_FLAGS',
+        PERIPHERAL_CONNECTION_INTERVAL_RANGE:             'PERIPHERAL_CONNECTION_INTERVAL_RANGE',
+        LIST_OF_16_BIT_SERVICE_SOLICITATION_UUIDS:        'LIST_OF_16_BIT_SERVICE_SOLICITATION_UUIDS',
+        LIST_OF_128_BIT_SERVICE_SOLICITATION_UUIDS:       'LIST_OF_128_BIT_SERVICE_SOLICITATION_UUIDS',
+        SERVICE_DATA_16_BIT_UUID:                         'SERVICE_DATA_16_BIT_UUID',
+        PUBLIC_TARGET_ADDRESS:                            'PUBLIC_TARGET_ADDRESS',
+        RANDOM_TARGET_ADDRESS:                            'RANDOM_TARGET_ADDRESS',
+        APPEARANCE:                                       'APPEARANCE',
+        ADVERTISING_INTERVAL:                             'ADVERTISING_INTERVAL',
+        LE_BLUETOOTH_DEVICE_ADDRESS:                      'LE_BLUETOOTH_DEVICE_ADDRESS',
+        LE_ROLE:                                          'LE_ROLE',
+        SIMPLE_PAIRING_HASH_C_256:                        'SIMPLE_PAIRING_HASH_C_256',
+        SIMPLE_PAIRING_RANDOMIZER_R_256:                  'SIMPLE_PAIRING_RANDOMIZER_R_256',
+        LIST_OF_32_BIT_SERVICE_SOLICITATION_UUIDS:        'LIST_OF_32_BIT_SERVICE_SOLICITATION_UUIDS',
+        SERVICE_DATA_32_BIT_UUID:                         'SERVICE_DATA_32_BIT_UUID',
+        SERVICE_DATA_128_BIT_UUID:                        'SERVICE_DATA_128_BIT_UUID',
+        LE_SECURE_CONNECTIONS_CONFIRMATION_VALUE:         'LE_SECURE_CONNECTIONS_CONFIRMATION_VALUE',
+        LE_SECURE_CONNECTIONS_RANDOM_VALUE:               'LE_SECURE_CONNECTIONS_RANDOM_VALUE',
+        URI:                                              'URI',
+        INDOOR_POSITIONING:                               'INDOOR_POSITIONING',
+        TRANSPORT_DISCOVERY_DATA:                         'TRANSPORT_DISCOVERY_DATA',
+        LE_SUPPORTED_FEATURES:                            'LE_SUPPORTED_FEATURES',
+        CHANNEL_MAP_UPDATE_INDICATION:                    'CHANNEL_MAP_UPDATE_INDICATION',
+        PB_ADV:                                           'PB_ADV',
+        MESH_MESSAGE:                                     'MESH_MESSAGE',
+        MESH_BEACON:                                      'MESH_BEACON',
+        BIGINFO:                                          'BIGINFO',
+        BROADCAST_CODE:                                   'BROADCAST_CODE',
+        RESOLVABLE_SET_IDENTIFIER:                        'RESOLVABLE_SET_IDENTIFIER',
+        ADVERTISING_INTERVAL_LONG:                        'ADVERTISING_INTERVAL_LONG',
+        BROADCAST_NAME:                                   'BROADCAST_NAME',
+        ENCRYPTED_ADVERTISING_DATA:                       'ENCRYPTED_ADVERTISING_DATA',
+        PERIODIC_ADVERTISING_RESPONSE_TIMING_INFORMATION: 'PERIODIC_ADVERTISING_RESPONSE_TIMING_INFORMATION',
+        ELECTRONIC_SHELF_LABEL:                           'ELECTRONIC_SHELF_LABEL',
+        THREE_D_INFORMATION_DATA:                         'THREE_D_INFORMATION_DATA',
+        MANUFACTURER_SPECIFIC_DATA:                       'MANUFACTURER_SPECIFIC_DATA'
     }
 
     LE_LIMITED_DISCOVERABLE_MODE_FLAG = 0x01
@@ -821,8 +1392,8 @@ class AdvertisingData:
             ad_structures = []
         self.ad_structures = ad_structures[:]
 
-    @staticmethod
-    def from_bytes(data):
+    @classmethod
+    def from_bytes(cls, data: bytes) -> AdvertisingData:
         instance = AdvertisingData()
         instance.append(data)
         return instance
@@ -911,7 +1482,11 @@ class AdvertisingData:
             ad_data_str = f'company={company_name}, data={ad_data[2:].hex()}'
         elif ad_type == AdvertisingData.APPEARANCE:
             ad_type_str = 'Appearance'
-            ad_data_str = ad_data.hex()
+            appearance = Appearance.from_int(struct.unpack_from('<H', ad_data, 0)[0])
+            ad_data_str = str(appearance)
+        elif ad_type == AdvertisingData.BROADCAST_NAME:
+            ad_type_str = 'Broadcast Name'
+            ad_data_str = ad_data.decode('utf-8')
         else:
             ad_type_str = AdvertisingData.AD_TYPE_NAMES.get(ad_type, f'0x{ad_type:02X}')
             ad_data_str = ad_data.hex()
@@ -920,7 +1495,7 @@ class AdvertisingData:
 
     # pylint: disable=too-many-return-statements
     @staticmethod
-    def ad_data_to_object(ad_type: int, ad_data: bytes) -> AdvertisingObject:
+    def ad_data_to_object(ad_type: int, ad_data: bytes) -> AdvertisingDataObject:
         if ad_type in (
             AdvertisingData.COMPLETE_LIST_OF_16_BIT_SERVICE_CLASS_UUIDS,
             AdvertisingData.INCOMPLETE_LIST_OF_16_BIT_SERVICE_CLASS_UUIDS,
@@ -955,16 +1530,14 @@ class AdvertisingData:
             AdvertisingData.SHORTENED_LOCAL_NAME,
             AdvertisingData.COMPLETE_LOCAL_NAME,
             AdvertisingData.URI,
+            AdvertisingData.BROADCAST_NAME,
         ):
             return ad_data.decode("utf-8")
 
         if ad_type in (AdvertisingData.TX_POWER_LEVEL, AdvertisingData.FLAGS):
             return cast(int, struct.unpack('B', ad_data)[0])
 
-        if ad_type in (
-            AdvertisingData.APPEARANCE,
-            AdvertisingData.ADVERTISING_INTERVAL,
-        ):
+        if ad_type in (AdvertisingData.ADVERTISING_INTERVAL,):
             return cast(int, struct.unpack('<H', ad_data)[0])
 
         if ad_type == AdvertisingData.CLASS_OF_DEVICE:
@@ -976,9 +1549,14 @@ class AdvertisingData:
         if ad_type == AdvertisingData.MANUFACTURER_SPECIFIC_DATA:
             return (cast(int, struct.unpack_from('<H', ad_data, 0)[0]), ad_data[2:])
 
+        if ad_type == AdvertisingData.APPEARANCE:
+            return Appearance.from_int(
+                cast(int, struct.unpack_from('<H', ad_data, 0)[0])
+            )
+
         return ad_data
 
-    def append(self, data):
+    def append(self, data: bytes) -> None:
         offset = 0
         while offset + 1 < len(data):
             length = data[offset]
@@ -989,27 +1567,27 @@ class AdvertisingData:
                 self.ad_structures.append((ad_type, ad_data))
             offset += length
 
-    def get_all(self, type_id: int, raw: bool = False) -> List[AdvertisingObject]:
+    def get_all(self, type_id: int, raw: bool = False) -> List[AdvertisingDataObject]:
         '''
         Get Advertising Data Structure(s) with a given type
 
         Returns a (possibly empty) list of matches.
         '''
 
-        def process_ad_data(ad_data: bytes) -> AdvertisingObject:
+        def process_ad_data(ad_data: bytes) -> AdvertisingDataObject:
             return ad_data if raw else self.ad_data_to_object(type_id, ad_data)
 
         return [process_ad_data(ad[1]) for ad in self.ad_structures if ad[0] == type_id]
 
-    def get(self, type_id: int, raw: bool = False) -> Optional[AdvertisingObject]:
+    def get(self, type_id: int, raw: bool = False) -> Optional[AdvertisingDataObject]:
         '''
         Get Advertising Data Structure(s) with a given type
 
         Returns the first entry, or None if no structure matches.
         '''
 
-        all = self.get_all(type_id, raw=raw)
-        return all[0] if all else None
+        all_objects = self.get_all(type_id, raw=raw)
+        return all_objects[0] if all_objects else None
 
     def __bytes__(self):
         return b''.join(

bumble/crypto.py

@@ -100,6 +100,16 @@ class EccKey:
 # -----------------------------------------------------------------------------
 
 
+# -----------------------------------------------------------------------------
+def generate_prand() -> bytes:
+    '''Generates random 3 bytes, with the 2 most significant bits of 0b01.
+
+    See Bluetooth spec, Vol 6, Part E - Table 1.2.
+    '''
+    prand_bytes = secrets.token_bytes(6)
+    return prand_bytes[:2] + bytes([(prand_bytes[2] & 0b01111111) | 0b01000000])
+
+
 # -----------------------------------------------------------------------------
 def xor(x: bytes, y: bytes) -> bytes:
     assert len(x) == len(y)

bumble/drivers/__init__.py

@@ -19,12 +19,17 @@ like loading firmware after a cold start.
 # -----------------------------------------------------------------------------
 # Imports
 # -----------------------------------------------------------------------------
-import abc
+from __future__ import annotations
 import logging
 import pathlib
 import platform
-from . import rtk
+from typing import Dict, Iterable, Optional, Type, TYPE_CHECKING
 
+from . import rtk, intel
+from .common import Driver
+
+if TYPE_CHECKING:
+    from bumble.host import Host
 
 # -----------------------------------------------------------------------------
 # Logging
@@ -32,40 +37,31 @@ from . import rtk
 logger = logging.getLogger(__name__)
 
 
-# -----------------------------------------------------------------------------
-# Classes
-# -----------------------------------------------------------------------------
-class Driver(abc.ABC):
-    """Base class for drivers."""
-
-    @staticmethod
-    async def for_host(_host):
-        """Return a driver instance for a host.
-
-        Args:
-            host: Host object for which a driver should be created.
-
-        Returns:
-            A Driver instance if a driver should be instantiated for this host, or
-            None if no driver instance of this class is needed.
-        """
-        return None
-
-    @abc.abstractmethod
-    async def init_controller(self):
-        """Initialize the controller."""
-
-
 # -----------------------------------------------------------------------------
 # Functions
 # -----------------------------------------------------------------------------
-async def get_driver_for_host(host):
-    """Probe all known diver classes until one returns a valid instance for a host,
-    or none is found.
+async def get_driver_for_host(host: Host) -> Optional[Driver]:
+    """Probe diver classes until one returns a valid instance for a host, or none is
+    found.
+    If a "driver" HCI metadata entry is present, only that driver class will be probed.
     """
-    if driver := await rtk.Driver.for_host(host):
-        logger.debug("Instantiated RTK driver")
-        return driver
+    driver_classes: Dict[str, Type[Driver]] = {"rtk": rtk.Driver, "intel": intel.Driver}
+    probe_list: Iterable[str]
+    if driver_name := host.hci_metadata.get("driver"):
+        # Only probe a single driver
+        probe_list = [driver_name]
+    else:
+        # Probe all drivers
+        probe_list = driver_classes.keys()
+
+    for driver_name in probe_list:
+        if driver_class := driver_classes.get(driver_name):
+            logger.debug(f"Probing driver class: {driver_name}")
+            if driver := await driver_class.for_host(host):
+                logger.debug(f"Instantiated {driver_name} driver")
+                return driver
+        else:
+            logger.debug(f"Skipping unknown driver class: {driver_name}")
 
     return None
 

bumble/drivers/common.py

@@ -0,0 +1,45 @@
+# 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.
+"""
+Common types for drivers.
+"""
+
+# -----------------------------------------------------------------------------
+# Imports
+# -----------------------------------------------------------------------------
+import abc
+
+
+# -----------------------------------------------------------------------------
+# Classes
+# -----------------------------------------------------------------------------
+class Driver(abc.ABC):
+    """Base class for drivers."""
+
+    @staticmethod
+    async def for_host(_host):
+        """Return a driver instance for a host.
+
+        Args:
+            host: Host object for which a driver should be created.
+
+        Returns:
+            A Driver instance if a driver should be instantiated for this host, or
+            None if no driver instance of this class is needed.
+        """
+        return None
+
+    @abc.abstractmethod
+    async def init_controller(self):
+        """Initialize the controller."""

bumble/drivers/intel.py

@@ -0,0 +1,102 @@
+# 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
+
+from bumble.drivers import common
+from bumble.hci import (
+    hci_vendor_command_op_code,  # type: ignore
+    HCI_Command,
+    HCI_Reset_Command,
+)
+
+# -----------------------------------------------------------------------------
+# Logging
+# -----------------------------------------------------------------------------
+logger = logging.getLogger(__name__)
+
+# -----------------------------------------------------------------------------
+# Constant
+# -----------------------------------------------------------------------------
+
+INTEL_USB_PRODUCTS = {
+    # Intel AX210
+    (0x8087, 0x0032),
+    # Intel BE200
+    (0x8087, 0x0036),
+}
+
+# -----------------------------------------------------------------------------
+# 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_Command.register_commands(globals())
+
+
+@HCI_Command.command(  # type: ignore
+    fields=[("params", "*")],
+    return_parameters_fields=[
+        ("params", "*"),
+    ],
+)
+class Hci_Intel_DDC_Config_Write_Command(HCI_Command):
+    pass
+
+
+class Driver(common.Driver):
+    def __init__(self, host):
+        self.host = host
+
+    @staticmethod
+    def check(host):
+        driver = host.hci_metadata.get("driver")
+        if driver == "intel":
+            return True
+
+        vendor_id = host.hci_metadata.get("vendor_id")
+        product_id = host.hci_metadata.get("product_id")
+
+        if vendor_id is None or product_id is None:
+            logger.debug("USB metadata not sufficient")
+            return False
+
+        if (vendor_id, product_id) not in INTEL_USB_PRODUCTS:
+            logger.debug(
+                f"USB device ({vendor_id:04X}, {product_id:04X}) " "not in known list"
+            )
+            return False
+
+        return True
+
+    @classmethod
+    async def for_host(cls, host, force=False):  # type: ignore
+        # 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):
+        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
+            )
+        )

bumble/drivers/rtk.py

@@ -41,7 +41,7 @@ from bumble.hci import (
     HCI_Reset_Command,
     HCI_Read_Local_Version_Information_Command,
 )
-
+from bumble.drivers import common
 
 # -----------------------------------------------------------------------------
 # Logging
@@ -285,7 +285,7 @@ class Firmware:
             )
 
 
-class Driver:
+class Driver(common.Driver):
     @dataclass
     class DriverInfo:
         rom: int
@@ -470,8 +470,12 @@ class Driver:
             logger.debug("USB metadata not found")
             return False
 
-        vendor_id = host.hci_metadata.get("vendor_id", None)
-        product_id = host.hci_metadata.get("product_id", None)
+        if host.hci_metadata.get('driver') == 'rtk':
+            # Forced driver
+            return True
+
+        vendor_id = host.hci_metadata.get("vendor_id")
+        product_id = host.hci_metadata.get("product_id")
         if vendor_id is None or product_id is None:
             logger.debug("USB metadata not sufficient")
             return False
@@ -486,6 +490,9 @@ class Driver:
 
     @classmethod
     async def driver_info_for_host(cls, host):
+        await host.send_command(HCI_Reset_Command(), check_result=True)
+        host.ready = True  # Needed to let the host know the controller is ready.
+
         response = await host.send_command(
             HCI_Read_Local_Version_Information_Command(), check_result=True
         )

bumble/gap.py

@@ -36,6 +36,7 @@ logger = logging.getLogger(__name__)
 # Classes
 # -----------------------------------------------------------------------------
 
+
 # -----------------------------------------------------------------------------
 class GenericAccessService(Service):
     def __init__(self, device_name, appearance=(0, 0)):

bumble/gatt.py

@@ -23,16 +23,28 @@
 # Imports
 # -----------------------------------------------------------------------------
 from __future__ import annotations
-import asyncio
 import enum
 import functools
 import logging
 import struct
-from typing import Optional, Sequence, Iterable, List, Union
+from typing import (
+    Callable,
+    Dict,
+    Iterable,
+    List,
+    Optional,
+    Sequence,
+    Union,
+    TYPE_CHECKING,
+)
 
-from .colors import color
-from .core import UUID, get_dict_key_by_value
-from .att import Attribute
+from bumble.colors import color
+from bumble.core import UUID
+from bumble.att import Attribute, AttributeValue
+
+if TYPE_CHECKING:
+    from bumble.gatt_client import AttributeProxy
+    from bumble.device import Connection
 
 
 # -----------------------------------------------------------------------------
@@ -330,9 +342,11 @@ class Service(Attribute):
             uuid = UUID(uuid)
 
         super().__init__(
-            GATT_PRIMARY_SERVICE_ATTRIBUTE_TYPE
-            if primary
-            else GATT_SECONDARY_SERVICE_ATTRIBUTE_TYPE,
+            (
+                GATT_PRIMARY_SERVICE_ATTRIBUTE_TYPE
+                if primary
+                else GATT_SECONDARY_SERVICE_ATTRIBUTE_TYPE
+            ),
             Attribute.READABLE,
             uuid.to_pdu_bytes(),
         )
@@ -368,9 +382,12 @@ class TemplateService(Service):
     UUID: UUID
 
     def __init__(
-        self, characteristics: List[Characteristic], primary: bool = True
+        self,
+        characteristics: List[Characteristic],
+        primary: bool = True,
+        included_services: List[Service] = [],
     ) -> None:
-        super().__init__(self.UUID, characteristics, primary)
+        super().__init__(self.UUID, characteristics, primary, included_services)
 
 
 # -----------------------------------------------------------------------------
@@ -519,56 +536,43 @@ class CharacteristicDeclaration(Attribute):
 
 
 # -----------------------------------------------------------------------------
-class CharacteristicValue:
-    '''
-    Characteristic value where reading and/or writing is delegated to functions
-    passed as arguments to the constructor.
-    '''
-
-    def __init__(self, read=None, write=None):
-        self._read = read
-        self._write = write
-
-    def read(self, connection):
-        return self._read(connection) if self._read else b''
-
-    def write(self, connection, value):
-        if self._write:
-            self._write(connection, value)
+class CharacteristicValue(AttributeValue):
+    """Same as AttributeValue, for backward compatibility"""
 
 
 # -----------------------------------------------------------------------------
 class CharacteristicAdapter:
     '''
-    An adapter that can adapt any object with `read_value` and `write_value`
-    methods (like Characteristic and CharacteristicProxy objects) by wrapping
-    those methods with ones that return/accept encoded/decoded values.
-    Objects with async methods are considered proxies, so the adaptation is one
-    where the return value of `read_value` is decoded and the value passed to
-    `write_value` is encoded. Other objects are considered local characteristics
-    so the adaptation is one where the return value of `read_value` is encoded
-    and the value passed to `write_value` is decoded.
-    If the characteristic has a `subscribe` method, it is wrapped with one where
-    the values are decoded before being passed to the subscriber.
+    An adapter that can adapt Characteristic and AttributeProxy objects
+    by wrapping their `read_value()` and `write_value()` methods with ones that
+    return/accept encoded/decoded values.
+
+    For proxies (i.e used by a GATT client), the adaptation is one where the return
+    value of `read_value()` is decoded and the value passed to `write_value()` is
+    encoded. The `subscribe()` method, is wrapped with one where the values are decoded
+    before being passed to the subscriber.
+
+    For local values (i.e hosted by a GATT server) the adaptation is one where the
+    return value of `read_value()` is encoded and the value passed to `write_value()`
+    is decoded.
     '''
 
-    def __init__(self, characteristic):
-        self.wrapped_characteristic = characteristic
-        self.subscribers = {}  # Map from subscriber to proxy subscriber
+    read_value: Callable
+    write_value: Callable
 
-        if asyncio.iscoroutinefunction(
-            characteristic.read_value
-        ) and asyncio.iscoroutinefunction(characteristic.write_value):
-            self.read_value = self.read_decoded_value
-            self.write_value = self.write_decoded_value
-        else:
+    def __init__(self, characteristic: Union[Characteristic, AttributeProxy]):
+        self.wrapped_characteristic = characteristic
+        self.subscribers: Dict[Callable, Callable] = (
+            {}
+        )  # Map from subscriber to proxy subscriber
+
+        if isinstance(characteristic, Characteristic):
             self.read_value = self.read_encoded_value
             self.write_value = self.write_encoded_value
-
-        if hasattr(self.wrapped_characteristic, 'subscribe'):
+        else:
+            self.read_value = self.read_decoded_value
+            self.write_value = self.write_decoded_value
             self.subscribe = self.wrapped_subscribe
-
-        if hasattr(self.wrapped_characteristic, 'unsubscribe'):
             self.unsubscribe = self.wrapped_unsubscribe
 
     def __getattr__(self, name):
@@ -587,11 +591,13 @@ class CharacteristicAdapter:
         else:
             setattr(self.wrapped_characteristic, name, value)
 
-    def read_encoded_value(self, connection):
-        return self.encode_value(self.wrapped_characteristic.read_value(connection))
+    async def read_encoded_value(self, connection):
+        return self.encode_value(
+            await self.wrapped_characteristic.read_value(connection)
+        )
 
-    def write_encoded_value(self, connection, value):
-        return self.wrapped_characteristic.write_value(
+    async def write_encoded_value(self, connection, value):
+        return await self.wrapped_characteristic.write_value(
             connection, self.decode_value(value)
         )
 
@@ -726,13 +732,24 @@ class Descriptor(Attribute):
     '''
 
     def __str__(self) -> str:
+        if isinstance(self.value, bytes):
+            value_str = self.value.hex()
+        elif isinstance(self.value, CharacteristicValue):
+            value = self.value.read(None)
+            if isinstance(value, bytes):
+                value_str = value.hex()
+            else:
+                value_str = '<async>'
+        else:
+            value_str = '<...>'
         return (
             f'Descriptor(handle=0x{self.handle:04X}, '
             f'type={self.type}, '
-            f'value={self.read_value(None).hex()})'
+            f'value={value_str})'
         )
 
 
+# -----------------------------------------------------------------------------
 class ClientCharacteristicConfigurationBits(enum.IntFlag):
     '''
     See Vol 3, Part G - 3.3.3.3 - Table 3.11 Client Characteristic Configuration bit

bumble/gatt_client.py

@@ -90,6 +90,22 @@ if TYPE_CHECKING:
 logger = logging.getLogger(__name__)
 
 
+# -----------------------------------------------------------------------------
+# Utils
+# -----------------------------------------------------------------------------
+
+
+def show_services(services: Iterable[ServiceProxy]) -> None:
+    for service in services:
+        print(color(str(service), 'cyan'))
+
+        for characteristic in service.characteristics:
+            print(color('  ' + str(characteristic), 'magenta'))
+
+            for descriptor in characteristic.descriptors:
+                print(color('    ' + str(descriptor), 'green'))
+
+
 # -----------------------------------------------------------------------------
 # Proxies
 # -----------------------------------------------------------------------------
@@ -352,9 +368,7 @@ class Client:
             if c.uuid == uuid
         ]
 
-    def get_attribute_grouping(
-        self, attribute_handle: int
-    ) -> Optional[
+    def get_attribute_grouping(self, attribute_handle: int) -> Optional[
         Union[
             ServiceProxy,
             Tuple[ServiceProxy, CharacteristicProxy],
@@ -1068,7 +1082,7 @@ class Client:
                 logger.warning('!!! unexpected response, there is no pending request')
                 return
 
-            # Sanity check: the response should match the pending request unless it is
+            # The response should match the pending request unless it is
             # an error response
             if att_pdu.op_code != ATT_ERROR_RESPONSE:
                 expected_response_name = self.pending_request.name.replace(

bumble/gatt_server.py

@@ -31,9 +31,9 @@ import struct
 from typing import List, Tuple, Optional, TypeVar, Type, Dict, Iterable, TYPE_CHECKING
 from pyee import EventEmitter
 
-from .colors import color
-from .core import UUID
-from .att import (
+from bumble.colors import color
+from bumble.core import UUID
+from bumble.att import (
     ATT_ATTRIBUTE_NOT_FOUND_ERROR,
     ATT_ATTRIBUTE_NOT_LONG_ERROR,
     ATT_CID,
@@ -60,7 +60,7 @@ from .att import (
     ATT_Write_Response,
     Attribute,
 )
-from .gatt import (
+from bumble.gatt import (
     GATT_CHARACTERISTIC_ATTRIBUTE_TYPE,
     GATT_CLIENT_CHARACTERISTIC_CONFIGURATION_DESCRIPTOR,
     GATT_MAX_ATTRIBUTE_VALUE_SIZE,
@@ -74,6 +74,7 @@ from .gatt import (
     Descriptor,
     Service,
 )
+from bumble.utils import AsyncRunner
 
 if TYPE_CHECKING:
     from bumble.device import Device, Connection
@@ -327,7 +328,7 @@ class Server(EventEmitter):
             f'handle=0x{characteristic.handle:04X}: {value.hex()}'
         )
 
-        # Sanity check
+        # Check parameters
         if len(value) != 2:
             logger.warning('CCCD value not 2 bytes long')
             return
@@ -379,7 +380,7 @@ class Server(EventEmitter):
 
         # Get or encode the value
         value = (
-            attribute.read_value(connection)
+            await attribute.read_value(connection)
             if value is None
             else attribute.encode_value(value)
         )
@@ -422,7 +423,7 @@ class Server(EventEmitter):
 
         # Get or encode the value
         value = (
-            attribute.read_value(connection)
+            await attribute.read_value(connection)
             if value is None
             else attribute.encode_value(value)
         )
@@ -444,9 +445,9 @@ class Server(EventEmitter):
             assert self.pending_confirmations[connection.handle] is None
 
             # Create a future value to hold the eventual response
-            pending_confirmation = self.pending_confirmations[
-                connection.handle
-            ] = asyncio.get_running_loop().create_future()
+            pending_confirmation = self.pending_confirmations[connection.handle] = (
+                asyncio.get_running_loop().create_future()
+            )
 
             try:
                 self.send_gatt_pdu(connection.handle, indication.to_bytes())
@@ -650,7 +651,8 @@ class Server(EventEmitter):
 
         self.send_response(connection, response)
 
-    def on_att_find_by_type_value_request(self, connection, request):
+    @AsyncRunner.run_in_task()
+    async def on_att_find_by_type_value_request(self, connection, request):
         '''
         See Bluetooth spec Vol 3, Part F - 3.4.3.3 Find By Type Value Request
         '''
@@ -658,13 +660,13 @@ class Server(EventEmitter):
         # Build list of returned attributes
         pdu_space_available = connection.att_mtu - 2
         attributes = []
-        for attribute in (
+        async for attribute in (
             attribute
             for attribute in self.attributes
             if attribute.handle >= request.starting_handle
             and attribute.handle <= request.ending_handle
             and attribute.type == request.attribute_type
-            and attribute.read_value(connection) == request.attribute_value
+            and (await attribute.read_value(connection)) == request.attribute_value
             and pdu_space_available >= 4
         ):
             # TODO: check permissions
@@ -702,7 +704,8 @@ class Server(EventEmitter):
 
         self.send_response(connection, response)
 
-    def on_att_read_by_type_request(self, connection, request):
+    @AsyncRunner.run_in_task()
+    async def on_att_read_by_type_request(self, connection, request):
         '''
         See Bluetooth spec Vol 3, Part F - 3.4.4.1 Read By Type Request
         '''
@@ -725,7 +728,7 @@ class Server(EventEmitter):
             and pdu_space_available
         ):
             try:
-                attribute_value = attribute.read_value(connection)
+                attribute_value = await attribute.read_value(connection)
             except ATT_Error as error:
                 # If the first attribute is unreadable, return an error
                 # Otherwise return attributes up to this point
@@ -767,14 +770,15 @@ class Server(EventEmitter):
 
         self.send_response(connection, response)
 
-    def on_att_read_request(self, connection, request):
+    @AsyncRunner.run_in_task()
+    async def on_att_read_request(self, connection, request):
         '''
         See Bluetooth spec Vol 3, Part F - 3.4.4.3 Read Request
         '''
 
         if attribute := self.get_attribute(request.attribute_handle):
             try:
-                value = attribute.read_value(connection)
+                value = await attribute.read_value(connection)
             except ATT_Error as error:
                 response = ATT_Error_Response(
                     request_opcode_in_error=request.op_code,
@@ -792,14 +796,15 @@ class Server(EventEmitter):
             )
         self.send_response(connection, response)
 
-    def on_att_read_blob_request(self, connection, request):
+    @AsyncRunner.run_in_task()
+    async def on_att_read_blob_request(self, connection, request):
         '''
         See Bluetooth spec Vol 3, Part F - 3.4.4.5 Read Blob Request
         '''
 
         if attribute := self.get_attribute(request.attribute_handle):
             try:
-                value = attribute.read_value(connection)
+                value = await attribute.read_value(connection)
             except ATT_Error as error:
                 response = ATT_Error_Response(
                     request_opcode_in_error=request.op_code,
@@ -836,7 +841,8 @@ class Server(EventEmitter):
             )
         self.send_response(connection, response)
 
-    def on_att_read_by_group_type_request(self, connection, request):
+    @AsyncRunner.run_in_task()
+    async def on_att_read_by_group_type_request(self, connection, request):
         '''
         See Bluetooth spec Vol 3, Part F - 3.4.4.9 Read by Group Type Request
         '''
@@ -864,7 +870,7 @@ class Server(EventEmitter):
         ):
             # No need to catch permission errors here, since these attributes
             # must all be world-readable
-            attribute_value = attribute.read_value(connection)
+            attribute_value = await attribute.read_value(connection)
             # Check the attribute value size
             max_attribute_size = min(connection.att_mtu - 6, 251)
             if len(attribute_value) > max_attribute_size:
@@ -903,7 +909,8 @@ class Server(EventEmitter):
 
         self.send_response(connection, response)
 
-    def on_att_write_request(self, connection, request):
+    @AsyncRunner.run_in_task()
+    async def on_att_write_request(self, connection, request):
         '''
         See Bluetooth spec Vol 3, Part F - 3.4.5.1 Write Request
         '''
@@ -936,12 +943,13 @@ class Server(EventEmitter):
             return
 
         # Accept the value
-        attribute.write_value(connection, request.attribute_value)
+        await attribute.write_value(connection, request.attribute_value)
 
         # Done
         self.send_response(connection, ATT_Write_Response())
 
-    def on_att_write_command(self, connection, request):
+    @AsyncRunner.run_in_task()
+    async def on_att_write_command(self, connection, request):
         '''
         See Bluetooth spec Vol 3, Part F - 3.4.5.3 Write Command
         '''
@@ -959,9 +967,9 @@ class Server(EventEmitter):
 
         # Accept the value
         try:
-            attribute.write_value(connection, request.attribute_value)
+            await attribute.write_value(connection, request.attribute_value)
         except Exception as error:
-            logger.warning(f'!!! ignoring exception: {error}')
+            logger.exception(f'!!! ignoring exception: {error}')
 
     def on_att_handle_value_confirmation(self, connection, _confirmation):
         '''

bumble/helpers.py

@@ -18,10 +18,17 @@
 from __future__ import annotations
 
 from collections.abc import Callable, MutableMapping
-from typing import cast, Any
+import datetime
+from typing import cast, Any, Optional
 import logging
 
+from bumble import avc
+from bumble import avctp
 from bumble import avdtp
+from bumble import avrcp
+from bumble import crypto
+from bumble import rfcomm
+from bumble import sdp
 from bumble.colors import color
 from bumble.att import ATT_CID, ATT_PDU
 from bumble.smp import SMP_CID, SMP_Command
@@ -37,6 +44,7 @@ from bumble.l2cap import (
     L2CAP_Connection_Response,
 )
 from bumble.hci import (
+    Address,
     HCI_EVENT_PACKET,
     HCI_ACL_DATA_PACKET,
     HCI_DISCONNECTION_COMPLETE_EVENT,
@@ -46,8 +54,7 @@ from bumble.hci import (
     HCI_AclDataPacket,
     HCI_Disconnection_Complete_Event,
 )
-from bumble.rfcomm import RFCOMM_Frame, RFCOMM_PSM
-from bumble.sdp import SDP_PDU, SDP_PSM
+
 
 # -----------------------------------------------------------------------------
 # Logging
@@ -57,28 +64,36 @@ logger = logging.getLogger(__name__)
 
 # -----------------------------------------------------------------------------
 PSM_NAMES = {
-    RFCOMM_PSM: 'RFCOMM',
-    SDP_PSM: 'SDP',
+    rfcomm.RFCOMM_PSM: 'RFCOMM',
+    sdp.SDP_PSM: 'SDP',
     avdtp.AVDTP_PSM: 'AVDTP',
+    avctp.AVCTP_PSM: 'AVCTP',
+    # TODO: add more PSM values
 }
 
+AVCTP_PID_NAMES = {avrcp.AVRCP_PID: 'AVRCP'}
+
 
 # -----------------------------------------------------------------------------
 class PacketTracer:
     class AclStream:
         psms: MutableMapping[int, int]
-        peer: PacketTracer.AclStream
+        peer: Optional[PacketTracer.AclStream]
         avdtp_assemblers: MutableMapping[int, avdtp.MessageAssembler]
+        avctp_assemblers: MutableMapping[int, avctp.MessageAssembler]
 
         def __init__(self, analyzer: PacketTracer.Analyzer) -> None:
             self.analyzer = analyzer
             self.packet_assembler = HCI_AclDataPacketAssembler(self.on_acl_pdu)
             self.avdtp_assemblers = {}  # AVDTP assemblers, by source_cid
+            self.avctp_assemblers = {}  # AVCTP assemblers, by source_cid
             self.psms = {}  # PSM, by source_cid
+            self.peer = None
 
         # pylint: disable=too-many-nested-blocks
         def on_acl_pdu(self, pdu: bytes) -> None:
             l2cap_pdu = L2CAP_PDU.from_bytes(pdu)
+            self.analyzer.emit(l2cap_pdu)
 
             if l2cap_pdu.cid == ATT_CID:
                 att_pdu = ATT_PDU.from_bytes(l2cap_pdu.payload)
@@ -100,42 +115,51 @@ class PacketTracer:
                         connection_response.result
                         == L2CAP_Connection_Response.CONNECTION_SUCCESSFUL
                     ):
-                        if self.peer:
-                            if psm := self.peer.psms.get(
-                                connection_response.source_cid
-                            ):
-                                # Found a pending connection
-                                self.psms[connection_response.destination_cid] = psm
-
-                                # For AVDTP connections, create a packet assembler for
-                                # each direction
-                                if psm == avdtp.AVDTP_PSM:
-                                    self.avdtp_assemblers[
-                                        connection_response.source_cid
-                                    ] = avdtp.MessageAssembler(self.on_avdtp_message)
-                                    self.peer.avdtp_assemblers[
-                                        connection_response.destination_cid
-                                    ] = avdtp.MessageAssembler(
-                                        self.peer.on_avdtp_message
-                                    )
+                        if self.peer and (
+                            psm := self.peer.psms.get(connection_response.source_cid)
+                        ):
+                            # Found a pending connection
+                            self.psms[connection_response.destination_cid] = psm
 
+                            # For AVDTP connections, create a packet assembler for
+                            # each direction
+                            if psm == avdtp.AVDTP_PSM:
+                                self.avdtp_assemblers[
+                                    connection_response.source_cid
+                                ] = avdtp.MessageAssembler(self.on_avdtp_message)
+                                self.peer.avdtp_assemblers[
+                                    connection_response.destination_cid
+                                ] = avdtp.MessageAssembler(self.peer.on_avdtp_message)
+                            elif psm == avctp.AVCTP_PSM:
+                                self.avctp_assemblers[
+                                    connection_response.source_cid
+                                ] = avctp.MessageAssembler(self.on_avctp_message)
+                                self.peer.avctp_assemblers[
+                                    connection_response.destination_cid
+                                ] = avctp.MessageAssembler(self.peer.on_avctp_message)
             else:
                 # Try to find the PSM associated with this PDU
                 if self.peer and (psm := self.peer.psms.get(l2cap_pdu.cid)):
-                    if psm == SDP_PSM:
-                        sdp_pdu = SDP_PDU.from_bytes(l2cap_pdu.payload)
+                    if psm == sdp.SDP_PSM:
+                        sdp_pdu = sdp.SDP_PDU.from_bytes(l2cap_pdu.payload)
                         self.analyzer.emit(sdp_pdu)
-                    elif psm == RFCOMM_PSM:
-                        rfcomm_frame = RFCOMM_Frame.from_bytes(l2cap_pdu.payload)
+                    elif psm == rfcomm.RFCOMM_PSM:
+                        rfcomm_frame = rfcomm.RFCOMM_Frame.from_bytes(l2cap_pdu.payload)
                         self.analyzer.emit(rfcomm_frame)
                     elif psm == avdtp.AVDTP_PSM:
                         self.analyzer.emit(
                             f'{color("L2CAP", "green")} [CID={l2cap_pdu.cid}, '
                             f'PSM=AVDTP]: {l2cap_pdu.payload.hex()}'
                         )
-                        assembler = self.avdtp_assemblers.get(l2cap_pdu.cid)
-                        if assembler:
-                            assembler.on_pdu(l2cap_pdu.payload)
+                        if avdtp_assembler := self.avdtp_assemblers.get(l2cap_pdu.cid):
+                            avdtp_assembler.on_pdu(l2cap_pdu.payload)
+                    elif psm == avctp.AVCTP_PSM:
+                        self.analyzer.emit(
+                            f'{color("L2CAP", "green")} [CID={l2cap_pdu.cid}, '
+                            f'PSM=AVCTP]: {l2cap_pdu.payload.hex()}'
+                        )
+                        if avctp_assembler := self.avctp_assemblers.get(l2cap_pdu.cid):
+                            avctp_assembler.on_pdu(l2cap_pdu.payload)
                     else:
                         psm_string = name_or_number(PSM_NAMES, psm)
                         self.analyzer.emit(
@@ -152,6 +176,28 @@ class PacketTracer:
                 f'{color("AVDTP", "green")} [{transaction_label}] {message}'
             )
 
+        def on_avctp_message(
+            self,
+            transaction_label: int,
+            is_command: bool,
+            ipid: bool,
+            pid: int,
+            payload: bytes,
+        ):
+            if pid == avrcp.AVRCP_PID:
+                avc_frame = avc.Frame.from_bytes(payload)
+                details = str(avc_frame)
+            else:
+                details = payload.hex()
+
+            c_r = 'Command' if is_command else 'Response'
+            self.analyzer.emit(
+                f'{color("AVCTP", "green")} '
+                f'{c_r}[{transaction_label}][{name_or_number(AVCTP_PID_NAMES, pid)}] '
+                f'{"#" if ipid else ""}'
+                f'{details}'
+            )
+
         def feed_packet(self, packet: HCI_AclDataPacket) -> None:
             self.packet_assembler.feed_packet(packet)
 
@@ -163,6 +209,7 @@ class PacketTracer:
             self.label = label
             self.emit_message = emit_message
             self.acl_streams = {}  # ACL streams, by connection handle
+            self.packet_timestamp: Optional[datetime.datetime] = None
 
         def start_acl_stream(self, connection_handle: int) -> PacketTracer.AclStream:
             logger.info(
@@ -190,7 +237,10 @@ class PacketTracer:
                 # Let the other forwarder know so it can cleanup its stream as well
                 self.peer.end_acl_stream(connection_handle)
 
-        def on_packet(self, packet: HCI_Packet) -> None:
+        def on_packet(
+            self, timestamp: Optional[datetime.datetime], packet: HCI_Packet
+        ) -> None:
+            self.packet_timestamp = timestamp
             self.emit(packet)
 
             if packet.hci_packet_type == HCI_ACL_DATA_PACKET:
@@ -210,13 +260,22 @@ class PacketTracer:
                     )
 
         def emit(self, message: Any) -> None:
-            self.emit_message(f'[{self.label}] {message}')
+            if self.packet_timestamp:
+                prefix = f"[{self.packet_timestamp.strftime('%Y-%m-%d %H:%M:%S.%f')}]"
+            else:
+                prefix = ""
+            self.emit_message(f'{prefix}[{self.label}] {message}')
 
-    def trace(self, packet: HCI_Packet, direction: int = 0) -> None:
+    def trace(
+        self,
+        packet: HCI_Packet,
+        direction: int = 0,
+        timestamp: Optional[datetime.datetime] = None,
+    ) -> None:
         if direction == 0:
-            self.host_to_controller_analyzer.on_packet(packet)
+            self.host_to_controller_analyzer.on_packet(timestamp, packet)
         else:
-            self.controller_to_host_analyzer.on_packet(packet)
+            self.controller_to_host_analyzer.on_packet(timestamp, packet)
 
     def __init__(
         self,
@@ -232,3 +291,15 @@ class PacketTracer:
         )
         self.host_to_controller_analyzer.peer = self.controller_to_host_analyzer
         self.controller_to_host_analyzer.peer = self.host_to_controller_analyzer
+
+
+def generate_irk() -> bytes:
+    return crypto.r()
+
+
+def verify_rpa_with_irk(rpa: Address, irk: bytes) -> bool:
+    rpa_bytes = bytes(rpa)
+    prand_given = rpa_bytes[3:]
+    hash_given = rpa_bytes[:3]
+    hash_local = crypto.ah(irk, prand_given)
+    return hash_local[:3] == hash_given

bumble/hid.py

@@ -19,16 +19,17 @@ from __future__ import annotations
 from dataclasses import dataclass
 import logging
 import enum
+import struct
 
+from abc import ABC, abstractmethod
 from pyee import EventEmitter
-from typing import Optional, TYPE_CHECKING
+from typing import Optional, Callable, TYPE_CHECKING
+from typing_extensions import override
 
-from bumble import l2cap
+from bumble import l2cap, device
 from bumble.colors import color
 from bumble.core import InvalidStateError, ProtocolError
-
-if TYPE_CHECKING:
-    from bumble.device import Device, Connection
+from .hci import Address
 
 
 # -----------------------------------------------------------------------------
@@ -47,6 +48,7 @@ HID_INTERRUPT_PSM = 0x0013
 
 class Message:
     message_type: MessageType
+
     # Report types
     class ReportType(enum.IntEnum):
         OTHER_REPORT = 0x00
@@ -60,6 +62,7 @@ class Message:
         NOT_READY = 0x01
         ERR_INVALID_REPORT_ID = 0x02
         ERR_UNSUPPORTED_REQUEST = 0x03
+        ERR_INVALID_PARAMETER = 0x04
         ERR_UNKNOWN = 0x0E
         ERR_FATAL = 0x0F
 
@@ -101,13 +104,14 @@ class GetReportMessage(Message):
     def __bytes__(self) -> bytes:
         packet_bytes = bytearray()
         packet_bytes.append(self.report_id)
-        packet_bytes.extend(
-            [(self.buffer_size & 0xFF), ((self.buffer_size >> 8) & 0xFF)]
-        )
-        if self.report_type == Message.ReportType.OTHER_REPORT:
+        if self.buffer_size == 0:
             return self.header(self.report_type) + packet_bytes
         else:
-            return self.header(0x08 | self.report_type) + packet_bytes
+            return (
+                self.header(0x08 | self.report_type)
+                + packet_bytes
+                + struct.pack("<H", self.buffer_size)
+            )
 
 
 @dataclass
@@ -120,6 +124,16 @@ class SetReportMessage(Message):
         return self.header(self.report_type) + self.data
 
 
+@dataclass
+class SendControlData(Message):
+    report_type: int
+    data: bytes
+    message_type = Message.MessageType.DATA
+
+    def __bytes__(self) -> bytes:
+        return self.header(self.report_type) + self.data
+
+
 @dataclass
 class GetProtocolMessage(Message):
     message_type = Message.MessageType.GET_PROTOCOL
@@ -161,31 +175,47 @@ class VirtualCableUnplug(Message):
         return self.header(Message.ControlCommand.VIRTUAL_CABLE_UNPLUG)
 
 
+# Device sends input report, host sends output report.
 @dataclass
 class SendData(Message):
     data: bytes
+    report_type: int
     message_type = Message.MessageType.DATA
 
     def __bytes__(self) -> bytes:
-        return self.header(Message.ReportType.OUTPUT_REPORT) + self.data
+        return self.header(self.report_type) + self.data
+
+
+@dataclass
+class SendHandshakeMessage(Message):
+    result_code: int
+    message_type = Message.MessageType.HANDSHAKE
+
+    def __bytes__(self) -> bytes:
+        return self.header(self.result_code)
 
 
 # -----------------------------------------------------------------------------
-class Host(EventEmitter):
-    l2cap_ctrl_channel: Optional[l2cap.ClassicChannel]
-    l2cap_intr_channel: Optional[l2cap.ClassicChannel]
+class HID(ABC, EventEmitter):
+    l2cap_ctrl_channel: Optional[l2cap.ClassicChannel] = None
+    l2cap_intr_channel: Optional[l2cap.ClassicChannel] = None
+    connection: Optional[device.Connection] = None
 
-    def __init__(self, device: Device, connection: Connection) -> None:
+    class Role(enum.IntEnum):
+        HOST = 0x00
+        DEVICE = 0x01
+
+    def __init__(self, device: device.Device, role: Role) -> None:
         super().__init__()
+        self.remote_device_bd_address: Optional[Address] = None
         self.device = device
-        self.connection = connection
-
-        self.l2cap_ctrl_channel = None
-        self.l2cap_intr_channel = None
+        self.role = role
 
         # Register ourselves with the L2CAP channel manager
-        device.register_l2cap_server(HID_CONTROL_PSM, self.on_connection)
-        device.register_l2cap_server(HID_INTERRUPT_PSM, self.on_connection)
+        device.register_l2cap_server(HID_CONTROL_PSM, self.on_l2cap_connection)
+        device.register_l2cap_server(HID_INTERRUPT_PSM, self.on_l2cap_connection)
+
+        device.on('connection', self.on_device_connection)
 
     async def connect_control_channel(self) -> None:
         # Create a new L2CAP connection - control channel
@@ -229,9 +259,18 @@ class Host(EventEmitter):
         self.l2cap_ctrl_channel = None
         await channel.disconnect()
 
-    def on_connection(self, l2cap_channel: l2cap.ClassicChannel) -> None:
+    def on_device_connection(self, connection: device.Connection) -> None:
+        self.connection = connection
+        self.remote_device_bd_address = connection.peer_address
+        connection.on('disconnection', self.on_device_disconnection)
+
+    def on_device_disconnection(self, reason: int) -> None:
+        self.connection = None
+
+    def on_l2cap_connection(self, l2cap_channel: l2cap.ClassicChannel) -> None:
         logger.debug(f'+++ New L2CAP connection: {l2cap_channel}')
         l2cap_channel.on('open', lambda: self.on_l2cap_channel_open(l2cap_channel))
+        l2cap_channel.on('close', lambda: self.on_l2cap_channel_close(l2cap_channel))
 
     def on_l2cap_channel_open(self, l2cap_channel: l2cap.ClassicChannel) -> None:
         if l2cap_channel.psm == HID_CONTROL_PSM:
@@ -242,63 +281,20 @@ class Host(EventEmitter):
             self.l2cap_intr_channel.sink = self.on_intr_pdu
         logger.debug(f'$$$ L2CAP channel open: {l2cap_channel}')
 
-    def on_ctrl_pdu(self, pdu: bytes) -> None:
-        logger.debug(f'<<< HID CONTROL PDU: {pdu.hex()}')
-        # Here we will receive all kinds of packets, parse and then call respective callbacks
-        message_type = pdu[0] >> 4
-        param = pdu[0] & 0x0F
-
-        if message_type == Message.MessageType.HANDSHAKE:
-            logger.debug(f'<<< HID HANDSHAKE: {Message.Handshake(param).name}')
-            self.emit('handshake', Message.Handshake(param))
-        elif message_type == Message.MessageType.DATA:
-            logger.debug('<<< HID CONTROL DATA')
-            self.emit('data', pdu)
-        elif message_type == Message.MessageType.CONTROL:
-            if param == Message.ControlCommand.SUSPEND:
-                logger.debug('<<< HID SUSPEND')
-                self.emit('suspend', pdu)
-            elif param == Message.ControlCommand.EXIT_SUSPEND:
-                logger.debug('<<< HID EXIT SUSPEND')
-                self.emit('exit_suspend', pdu)
-            elif param == Message.ControlCommand.VIRTUAL_CABLE_UNPLUG:
-                logger.debug('<<< HID VIRTUAL CABLE UNPLUG')
-                self.emit('virtual_cable_unplug')
-            else:
-                logger.debug('<<< HID CONTROL OPERATION UNSUPPORTED')
+    def on_l2cap_channel_close(self, l2cap_channel: l2cap.ClassicChannel) -> None:
+        if l2cap_channel.psm == HID_CONTROL_PSM:
+            self.l2cap_ctrl_channel = None
         else:
-            logger.debug('<<< HID CONTROL DATA')
-            self.emit('data', pdu)
+            self.l2cap_intr_channel = None
+        logger.debug(f'$$$ L2CAP channel close: {l2cap_channel}')
+
+    @abstractmethod
+    def on_ctrl_pdu(self, pdu: bytes) -> None:
+        pass
 
     def on_intr_pdu(self, pdu: bytes) -> None:
         logger.debug(f'<<< HID INTERRUPT PDU: {pdu.hex()}')
-        self.emit("data", pdu)
-
-    def get_report(self, report_type: int, report_id: int, buffer_size: int) -> None:
-        msg = GetReportMessage(
-            report_type=report_type, report_id=report_id, buffer_size=buffer_size
-        )
-        hid_message = bytes(msg)
-        logger.debug(f'>>> HID CONTROL GET REPORT, PDU: {hid_message.hex()}')
-        self.send_pdu_on_ctrl(hid_message)
-
-    def set_report(self, report_type: int, data: bytes):
-        msg = SetReportMessage(report_type=report_type, data=data)
-        hid_message = bytes(msg)
-        logger.debug(f'>>> HID CONTROL SET REPORT, PDU:{hid_message.hex()}')
-        self.send_pdu_on_ctrl(hid_message)
-
-    def get_protocol(self):
-        msg = GetProtocolMessage()
-        hid_message = bytes(msg)
-        logger.debug(f'>>> HID CONTROL GET PROTOCOL, PDU: {hid_message.hex()}')
-        self.send_pdu_on_ctrl(hid_message)
-
-    def set_protocol(self, protocol_mode: int):
-        msg = SetProtocolMessage(protocol_mode=protocol_mode)
-        hid_message = bytes(msg)
-        logger.debug(f'>>> HID CONTROL SET PROTOCOL, PDU: {hid_message.hex()}')
-        self.send_pdu_on_ctrl(hid_message)
+        self.emit("interrupt_data", pdu)
 
     def send_pdu_on_ctrl(self, msg: bytes) -> None:
         assert self.l2cap_ctrl_channel
@@ -308,26 +304,252 @@ class Host(EventEmitter):
         assert self.l2cap_intr_channel
         self.l2cap_intr_channel.send_pdu(msg)
 
-    def send_data(self, data):
-        msg = SendData(data)
+    def send_data(self, data: bytes) -> None:
+        if self.role == HID.Role.HOST:
+            report_type = Message.ReportType.OUTPUT_REPORT
+        else:
+            report_type = Message.ReportType.INPUT_REPORT
+        msg = SendData(data, report_type)
         hid_message = bytes(msg)
-        logger.debug(f'>>> HID INTERRUPT SEND DATA, PDU: {hid_message.hex()}')
-        self.send_pdu_on_intr(hid_message)
+        if self.l2cap_intr_channel is not None:
+            logger.debug(f'>>> HID INTERRUPT SEND DATA, PDU: {hid_message.hex()}')
+            self.send_pdu_on_intr(hid_message)
 
-    def suspend(self):
-        msg = Suspend()
-        hid_message = bytes(msg)
-        logger.debug(f'>>> HID CONTROL SUSPEND, PDU:{hid_message.hex()}')
-        self.send_pdu_on_ctrl(msg)
-
-    def exit_suspend(self):
-        msg = ExitSuspend()
-        hid_message = bytes(msg)
-        logger.debug(f'>>> HID CONTROL EXIT SUSPEND, PDU:{hid_message.hex()}')
-        self.send_pdu_on_ctrl(msg)
-
-    def virtual_cable_unplug(self):
+    def virtual_cable_unplug(self) -> None:
         msg = VirtualCableUnplug()
         hid_message = bytes(msg)
         logger.debug(f'>>> HID CONTROL VIRTUAL CABLE UNPLUG, PDU: {hid_message.hex()}')
-        self.send_pdu_on_ctrl(msg)
+        self.send_pdu_on_ctrl(hid_message)
+
+
+# -----------------------------------------------------------------------------
+
+
+class Device(HID):
+    class GetSetReturn(enum.IntEnum):
+        FAILURE = 0x00
+        REPORT_ID_NOT_FOUND = 0x01
+        ERR_UNSUPPORTED_REQUEST = 0x02
+        ERR_UNKNOWN = 0x03
+        ERR_INVALID_PARAMETER = 0x04
+        SUCCESS = 0xFF
+
+    class GetSetStatus:
+        def __init__(self) -> None:
+            self.data = bytearray()
+            self.status = 0
+
+    def __init__(self, device: device.Device) -> None:
+        super().__init__(device, HID.Role.DEVICE)
+        get_report_cb: Optional[Callable[[int, int, int], None]] = None
+        set_report_cb: Optional[Callable[[int, int, int, bytes], None]] = None
+        get_protocol_cb: Optional[Callable[[], None]] = None
+        set_protocol_cb: Optional[Callable[[int], None]] = None
+
+    @override
+    def on_ctrl_pdu(self, pdu: bytes) -> None:
+        logger.debug(f'<<< HID CONTROL PDU: {pdu.hex()}')
+        param = pdu[0] & 0x0F
+        message_type = pdu[0] >> 4
+
+        if message_type == Message.MessageType.GET_REPORT:
+            logger.debug('<<< HID GET REPORT')
+            self.handle_get_report(pdu)
+        elif message_type == Message.MessageType.SET_REPORT:
+            logger.debug('<<< HID SET REPORT')
+            self.handle_set_report(pdu)
+        elif message_type == Message.MessageType.GET_PROTOCOL:
+            logger.debug('<<< HID GET PROTOCOL')
+            self.handle_get_protocol(pdu)
+        elif message_type == Message.MessageType.SET_PROTOCOL:
+            logger.debug('<<< HID SET PROTOCOL')
+            self.handle_set_protocol(pdu)
+        elif message_type == Message.MessageType.DATA:
+            logger.debug('<<< HID CONTROL DATA')
+            self.emit('control_data', pdu)
+        elif message_type == Message.MessageType.CONTROL:
+            if param == Message.ControlCommand.SUSPEND:
+                logger.debug('<<< HID SUSPEND')
+                self.emit('suspend')
+            elif param == Message.ControlCommand.EXIT_SUSPEND:
+                logger.debug('<<< HID EXIT SUSPEND')
+                self.emit('exit_suspend')
+            elif param == Message.ControlCommand.VIRTUAL_CABLE_UNPLUG:
+                logger.debug('<<< HID VIRTUAL CABLE UNPLUG')
+                self.emit('virtual_cable_unplug')
+            else:
+                logger.debug('<<< HID CONTROL OPERATION UNSUPPORTED')
+        else:
+            logger.debug('<<< HID MESSAGE TYPE UNSUPPORTED')
+            self.send_handshake_message(Message.Handshake.ERR_UNSUPPORTED_REQUEST)
+
+    def send_handshake_message(self, result_code: int) -> None:
+        msg = SendHandshakeMessage(result_code)
+        hid_message = bytes(msg)
+        logger.debug(f'>>> HID HANDSHAKE MESSAGE, PDU: {hid_message.hex()}')
+        self.send_pdu_on_ctrl(hid_message)
+
+    def send_control_data(self, report_type: int, data: bytes):
+        msg = SendControlData(report_type=report_type, data=data)
+        hid_message = bytes(msg)
+        logger.debug(f'>>> HID CONTROL DATA: {hid_message.hex()}')
+        self.send_pdu_on_ctrl(hid_message)
+
+    def handle_get_report(self, pdu: bytes):
+        if self.get_report_cb is None:
+            logger.debug("GetReport callback not registered !!")
+            self.send_handshake_message(Message.Handshake.ERR_UNSUPPORTED_REQUEST)
+            return
+        report_type = pdu[0] & 0x03
+        buffer_flag = (pdu[0] & 0x08) >> 3
+        report_id = pdu[1]
+        logger.debug(f"buffer_flag: {buffer_flag}")
+        if buffer_flag == 1:
+            buffer_size = (pdu[3] << 8) | pdu[2]
+        else:
+            buffer_size = 0
+
+        ret = self.get_report_cb(report_id, report_type, buffer_size)
+        assert ret is not None
+        if ret.status == self.GetSetReturn.FAILURE:
+            self.send_handshake_message(Message.Handshake.ERR_UNKNOWN)
+        elif ret.status == self.GetSetReturn.SUCCESS:
+            data = bytearray()
+            data.append(report_id)
+            data.extend(ret.data)
+            if len(data) < self.l2cap_ctrl_channel.peer_mtu:  # type: ignore[union-attr]
+                self.send_control_data(report_type=report_type, data=data)
+            else:
+                self.send_handshake_message(Message.Handshake.ERR_INVALID_PARAMETER)
+        elif ret.status == self.GetSetReturn.REPORT_ID_NOT_FOUND:
+            self.send_handshake_message(Message.Handshake.ERR_INVALID_REPORT_ID)
+        elif ret.status == self.GetSetReturn.ERR_INVALID_PARAMETER:
+            self.send_handshake_message(Message.Handshake.ERR_INVALID_PARAMETER)
+        elif ret.status == self.GetSetReturn.ERR_UNSUPPORTED_REQUEST:
+            self.send_handshake_message(Message.Handshake.ERR_UNSUPPORTED_REQUEST)
+
+    def register_get_report_cb(self, cb: Callable[[int, int, int], None]) -> None:
+        self.get_report_cb = cb
+        logger.debug("GetReport callback registered successfully")
+
+    def handle_set_report(self, pdu: bytes):
+        if self.set_report_cb is None:
+            logger.debug("SetReport callback not registered !!")
+            self.send_handshake_message(Message.Handshake.ERR_UNSUPPORTED_REQUEST)
+            return
+        report_type = pdu[0] & 0x03
+        report_id = pdu[1]
+        report_data = pdu[2:]
+        report_size = len(report_data) + 1
+        ret = self.set_report_cb(report_id, report_type, report_size, report_data)
+        assert ret is not None
+        if ret.status == self.GetSetReturn.SUCCESS:
+            self.send_handshake_message(Message.Handshake.SUCCESSFUL)
+        elif ret.status == self.GetSetReturn.ERR_INVALID_PARAMETER:
+            self.send_handshake_message(Message.Handshake.ERR_INVALID_PARAMETER)
+        elif ret.status == self.GetSetReturn.REPORT_ID_NOT_FOUND:
+            self.send_handshake_message(Message.Handshake.ERR_INVALID_REPORT_ID)
+        else:
+            self.send_handshake_message(Message.Handshake.ERR_UNSUPPORTED_REQUEST)
+
+    def register_set_report_cb(
+        self, cb: Callable[[int, int, int, bytes], None]
+    ) -> None:
+        self.set_report_cb = cb
+        logger.debug("SetReport callback registered successfully")
+
+    def handle_get_protocol(self, pdu: bytes):
+        if self.get_protocol_cb is None:
+            logger.debug("GetProtocol callback not registered !!")
+            self.send_handshake_message(Message.Handshake.ERR_UNSUPPORTED_REQUEST)
+            return
+        ret = self.get_protocol_cb()
+        assert ret is not None
+        if ret.status == self.GetSetReturn.SUCCESS:
+            self.send_control_data(Message.ReportType.OTHER_REPORT, ret.data)
+        else:
+            self.send_handshake_message(Message.Handshake.ERR_UNSUPPORTED_REQUEST)
+
+    def register_get_protocol_cb(self, cb: Callable[[], None]) -> None:
+        self.get_protocol_cb = cb
+        logger.debug("GetProtocol callback registered successfully")
+
+    def handle_set_protocol(self, pdu: bytes):
+        if self.set_protocol_cb is None:
+            logger.debug("SetProtocol callback not registered !!")
+            self.send_handshake_message(Message.Handshake.ERR_UNSUPPORTED_REQUEST)
+            return
+        ret = self.set_protocol_cb(pdu[0] & 0x01)
+        assert ret is not None
+        if ret.status == self.GetSetReturn.SUCCESS:
+            self.send_handshake_message(Message.Handshake.SUCCESSFUL)
+        else:
+            self.send_handshake_message(Message.Handshake.ERR_UNSUPPORTED_REQUEST)
+
+    def register_set_protocol_cb(self, cb: Callable[[int], None]) -> None:
+        self.set_protocol_cb = cb
+        logger.debug("SetProtocol callback registered successfully")
+
+
+# -----------------------------------------------------------------------------
+class Host(HID):
+    def __init__(self, device: device.Device) -> None:
+        super().__init__(device, HID.Role.HOST)
+
+    def get_report(self, report_type: int, report_id: int, buffer_size: int) -> None:
+        msg = GetReportMessage(
+            report_type=report_type, report_id=report_id, buffer_size=buffer_size
+        )
+        hid_message = bytes(msg)
+        logger.debug(f'>>> HID CONTROL GET REPORT, PDU: {hid_message.hex()}')
+        self.send_pdu_on_ctrl(hid_message)
+
+    def set_report(self, report_type: int, data: bytes) -> None:
+        msg = SetReportMessage(report_type=report_type, data=data)
+        hid_message = bytes(msg)
+        logger.debug(f'>>> HID CONTROL SET REPORT, PDU:{hid_message.hex()}')
+        self.send_pdu_on_ctrl(hid_message)
+
+    def get_protocol(self) -> None:
+        msg = GetProtocolMessage()
+        hid_message = bytes(msg)
+        logger.debug(f'>>> HID CONTROL GET PROTOCOL, PDU: {hid_message.hex()}')
+        self.send_pdu_on_ctrl(hid_message)
+
+    def set_protocol(self, protocol_mode: int) -> None:
+        msg = SetProtocolMessage(protocol_mode=protocol_mode)
+        hid_message = bytes(msg)
+        logger.debug(f'>>> HID CONTROL SET PROTOCOL, PDU: {hid_message.hex()}')
+        self.send_pdu_on_ctrl(hid_message)
+
+    def suspend(self) -> None:
+        msg = Suspend()
+        hid_message = bytes(msg)
+        logger.debug(f'>>> HID CONTROL SUSPEND, PDU:{hid_message.hex()}')
+        self.send_pdu_on_ctrl(hid_message)
+
+    def exit_suspend(self) -> None:
+        msg = ExitSuspend()
+        hid_message = bytes(msg)
+        logger.debug(f'>>> HID CONTROL EXIT SUSPEND, PDU:{hid_message.hex()}')
+        self.send_pdu_on_ctrl(hid_message)
+
+    @override
+    def on_ctrl_pdu(self, pdu: bytes) -> None:
+        logger.debug(f'<<< HID CONTROL PDU: {pdu.hex()}')
+        param = pdu[0] & 0x0F
+        message_type = pdu[0] >> 4
+        if message_type == Message.MessageType.HANDSHAKE:
+            logger.debug(f'<<< HID HANDSHAKE: {Message.Handshake(param).name}')
+            self.emit('handshake', Message.Handshake(param))
+        elif message_type == Message.MessageType.DATA:
+            logger.debug('<<< HID CONTROL DATA')
+            self.emit('control_data', pdu)
+        elif message_type == Message.MessageType.CONTROL:
+            if param == Message.ControlCommand.VIRTUAL_CABLE_UNPLUG:
+                logger.debug('<<< HID VIRTUAL CABLE UNPLUG')
+                self.emit('virtual_cable_unplug')
+            else:
+                logger.debug('<<< HID CONTROL OPERATION UNSUPPORTED')
+        else:
+            logger.debug('<<< HID MESSAGE TYPE UNSUPPORTED')

bumble/keys.py

@@ -25,7 +25,8 @@ import asyncio
 import logging
 import os
 import json
-from typing import TYPE_CHECKING, Dict, List, Optional, Tuple
+from typing import TYPE_CHECKING, Dict, List, Optional, Tuple, Type
+from typing_extensions import Self
 
 from .colors import color
 from .hci import Address
@@ -128,10 +129,10 @@ class PairingKeys:
 
     def print(self, prefix=''):
         keys_dict = self.to_dict()
-        for (container_property, value) in keys_dict.items():
+        for container_property, value in keys_dict.items():
             if isinstance(value, dict):
                 print(f'{prefix}{color(container_property, "cyan")}:')
-                for (key_property, key_value) in value.items():
+                for key_property, key_value in value.items():
                     print(f'{prefix}  {color(key_property, "green")}: {key_value}')
             else:
                 print(f'{prefix}{color(container_property, "cyan")}: {value}')
@@ -158,7 +159,7 @@ class KeyStore:
     async def get_resolving_keys(self):
         all_keys = await self.get_all()
         resolving_keys = []
-        for (name, keys) in all_keys:
+        for name, keys in all_keys:
             if keys.irk is not None:
                 if keys.address_type is None:
                     address_type = Address.RANDOM_DEVICE_ADDRESS
@@ -171,7 +172,7 @@ class KeyStore:
     async def print(self, prefix=''):
         entries = await self.get_all()
         separator = ''
-        for (name, keys) in entries:
+        for name, keys in entries:
             print(separator + prefix + color(name, 'yellow'))
             keys.print(prefix=prefix + '  ')
             separator = '\n'
@@ -253,8 +254,10 @@ class JsonKeyStore(KeyStore):
 
         logger.debug(f'JSON keystore: {self.filename}')
 
-    @staticmethod
-    def from_device(device: Device, filename=None) -> Optional[JsonKeyStore]:
+    @classmethod
+    def from_device(
+        cls: Type[Self], device: Device, filename: Optional[str] = None
+    ) -> Self:
         if not filename:
             # Extract the filename from the config if there is one
             if device.config.keystore is not None:
@@ -270,7 +273,7 @@ class JsonKeyStore(KeyStore):
         else:
             namespace = JsonKeyStore.DEFAULT_NAMESPACE
 
-        return JsonKeyStore(namespace, filename)
+        return cls(namespace, filename)
 
     async def load(self):
         # Try to open the file, without failing. If the file does not exist, it

bumble/l2cap.py

@@ -70,6 +70,7 @@ L2CAP_LE_SIGNALING_CID = 0x05
 
 L2CAP_MIN_LE_MTU     = 23
 L2CAP_MIN_BR_EDR_MTU = 48
+L2CAP_MAX_BR_EDR_MTU = 65535
 
 L2CAP_DEFAULT_MTU = 2048  # Default value for the MTU we are willing to accept
 
@@ -149,9 +150,10 @@ L2CAP_INVALID_CID_IN_REQUEST_REASON = 0x0002
 
 L2CAP_LE_CREDIT_BASED_CONNECTION_MAX_CREDITS             = 65535
 L2CAP_LE_CREDIT_BASED_CONNECTION_MIN_MTU                 = 23
+L2CAP_LE_CREDIT_BASED_CONNECTION_MAX_MTU                 = 65535
 L2CAP_LE_CREDIT_BASED_CONNECTION_MIN_MPS                 = 23
 L2CAP_LE_CREDIT_BASED_CONNECTION_MAX_MPS                 = 65533
-L2CAP_LE_CREDIT_BASED_CONNECTION_DEFAULT_MTU             = 2046
+L2CAP_LE_CREDIT_BASED_CONNECTION_DEFAULT_MTU             = 2048
 L2CAP_LE_CREDIT_BASED_CONNECTION_DEFAULT_MPS             = 2048
 L2CAP_LE_CREDIT_BASED_CONNECTION_DEFAULT_INITIAL_CREDITS = 256
 
@@ -172,7 +174,7 @@ L2CAP_MTU_CONFIGURATION_PARAMETER_TYPE = 0x01
 @dataclasses.dataclass
 class ClassicChannelSpec:
     psm: Optional[int] = None
-    mtu: int = L2CAP_MIN_BR_EDR_MTU
+    mtu: int = L2CAP_DEFAULT_MTU
 
 
 @dataclasses.dataclass
@@ -188,8 +190,11 @@ class LeCreditBasedChannelSpec:
             or self.max_credits > L2CAP_LE_CREDIT_BASED_CONNECTION_MAX_CREDITS
         ):
             raise ValueError('max credits out of range')
-        if self.mtu < L2CAP_LE_CREDIT_BASED_CONNECTION_MIN_MTU:
-            raise ValueError('MTU too small')
+        if (
+            self.mtu < L2CAP_LE_CREDIT_BASED_CONNECTION_MIN_MTU
+            or self.mtu > L2CAP_LE_CREDIT_BASED_CONNECTION_MAX_MTU
+        ):
+            raise ValueError('MTU out of range')
         if (
             self.mps < L2CAP_LE_CREDIT_BASED_CONNECTION_MIN_MPS
             or self.mps > L2CAP_LE_CREDIT_BASED_CONNECTION_MAX_MPS
@@ -204,7 +209,7 @@ class L2CAP_PDU:
 
     @staticmethod
     def from_bytes(data: bytes) -> L2CAP_PDU:
-        # Sanity check
+        # Check parameters
         if len(data) < 4:
             raise ValueError('not enough data for L2CAP header')
 
@@ -745,6 +750,8 @@ class ClassicChannel(EventEmitter):
     sink: Optional[Callable[[bytes], Any]]
     state: State
     connection: Connection
+    mtu: int
+    peer_mtu: int
 
     def __init__(
         self,
@@ -761,6 +768,7 @@ class ClassicChannel(EventEmitter):
         self.signaling_cid = signaling_cid
         self.state = self.State.CLOSED
         self.mtu = mtu
+        self.peer_mtu = L2CAP_MIN_BR_EDR_MTU
         self.psm = psm
         self.source_cid = source_cid
         self.destination_cid = 0
@@ -825,7 +833,9 @@ class ClassicChannel(EventEmitter):
 
         # Wait for the connection to succeed or fail
         try:
-            return await self.connection_result
+            return await self.connection.abort_on(
+                'disconnection', self.connection_result
+            )
         finally:
             self.connection_result = None
 
@@ -857,7 +867,7 @@ class ClassicChannel(EventEmitter):
             [
                 (
                     L2CAP_MAXIMUM_TRANSMISSION_UNIT_CONFIGURATION_OPTION_TYPE,
-                    struct.pack('<H', L2CAP_DEFAULT_MTU),
+                    struct.pack('<H', self.mtu),
                 )
             ]
         )
@@ -922,8 +932,8 @@ class ClassicChannel(EventEmitter):
         options = L2CAP_Control_Frame.decode_configuration_options(request.options)
         for option in options:
             if option[0] == L2CAP_MTU_CONFIGURATION_PARAMETER_TYPE:
-                self.mtu = struct.unpack('<H', option[1])[0]
-                logger.debug(f'MTU = {self.mtu}')
+                self.peer_mtu = struct.unpack('<H', option[1])[0]
+                logger.debug(f'peer MTU = {self.peer_mtu}')
 
         self.send_control_frame(
             L2CAP_Configure_Response(
@@ -1022,7 +1032,7 @@ class ClassicChannel(EventEmitter):
         return (
             f'Channel({self.source_cid}->{self.destination_cid}, '
             f'PSM={self.psm}, '
-            f'MTU={self.mtu}, '
+            f'MTU={self.mtu}/{self.peer_mtu}, '
             f'state={self.state.name})'
         )
 
@@ -1644,12 +1654,13 @@ class ChannelManager:
 
     def send_pdu(self, connection, cid: int, pdu: Union[SupportsBytes, bytes]) -> None:
         pdu_str = pdu.hex() if isinstance(pdu, bytes) else str(pdu)
+        pdu_bytes = bytes(pdu)
         logger.debug(
             f'{color(">>> Sending L2CAP PDU", "blue")} '
             f'on connection [0x{connection.handle:04X}] (CID={cid}) '
-            f'{connection.peer_address}: {pdu_str}'
+            f'{connection.peer_address}: {len(pdu_bytes)} bytes, {pdu_str}'
         )
-        self.host.send_l2cap_pdu(connection.handle, cid, bytes(pdu))
+        self.host.send_l2cap_pdu(connection.handle, cid, pdu_bytes)
 
     def on_pdu(self, connection: Connection, cid: int, pdu: bytes) -> None:
         if cid in (L2CAP_SIGNALING_CID, L2CAP_LE_SIGNALING_CID):
@@ -2217,7 +2228,7 @@ class ChannelManager:
         # Connect
         try:
             await channel.connect()
-        except Exception as e:
+        except BaseException as e:
             del connection_channels[source_cid]
             raise e
 

bumble/link.py

@@ -26,9 +26,13 @@ from bumble.hci import (
     HCI_SUCCESS,
     HCI_CONNECTION_ACCEPT_TIMEOUT_ERROR,
     HCI_CONNECTION_TIMEOUT_ERROR,
+    HCI_UNKNOWN_CONNECTION_IDENTIFIER_ERROR,
     HCI_PAGE_TIMEOUT_ERROR,
     HCI_Connection_Complete_Event,
 )
+from bumble import controller
+
+from typing import Optional, Set
 
 # -----------------------------------------------------------------------------
 # Logging
@@ -57,6 +61,8 @@ class LocalLink:
     Link bus for controllers to communicate with each other
     '''
 
+    controllers: Set[controller.Controller]
+
     def __init__(self):
         self.controllers = set()
         self.pending_connection = None
@@ -79,7 +85,9 @@ class LocalLink:
                 return controller
         return None
 
-    def find_classic_controller(self, address):
+    def find_classic_controller(
+        self, address: Address
+    ) -> Optional[controller.Controller]:
         for controller in self.controllers:
             if controller.public_address == address:
                 return controller
@@ -188,6 +196,60 @@ class LocalLink:
         if peripheral_controller := self.find_controller(peripheral_address):
             peripheral_controller.on_link_encrypted(central_address, rand, ediv, ltk)
 
+    def create_cis(
+        self,
+        central_controller: controller.Controller,
+        peripheral_address: Address,
+        cig_id: int,
+        cis_id: int,
+    ) -> None:
+        logger.debug(
+            f'$$$ CIS Request {central_controller.random_address} -> {peripheral_address}'
+        )
+        if peripheral_controller := self.find_controller(peripheral_address):
+            asyncio.get_running_loop().call_soon(
+                peripheral_controller.on_link_cis_request,
+                central_controller.random_address,
+                cig_id,
+                cis_id,
+            )
+
+    def accept_cis(
+        self,
+        peripheral_controller: controller.Controller,
+        central_address: Address,
+        cig_id: int,
+        cis_id: int,
+    ) -> None:
+        logger.debug(
+            f'$$$ CIS Accept {peripheral_controller.random_address} -> {central_address}'
+        )
+        if central_controller := self.find_controller(central_address):
+            asyncio.get_running_loop().call_soon(
+                central_controller.on_link_cis_established, cig_id, cis_id
+            )
+            asyncio.get_running_loop().call_soon(
+                peripheral_controller.on_link_cis_established, cig_id, cis_id
+            )
+
+    def disconnect_cis(
+        self,
+        initiator_controller: controller.Controller,
+        peer_address: Address,
+        cig_id: int,
+        cis_id: int,
+    ) -> None:
+        logger.debug(
+            f'$$$ CIS Disconnect {initiator_controller.random_address} -> {peer_address}'
+        )
+        if peer_controller := self.find_controller(peer_address):
+            asyncio.get_running_loop().call_soon(
+                initiator_controller.on_link_cis_disconnected, cig_id, cis_id
+            )
+            asyncio.get_running_loop().call_soon(
+                peer_controller.on_link_cis_disconnected, cig_id, cis_id
+            )
+
     ############################################################
     # Classic handlers
     ############################################################
@@ -271,6 +333,52 @@ class LocalLink:
             initiator_controller.public_address, int(not (initiator_new_role))
         )
 
+    def classic_sco_connect(
+        self,
+        initiator_controller: controller.Controller,
+        responder_address: Address,
+        link_type: int,
+    ):
+        logger.debug(
+            f'[Classic] {initiator_controller.public_address} connects SCO to {responder_address}'
+        )
+        responder_controller = self.find_classic_controller(responder_address)
+        # Initiator controller should handle it.
+        assert responder_controller
+
+        responder_controller.on_classic_connection_request(
+            initiator_controller.public_address,
+            link_type,
+        )
+
+    def classic_accept_sco_connection(
+        self,
+        responder_controller: controller.Controller,
+        initiator_address: Address,
+        link_type: int,
+    ):
+        logger.debug(
+            f'[Classic] {responder_controller.public_address} accepts to connect SCO {initiator_address}'
+        )
+        initiator_controller = self.find_classic_controller(initiator_address)
+        if initiator_controller is None:
+            responder_controller.on_classic_sco_connection_complete(
+                responder_controller.public_address,
+                HCI_UNKNOWN_CONNECTION_IDENTIFIER_ERROR,
+                link_type,
+            )
+            return
+
+        async def task():
+            initiator_controller.on_classic_sco_connection_complete(
+                responder_controller.public_address, HCI_SUCCESS, link_type
+            )
+
+        asyncio.create_task(task())
+        responder_controller.on_classic_sco_connection_complete(
+            initiator_controller.public_address, HCI_SUCCESS, link_type
+        )
+
 
 # -----------------------------------------------------------------------------
 class RemoteLink:

bumble/pandora/host.py

@@ -28,14 +28,18 @@ from bumble.core import (
     BT_PERIPHERAL_ROLE,
     UUID,
     AdvertisingData,
+    Appearance,
     ConnectionError,
 )
 from bumble.device import (
     DEVICE_DEFAULT_SCAN_INTERVAL,
     DEVICE_DEFAULT_SCAN_WINDOW,
     Advertisement,
+    AdvertisingParameters,
+    AdvertisingEventProperties,
     AdvertisingType,
     Device,
+    Phy,
 )
 from bumble.gatt import Service
 from bumble.hci import (
@@ -47,9 +51,12 @@ from bumble.hci import (
 from google.protobuf import any_pb2  # pytype: disable=pyi-error
 from google.protobuf import empty_pb2  # pytype: disable=pyi-error
 from pandora.host_grpc_aio import HostServicer
+from pandora import host_pb2
 from pandora.host_pb2 import (
     NOT_CONNECTABLE,
     NOT_DISCOVERABLE,
+    DISCOVERABLE_LIMITED,
+    DISCOVERABLE_GENERAL,
     PRIMARY_1M,
     PRIMARY_CODED,
     SECONDARY_1M,
@@ -65,6 +72,7 @@ from pandora.host_pb2 import (
     ConnectResponse,
     DataTypes,
     DisconnectRequest,
+    DiscoverabilityMode,
     InquiryResponse,
     PrimaryPhy,
     ReadLocalAddressResponse,
@@ -94,6 +102,25 @@ SECONDARY_PHY_MAP: Dict[int, SecondaryPhy] = {
     3: SECONDARY_CODED,
 }
 
+PRIMARY_PHY_TO_BUMBLE_PHY_MAP: Dict[PrimaryPhy, Phy] = {
+    PRIMARY_1M: Phy.LE_1M,
+    PRIMARY_CODED: Phy.LE_CODED,
+}
+
+SECONDARY_PHY_TO_BUMBLE_PHY_MAP: Dict[SecondaryPhy, Phy] = {
+    SECONDARY_NONE: Phy.LE_1M,
+    SECONDARY_1M: Phy.LE_1M,
+    SECONDARY_2M: Phy.LE_2M,
+    SECONDARY_CODED: Phy.LE_CODED,
+}
+
+OWN_ADDRESS_MAP: Dict[host_pb2.OwnAddressType, bumble.hci.OwnAddressType] = {
+    host_pb2.PUBLIC: bumble.hci.OwnAddressType.PUBLIC,
+    host_pb2.RANDOM: bumble.hci.OwnAddressType.RANDOM,
+    host_pb2.RESOLVABLE_OR_PUBLIC: bumble.hci.OwnAddressType.RESOLVABLE_OR_PUBLIC,
+    host_pb2.RESOLVABLE_OR_RANDOM: bumble.hci.OwnAddressType.RESOLVABLE_OR_RANDOM,
+}
+
 
 class HostService(HostServicer):
     waited_connections: Set[int]
@@ -261,9 +288,9 @@ class HostService(HostServicer):
         self.log.debug(f"WaitDisconnection: {connection_handle}")
 
         if connection := self.device.lookup_connection(connection_handle):
-            disconnection_future: asyncio.Future[
-                None
-            ] = asyncio.get_running_loop().create_future()
+            disconnection_future: asyncio.Future[None] = (
+                asyncio.get_running_loop().create_future()
+            )
 
             def on_disconnection(_: None) -> None:
                 disconnection_future.set_result(None)
@@ -281,14 +308,118 @@ class HostService(HostServicer):
     async def Advertise(
         self, request: AdvertiseRequest, context: grpc.ServicerContext
     ) -> AsyncGenerator[AdvertiseResponse, None]:
-        if not request.legacy:
-            raise NotImplementedError(
-                "TODO: add support for extended advertising in Bumble"
+        try:
+            if request.legacy:
+                async for rsp in self.legacy_advertise(request, context):
+                    yield rsp
+            else:
+                async for rsp in self.extended_advertise(request, context):
+                    yield rsp
+        finally:
+            pass
+
+    async def extended_advertise(
+        self, request: AdvertiseRequest, context: grpc.ServicerContext
+    ) -> AsyncGenerator[AdvertiseResponse, None]:
+        advertising_data = bytes(self.unpack_data_types(request.data))
+        scan_response_data = bytes(self.unpack_data_types(request.scan_response_data))
+        scannable = len(scan_response_data) != 0
+
+        advertising_event_properties = AdvertisingEventProperties(
+            is_connectable=request.connectable,
+            is_scannable=scannable,
+            is_directed=request.target is not None,
+            is_high_duty_cycle_directed_connectable=False,
+            is_legacy=False,
+            is_anonymous=False,
+            include_tx_power=False,
+        )
+
+        peer_address = Address.ANY
+        if request.target:
+            # Need to reverse bytes order since Bumble Address is using MSB.
+            target_bytes = bytes(reversed(request.target))
+            if request.target_variant() == "public":
+                peer_address = Address(target_bytes, Address.PUBLIC_DEVICE_ADDRESS)
+            else:
+                peer_address = Address(target_bytes, Address.RANDOM_DEVICE_ADDRESS)
+
+        advertising_parameters = AdvertisingParameters(
+            advertising_event_properties=advertising_event_properties,
+            own_address_type=OWN_ADDRESS_MAP[request.own_address_type],
+            peer_address=peer_address,
+            primary_advertising_phy=PRIMARY_PHY_TO_BUMBLE_PHY_MAP[request.primary_phy],
+            secondary_advertising_phy=SECONDARY_PHY_TO_BUMBLE_PHY_MAP[
+                request.secondary_phy
+            ],
+        )
+        if advertising_interval := request.interval:
+            advertising_parameters.primary_advertising_interval_min = int(
+                advertising_interval
             )
-        if request.interval:
-            raise NotImplementedError("TODO: add support for `request.interval`")
-        if request.interval_range:
-            raise NotImplementedError("TODO: add support for `request.interval_range`")
+            advertising_parameters.primary_advertising_interval_max = int(
+                advertising_interval
+            )
+        if interval_range := request.interval_range:
+            advertising_parameters.primary_advertising_interval_max += int(
+                interval_range
+            )
+
+        advertising_set = await self.device.create_advertising_set(
+            advertising_parameters=advertising_parameters,
+            advertising_data=advertising_data,
+            scan_response_data=scan_response_data,
+        )
+
+        pending_connection: asyncio.Future[bumble.device.Connection] = (
+            asyncio.get_running_loop().create_future()
+        )
+
+        if request.connectable:
+
+            def on_connection(connection: bumble.device.Connection) -> None:
+                if (
+                    connection.transport == BT_LE_TRANSPORT
+                    and connection.role == BT_PERIPHERAL_ROLE
+                ):
+                    pending_connection.set_result(connection)
+
+            self.device.on('connection', on_connection)
+
+        try:
+            # Advertise until RPC is canceled
+            while True:
+                if not advertising_set.enabled:
+                    self.log.debug('Advertise (extended)')
+                    await advertising_set.start()
+
+                if not request.connectable:
+                    await asyncio.sleep(1)
+                    continue
+
+                connection = await pending_connection
+                pending_connection = asyncio.get_running_loop().create_future()
+
+                cookie = any_pb2.Any(value=connection.handle.to_bytes(4, 'big'))
+                yield AdvertiseResponse(connection=Connection(cookie=cookie))
+
+                await asyncio.sleep(1)
+        finally:
+            try:
+                self.log.debug('Stop Advertise (extended)')
+                await advertising_set.stop()
+                await advertising_set.remove()
+            except Exception:
+                pass
+
+    async def legacy_advertise(
+        self, request: AdvertiseRequest, context: grpc.ServicerContext
+    ) -> AsyncGenerator[AdvertiseResponse, None]:
+        if advertising_interval := request.interval:
+            self.device.config.advertising_interval_min = int(advertising_interval)
+            self.device.config.advertising_interval_max = int(advertising_interval)
+        if interval_range := request.interval_range:
+            self.device.config.advertising_interval_max += int(interval_range)
         if request.primary_phy:
             raise NotImplementedError("TODO: add support for `request.primary_phy`")
         if request.secondary_phy:
@@ -356,14 +487,10 @@ class HostService(HostServicer):
             target_bytes = bytes(reversed(request.target))
             if request.target_variant() == "public":
                 target = Address(target_bytes, Address.PUBLIC_DEVICE_ADDRESS)
-                advertising_type = (
-                    AdvertisingType.DIRECTED_CONNECTABLE_HIGH_DUTY
-                )  # FIXME: HIGH_DUTY ?
+                advertising_type = AdvertisingType.DIRECTED_CONNECTABLE_LOW_DUTY
             else:
                 target = Address(target_bytes, Address.RANDOM_DEVICE_ADDRESS)
-                advertising_type = (
-                    AdvertisingType.DIRECTED_CONNECTABLE_HIGH_DUTY
-                )  # FIXME: HIGH_DUTY ?
+                advertising_type = AdvertisingType.DIRECTED_CONNECTABLE_LOW_DUTY
 
         if request.connectable:
 
@@ -390,9 +517,9 @@ class HostService(HostServicer):
                     await asyncio.sleep(1)
                     continue
 
-                pending_connection: asyncio.Future[
-                    bumble.device.Connection
-                ] = asyncio.get_running_loop().create_future()
+                pending_connection: asyncio.Future[bumble.device.Connection] = (
+                    asyncio.get_running_loop().create_future()
+                )
 
                 self.log.debug('Wait for LE connection...')
                 connection = await pending_connection
@@ -421,23 +548,31 @@ class HostService(HostServicer):
         self, request: ScanRequest, context: grpc.ServicerContext
     ) -> AsyncGenerator[ScanningResponse, None]:
         # TODO: modify `start_scanning` to accept floats instead of int for ms values
-        if request.phys:
-            raise NotImplementedError("TODO: add support for `request.phys`")
-
         self.log.debug('Scan')
 
+        scanning_phys = []
+        if PRIMARY_1M in request.phys:
+            scanning_phys.append(int(Phy.LE_1M))
+        if PRIMARY_CODED in request.phys:
+            scanning_phys.append(int(Phy.LE_CODED))
+        if not scanning_phys:
+            scanning_phys = [int(Phy.LE_1M), int(Phy.LE_CODED)]
+
         scan_queue: asyncio.Queue[Advertisement] = asyncio.Queue()
         handler = self.device.on('advertisement', scan_queue.put_nowait)
         await self.device.start_scanning(
             legacy=request.legacy,
             active=not request.passive,
             own_address_type=request.own_address_type,
-            scan_interval=int(request.interval)
-            if request.interval
-            else DEVICE_DEFAULT_SCAN_INTERVAL,
-            scan_window=int(request.window)
-            if request.window
-            else DEVICE_DEFAULT_SCAN_WINDOW,
+            scan_interval=(
+                int(request.interval)
+                if request.interval
+                else DEVICE_DEFAULT_SCAN_INTERVAL
+            ),
+            scan_window=(
+                int(request.window) if request.window else DEVICE_DEFAULT_SCAN_WINDOW
+            ),
+            scanning_phys=scanning_phys,
         )
 
         try:
@@ -650,9 +785,11 @@ class HostService(HostServicer):
                             *struct.pack('<H', dt.peripheral_connection_interval_min),
                             *struct.pack(
                                 '<H',
-                                dt.peripheral_connection_interval_max
-                                if dt.peripheral_connection_interval_max
-                                else dt.peripheral_connection_interval_min,
+                                (
+                                    dt.peripheral_connection_interval_max
+                                    if dt.peripheral_connection_interval_max
+                                    else dt.peripheral_connection_interval_min
+                                ),
                             ),
                         ]
                     ),
@@ -734,6 +871,16 @@ class HostService(HostServicer):
                 )
             )
 
+        flag_map = {
+            NOT_DISCOVERABLE: 0x00,
+            DISCOVERABLE_LIMITED: AdvertisingData.LE_LIMITED_DISCOVERABLE_MODE_FLAG,
+            DISCOVERABLE_GENERAL: AdvertisingData.LE_GENERAL_DISCOVERABLE_MODE_FLAG,
+        }
+
+        if dt.le_discoverability_mode:
+            flags = flag_map[dt.le_discoverability_mode]
+            ad_structures.append((AdvertisingData.FLAGS, flags.to_bytes(1, 'big')))
+
         return AdvertisingData(ad_structures)
 
     def pack_data_types(self, ad: AdvertisingData) -> DataTypes:
@@ -842,8 +989,8 @@ class HostService(HostServicer):
             dt.random_target_addresses.extend(
                 [data[i * 6 :: i * 6 + 6] for i in range(int(len(data) / 6))]
             )
-        if i := cast(int, ad.get(AdvertisingData.APPEARANCE)):
-            dt.appearance = i
+        if appearance := cast(Appearance, ad.get(AdvertisingData.APPEARANCE)):
+            dt.appearance = int(appearance)
         if i := cast(int, ad.get(AdvertisingData.ADVERTISING_INTERVAL)):
             dt.advertising_interval = i
         if s := cast(str, ad.get(AdvertisingData.URI)):

bumble/pandora/security.py

@@ -110,7 +110,7 @@ class PairingDelegate(BasePairingDelegate):
 
         event = self.add_origin(PairingEvent(just_works=empty_pb2.Empty()))
         self.service.event_queue.put_nowait(event)
-        answer = await anext(self.service.event_answer)  # pytype: disable=name-error
+        answer = await anext(self.service.event_answer)  # type: ignore
         assert answer.event == event
         assert answer.answer_variant() == 'confirm' and answer.confirm is not None
         return answer.confirm
@@ -125,7 +125,7 @@ class PairingDelegate(BasePairingDelegate):
 
         event = self.add_origin(PairingEvent(numeric_comparison=number))
         self.service.event_queue.put_nowait(event)
-        answer = await anext(self.service.event_answer)  # pytype: disable=name-error
+        answer = await anext(self.service.event_answer)  # type: ignore
         assert answer.event == event
         assert answer.answer_variant() == 'confirm' and answer.confirm is not None
         return answer.confirm
@@ -140,7 +140,7 @@ class PairingDelegate(BasePairingDelegate):
 
         event = self.add_origin(PairingEvent(passkey_entry_request=empty_pb2.Empty()))
         self.service.event_queue.put_nowait(event)
-        answer = await anext(self.service.event_answer)  # pytype: disable=name-error
+        answer = await anext(self.service.event_answer)  # type: ignore
         assert answer.event == event
         if answer.answer_variant() is None:
             return None
@@ -157,7 +157,7 @@ class PairingDelegate(BasePairingDelegate):
 
         event = self.add_origin(PairingEvent(pin_code_request=empty_pb2.Empty()))
         self.service.event_queue.put_nowait(event)
-        answer = await anext(self.service.event_answer)  # pytype: disable=name-error
+        answer = await anext(self.service.event_answer)  # type: ignore
         assert answer.event == event
         if answer.answer_variant() is None:
             return None
@@ -383,9 +383,9 @@ class SecurityService(SecurityServicer):
             connection.transport
         ] == request.level_variant()
 
-        wait_for_security: asyncio.Future[
-            str
-        ] = asyncio.get_running_loop().create_future()
+        wait_for_security: asyncio.Future[str] = (
+            asyncio.get_running_loop().create_future()
+        )
         authenticate_task: Optional[asyncio.Future[None]] = None
         pair_task: Optional[asyncio.Future[None]] = None
 

bumble/profiles/asha_service.py

@@ -18,7 +18,7 @@
 # -----------------------------------------------------------------------------
 import struct
 import logging
-from typing import List
+from typing import List, Optional
 
 from bumble import l2cap
 from ..core import AdvertisingData
@@ -67,7 +67,7 @@ class AshaService(TemplateService):
             self.emit('volume', connection, value[0])
 
         # Handler for audio control commands
-        def on_audio_control_point_write(connection: Connection, value):
+        def on_audio_control_point_write(connection: Optional[Connection], value):
             logger.info(f'--- AUDIO CONTROL POINT Write:{value.hex()}')
             opcode = value[0]
             if opcode == AshaService.OPCODE_START:

bumble/profiles/cap.py

@@ -0,0 +1,52 @@
+# 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.
+
+
+# -----------------------------------------------------------------------------
+# Imports
+# -----------------------------------------------------------------------------
+from __future__ import annotations
+
+from bumble import gatt
+from bumble import gatt_client
+from bumble.profiles import csip
+
+
+# -----------------------------------------------------------------------------
+# Server
+# -----------------------------------------------------------------------------
+class CommonAudioServiceService(gatt.TemplateService):
+    UUID = gatt.GATT_COMMON_AUDIO_SERVICE
+
+    def __init__(
+        self,
+        coordinated_set_identification_service: csip.CoordinatedSetIdentificationService,
+    ) -> None:
+        self.coordinated_set_identification_service = (
+            coordinated_set_identification_service
+        )
+        super().__init__(
+            characteristics=[],
+            included_services=[coordinated_set_identification_service],
+        )
+
+
+# -----------------------------------------------------------------------------
+# Client
+# -----------------------------------------------------------------------------
+class CommonAudioServiceServiceProxy(gatt_client.ProfileServiceProxy):
+    SERVICE_CLASS = CommonAudioServiceService
+
+    def __init__(self, service_proxy: gatt_client.ServiceProxy) -> None:
+        self.service_proxy = service_proxy

bumble/profiles/csip.py

@@ -19,8 +19,11 @@
 from __future__ import annotations
 import enum
 import struct
-from typing import Optional
+from typing import Optional, Tuple
 
+from bumble import core
+from bumble import crypto
+from bumble import device
 from bumble import gatt
 from bumble import gatt_client
 
@@ -28,6 +31,9 @@ from bumble import gatt_client
 # -----------------------------------------------------------------------------
 # Constants
 # -----------------------------------------------------------------------------
+SET_IDENTITY_RESOLVING_KEY_LENGTH = 16
+
+
 class SirkType(enum.IntEnum):
     '''Coordinated Set Identification Service - 5.1 Set Identity Resolving Key.'''
 
@@ -43,9 +49,47 @@ class MemberLock(enum.IntEnum):
 
 
 # -----------------------------------------------------------------------------
-# Utils
+# Crypto Toolbox
 # -----------------------------------------------------------------------------
-# TODO: Implement RSI Generator
+def s1(m: bytes) -> bytes:
+    '''
+    Coordinated Set Identification Service - 4.3 s1 SALT generation function.
+    '''
+    return crypto.aes_cmac(m[::-1], bytes(16))[::-1]
+
+
+def k1(n: bytes, salt: bytes, p: bytes) -> bytes:
+    '''
+    Coordinated Set Identification Service - 4.4 k1 derivation function.
+    '''
+    t = crypto.aes_cmac(n[::-1], salt[::-1])
+    return crypto.aes_cmac(p[::-1], t)[::-1]
+
+
+def sef(k: bytes, r: bytes) -> bytes:
+    '''
+    Coordinated Set Identification Service - 4.5 SIRK encryption function sef.
+
+    SIRK decryption function sdf shares the same algorithm. The only difference is that argument r is:
+      * Plaintext in encryption
+      * Cipher in decryption
+    '''
+    return crypto.xor(k1(k, s1(b'SIRKenc'[::-1]), b'csis'[::-1]), r)
+
+
+def sih(k: bytes, r: bytes) -> bytes:
+    '''
+    Coordinated Set Identification Service - 4.7 Resolvable Set Identifier hash function sih.
+    '''
+    return crypto.e(k, r + bytes(13))[:3]
+
+
+def generate_rsi(sirk: bytes) -> bytes:
+    '''
+    Coordinated Set Identification Service - 4.8 Resolvable Set Identifier generation operation.
+    '''
+    prand = crypto.generate_prand()
+    return sih(sirk, prand) + prand
 
 
 # -----------------------------------------------------------------------------
@@ -54,6 +98,7 @@ class MemberLock(enum.IntEnum):
 class CoordinatedSetIdentificationService(gatt.TemplateService):
     UUID = gatt.GATT_COORDINATED_SET_IDENTIFICATION_SERVICE
 
+    set_identity_resolving_key: bytes
     set_identity_resolving_key_characteristic: gatt.Characteristic
     coordinated_set_size_characteristic: Optional[gatt.Characteristic] = None
     set_member_lock_characteristic: Optional[gatt.Characteristic] = None
@@ -62,19 +107,26 @@ class CoordinatedSetIdentificationService(gatt.TemplateService):
     def __init__(
         self,
         set_identity_resolving_key: bytes,
+        set_identity_resolving_key_type: SirkType,
         coordinated_set_size: Optional[int] = None,
         set_member_lock: Optional[MemberLock] = None,
         set_member_rank: Optional[int] = None,
     ) -> None:
+        if len(set_identity_resolving_key) != SET_IDENTITY_RESOLVING_KEY_LENGTH:
+            raise ValueError(
+                f'Invalid SIRK length {len(set_identity_resolving_key)}, expected {SET_IDENTITY_RESOLVING_KEY_LENGTH}'
+            )
+
         characteristics = []
 
+        self.set_identity_resolving_key = set_identity_resolving_key
+        self.set_identity_resolving_key_type = set_identity_resolving_key_type
         self.set_identity_resolving_key_characteristic = gatt.Characteristic(
             uuid=gatt.GATT_SET_IDENTITY_RESOLVING_KEY_CHARACTERISTIC,
             properties=gatt.Characteristic.Properties.READ
             | gatt.Characteristic.Properties.NOTIFY,
-            permissions=gatt.Characteristic.Permissions.READABLE,
-            # TODO: Implement encrypted SIRK reader.
-            value=struct.pack('B', SirkType.PLAINTEXT) + set_identity_resolving_key,
+            permissions=gatt.Characteristic.Permissions.READ_REQUIRES_ENCRYPTION,
+            value=gatt.CharacteristicValue(read=self.on_sirk_read),
         )
         characteristics.append(self.set_identity_resolving_key_characteristic)
 
@@ -83,7 +135,7 @@ class CoordinatedSetIdentificationService(gatt.TemplateService):
                 uuid=gatt.GATT_COORDINATED_SET_SIZE_CHARACTERISTIC,
                 properties=gatt.Characteristic.Properties.READ
                 | gatt.Characteristic.Properties.NOTIFY,
-                permissions=gatt.Characteristic.Permissions.READABLE,
+                permissions=gatt.Characteristic.Permissions.READ_REQUIRES_ENCRYPTION,
                 value=struct.pack('B', coordinated_set_size),
             )
             characteristics.append(self.coordinated_set_size_characteristic)
@@ -94,7 +146,7 @@ class CoordinatedSetIdentificationService(gatt.TemplateService):
                 properties=gatt.Characteristic.Properties.READ
                 | gatt.Characteristic.Properties.NOTIFY
                 | gatt.Characteristic.Properties.WRITE,
-                permissions=gatt.Characteristic.Permissions.READABLE
+                permissions=gatt.Characteristic.Permissions.READ_REQUIRES_ENCRYPTION
                 | gatt.Characteristic.Permissions.WRITEABLE,
                 value=struct.pack('B', set_member_lock),
             )
@@ -105,13 +157,45 @@ class CoordinatedSetIdentificationService(gatt.TemplateService):
                 uuid=gatt.GATT_SET_MEMBER_RANK_CHARACTERISTIC,
                 properties=gatt.Characteristic.Properties.READ
                 | gatt.Characteristic.Properties.NOTIFY,
-                permissions=gatt.Characteristic.Permissions.READABLE,
+                permissions=gatt.Characteristic.Permissions.READ_REQUIRES_ENCRYPTION,
                 value=struct.pack('B', set_member_rank),
             )
             characteristics.append(self.set_member_rank_characteristic)
 
         super().__init__(characteristics)
 
+    async def on_sirk_read(self, connection: Optional[device.Connection]) -> bytes:
+        if self.set_identity_resolving_key_type == SirkType.PLAINTEXT:
+            sirk_bytes = self.set_identity_resolving_key
+        else:
+            assert connection
+
+            if connection.transport == core.BT_LE_TRANSPORT:
+                key = await connection.device.get_long_term_key(
+                    connection_handle=connection.handle, rand=b'', ediv=0
+                )
+            else:
+                key = await connection.device.get_link_key(connection.peer_address)
+
+            if not key:
+                raise RuntimeError('LTK or LinkKey is not present')
+
+            sirk_bytes = sef(key, self.set_identity_resolving_key)
+
+        return bytes([self.set_identity_resolving_key_type]) + sirk_bytes
+
+    def get_advertising_data(self) -> bytes:
+        return bytes(
+            core.AdvertisingData(
+                [
+                    (
+                        core.AdvertisingData.RESOLVABLE_SET_IDENTIFIER,
+                        generate_rsi(self.set_identity_resolving_key),
+                    ),
+                ]
+            )
+        )
+
 
 # -----------------------------------------------------------------------------
 # Client
@@ -145,3 +229,29 @@ class CoordinatedSetIdentificationProxy(gatt_client.ProfileServiceProxy):
             gatt.GATT_SET_MEMBER_RANK_CHARACTERISTIC
         ):
             self.set_member_rank = characteristics[0]
+
+    async def read_set_identity_resolving_key(self) -> Tuple[SirkType, bytes]:
+        '''Reads SIRK and decrypts if encrypted.'''
+        response = await self.set_identity_resolving_key.read_value()
+        if len(response) != SET_IDENTITY_RESOLVING_KEY_LENGTH + 1:
+            raise RuntimeError('Invalid SIRK value')
+
+        sirk_type = SirkType(response[0])
+        if sirk_type == SirkType.PLAINTEXT:
+            sirk = response[1:]
+        else:
+            connection = self.service_proxy.client.connection
+            device = connection.device
+            if connection.transport == core.BT_LE_TRANSPORT:
+                key = await device.get_long_term_key(
+                    connection_handle=connection.handle, rand=b'', ediv=0
+                )
+            else:
+                key = await device.get_link_key(connection.peer_address)
+
+            if not key:
+                raise RuntimeError('LTK or LinkKey is not present')
+
+            sirk = sef(key, response[1:])
+
+        return (sirk_type, sirk)

bumble/profiles/device_information_service.py

@@ -19,8 +19,8 @@
 import struct
 from typing import Optional, Tuple
 
-from ..gatt_client import ProfileServiceProxy
-from ..gatt import (
+from bumble.gatt_client import ServiceProxy, ProfileServiceProxy, CharacteristicProxy
+from bumble.gatt import (
     GATT_DEVICE_INFORMATION_SERVICE,
     GATT_FIRMWARE_REVISION_STRING_CHARACTERISTIC,
     GATT_HARDWARE_REVISION_STRING_CHARACTERISTIC,
@@ -59,7 +59,7 @@ class DeviceInformationService(TemplateService):
         firmware_revision: Optional[str] = None,
         software_revision: Optional[str] = None,
         system_id: Optional[Tuple[int, int]] = None,  # (OUI, Manufacturer ID)
-        ieee_regulatory_certification_data_list: Optional[bytes] = None
+        ieee_regulatory_certification_data_list: Optional[bytes] = None,
         # TODO: pnp_id
     ):
         characteristics = [
@@ -104,10 +104,19 @@ class DeviceInformationService(TemplateService):
 class DeviceInformationServiceProxy(ProfileServiceProxy):
     SERVICE_CLASS = DeviceInformationService
 
-    def __init__(self, service_proxy):
+    manufacturer_name: Optional[UTF8CharacteristicAdapter]
+    model_number: Optional[UTF8CharacteristicAdapter]
+    serial_number: Optional[UTF8CharacteristicAdapter]
+    hardware_revision: Optional[UTF8CharacteristicAdapter]
+    firmware_revision: Optional[UTF8CharacteristicAdapter]
+    software_revision: Optional[UTF8CharacteristicAdapter]
+    system_id: Optional[DelegatedCharacteristicAdapter]
+    ieee_regulatory_certification_data_list: Optional[CharacteristicProxy]
+
+    def __init__(self, service_proxy: ServiceProxy):
         self.service_proxy = service_proxy
 
-        for (field, uuid) in (
+        for field, uuid in (
             ('manufacturer_name', GATT_MANUFACTURER_NAME_STRING_CHARACTERISTIC),
             ('model_number', GATT_MODEL_NUMBER_STRING_CHARACTERISTIC),
             ('serial_number', GATT_SERIAL_NUMBER_STRING_CHARACTERISTIC),

bumble/profiles/le_audio.py

@@ -0,0 +1,49 @@
+# 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 dataclasses
+from typing import List
+from typing_extensions import Self
+
+
+# -----------------------------------------------------------------------------
+# Classes
+# -----------------------------------------------------------------------------
+@dataclasses.dataclass
+class Metadata:
+    @dataclasses.dataclass
+    class Entry:
+        tag: int
+        data: bytes
+
+    entries: List[Entry]
+
+    @classmethod
+    def from_bytes(cls, data: bytes) -> Self:
+        entries = []
+        offset = 0
+        length = len(data)
+        while length >= 2:
+            entry_length = data[offset]
+            entry_tag = data[offset + 1]
+            entry_data = data[offset + 2 : offset + 2 + entry_length - 1]
+            entries.append(cls.Entry(entry_tag, entry_data))
+            length -= entry_length
+            offset += entry_length
+
+        return cls(entries)

bumble/profiles/pbp.py

@@ -0,0 +1,46 @@
+# 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 dataclasses
+import enum
+from typing_extensions import Self
+
+from bumble.profiles import le_audio
+
+
+# -----------------------------------------------------------------------------
+# Classes
+# -----------------------------------------------------------------------------
+@dataclasses.dataclass
+class PublicBroadcastAnnouncement:
+    class Features(enum.IntFlag):
+        ENCRYPTED = 1 << 0
+        STANDARD_QUALITY_CONFIGURATION = 1 << 1
+        HIGH_QUALITY_CONFIGURATION = 1 << 2
+
+    features: Features
+    metadata: le_audio.Metadata
+
+    @classmethod
+    def from_bytes(cls, data: bytes) -> Self:
+        features = cls.Features(data[0])
+        metadata_length = data[1]
+        metadata_ltv = data[1 : 1 + metadata_length]
+        return cls(
+            features=features, metadata=le_audio.Metadata.from_bytes(metadata_ltv)
+        )

bumble/profiles/vcp.py

@@ -0,0 +1,228 @@
+# Copyright 2021-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 enum
+
+from bumble import att
+from bumble import device
+from bumble import gatt
+from bumble import gatt_client
+
+from typing import Optional
+
+# -----------------------------------------------------------------------------
+# Constants
+# -----------------------------------------------------------------------------
+
+MIN_VOLUME = 0
+MAX_VOLUME = 255
+
+
+class ErrorCode(enum.IntEnum):
+    '''
+    See Volume Control Service 1.6. Application error codes.
+    '''
+
+    INVALID_CHANGE_COUNTER = 0x80
+    OPCODE_NOT_SUPPORTED = 0x81
+
+
+class VolumeFlags(enum.IntFlag):
+    '''
+    See Volume Control Service 3.3. Volume Flags.
+    '''
+
+    VOLUME_SETTING_PERSISTED = 0x01
+    # RFU
+
+
+class VolumeControlPointOpcode(enum.IntEnum):
+    '''
+    See Volume Control Service Table 3.3: Volume Control Point procedure requirements.
+    '''
+
+    # fmt: off
+    RELATIVE_VOLUME_DOWN        = 0x00
+    RELATIVE_VOLUME_UP          = 0x01
+    UNMUTE_RELATIVE_VOLUME_DOWN = 0x02
+    UNMUTE_RELATIVE_VOLUME_UP   = 0x03
+    SET_ABSOLUTE_VOLUME         = 0x04
+    UNMUTE                      = 0x05
+    MUTE                        = 0x06
+
+
+# -----------------------------------------------------------------------------
+# Server
+# -----------------------------------------------------------------------------
+class VolumeControlService(gatt.TemplateService):
+    UUID = gatt.GATT_VOLUME_CONTROL_SERVICE
+
+    volume_state: gatt.Characteristic
+    volume_control_point: gatt.Characteristic
+    volume_flags: gatt.Characteristic
+
+    volume_setting: int
+    muted: int
+    change_counter: int
+
+    def __init__(
+        self,
+        step_size: int = 16,
+        volume_setting: int = 0,
+        muted: int = 0,
+        change_counter: int = 0,
+        volume_flags: int = 0,
+    ) -> None:
+        self.step_size = step_size
+        self.volume_setting = volume_setting
+        self.muted = muted
+        self.change_counter = change_counter
+
+        self.volume_state = gatt.Characteristic(
+            uuid=gatt.GATT_VOLUME_STATE_CHARACTERISTIC,
+            properties=(
+                gatt.Characteristic.Properties.READ
+                | gatt.Characteristic.Properties.NOTIFY
+            ),
+            permissions=gatt.Characteristic.Permissions.READ_REQUIRES_ENCRYPTION,
+            value=gatt.CharacteristicValue(read=self._on_read_volume_state),
+        )
+        self.volume_control_point = gatt.Characteristic(
+            uuid=gatt.GATT_VOLUME_CONTROL_POINT_CHARACTERISTIC,
+            properties=gatt.Characteristic.Properties.WRITE,
+            permissions=gatt.Characteristic.Permissions.WRITE_REQUIRES_ENCRYPTION,
+            value=gatt.CharacteristicValue(write=self._on_write_volume_control_point),
+        )
+        self.volume_flags = gatt.Characteristic(
+            uuid=gatt.GATT_VOLUME_FLAGS_CHARACTERISTIC,
+            properties=gatt.Characteristic.Properties.READ,
+            permissions=gatt.Characteristic.Permissions.READ_REQUIRES_ENCRYPTION,
+            value=bytes([volume_flags]),
+        )
+
+        super().__init__(
+            [
+                self.volume_state,
+                self.volume_control_point,
+                self.volume_flags,
+            ]
+        )
+
+    @property
+    def volume_state_bytes(self) -> bytes:
+        return bytes([self.volume_setting, self.muted, self.change_counter])
+
+    @volume_state_bytes.setter
+    def volume_state_bytes(self, new_value: bytes) -> None:
+        self.volume_setting, self.muted, self.change_counter = new_value
+
+    def _on_read_volume_state(self, _connection: Optional[device.Connection]) -> bytes:
+        return self.volume_state_bytes
+
+    def _on_write_volume_control_point(
+        self, connection: Optional[device.Connection], value: bytes
+    ) -> None:
+        assert connection
+
+        opcode = VolumeControlPointOpcode(value[0])
+        change_counter = value[1]
+
+        if change_counter != self.change_counter:
+            raise att.ATT_Error(ErrorCode.INVALID_CHANGE_COUNTER)
+
+        handler = getattr(self, '_on_' + opcode.name.lower())
+        if handler(*value[2:]):
+            self.change_counter = (self.change_counter + 1) % 256
+            connection.abort_on(
+                'disconnection',
+                connection.device.notify_subscribers(
+                    attribute=self.volume_state,
+                    value=self.volume_state_bytes,
+                ),
+            )
+            self.emit(
+                'volume_state', self.volume_setting, self.muted, self.change_counter
+            )
+
+    def _on_relative_volume_down(self) -> bool:
+        old_volume = self.volume_setting
+        self.volume_setting = max(self.volume_setting - self.step_size, MIN_VOLUME)
+        return self.volume_setting != old_volume
+
+    def _on_relative_volume_up(self) -> bool:
+        old_volume = self.volume_setting
+        self.volume_setting = min(self.volume_setting + self.step_size, MAX_VOLUME)
+        return self.volume_setting != old_volume
+
+    def _on_unmute_relative_volume_down(self) -> bool:
+        old_volume, old_muted_state = self.volume_setting, self.muted
+        self.volume_setting = max(self.volume_setting - self.step_size, MIN_VOLUME)
+        self.muted = 0
+        return (self.volume_setting, self.muted) != (old_volume, old_muted_state)
+
+    def _on_unmute_relative_volume_up(self) -> bool:
+        old_volume, old_muted_state = self.volume_setting, self.muted
+        self.volume_setting = min(self.volume_setting + self.step_size, MAX_VOLUME)
+        self.muted = 0
+        return (self.volume_setting, self.muted) != (old_volume, old_muted_state)
+
+    def _on_set_absolute_volume(self, volume_setting: int) -> bool:
+        old_volume_setting = self.volume_setting
+        self.volume_setting = volume_setting
+        return old_volume_setting != self.volume_setting
+
+    def _on_unmute(self) -> bool:
+        old_muted_state = self.muted
+        self.muted = 0
+        return self.muted != old_muted_state
+
+    def _on_mute(self) -> bool:
+        old_muted_state = self.muted
+        self.muted = 1
+        return self.muted != old_muted_state
+
+
+# -----------------------------------------------------------------------------
+# Client
+# -----------------------------------------------------------------------------
+class VolumeControlServiceProxy(gatt_client.ProfileServiceProxy):
+    SERVICE_CLASS = VolumeControlService
+
+    volume_control_point: gatt_client.CharacteristicProxy
+
+    def __init__(self, service_proxy: gatt_client.ServiceProxy) -> None:
+        self.service_proxy = service_proxy
+
+        self.volume_state = gatt.PackedCharacteristicAdapter(
+            service_proxy.get_characteristics_by_uuid(
+                gatt.GATT_VOLUME_STATE_CHARACTERISTIC
+            )[0],
+            'BBB',
+        )
+
+        self.volume_control_point = service_proxy.get_characteristics_by_uuid(
+            gatt.GATT_VOLUME_CONTROL_POINT_CHARACTERISTIC
+        )[0]
+
+        self.volume_flags = gatt.PackedCharacteristicAdapter(
+            service_proxy.get_characteristics_by_uuid(
+                gatt.GATT_VOLUME_FLAGS_CHARACTERISTIC
+            )[0],
+            'B',
+        )

bumble/rfcomm.py

@@ -19,12 +19,17 @@ from __future__ import annotations
 
 import logging
 import asyncio
+import collections
+import dataclasses
 import enum
 from typing import Callable, Dict, List, Optional, Tuple, Union, TYPE_CHECKING
+from typing_extensions import Self
 
 from pyee import EventEmitter
 
-from . import core, l2cap
+from bumble import core
+from bumble import l2cap
+from bumble import sdp
 from .colors import color
 from .core import (
     UUID,
@@ -34,15 +39,6 @@ from .core import (
     InvalidStateError,
     ProtocolError,
 )
-from .sdp import (
-    SDP_SERVICE_RECORD_HANDLE_ATTRIBUTE_ID,
-    SDP_BROWSE_GROUP_LIST_ATTRIBUTE_ID,
-    SDP_SERVICE_CLASS_ID_LIST_ATTRIBUTE_ID,
-    SDP_PROTOCOL_DESCRIPTOR_LIST_ATTRIBUTE_ID,
-    SDP_PUBLIC_BROWSE_ROOT,
-    DataElement,
-    ServiceAttribute,
-)
 
 if TYPE_CHECKING:
     from bumble.device import Device, Connection
@@ -59,28 +55,20 @@ logger = logging.getLogger(__name__)
 # fmt: off
 
 RFCOMM_PSM = 0x0003
+DEFAULT_RX_QUEUE_SIZE = 32
 
+class FrameType(enum.IntEnum):
+    SABM = 0x2F  # Control field [1,1,1,1,_,1,0,0] LSB-first
+    UA   = 0x63  # Control field [0,1,1,0,_,0,1,1] LSB-first
+    DM   = 0x0F  # Control field [1,1,1,1,_,0,0,0] LSB-first
+    DISC = 0x43  # Control field [0,1,0,_,0,0,1,1] LSB-first
+    UIH  = 0xEF  # Control field [1,1,1,_,1,1,1,1] LSB-first
+    UI   = 0x03  # Control field [0,0,0,_,0,0,1,1] LSB-first
 
-# Frame types
-RFCOMM_SABM_FRAME = 0x2F  # Control field [1,1,1,1,_,1,0,0] LSB-first
-RFCOMM_UA_FRAME   = 0x63  # Control field [0,1,1,0,_,0,1,1] LSB-first
-RFCOMM_DM_FRAME   = 0x0F  # Control field [1,1,1,1,_,0,0,0] LSB-first
-RFCOMM_DISC_FRAME = 0x43  # Control field [0,1,0,_,0,0,1,1] LSB-first
-RFCOMM_UIH_FRAME  = 0xEF  # Control field [1,1,1,_,1,1,1,1] LSB-first
-RFCOMM_UI_FRAME   = 0x03  # Control field [0,0,0,_,0,0,1,1] LSB-first
+class MccType(enum.IntEnum):
+    PN  = 0x20
+    MSC = 0x38
 
-RFCOMM_FRAME_TYPE_NAMES = {
-    RFCOMM_SABM_FRAME: 'SABM',
-    RFCOMM_UA_FRAME:   'UA',
-    RFCOMM_DM_FRAME:   'DM',
-    RFCOMM_DISC_FRAME: 'DISC',
-    RFCOMM_UIH_FRAME:  'UIH',
-    RFCOMM_UI_FRAME:   'UI'
-}
-
-# MCC Types
-RFCOMM_MCC_PN_TYPE  = 0x20
-RFCOMM_MCC_MSC_TYPE = 0x38
 
 # FCS CRC
 CRC_TABLE = bytes([
@@ -118,8 +106,11 @@ CRC_TABLE = bytes([
     0XBA, 0X2B, 0X59, 0XC8, 0XBD, 0X2C, 0X5E, 0XCF
 ])
 
-RFCOMM_DEFAULT_INITIAL_RX_CREDITS = 7
-RFCOMM_DEFAULT_PREFERRED_MTU      = 1280
+RFCOMM_DEFAULT_L2CAP_MTU        = 2048
+RFCOMM_DEFAULT_INITIAL_CREDITS  = 7
+RFCOMM_DEFAULT_MAX_CREDITS      = 32
+RFCOMM_DEFAULT_CREDIT_THRESHOLD = RFCOMM_DEFAULT_MAX_CREDITS // 2
+RFCOMM_DEFAULT_MAX_FRAME_SIZE   = 2000
 
 RFCOMM_DYNAMIC_CHANNEL_NUMBER_START = 1
 RFCOMM_DYNAMIC_CHANNEL_NUMBER_END   = 30
@@ -130,29 +121,33 @@ RFCOMM_DYNAMIC_CHANNEL_NUMBER_END   = 30
 # -----------------------------------------------------------------------------
 def make_service_sdp_records(
     service_record_handle: int, channel: int, uuid: Optional[UUID] = None
-) -> List[ServiceAttribute]:
+) -> List[sdp.ServiceAttribute]:
     """
     Create SDP records for an RFComm service given a channel number and an
     optional UUID. A Service Class Attribute is included only if the UUID is not None.
     """
     records = [
-        ServiceAttribute(
-            SDP_SERVICE_RECORD_HANDLE_ATTRIBUTE_ID,
-            DataElement.unsigned_integer_32(service_record_handle),
+        sdp.ServiceAttribute(
+            sdp.SDP_SERVICE_RECORD_HANDLE_ATTRIBUTE_ID,
+            sdp.DataElement.unsigned_integer_32(service_record_handle),
         ),
-        ServiceAttribute(
-            SDP_BROWSE_GROUP_LIST_ATTRIBUTE_ID,
-            DataElement.sequence([DataElement.uuid(SDP_PUBLIC_BROWSE_ROOT)]),
+        sdp.ServiceAttribute(
+            sdp.SDP_BROWSE_GROUP_LIST_ATTRIBUTE_ID,
+            sdp.DataElement.sequence(
+                [sdp.DataElement.uuid(sdp.SDP_PUBLIC_BROWSE_ROOT)]
+            ),
         ),
-        ServiceAttribute(
-            SDP_PROTOCOL_DESCRIPTOR_LIST_ATTRIBUTE_ID,
-            DataElement.sequence(
+        sdp.ServiceAttribute(
+            sdp.SDP_PROTOCOL_DESCRIPTOR_LIST_ATTRIBUTE_ID,
+            sdp.DataElement.sequence(
                 [
-                    DataElement.sequence([DataElement.uuid(BT_L2CAP_PROTOCOL_ID)]),
-                    DataElement.sequence(
+                    sdp.DataElement.sequence(
+                        [sdp.DataElement.uuid(BT_L2CAP_PROTOCOL_ID)]
+                    ),
+                    sdp.DataElement.sequence(
                         [
-                            DataElement.uuid(BT_RFCOMM_PROTOCOL_ID),
-                            DataElement.unsigned_integer_8(channel),
+                            sdp.DataElement.uuid(BT_RFCOMM_PROTOCOL_ID),
+                            sdp.DataElement.unsigned_integer_8(channel),
                         ]
                     ),
                 ]
@@ -162,15 +157,81 @@ def make_service_sdp_records(
 
     if uuid:
         records.append(
-            ServiceAttribute(
-                SDP_SERVICE_CLASS_ID_LIST_ATTRIBUTE_ID,
-                DataElement.sequence([DataElement.uuid(uuid)]),
+            sdp.ServiceAttribute(
+                sdp.SDP_SERVICE_CLASS_ID_LIST_ATTRIBUTE_ID,
+                sdp.DataElement.sequence([sdp.DataElement.uuid(uuid)]),
             )
         )
 
     return records
 
 
+# -----------------------------------------------------------------------------
+async def find_rfcomm_channels(connection: Connection) -> Dict[int, List[UUID]]:
+    """Searches all RFCOMM channels and their associated UUID from SDP service records.
+
+    Args:
+        connection: ACL connection to make SDP search.
+
+    Returns:
+        Dictionary mapping from channel number to service class UUID list.
+    """
+    results = {}
+    async with sdp.Client(connection) as sdp_client:
+        search_result = await sdp_client.search_attributes(
+            uuids=[core.BT_RFCOMM_PROTOCOL_ID],
+            attribute_ids=[
+                sdp.SDP_PROTOCOL_DESCRIPTOR_LIST_ATTRIBUTE_ID,
+                sdp.SDP_SERVICE_CLASS_ID_LIST_ATTRIBUTE_ID,
+            ],
+        )
+        for attribute_lists in search_result:
+            service_classes: List[UUID] = []
+            channel: Optional[int] = None
+            for attribute in attribute_lists:
+                # The layout is [[L2CAP_PROTOCOL], [RFCOMM_PROTOCOL, RFCOMM_CHANNEL]].
+                if attribute.id == sdp.SDP_PROTOCOL_DESCRIPTOR_LIST_ATTRIBUTE_ID:
+                    protocol_descriptor_list = attribute.value.value
+                    channel = protocol_descriptor_list[1].value[1].value
+                elif attribute.id == sdp.SDP_SERVICE_CLASS_ID_LIST_ATTRIBUTE_ID:
+                    service_class_id_list = attribute.value.value
+                    service_classes = [
+                        service_class.value for service_class in service_class_id_list
+                    ]
+            if not service_classes or not channel:
+                logger.warning(f"Bad result {attribute_lists}.")
+            else:
+                results[channel] = service_classes
+    return results
+
+
+# -----------------------------------------------------------------------------
+async def find_rfcomm_channel_with_uuid(
+    connection: Connection, uuid: str | UUID
+) -> Optional[int]:
+    """Searches an RFCOMM channel associated with given UUID from service records.
+
+    Args:
+        connection: ACL connection to make SDP search.
+        uuid: UUID of service record to search for.
+
+    Returns:
+        RFCOMM channel number if found, otherwise None.
+    """
+    if isinstance(uuid, str):
+        uuid = UUID(uuid)
+    return next(
+        (
+            channel
+            for channel, class_id_list in (
+                await find_rfcomm_channels(connection)
+            ).items()
+            if uuid in class_id_list
+        ),
+        None,
+    )
+
+
 # -----------------------------------------------------------------------------
 def compute_fcs(buffer: bytes) -> int:
     result = 0xFF
@@ -183,7 +244,7 @@ def compute_fcs(buffer: bytes) -> int:
 class RFCOMM_Frame:
     def __init__(
         self,
-        frame_type: int,
+        frame_type: FrameType,
         c_r: int,
         dlci: int,
         p_f: int,
@@ -206,14 +267,11 @@ class RFCOMM_Frame:
             self.length = bytes([(length << 1) | 1])
         self.address = (dlci << 2) | (c_r << 1) | 1
         self.control = frame_type | (p_f << 4)
-        if frame_type == RFCOMM_UIH_FRAME:
+        if frame_type == FrameType.UIH:
             self.fcs = compute_fcs(bytes([self.address, self.control]))
         else:
             self.fcs = compute_fcs(bytes([self.address, self.control]) + self.length)
 
-    def type_name(self) -> str:
-        return RFCOMM_FRAME_TYPE_NAMES[self.type]
-
     @staticmethod
     def parse_mcc(data) -> Tuple[int, bool, bytes]:
         mcc_type = data[0] >> 2
@@ -237,24 +295,24 @@ class RFCOMM_Frame:
 
     @staticmethod
     def sabm(c_r: int, dlci: int):
-        return RFCOMM_Frame(RFCOMM_SABM_FRAME, c_r, dlci, 1)
+        return RFCOMM_Frame(FrameType.SABM, c_r, dlci, 1)
 
     @staticmethod
     def ua(c_r: int, dlci: int):
-        return RFCOMM_Frame(RFCOMM_UA_FRAME, c_r, dlci, 1)
+        return RFCOMM_Frame(FrameType.UA, c_r, dlci, 1)
 
     @staticmethod
     def dm(c_r: int, dlci: int):
-        return RFCOMM_Frame(RFCOMM_DM_FRAME, c_r, dlci, 1)
+        return RFCOMM_Frame(FrameType.DM, c_r, dlci, 1)
 
     @staticmethod
     def disc(c_r: int, dlci: int):
-        return RFCOMM_Frame(RFCOMM_DISC_FRAME, c_r, dlci, 1)
+        return RFCOMM_Frame(FrameType.DISC, c_r, dlci, 1)
 
     @staticmethod
     def uih(c_r: int, dlci: int, information: bytes, p_f: int = 0):
         return RFCOMM_Frame(
-            RFCOMM_UIH_FRAME, c_r, dlci, p_f, information, with_credits=(p_f == 1)
+            FrameType.UIH, c_r, dlci, p_f, information, with_credits=(p_f == 1)
         )
 
     @staticmethod
@@ -262,7 +320,7 @@ class RFCOMM_Frame:
         # Extract fields
         dlci = (data[0] >> 2) & 0x3F
         c_r = (data[0] >> 1) & 0x01
-        frame_type = data[1] & 0xEF
+        frame_type = FrameType(data[1] & 0xEF)
         p_f = (data[1] >> 4) & 0x01
         length = data[2]
         if length & 0x01:
@@ -291,7 +349,7 @@ class RFCOMM_Frame:
 
     def __str__(self) -> str:
         return (
-            f'{color(self.type_name(), "yellow")}'
+            f'{color(self.type.name, "yellow")}'
             f'(c/r={self.c_r},'
             f'dlci={self.dlci},'
             f'p/f={self.p_f},'
@@ -301,6 +359,7 @@ class RFCOMM_Frame:
 
 
 # -----------------------------------------------------------------------------
+@dataclasses.dataclass
 class RFCOMM_MCC_PN:
     dlci: int
     cl: int
@@ -308,25 +367,13 @@ class RFCOMM_MCC_PN:
     ack_timer: int
     max_frame_size: int
     max_retransmissions: int
-    window_size: int
+    initial_credits: int
 
-    def __init__(
-        self,
-        dlci: int,
-        cl: int,
-        priority: int,
-        ack_timer: int,
-        max_frame_size: int,
-        max_retransmissions: int,
-        window_size: int,
-    ) -> None:
-        self.dlci = dlci
-        self.cl = cl
-        self.priority = priority
-        self.ack_timer = ack_timer
-        self.max_frame_size = max_frame_size
-        self.max_retransmissions = max_retransmissions
-        self.window_size = window_size
+    def __post_init__(self) -> None:
+        if self.initial_credits < 1 or self.initial_credits > 7:
+            logger.warning(
+                f'Initial credits {self.initial_credits} is out of range [1, 7].'
+            )
 
     @staticmethod
     def from_bytes(data: bytes) -> RFCOMM_MCC_PN:
@@ -337,7 +384,7 @@ class RFCOMM_MCC_PN:
             ack_timer=data[3],
             max_frame_size=data[4] | data[5] << 8,
             max_retransmissions=data[6],
-            window_size=data[7],
+            initial_credits=data[7] & 0x07,
         )
 
     def __bytes__(self) -> bytes:
@@ -350,23 +397,14 @@ class RFCOMM_MCC_PN:
                 self.max_frame_size & 0xFF,
                 (self.max_frame_size >> 8) & 0xFF,
                 self.max_retransmissions & 0xFF,
-                self.window_size & 0xFF,
+                # Only 3 bits are meaningful.
+                self.initial_credits & 0x07,
             ]
         )
 
-    def __str__(self) -> str:
-        return (
-            f'PN(dlci={self.dlci},'
-            f'cl={self.cl},'
-            f'priority={self.priority},'
-            f'ack_timer={self.ack_timer},'
-            f'max_frame_size={self.max_frame_size},'
-            f'max_retransmissions={self.max_retransmissions},'
-            f'window_size={self.window_size})'
-        )
-
 
 # -----------------------------------------------------------------------------
+@dataclasses.dataclass
 class RFCOMM_MCC_MSC:
     dlci: int
     fc: int
@@ -375,16 +413,6 @@ class RFCOMM_MCC_MSC:
     ic: int
     dv: int
 
-    def __init__(
-        self, dlci: int, fc: int, rtc: int, rtr: int, ic: int, dv: int
-    ) -> None:
-        self.dlci = dlci
-        self.fc = fc
-        self.rtc = rtc
-        self.rtr = rtr
-        self.ic = ic
-        self.dv = dv
-
     @staticmethod
     def from_bytes(data: bytes) -> RFCOMM_MCC_MSC:
         return RFCOMM_MCC_MSC(
@@ -409,16 +437,6 @@ class RFCOMM_MCC_MSC:
             ]
         )
 
-    def __str__(self) -> str:
-        return (
-            f'MSC(dlci={self.dlci},'
-            f'fc={self.fc},'
-            f'rtc={self.rtc},'
-            f'rtr={self.rtr},'
-            f'ic={self.ic},'
-            f'dv={self.dv})'
-        )
-
 
 # -----------------------------------------------------------------------------
 class DLC(EventEmitter):
@@ -430,35 +448,58 @@ class DLC(EventEmitter):
         DISCONNECTED = 0x04
         RESET = 0x05
 
-    connection_result: Optional[asyncio.Future]
-    sink: Optional[Callable[[bytes], None]]
-
     def __init__(
         self,
         multiplexer: Multiplexer,
         dlci: int,
-        max_frame_size: int,
-        initial_tx_credits: int,
+        tx_max_frame_size: int,
+        tx_initial_credits: int,
+        rx_max_frame_size: int,
+        rx_initial_credits: int,
     ) -> None:
         super().__init__()
         self.multiplexer = multiplexer
         self.dlci = dlci
-        self.rx_credits = RFCOMM_DEFAULT_INITIAL_RX_CREDITS
-        self.rx_threshold = self.rx_credits // 2
-        self.tx_credits = initial_tx_credits
+        self.rx_max_frame_size = rx_max_frame_size
+        self.rx_initial_credits = rx_initial_credits
+        self.rx_max_credits = RFCOMM_DEFAULT_MAX_CREDITS
+        self.rx_credits = rx_initial_credits
+        self.rx_credits_threshold = RFCOMM_DEFAULT_CREDIT_THRESHOLD
+        self.tx_max_frame_size = tx_max_frame_size
+        self.tx_credits = tx_initial_credits
         self.tx_buffer = b''
         self.state = DLC.State.INIT
         self.role = multiplexer.role
         self.c_r = 1 if self.role == Multiplexer.Role.INITIATOR else 0
-        self.sink = None
-        self.connection_result = None
+        self.connection_result: Optional[asyncio.Future] = None
+        self.disconnection_result: Optional[asyncio.Future] = None
+        self.drained = asyncio.Event()
+        self.drained.set()
+        # Queued packets when sink is not set.
+        self._enqueued_rx_packets: collections.deque[bytes] = collections.deque(
+            maxlen=DEFAULT_RX_QUEUE_SIZE
+        )
+        self._sink: Optional[Callable[[bytes], None]] = None
 
         # Compute the MTU
         max_overhead = 4 + 1  # header with 2-byte length + fcs
         self.mtu = min(
-            max_frame_size, self.multiplexer.l2cap_channel.mtu - max_overhead
+            tx_max_frame_size, self.multiplexer.l2cap_channel.peer_mtu - max_overhead
         )
 
+    @property
+    def sink(self) -> Optional[Callable[[bytes], None]]:
+        return self._sink
+
+    @sink.setter
+    def sink(self, sink: Optional[Callable[[bytes], None]]) -> None:
+        self._sink = sink
+        # Dump queued packets to sink
+        if sink:
+            for packet in self._enqueued_rx_packets:
+                sink(packet)  # pylint: disable=not-callable
+            self._enqueued_rx_packets.clear()
+
     def change_state(self, new_state: State) -> None:
         logger.debug(f'{self} state change -> {color(new_state.name, "magenta")}')
         self.state = new_state
@@ -467,7 +508,7 @@ class DLC(EventEmitter):
         self.multiplexer.send_frame(frame)
 
     def on_frame(self, frame: RFCOMM_Frame) -> None:
-        handler = getattr(self, f'on_{frame.type_name()}_frame'.lower())
+        handler = getattr(self, f'on_{frame.type.name}_frame'.lower())
         handler(frame)
 
     def on_sabm_frame(self, _frame: RFCOMM_Frame) -> None:
@@ -481,9 +522,7 @@ class DLC(EventEmitter):
 
         # Exchange the modem status with the peer
         msc = RFCOMM_MCC_MSC(dlci=self.dlci, fc=0, rtc=1, rtr=1, ic=0, dv=1)
-        mcc = RFCOMM_Frame.make_mcc(
-            mcc_type=RFCOMM_MCC_MSC_TYPE, c_r=1, data=bytes(msc)
-        )
+        mcc = RFCOMM_Frame.make_mcc(mcc_type=MccType.MSC, c_r=1, data=bytes(msc))
         logger.debug(f'>>> MCC MSC Command: {msc}')
         self.send_frame(RFCOMM_Frame.uih(c_r=self.c_r, dlci=0, information=mcc))
 
@@ -491,22 +530,35 @@ class DLC(EventEmitter):
         self.emit('open')
 
     def on_ua_frame(self, _frame: RFCOMM_Frame) -> None:
-        if self.state != DLC.State.CONNECTING:
+        if self.state == DLC.State.CONNECTING:
+            # Exchange the modem status with the peer
+            msc = RFCOMM_MCC_MSC(dlci=self.dlci, fc=0, rtc=1, rtr=1, ic=0, dv=1)
+            mcc = RFCOMM_Frame.make_mcc(mcc_type=MccType.MSC, c_r=1, data=bytes(msc))
+            logger.debug(f'>>> MCC MSC Command: {msc}')
+            self.send_frame(RFCOMM_Frame.uih(c_r=self.c_r, dlci=0, information=mcc))
+
+            self.change_state(DLC.State.CONNECTED)
+            if self.connection_result:
+                self.connection_result.set_result(None)
+                self.connection_result = None
+            self.multiplexer.on_dlc_open_complete(self)
+        elif self.state == DLC.State.DISCONNECTING:
+            self.change_state(DLC.State.DISCONNECTED)
+            if self.disconnection_result:
+                self.disconnection_result.set_result(None)
+                self.disconnection_result = None
+            self.multiplexer.on_dlc_disconnection(self)
+            self.emit('close')
+        else:
             logger.warning(
-                color('!!! received SABM when not in CONNECTING state', 'red')
+                color(
+                    (
+                        '!!! received UA frame when not in '
+                        'CONNECTING or DISCONNECTING state'
+                    ),
+                    'red',
+                )
             )
-            return
-
-        # Exchange the modem status with the peer
-        msc = RFCOMM_MCC_MSC(dlci=self.dlci, fc=0, rtc=1, rtr=1, ic=0, dv=1)
-        mcc = RFCOMM_Frame.make_mcc(
-            mcc_type=RFCOMM_MCC_MSC_TYPE, c_r=1, data=bytes(msc)
-        )
-        logger.debug(f'>>> MCC MSC Command: {msc}')
-        self.send_frame(RFCOMM_Frame.uih(c_r=self.c_r, dlci=0, information=mcc))
-
-        self.change_state(DLC.State.CONNECTED)
-        self.multiplexer.on_dlc_open_complete(self)
 
     def on_dm_frame(self, frame: RFCOMM_Frame) -> None:
         # TODO: handle all states
@@ -534,14 +586,22 @@ class DLC(EventEmitter):
             f'[{self.dlci}] {len(data)} bytes, '
             f'rx_credits={self.rx_credits}: {data.hex()}'
         )
-        if len(data) and self.sink:
-            self.sink(data)  # pylint: disable=not-callable
+        if data:
+            if self._sink:
+                self._sink(data)  # pylint: disable=not-callable
+            else:
+                self._enqueued_rx_packets.append(data)
+            if (
+                self._enqueued_rx_packets.maxlen
+                and len(self._enqueued_rx_packets) >= self._enqueued_rx_packets.maxlen
+            ):
+                logger.warning(f'DLC [{self.dlci}] received packet queue is full')
 
-        # Update the credits
-        if self.rx_credits > 0:
-            self.rx_credits -= 1
-        else:
-            logger.warning(color('!!! received frame with no rx credits', 'red'))
+            # Update the credits
+            if self.rx_credits > 0:
+                self.rx_credits -= 1
+            else:
+                logger.warning(color('!!! received frame with no rx credits', 'red'))
 
         # Check if there's anything to send (including credits)
         self.process_tx()
@@ -554,9 +614,7 @@ class DLC(EventEmitter):
             # Command
             logger.debug(f'<<< MCC MSC Command: {msc}')
             msc = RFCOMM_MCC_MSC(dlci=self.dlci, fc=0, rtc=1, rtr=1, ic=0, dv=1)
-            mcc = RFCOMM_Frame.make_mcc(
-                mcc_type=RFCOMM_MCC_MSC_TYPE, c_r=0, data=bytes(msc)
-            )
+            mcc = RFCOMM_Frame.make_mcc(mcc_type=MccType.MSC, c_r=0, data=bytes(msc))
             logger.debug(f'>>> MCC MSC Response: {msc}')
             self.send_frame(RFCOMM_Frame.uih(c_r=self.c_r, dlci=0, information=mcc))
         else:
@@ -571,6 +629,19 @@ class DLC(EventEmitter):
         self.connection_result = asyncio.get_running_loop().create_future()
         self.send_frame(RFCOMM_Frame.sabm(c_r=self.c_r, dlci=self.dlci))
 
+    async def disconnect(self) -> None:
+        if self.state != DLC.State.CONNECTED:
+            raise InvalidStateError('invalid state')
+
+        self.disconnection_result = asyncio.get_running_loop().create_future()
+        self.change_state(DLC.State.DISCONNECTING)
+        self.send_frame(
+            RFCOMM_Frame.disc(
+                c_r=1 if self.role == Multiplexer.Role.INITIATOR else 0, dlci=self.dlci
+            )
+        )
+        await self.disconnection_result
+
     def accept(self) -> None:
         if self.state != DLC.State.INIT:
             raise InvalidStateError('invalid state')
@@ -580,18 +651,18 @@ class DLC(EventEmitter):
             cl=0xE0,
             priority=7,
             ack_timer=0,
-            max_frame_size=RFCOMM_DEFAULT_PREFERRED_MTU,
+            max_frame_size=self.rx_max_frame_size,
             max_retransmissions=0,
-            window_size=RFCOMM_DEFAULT_INITIAL_RX_CREDITS,
+            initial_credits=self.rx_initial_credits,
         )
-        mcc = RFCOMM_Frame.make_mcc(mcc_type=RFCOMM_MCC_PN_TYPE, c_r=0, data=bytes(pn))
+        mcc = RFCOMM_Frame.make_mcc(mcc_type=MccType.PN, c_r=0, data=bytes(pn))
         logger.debug(f'>>> PN Response: {pn}')
         self.send_frame(RFCOMM_Frame.uih(c_r=self.c_r, dlci=0, information=mcc))
         self.change_state(DLC.State.CONNECTING)
 
     def rx_credits_needed(self) -> int:
-        if self.rx_credits <= self.rx_threshold:
-            return RFCOMM_DEFAULT_INITIAL_RX_CREDITS - self.rx_credits
+        if self.rx_credits <= self.rx_credits_threshold:
+            return self.rx_max_credits - self.rx_credits
 
         return 0
 
@@ -631,6 +702,8 @@ class DLC(EventEmitter):
             )
 
             rx_credits_needed = 0
+            if not self.tx_buffer:
+                self.drained.set()
 
     # Stream protocol
     def write(self, data: Union[bytes, str]) -> None:
@@ -643,14 +716,34 @@ class DLC(EventEmitter):
                 raise ValueError('write only accept bytes or strings')
 
         self.tx_buffer += data
+        self.drained.clear()
         self.process_tx()
 
-    def drain(self) -> None:
-        # TODO
-        pass
+    async def drain(self) -> None:
+        await self.drained.wait()
+
+    def abort(self) -> None:
+        logger.debug(f'aborting DLC: {self}')
+        if self.connection_result:
+            self.connection_result.cancel()
+            self.connection_result = None
+        if self.disconnection_result:
+            self.disconnection_result.cancel()
+            self.disconnection_result = None
+        self.change_state(DLC.State.RESET)
+        self.emit('close')
 
     def __str__(self) -> str:
-        return f'DLC(dlci={self.dlci},state={self.state.name})'
+        return (
+            f'DLC(dlci={self.dlci}, '
+            f'state={self.state.name}, '
+            f'rx_max_frame_size={self.rx_max_frame_size}, '
+            f'rx_credits={self.rx_credits}, '
+            f'rx_max_credits={self.rx_max_credits}, '
+            f'tx_max_frame_size={self.tx_max_frame_size}, '
+            f'tx_credits={self.tx_credits}'
+            ')'
+        )
 
 
 # -----------------------------------------------------------------------------
@@ -671,7 +764,7 @@ class Multiplexer(EventEmitter):
     connection_result: Optional[asyncio.Future]
     disconnection_result: Optional[asyncio.Future]
     open_result: Optional[asyncio.Future]
-    acceptor: Optional[Callable[[int], bool]]
+    acceptor: Optional[Callable[[int], Optional[Tuple[int, int]]]]
     dlcs: Dict[int, DLC]
 
     def __init__(self, l2cap_channel: l2cap.ClassicChannel, role: Role) -> None:
@@ -683,11 +776,15 @@ class Multiplexer(EventEmitter):
         self.connection_result = None
         self.disconnection_result = None
         self.open_result = None
+        self.open_pn: Optional[RFCOMM_MCC_PN] = None
+        self.open_rx_max_credits = 0
         self.acceptor = None
 
         # Become a sink for the L2CAP channel
         l2cap_channel.sink = self.on_pdu
 
+        l2cap_channel.on('close', self.on_l2cap_channel_close)
+
     def change_state(self, new_state: State) -> None:
         logger.debug(f'{self} state change -> {color(new_state.name, "cyan")}')
         self.state = new_state
@@ -704,7 +801,7 @@ class Multiplexer(EventEmitter):
         if frame.dlci == 0:
             self.on_frame(frame)
         else:
-            if frame.type == RFCOMM_DM_FRAME:
+            if frame.type == FrameType.DM:
                 # DM responses are for a DLCI, but since we only create the dlc when we
                 # receive a PN response (because we need the parameters), we handle DM
                 # frames at the Multiplexer level
@@ -717,7 +814,7 @@ class Multiplexer(EventEmitter):
                 dlc.on_frame(frame)
 
     def on_frame(self, frame: RFCOMM_Frame) -> None:
-        handler = getattr(self, f'on_{frame.type_name()}_frame'.lower())
+        handler = getattr(self, f'on_{frame.type.name}_frame'.lower())
         handler(frame)
 
     def on_sabm_frame(self, _frame: RFCOMM_Frame) -> None:
@@ -751,6 +848,7 @@ class Multiplexer(EventEmitter):
                         'rfcomm',
                     )
                 )
+                self.open_result = None
         else:
             logger.warning(f'unexpected state for DM: {self}')
 
@@ -765,10 +863,10 @@ class Multiplexer(EventEmitter):
     def on_uih_frame(self, frame: RFCOMM_Frame) -> None:
         (mcc_type, c_r, value) = RFCOMM_Frame.parse_mcc(frame.information)
 
-        if mcc_type == RFCOMM_MCC_PN_TYPE:
+        if mcc_type == MccType.PN:
             pn = RFCOMM_MCC_PN.from_bytes(value)
             self.on_mcc_pn(c_r, pn)
-        elif mcc_type == RFCOMM_MCC_MSC_TYPE:
+        elif mcc_type == MccType.MSC:
             mcs = RFCOMM_MCC_MSC.from_bytes(value)
             self.on_mcc_msc(c_r, mcs)
 
@@ -788,9 +886,16 @@ class Multiplexer(EventEmitter):
             else:
                 if self.acceptor:
                     channel_number = pn.dlci >> 1
-                    if self.acceptor(channel_number):
+                    if dlc_params := self.acceptor(channel_number):
                         # Create a new DLC
-                        dlc = DLC(self, pn.dlci, pn.max_frame_size, pn.window_size)
+                        dlc = DLC(
+                            self,
+                            dlci=pn.dlci,
+                            tx_max_frame_size=pn.max_frame_size,
+                            tx_initial_credits=pn.initial_credits,
+                            rx_max_frame_size=dlc_params[0],
+                            rx_initial_credits=dlc_params[1],
+                        )
                         self.dlcs[pn.dlci] = dlc
 
                         # Re-emit the handshake completion event
@@ -808,8 +913,17 @@ class Multiplexer(EventEmitter):
             # Response
             logger.debug(f'>>> PN Response: {pn}')
             if self.state == Multiplexer.State.OPENING:
-                dlc = DLC(self, pn.dlci, pn.max_frame_size, pn.window_size)
+                assert self.open_pn
+                dlc = DLC(
+                    self,
+                    dlci=pn.dlci,
+                    tx_max_frame_size=pn.max_frame_size,
+                    tx_initial_credits=pn.initial_credits,
+                    rx_max_frame_size=self.open_pn.max_frame_size,
+                    rx_initial_credits=self.open_pn.initial_credits,
+                )
                 self.dlcs[pn.dlci] = dlc
+                self.open_pn = None
                 dlc.connect()
             else:
                 logger.warning('ignoring PN response')
@@ -843,24 +957,31 @@ class Multiplexer(EventEmitter):
         )
         await self.disconnection_result
 
-    async def open_dlc(self, channel: int) -> DLC:
+    async def open_dlc(
+        self,
+        channel: int,
+        max_frame_size: int = RFCOMM_DEFAULT_MAX_FRAME_SIZE,
+        initial_credits: int = RFCOMM_DEFAULT_INITIAL_CREDITS,
+    ) -> DLC:
         if self.state != Multiplexer.State.CONNECTED:
             if self.state == Multiplexer.State.OPENING:
                 raise InvalidStateError('open already in progress')
 
             raise InvalidStateError('not connected')
 
-        pn = RFCOMM_MCC_PN(
+        self.open_pn = RFCOMM_MCC_PN(
             dlci=channel << 1,
             cl=0xF0,
             priority=7,
             ack_timer=0,
-            max_frame_size=RFCOMM_DEFAULT_PREFERRED_MTU,
+            max_frame_size=max_frame_size,
             max_retransmissions=0,
-            window_size=RFCOMM_DEFAULT_INITIAL_RX_CREDITS,
+            initial_credits=initial_credits,
         )
-        mcc = RFCOMM_Frame.make_mcc(mcc_type=RFCOMM_MCC_PN_TYPE, c_r=1, data=bytes(pn))
-        logger.debug(f'>>> Sending MCC: {pn}')
+        mcc = RFCOMM_Frame.make_mcc(
+            mcc_type=MccType.PN, c_r=1, data=bytes(self.open_pn)
+        )
+        logger.debug(f'>>> Sending MCC: {self.open_pn}')
         self.open_result = asyncio.get_running_loop().create_future()
         self.change_state(Multiplexer.State.OPENING)
         self.send_frame(
@@ -870,15 +991,31 @@ class Multiplexer(EventEmitter):
                 information=mcc,
             )
         )
-        result = await self.open_result
-        self.open_result = None
-        return result
+        return await self.open_result
 
     def on_dlc_open_complete(self, dlc: DLC) -> None:
         logger.debug(f'DLC [{dlc.dlci}] open complete')
+
         self.change_state(Multiplexer.State.CONNECTED)
+
         if self.open_result:
             self.open_result.set_result(dlc)
+            self.open_result = None
+
+    def on_dlc_disconnection(self, dlc: DLC) -> None:
+        logger.debug(f'DLC [{dlc.dlci}] disconnection')
+        self.dlcs.pop(dlc.dlci, None)
+
+    def on_l2cap_channel_close(self) -> None:
+        logger.debug('L2CAP channel closed, cleaning up')
+        if self.open_result:
+            self.open_result.cancel()
+            self.open_result = None
+        if self.disconnection_result:
+            self.disconnection_result.cancel()
+            self.disconnection_result = None
+        for dlc in self.dlcs.values():
+            dlc.abort()
 
     def __str__(self) -> str:
         return f'Multiplexer(state={self.state.name})'
@@ -889,8 +1026,11 @@ class Client:
     multiplexer: Optional[Multiplexer]
     l2cap_channel: Optional[l2cap.ClassicChannel]
 
-    def __init__(self, connection: Connection) -> None:
+    def __init__(
+        self, connection: Connection, l2cap_mtu: int = RFCOMM_DEFAULT_L2CAP_MTU
+    ) -> None:
         self.connection = connection
+        self.l2cap_mtu = l2cap_mtu
         self.l2cap_channel = None
         self.multiplexer = None
 
@@ -898,7 +1038,7 @@ class Client:
         # Create a new L2CAP connection
         try:
             self.l2cap_channel = await self.connection.create_l2cap_channel(
-                spec=l2cap.ClassicChannelSpec(RFCOMM_PSM)
+                spec=l2cap.ClassicChannelSpec(psm=RFCOMM_PSM, mtu=self.l2cap_mtu)
             )
         except ProtocolError as error:
             logger.warning(f'L2CAP connection failed: {error}')
@@ -921,25 +1061,40 @@ class Client:
         self.multiplexer = None
 
         # Close the L2CAP channel
-        # TODO
+        if self.l2cap_channel:
+            await self.l2cap_channel.disconnect()
+            self.l2cap_channel = None
+
+    async def __aenter__(self) -> Multiplexer:
+        return await self.start()
+
+    async def __aexit__(self, *args) -> None:
+        await self.shutdown()
 
 
 # -----------------------------------------------------------------------------
 class Server(EventEmitter):
-    acceptors: Dict[int, Callable[[DLC], None]]
-
-    def __init__(self, device: Device) -> None:
+    def __init__(
+        self, device: Device, l2cap_mtu: int = RFCOMM_DEFAULT_L2CAP_MTU
+    ) -> None:
         super().__init__()
         self.device = device
-        self.multiplexer = None
-        self.acceptors = {}
+        self.acceptors: Dict[int, Callable[[DLC], None]] = {}
+        self.dlc_configs: Dict[int, Tuple[int, int]] = {}
 
         # Register ourselves with the L2CAP channel manager
-        device.create_l2cap_server(
-            spec=l2cap.ClassicChannelSpec(psm=RFCOMM_PSM), handler=self.on_connection
+        self.l2cap_server = device.create_l2cap_server(
+            spec=l2cap.ClassicChannelSpec(psm=RFCOMM_PSM, mtu=l2cap_mtu),
+            handler=self.on_connection,
         )
 
-    def listen(self, acceptor: Callable[[DLC], None], channel: int = 0) -> int:
+    def listen(
+        self,
+        acceptor: Callable[[DLC], None],
+        channel: int = 0,
+        max_frame_size: int = RFCOMM_DEFAULT_MAX_FRAME_SIZE,
+        initial_credits: int = RFCOMM_DEFAULT_INITIAL_CREDITS,
+    ) -> int:
         if channel:
             if channel in self.acceptors:
                 # Busy
@@ -959,6 +1114,8 @@ class Server(EventEmitter):
                 return 0
 
         self.acceptors[channel] = acceptor
+        self.dlc_configs[channel] = (max_frame_size, initial_credits)
+
         return channel
 
     def on_connection(self, l2cap_channel: l2cap.ClassicChannel) -> None:
@@ -976,13 +1133,18 @@ class Server(EventEmitter):
         # Notify
         self.emit('start', multiplexer)
 
-    def accept_dlc(self, channel_number: int) -> bool:
-        return channel_number in self.acceptors
+    def accept_dlc(self, channel_number: int) -> Optional[Tuple[int, int]]:
+        return self.dlc_configs.get(channel_number)
 
     def on_dlc(self, dlc: DLC) -> None:
         logger.debug(f'@@@ new DLC connected: {dlc}')
 
         # Let the acceptor know
-        acceptor = self.acceptors.get(dlc.dlci >> 1)
-        if acceptor:
+        if acceptor := self.acceptors.get(dlc.dlci >> 1):
             acceptor(dlc)
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(self, *args) -> None:
+        self.l2cap_server.close()

bumble/sdp.py

@@ -19,6 +19,7 @@ from __future__ import annotations
 import logging
 import struct
 from typing import Dict, List, Type, Optional, Tuple, Union, NewType, TYPE_CHECKING
+from typing_extensions import Self
 
 from . import core, l2cap
 from .colors import color
@@ -97,7 +98,8 @@ SDP_CLIENT_EXECUTABLE_URL_ATTRIBUTE_ID               = 0X000B
 SDP_ICON_URL_ATTRIBUTE_ID                            = 0X000C
 SDP_ADDITIONAL_PROTOCOL_DESCRIPTOR_LIST_ATTRIBUTE_ID = 0X000D
 
-# Attribute Identifier (cf. Assigned Numbers for Service Discovery)
+
+# Profile-specific Attribute Identifiers (cf. Assigned Numbers for Service Discovery)
 # used by AVRCP, HFP and A2DP
 SDP_SUPPORTED_FEATURES_ATTRIBUTE_ID = 0x0311
 
@@ -115,7 +117,8 @@ SDP_ATTRIBUTE_ID_NAMES = {
     SDP_DOCUMENTATION_URL_ATTRIBUTE_ID:                   'SDP_DOCUMENTATION_URL_ATTRIBUTE_ID',
     SDP_CLIENT_EXECUTABLE_URL_ATTRIBUTE_ID:               'SDP_CLIENT_EXECUTABLE_URL_ATTRIBUTE_ID',
     SDP_ICON_URL_ATTRIBUTE_ID:                            'SDP_ICON_URL_ATTRIBUTE_ID',
-    SDP_ADDITIONAL_PROTOCOL_DESCRIPTOR_LIST_ATTRIBUTE_ID: 'SDP_ADDITIONAL_PROTOCOL_DESCRIPTOR_LIST_ATTRIBUTE_ID'
+    SDP_ADDITIONAL_PROTOCOL_DESCRIPTOR_LIST_ATTRIBUTE_ID: 'SDP_ADDITIONAL_PROTOCOL_DESCRIPTOR_LIST_ATTRIBUTE_ID',
+    SDP_SUPPORTED_FEATURES_ATTRIBUTE_ID:                  'SDP_SUPPORTED_FEATURES_ATTRIBUTE_ID',
 }
 
 SDP_PUBLIC_BROWSE_ROOT = core.UUID.from_16_bits(0x1002, 'PublicBrowseRoot')
@@ -822,11 +825,13 @@ class Client:
         )
         attribute_id_list = DataElement.sequence(
             [
-                DataElement.unsigned_integer(
-                    attribute_id[0], value_size=attribute_id[1]
+                (
+                    DataElement.unsigned_integer(
+                        attribute_id[0], value_size=attribute_id[1]
+                    )
+                    if isinstance(attribute_id, tuple)
+                    else DataElement.unsigned_integer_16(attribute_id)
                 )
-                if isinstance(attribute_id, tuple)
-                else DataElement.unsigned_integer_16(attribute_id)
                 for attribute_id in attribute_ids
             ]
         )
@@ -878,11 +883,13 @@ class Client:
 
         attribute_id_list = DataElement.sequence(
             [
-                DataElement.unsigned_integer(
-                    attribute_id[0], value_size=attribute_id[1]
+                (
+                    DataElement.unsigned_integer(
+                        attribute_id[0], value_size=attribute_id[1]
+                    )
+                    if isinstance(attribute_id, tuple)
+                    else DataElement.unsigned_integer_16(attribute_id)
                 )
-                if isinstance(attribute_id, tuple)
-                else DataElement.unsigned_integer_16(attribute_id)
                 for attribute_id in attribute_ids
             ]
         )
@@ -918,6 +925,13 @@ class Client:
 
         return ServiceAttribute.list_from_data_elements(attribute_list_sequence.value)
 
+    async def __aenter__(self) -> Self:
+        await self.connect()
+        return self
+
+    async def __aexit__(self, *args) -> None:
+        await self.disconnect()
+
 
 # -----------------------------------------------------------------------------
 class Server:
@@ -983,7 +997,7 @@ class Server:
             try:
                 handler(sdp_pdu)
             except Exception as error:
-                logger.warning(f'{color("!!! Exception in handler:", "red")} {error}')
+                logger.exception(f'{color("!!! Exception in handler:", "red")} {error}')
                 self.send_response(
                     SDP_ErrorResponse(
                         transaction_id=sdp_pdu.transaction_id,

bumble/smp.py

@@ -737,9 +737,9 @@ class Session:
 
         # Create a future that can be used to wait for the session to complete
         if self.is_initiator:
-            self.pairing_result: Optional[
-                asyncio.Future[None]
-            ] = asyncio.get_running_loop().create_future()
+            self.pairing_result: Optional[asyncio.Future[None]] = (
+                asyncio.get_running_loop().create_future()
+            )
         else:
             self.pairing_result = None
 
@@ -1134,8 +1134,10 @@ class Session:
 
     async def get_link_key_and_derive_ltk(self) -> None:
         '''Retrieves BR/EDR Link Key from storage and derive it to LE LTK.'''
-        link_key = await self.manager.device.get_link_key(self.connection.peer_address)
-        if link_key is None:
+        self.link_key = await self.manager.device.get_link_key(
+            self.connection.peer_address
+        )
+        if self.link_key is None:
             logging.warning(
                 'Try to derive LTK but host does not have the LK. Send a SMP_PAIRING_FAILED but the procedure will not be paused!'
             )
@@ -1143,7 +1145,7 @@ class Session:
                 SMP_CROSS_TRANSPORT_KEY_DERIVATION_NOT_ALLOWED_ERROR
             )
         else:
-            self.ltk = self.derive_ltk(link_key, self.ct2)
+            self.ltk = self.derive_ltk(self.link_key, self.ct2)
 
     def distribute_keys(self) -> None:
         # Distribute the keys as required
@@ -1991,10 +1993,8 @@ class Manager(EventEmitter):
     ) -> None:
         # Store the keys in the key store
         if self.device.keystore and identity_address is not None:
-            self.device.abort_on(
-                'flush', self.device.update_keys(str(identity_address), keys)
-            )
-
+            # Make sure on_pairing emits after key update.
+            await self.device.update_keys(str(identity_address), keys)
         # Notify the device
         self.device.on_pairing(session.connection, identity_address, keys, session.sc)
 

bumble/transport/__init__.py

@@ -18,6 +18,7 @@
 from contextlib import asynccontextmanager
 import logging
 import os
+from typing import Optional
 
 from .common import Transport, AsyncPipeSink, SnoopingTransport
 from ..snoop import create_snooper
@@ -52,8 +53,16 @@ def _wrap_transport(transport: Transport) -> Transport:
 async def open_transport(name: str) -> Transport:
     """
     Open a transport by name.
-    The name must be <type>:<parameters>
-    Where <parameters> depend on the type (and may be empty for some types).
+    The name must be <type>:<metadata><parameters>
+    Where <parameters> depend on the type (and may be empty for some types), and
+    <metadata> is either omitted, or a ,-separated list of <key>=<value> pairs,
+    enclosed in [].
+    If there are not metadata or parameter, the : after the <type> may be omitted.
+    Examples:
+      * usb:0
+      * usb:[driver=rtk]0
+      * android-netsim
+
     The supported types are:
       * serial
       * udp
@@ -71,87 +80,105 @@ async def open_transport(name: str) -> Transport:
       * android-netsim
     """
 
-    return _wrap_transport(await _open_transport(name))
+    scheme, *tail = name.split(':', 1)
+    spec = tail[0] if tail else None
+    metadata = None
+    if spec:
+        # Metadata may precede the spec
+        if spec.startswith('['):
+            metadata_str, *tail = spec[1:].split(']')
+            spec = tail[0] if tail else None
+            metadata = dict([entry.split('=') for entry in metadata_str.split(',')])
+
+    transport = await _open_transport(scheme, spec)
+    if metadata:
+        transport.source.metadata = {  # type: ignore[attr-defined]
+            **metadata,
+            **getattr(transport.source, 'metadata', {}),
+        }
+        # pylint: disable=line-too-long
+        logger.debug(f'HCI metadata: {transport.source.metadata}')  # type: ignore[attr-defined]
+
+    return _wrap_transport(transport)
 
 
 # -----------------------------------------------------------------------------
-async def _open_transport(name: str) -> Transport:
+async def _open_transport(scheme: str, spec: Optional[str]) -> Transport:
     # pylint: disable=import-outside-toplevel
     # pylint: disable=too-many-return-statements
 
-    scheme, *spec = name.split(':', 1)
     if scheme == 'serial' and spec:
         from .serial import open_serial_transport
 
-        return await open_serial_transport(spec[0])
+        return await open_serial_transport(spec)
 
     if scheme == 'udp' and spec:
         from .udp import open_udp_transport
 
-        return await open_udp_transport(spec[0])
+        return await open_udp_transport(spec)
 
     if scheme == 'tcp-client' and spec:
         from .tcp_client import open_tcp_client_transport
 
-        return await open_tcp_client_transport(spec[0])
+        return await open_tcp_client_transport(spec)
 
     if scheme == 'tcp-server' and spec:
         from .tcp_server import open_tcp_server_transport
 
-        return await open_tcp_server_transport(spec[0])
+        return await open_tcp_server_transport(spec)
 
     if scheme == 'ws-client' and spec:
         from .ws_client import open_ws_client_transport
 
-        return await open_ws_client_transport(spec[0])
+        return await open_ws_client_transport(spec)
 
     if scheme == 'ws-server' and spec:
         from .ws_server import open_ws_server_transport
 
-        return await open_ws_server_transport(spec[0])
+        return await open_ws_server_transport(spec)
 
     if scheme == 'pty':
         from .pty import open_pty_transport
 
-        return await open_pty_transport(spec[0] if spec else None)
+        return await open_pty_transport(spec)
 
     if scheme == 'file':
         from .file import open_file_transport
 
         assert spec is not None
-        return await open_file_transport(spec[0])
+        return await open_file_transport(spec)
 
     if scheme == 'vhci':
         from .vhci import open_vhci_transport
 
-        return await open_vhci_transport(spec[0] if spec else None)
+        return await open_vhci_transport(spec)
 
     if scheme == 'hci-socket':
         from .hci_socket import open_hci_socket_transport
 
-        return await open_hci_socket_transport(spec[0] if spec else None)
+        return await open_hci_socket_transport(spec)
 
     if scheme == 'usb':
         from .usb import open_usb_transport
 
-        assert spec is not None
-        return await open_usb_transport(spec[0])
+        assert spec
+        return await open_usb_transport(spec)
 
     if scheme == 'pyusb':
         from .pyusb import open_pyusb_transport
 
-        assert spec is not None
-        return await open_pyusb_transport(spec[0])
+        assert spec
+        return await open_pyusb_transport(spec)
 
     if scheme == 'android-emulator':
         from .android_emulator import open_android_emulator_transport
 
-        return await open_android_emulator_transport(spec[0] if spec else None)
+        return await open_android_emulator_transport(spec)
 
     if scheme == 'android-netsim':
         from .android_netsim import open_android_netsim_transport
 
-        return await open_android_netsim_transport(spec[0] if spec else None)
+        return await open_android_netsim_transport(spec)
 
     raise ValueError('unknown transport scheme')
 
@@ -170,12 +197,13 @@ async def open_transport_or_link(name: str) -> Transport:
 
     """
     if name.startswith('link-relay:'):
+        logger.warning('Link Relay has been deprecated.')
         from ..controller import Controller
         from ..link import RemoteLink  # lazy import
 
         link = RemoteLink(name[11:])
         await link.wait_until_connected()
-        controller = Controller('remote', link=link)
+        controller = Controller('remote', link=link)  # type:ignore[arg-type]
 
         class LinkTransport(Transport):
             async def close(self):

bumble/transport/android_emulator.py

@@ -69,7 +69,7 @@ async def open_android_emulator_transport(spec: Optional[str]) -> Transport:
     mode = 'host'
     server_host = 'localhost'
     server_port = '8554'
-    if spec is not None:
+    if spec:
         params = spec.split(',')
         for param in params:
             if param.startswith('mode='):

bumble/transport/common.py

@@ -21,7 +21,7 @@ import struct
 import asyncio
 import logging
 import io
-from typing import ContextManager, Tuple, Optional, Protocol, Dict
+from typing import Any, ContextManager, Tuple, Optional, Protocol, Dict
 
 from bumble import hci
 from bumble.colors import color
@@ -42,6 +42,7 @@ HCI_PACKET_INFO: Dict[int, Tuple[int, int, str]] = {
     hci.HCI_ACL_DATA_PACKET: (2, 2, 'H'),
     hci.HCI_SYNCHRONOUS_DATA_PACKET: (1, 2, 'B'),
     hci.HCI_EVENT_PACKET: (1, 1, 'B'),
+    hci.HCI_ISO_DATA_PACKET: (2, 2, 'H'),
 }
 
 
@@ -58,15 +59,13 @@ class TransportLostError(Exception):
 # Typing Protocols
 # -----------------------------------------------------------------------------
 class TransportSink(Protocol):
-    def on_packet(self, packet: bytes) -> None:
-        ...
+    def on_packet(self, packet: bytes) -> None: ...
 
 
 class TransportSource(Protocol):
     terminated: asyncio.Future[None]
 
-    def set_packet_sink(self, sink: TransportSink) -> None:
-        ...
+    def set_packet_sink(self, sink: TransportSink) -> None: ...
 
 
 # -----------------------------------------------------------------------------
@@ -167,11 +166,13 @@ class PacketReader:
 
     def __init__(self, source: io.BufferedReader) -> None:
         self.source = source
+        self.at_end = False
 
     def next_packet(self) -> Optional[bytes]:
         # Get the packet type
         packet_type = self.source.read(1)
         if len(packet_type) != 1:
+            self.at_end = True
             return None
 
         # Get the packet info based on its type
@@ -424,6 +425,10 @@ class SnoopingTransport(Transport):
     class Source:
         sink: TransportSink
 
+        @property
+        def metadata(self) -> dict[str, Any]:
+            return getattr(self.source, 'metadata', {})
+
         def __init__(self, source: TransportSource, snooper: Snooper):
             self.source = source
             self.snooper = snooper

bumble/transport/hci_socket.py

@@ -59,10 +59,7 @@ async def open_hci_socket_transport(spec: Optional[str]) -> Transport:
         ) from error
 
     # Compute the adapter index
-    if spec is None:
-        adapter_index = 0
-    else:
-        adapter_index = int(spec)
+    adapter_index = int(spec) if spec else 0
 
     # Bind the socket
     # NOTE: since Python doesn't support binding with the required address format (yet),

bumble/transport/pyusb.py

@@ -23,11 +23,24 @@ import time
 import usb.core
 import usb.util
 
+from typing import Optional
+from usb.core import Device as UsbDevice
+from usb.core import USBError
+from usb.util import CTRL_TYPE_CLASS, CTRL_RECIPIENT_OTHER
+from usb.legacy import REQ_SET_FEATURE, REQ_CLEAR_FEATURE, CLASS_HUB
+
 from .common import Transport, ParserSource
 from .. import hci
 from ..colors import color
 
 
+# -----------------------------------------------------------------------------
+# Constant
+# -----------------------------------------------------------------------------
+USB_PORT_FEATURE_POWER = 8
+POWER_CYCLE_DELAY = 1
+RESET_DELAY = 3
+
 # -----------------------------------------------------------------------------
 # Logging
 # -----------------------------------------------------------------------------
@@ -113,9 +126,10 @@ async def open_pyusb_transport(spec: str) -> Transport:
             self.loop.call_soon_threadsafe(self.stop_event.set)
 
     class UsbPacketSource(asyncio.Protocol, ParserSource):
-        def __init__(self, device, sco_enabled):
+        def __init__(self, device, metadata, sco_enabled):
             super().__init__()
             self.device = device
+            self.metadata = metadata
             self.loop = asyncio.get_running_loop()
             self.queue = asyncio.Queue()
             self.dequeue_task = None
@@ -213,9 +227,22 @@ async def open_pyusb_transport(spec: str) -> Transport:
         usb_find = libusb_package.find
 
     # Find the device according to the spec moniker
+    power_cycle = False
+    if spec.startswith('!'):
+        power_cycle = True
+        spec = spec[1:]
     if ':' in spec:
         vendor_id, product_id = spec.split(':')
         device = usb_find(idVendor=int(vendor_id, 16), idProduct=int(product_id, 16))
+    elif '-' in spec:
+
+        def device_path(device):
+            if device.port_numbers:
+                return f'{device.bus}-{".".join(map(str, device.port_numbers))}'
+            else:
+                return str(device.bus)
+
+        device = usb_find(custom_match=lambda device: device_path(device) == spec)
     else:
         device_index = int(spec)
         devices = list(
@@ -235,6 +262,17 @@ async def open_pyusb_transport(spec: str) -> Transport:
         raise ValueError('device not found')
     logger.debug(f'USB Device: {device}')
 
+    # Power Cycle the device
+    if power_cycle:
+        try:
+            device = await _power_cycle(device)  # type: ignore
+        except Exception as e:
+            logging.debug(e)
+            logging.info(f"Unable to power cycle {hex(device.idVendor)} {hex(device.idProduct)}")  # type: ignore
+
+    # Collect the metadata
+    device_metadata = {'vendor_id': device.idVendor, 'product_id': device.idProduct}
+
     # Detach the kernel driver if needed
     if device.is_kernel_driver_active(0):
         logger.debug("detaching kernel driver")
@@ -289,9 +327,79 @@ async def open_pyusb_transport(spec: str) -> Transport:
     #     except usb.USBError:
     #         logger.warning('failed to set alternate setting')
 
-    packet_source = UsbPacketSource(device, sco_enabled)
+    packet_source = UsbPacketSource(device, device_metadata, sco_enabled)
     packet_sink = UsbPacketSink(device)
     packet_source.start()
     packet_sink.start()
 
     return UsbTransport(device, packet_source, packet_sink)
+
+
+async def _power_cycle(device: UsbDevice) -> UsbDevice:
+    """
+    For devices connected to compatible USB hubs: Performs a power cycle on a given USB device.
+    This involves temporarily disabling its port on the hub and then re-enabling it.
+    """
+    device_path = f'{device.bus}-{".".join(map(str, device.port_numbers))}'  # type: ignore
+    hub = _find_hub_by_device_path(device_path)
+
+    if hub:
+        try:
+            device_port = device.port_numbers[-1]  # type: ignore
+            _set_port_status(hub, device_port, False)
+            await asyncio.sleep(POWER_CYCLE_DELAY)
+            _set_port_status(hub, device_port, True)
+            await asyncio.sleep(RESET_DELAY)
+
+            # Device needs to be find again otherwise it will appear as disconnected
+            return usb.core.find(idVendor=device.idVendor, idProduct=device.idProduct)  # type: ignore
+        except USBError as e:
+            logger.error(f"Adjustment needed: Please revise the udev rule for device {hex(device.idVendor)}:{hex(device.idProduct)} for proper recognition.")  # type: ignore
+            logger.error(e)
+
+    return device
+
+
+def _set_port_status(device: UsbDevice, port: int, on: bool):
+    """Sets the power status of a specific port on a USB hub."""
+    device.ctrl_transfer(
+        bmRequestType=CTRL_TYPE_CLASS | CTRL_RECIPIENT_OTHER,
+        bRequest=REQ_SET_FEATURE if on else REQ_CLEAR_FEATURE,
+        wIndex=port,
+        wValue=USB_PORT_FEATURE_POWER,
+    )
+
+
+def _find_device_by_path(sys_path: str) -> Optional[UsbDevice]:
+    """Finds a USB device based on its system path."""
+    bus_num, *port_parts = sys_path.split('-')
+    ports = [int(port) for port in port_parts[0].split('.')]
+    devices = usb.core.find(find_all=True, bus=int(bus_num))
+    if devices:
+        for device in devices:
+            if device.bus == int(bus_num) and list(device.port_numbers) == ports:  # type: ignore
+                return device
+
+    return None
+
+
+def _find_hub_by_device_path(sys_path: str) -> Optional[UsbDevice]:
+    """Finds the USB hub associated with a specific device path."""
+    hub_sys_path = sys_path.rsplit('.', 1)[0]
+    hub_device = _find_device_by_path(hub_sys_path)
+
+    if hub_device is None:
+        return None
+    else:
+        return hub_device if _is_hub(hub_device) else None
+
+
+def _is_hub(device: UsbDevice) -> bool:
+    """Checks if a USB device is a hub"""
+    if device.bDeviceClass == CLASS_HUB:  # type: ignore
+        return True
+    for config in device:
+        for interface in config:
+            if interface.bInterfaceClass == CLASS_HUB:  # type: ignore
+                return True
+    return False

bumble/transport/tcp_server.py

@@ -18,6 +18,7 @@
 from __future__ import annotations
 import asyncio
 import logging
+import socket
 
 from .common import Transport, StreamPacketSource
 
@@ -28,6 +29,13 @@ logger = logging.getLogger(__name__)
 
 
 # -----------------------------------------------------------------------------
+
+
+# A pass-through function to ease mock testing.
+async def _create_server(*args, **kw_args):
+    await asyncio.get_running_loop().create_server(*args, **kw_args)
+
+
 async def open_tcp_server_transport(spec: str) -> Transport:
     '''
     Open a TCP server transport.
@@ -38,7 +46,22 @@ async def open_tcp_server_transport(spec: str) -> Transport:
 
     Example: _:9001
     '''
+    local_host, local_port = spec.split(':')
+    return await _open_tcp_server_transport_impl(
+        host=local_host if local_host != '_' else None, port=int(local_port)
+    )
 
+
+async def open_tcp_server_transport_with_socket(sock: socket.socket) -> Transport:
+    '''
+    Open a TCP server transport with an existing socket.
+
+    One reason to use this variant is to let python pick an unused port.
+    '''
+    return await _open_tcp_server_transport_impl(sock=sock)
+
+
+async def _open_tcp_server_transport_impl(**kwargs) -> Transport:
     class TcpServerTransport(Transport):
         async def close(self):
             await super().close()
@@ -77,13 +100,10 @@ async def open_tcp_server_transport(spec: str) -> Transport:
             else:
                 logger.debug('no client, dropping packet')
 
-    local_host, local_port = spec.split(':')
     packet_source = StreamPacketSource()
     packet_sink = TcpServerPacketSink()
-    await asyncio.get_running_loop().create_server(
-        lambda: TcpServerProtocol(packet_source, packet_sink),
-        host=local_host if local_host != '_' else None,
-        port=int(local_port),
+    await _create_server(
+        lambda: TcpServerProtocol(packet_source, packet_sink), **kwargs
     )
 
     return TcpServerTransport(packet_source, packet_sink)

bumble/transport/usb.py

@@ -108,7 +108,7 @@ async def open_usb_transport(spec: str) -> Transport:
         USB_DEVICE_PROTOCOL_BLUETOOTH_PRIMARY_CONTROLLER,
     )
 
-    READ_SIZE = 1024
+    READ_SIZE = 4096
 
     class UsbPacketSink:
         def __init__(self, device, acl_out):
@@ -396,6 +396,16 @@ async def open_usb_transport(spec: str) -> Transport:
                         break
                     device_index -= 1
                 device.close()
+        elif '-' in spec:
+
+            def device_path(device):
+                return f'{device.getBusNumber()}-{".".join(map(str, device.getPortNumberList()))}'
+
+            for device in context.getDeviceIterator(skip_on_error=True):
+                if device_path(device) == spec:
+                    found = device
+                    break
+                device.close()
         else:
             # Look for a compatible device by index
             def device_is_bluetooth_hci(device):
@@ -439,7 +449,7 @@ async def open_usb_transport(spec: str) -> Transport:
         # Look for the first interface with the right class and endpoints
         def find_endpoints(device):
             # pylint: disable-next=too-many-nested-blocks
-            for (configuration_index, configuration) in enumerate(device):
+            for configuration_index, configuration in enumerate(device):
                 interface = None
                 for interface in configuration:
                     setting = None

bumble/utils.py

@@ -17,9 +17,10 @@
 # -----------------------------------------------------------------------------
 from __future__ import annotations
 import asyncio
-import logging
-import traceback
 import collections
+import enum
+import functools
+import logging
 import sys
 import warnings
 from typing import (
@@ -34,7 +35,7 @@ from typing import (
     Union,
     overload,
 )
-from functools import wraps, partial
+
 from pyee import EventEmitter
 
 from .colors import color
@@ -116,12 +117,12 @@ class EventWatcher:
         self.handlers = []
 
     @overload
-    def on(self, emitter: EventEmitter, event: str) -> Callable[[_Handler], _Handler]:
-        ...
+    def on(
+        self, emitter: EventEmitter, event: str
+    ) -> Callable[[_Handler], _Handler]: ...
 
     @overload
-    def on(self, emitter: EventEmitter, event: str, handler: _Handler) -> _Handler:
-        ...
+    def on(self, emitter: EventEmitter, event: str, handler: _Handler) -> _Handler: ...
 
     def on(
         self, emitter: EventEmitter, event: str, handler: Optional[_Handler] = None
@@ -131,23 +132,26 @@ class EventWatcher:
         Args:
             emitter: EventEmitter to watch
             event: Event name
-            handler: (Optional) Event handler. When nothing is passed, this method works as a decorator.
+            handler: (Optional) Event handler. When nothing is passed, this method
+            works as a decorator.
         '''
 
-        def wrapper(f: _Handler) -> _Handler:
-            self.handlers.append((emitter, event, f))
-            emitter.on(event, f)
-            return f
+        def wrapper(wrapped: _Handler) -> _Handler:
+            self.handlers.append((emitter, event, wrapped))
+            emitter.on(event, wrapped)
+            return wrapped
 
         return wrapper if handler is None else wrapper(handler)
 
     @overload
-    def once(self, emitter: EventEmitter, event: str) -> Callable[[_Handler], _Handler]:
-        ...
+    def once(
+        self, emitter: EventEmitter, event: str
+    ) -> Callable[[_Handler], _Handler]: ...
 
     @overload
-    def once(self, emitter: EventEmitter, event: str, handler: _Handler) -> _Handler:
-        ...
+    def once(
+        self, emitter: EventEmitter, event: str, handler: _Handler
+    ) -> _Handler: ...
 
     def once(
         self, emitter: EventEmitter, event: str, handler: Optional[_Handler] = None
@@ -157,13 +161,14 @@ class EventWatcher:
         Args:
             emitter: EventEmitter to watch
             event: Event name
-            handler: (Optional) Event handler. When nothing passed, this method works as a decorator.
+            handler: (Optional) Event handler. When nothing passed, this method works
+            as a decorator.
         '''
 
-        def wrapper(f: _Handler) -> _Handler:
-            self.handlers.append((emitter, event, f))
-            emitter.once(event, f)
-            return f
+        def wrapper(wrapped: _Handler) -> _Handler:
+            self.handlers.append((emitter, event, wrapped))
+            emitter.once(event, wrapped)
+            return wrapped
 
         return wrapper if handler is None else wrapper(handler)
 
@@ -223,13 +228,13 @@ class CompositeEventEmitter(AbortableEventEmitter):
         if self._listener:
             # Call the deregistration methods for each base class that has them
             for cls in self._listener.__class__.mro():
-                if hasattr(cls, '_bumble_register_composite'):
-                    cls._bumble_deregister_composite(listener, self)
+                if '_bumble_register_composite' in cls.__dict__:
+                    cls._bumble_deregister_composite(self._listener, self)
         self._listener = listener
         if listener:
             # Call the registration methods for each base class that has them
             for cls in listener.__class__.mro():
-                if hasattr(cls, '_bumble_deregister_composite'):
+                if '_bumble_deregister_composite' in cls.__dict__:
                     cls._bumble_register_composite(listener, self)
 
 
@@ -276,21 +281,18 @@ class AsyncRunner:
         """
 
         def decorator(func):
-            @wraps(func)
+            @functools.wraps(func)
             def wrapper(*args, **kwargs):
                 coroutine = func(*args, **kwargs)
                 if queue is None:
-                    # Create a task to run the coroutine
+                    # Spawn the coroutine as a task
                     async def run():
                         try:
                             await coroutine
                         except Exception:
-                            logger.warning(
-                                f'{color("!!! Exception in wrapper:", "red")} '
-                                f'{traceback.format_exc()}'
-                            )
+                            logger.exception(color("!!! Exception in wrapper:", "red"))
 
-                    asyncio.create_task(run())
+                    AsyncRunner.spawn(run())
                 else:
                     # Queue the coroutine to be awaited by the work queue
                     queue.enqueue(coroutine)
@@ -413,30 +415,35 @@ class FlowControlAsyncPipe:
             self.check_pump()
 
 
+# -----------------------------------------------------------------------------
 async def async_call(function, *args, **kwargs):
     """
-    Immediately calls the function with provided args and kwargs, wrapping it in an async function.
-    Rust's `pyo3_asyncio` library needs functions to be marked async to properly inject a running loop.
+    Immediately calls the function with provided args and kwargs, wrapping it in an
+    async function.
+    Rust's `pyo3_asyncio` library needs functions to be marked async to properly inject
+    a running loop.
 
     result = await async_call(some_function, ...)
     """
     return function(*args, **kwargs)
 
 
+# -----------------------------------------------------------------------------
 def wrap_async(function):
     """
     Wraps the provided function in an async function.
     """
-    return partial(async_call, function)
+    return functools.partial(async_call, function)
 
 
+# -----------------------------------------------------------------------------
 def deprecated(msg: str):
     """
     Throw deprecation warning before execution.
     """
 
     def wrapper(function):
-        @wraps(function)
+        @functools.wraps(function)
         def inner(*args, **kwargs):
             warnings.warn(msg, DeprecationWarning)
             return function(*args, **kwargs)
@@ -446,13 +453,14 @@ def deprecated(msg: str):
     return wrapper
 
 
+# -----------------------------------------------------------------------------
 def experimental(msg: str):
     """
     Throws a future warning before execution.
     """
 
     def wrapper(function):
-        @wraps(function)
+        @functools.wraps(function)
         def inner(*args, **kwargs):
             warnings.warn(msg, FutureWarning)
             return function(*args, **kwargs)
@@ -460,3 +468,22 @@ def experimental(msg: str):
         return inner
 
     return wrapper
+
+
+# -----------------------------------------------------------------------------
+class OpenIntEnum(enum.IntEnum):
+    """
+    Subclass of enum.IntEnum that can hold integer values outside the set of
+    predefined values. This is convenient for implementing protocols where some
+    integer constants may be added over time.
+    """
+
+    @classmethod
+    def _missing_(cls, value):
+        if not isinstance(value, int):
+            return None
+
+        obj = int.__new__(cls, value)
+        obj._value_ = value
+        obj._name_ = f"{cls.__name__}[{value}]"
+        return obj

docs/mkdocs/src/apps_and_tools/bench.md

@@ -7,16 +7,36 @@ throughput and/or latency between two devices.
 # General Usage
 
 ```
-Usage: bench.py [OPTIONS] COMMAND [ARGS]...
+Usage: bumble-bench [OPTIONS] COMMAND [ARGS]...
 
 Options:
   --device-config FILENAME        Device configuration file
   --role [sender|receiver|ping|pong]
   --mode [gatt-client|gatt-server|l2cap-client|l2cap-server|rfcomm-client|rfcomm-server]
   --att-mtu MTU                   GATT MTU (gatt-client mode)  [23<=x<=517]
-  -s, --packet-size SIZE          Packet size (server role)  [8<=x<=4096]
-  -c, --packet-count COUNT        Packet count (server role)
-  -sd, --start-delay SECONDS      Start delay (server role)
+  --extended-data-length TEXT     Request a data length upon connection,
+                                  specified as tx_octets/tx_time
+  --rfcomm-channel INTEGER        RFComm channel to use
+  --rfcomm-uuid TEXT              RFComm service UUID to use (ignored if
+                                  --rfcomm-channel is not 0)
+  --l2cap-psm INTEGER             L2CAP PSM to use
+  --l2cap-mtu INTEGER             L2CAP MTU to use
+  --l2cap-mps INTEGER             L2CAP MPS to use
+  --l2cap-max-credits INTEGER     L2CAP maximum number of credits allowed for
+                                  the peer
+  -s, --packet-size SIZE          Packet size (client or ping role)
+                                  [8<=x<=4096]
+  -c, --packet-count COUNT        Packet count (client or ping role)
+  -sd, --start-delay SECONDS      Start delay (client or ping role)
+  --repeat N                      Repeat the run N times (client and ping
+                                  roles)(0, which is the fault, to run just
+                                  once)
+  --repeat-delay SECONDS          Delay, in seconds, between repeats
+  --pace MILLISECONDS             Wait N milliseconds between packets (0,
+                                  which is the fault, to send as fast as
+                                  possible)
+  --linger                        Don't exit at the end of a run (server and
+                                  pong roles)
   --help                          Show this message and exit.
 
 Commands:
@@ -35,17 +55,18 @@ Options:
   --connection-interval, --ci CONNECTION_INTERVAL
                                   Connection interval (in ms)
   --phy [1m|2m|coded]             PHY to use
+  --authenticate                  Authenticate (RFComm only)
+  --encrypt                       Encrypt the connection (RFComm only)
   --help                          Show this message and exit.
 ```
 
-
-To test once device against another, one of the two devices must be running 
+To test once device against another, one of the two devices must be running
 the ``peripheral`` command and the other the ``central`` command. The device
 running the ``peripheral`` command will accept connections from the device
 running the ``central`` command.
 When using Bluetooth LE (all modes except for ``rfcomm-server`` and ``rfcomm-client``utils),
-the default addresses configured in the tool should be sufficient. But when using 
-Bluetooth Classic, the address of the Peripheral must be specified on the Central 
+the default addresses configured in the tool should be sufficient. But when using
+Bluetooth Classic, the address of the Peripheral must be specified on the Central
 using the ``--peripheral`` option. The address will be printed by the Peripheral when
 it starts.
 
@@ -83,7 +104,7 @@ the other on `usb:1`, and two consoles/terminals. We will run a command in each.
     $ bumble-bench central usb:1
     ```
 
-    In this default configuration, the Central runs a Sender, as a GATT client, 
+    In this default configuration, the Central runs a Sender, as a GATT client,
     connecting to the Peripheral running a Receiver, as a GATT server.
 
 !!! example "L2CAP Throughput"

docs/mkdocs/src/apps_and_tools/hci_bridge.md

@@ -12,12 +12,25 @@ a host that send custom HCI commands that the controller may not understand.
     ```
     python hci_bridge.py <host-transport-spec> <controller-transport-spec> [command-short-circuit-list]
     ```
+    The command-short-circuit-list field is specified by a series of comma separated Opcode Group 
+    Field (OGF) : OpCode Command Field (OCF) pairs. The OGF/OCF values are specified in the Blutooth
+    core specification.
+
+    For the commands that are listed in the short-circuit-list, the HCI bridge will always generate
+    a Command Complete Event for the specified op code. The return parameter will be HCI_SUCCESS.
+
+    This feature can only be used for commands that return Command Complete. Other events will not be
+    generated by the HCI bridge tool.
 
 !!! example "UDP to Serial"
     ```
     python hci_bridge.py udp:0.0.0.0:9000,127.0.0.1:9001 serial:/dev/tty.usbmodem0006839912171,1000000 0x3f:0x0070,0x3f:0x0074,0x3f:0x0077,0x3f:0x0078
     ```
 
+    In this example, the short circuit list is specified to respond to the Vendor-specific Opcode Group 
+    Field (0x3f) commands 0x70, 0x74, 0x77, 0x78 with Command Complete. The short circuit list can be
+    used where the Host uses some HCI commands that are not supported/implemented by the Controller.
+
 !!! example "PTY to Link Relay"
     ```
     python hci_bridge.py serial:emulated_uart_pty,1000000 link-relay:ws://127.0.0.1:10723/test
@@ -28,3 +41,4 @@ a host that send custom HCI commands that the controller may not understand.
     (through which the communication with other virtual controllers will be mediated).
 
     NOTE: this assumes you're running a Link Relay on port `10723`.
+

docs/mkdocs/src/drivers/index.md

@@ -5,6 +5,15 @@ Some Bluetooth controllers require a driver to function properly.
 This may include, for instance, loading a Firmware image or patch,
 loading a configuration.
 
+By default, drivers will be automatically probed to determine if they should be
+used with particular HCI controller.
+When the transport for an HCI controller is instantiated from a transport name,
+a driver may also be forced by specifying ``driver=<driver-name>`` in the optional
+metadata portion of the transport name. For example,
+``usb:[driver=rtk]0`` indicates that the ``rtk`` driver should be used with the
+first USB device, even if a normal probe would not have selected it based on the
+USB vendor ID and product ID.
+
 Drivers included in the module are:
 
   * [Realtek](realtek.md): Loading of Firmware and Config for Realtek USB dongles.

docs/mkdocs/src/drivers/realtek.md

@@ -1,13 +1,16 @@
 REALTEK DRIVER
 ==============
 
-This driver supports loading firmware images and optional config data to 
+This driver supports loading firmware images and optional config data to
 USB dongles with a Realtek chipset.
 A number of USB dongles are supported, but likely not all.
-When using a USB dongle, the USB product ID and manufacturer ID are used
+When using a USB dongle, 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=rtk`` may be specified in a transport
+name to force that driver to be used (ex: ``usb:[driver=rtk]0`` instead of just
+``usb:0`` for the first USB device).
 The driver will look for those files by name, in order, in:
 
   * The directory specified by the environment variable `BUMBLE_RTK_FIRMWARE_DIR`

docs/mkdocs/src/extras/android_remote_hci.md

@@ -1,19 +1,19 @@
 ANDROID REMOTE HCI APP
 ======================
 
-This application allows using an android phone's built-in Bluetooth controller with 
+This application allows using an android phone's built-in Bluetooth controller with
 a Bumble host stack running outside the phone (typically a development laptop or desktop).
 The app runs an HCI proxy between a TCP socket on the "outside" and the Bluetooth HCI HAL
-on the "inside". (See [this page](https://source.android.com/docs/core/connect/bluetooth) for a high level 
+on the "inside". (See [this page](https://source.android.com/docs/core/connect/bluetooth) for a high level
 description of the Android Bluetooth HCI HAL).
-The HCI packets received on the TCP socket are forwarded to the phone's controller, and the 
+The HCI packets received on the TCP socket are forwarded to the phone's controller, and the
 packets coming from the controller are forwarded to the TCP socket.
 
 
 Building
 --------
 
-You can build the app by running `./gradlew build` (use `gradlew.bat` on Windows) from the `RemoteHCI` top level directory.
+You can build the app by running `./gradlew build` (use `gradlew.bat` on Windows) from the `extras/android/RemoteHCI` top level directory.
 You can also build with Android Studio: open the `RemoteHCI` project. You can build and/or debug from there.
 
 If the build succeeds, you can find the app APKs (debug and release) at:
@@ -25,9 +25,23 @@ If the build succeeds, you can find the app APKs (debug and release) at:
 Running
 -------
 
+!!! note
+    In the following examples, it is assumed that shell commands are executed while in the
+    app's root directory, `extras/android/RemoteHCI`. If you are in a different directory,
+    adjust the relative paths accordingly.
+
 ### Preconditions
-When the proxy starts (tapping the "Start" button in the app's main activity), it will try to 
-bind to the Bluetooth HAL. This requires disabling SELinux temporarily, and being the only HAL client.
+When the proxy starts (tapping the "Start" button in the app's main activity, or running the proxy
+from an `adb shell` command line), it will try to bind to the Bluetooth HAL.
+This requires that there is no other HAL client, and requires certain privileges.
+For running as a regular app, this requires disabling SELinux temporarily.
+For running as a command-line executable, this just requires a root shell.
+
+#### Root Shell
+!!! tip "Restart `adb` as root"
+    ```bash
+    $ adb root
+    ```
 
 #### Disabling SELinux
 Binding to the Bluetooth HCI HAL requires certain SELinux permissions that can't simply be changed
@@ -56,8 +70,8 @@ development phone).
     This state will also reset to the normal SELinux enforcement when you reboot.
 
 #### Stopping the bluetooth process
-Since the Bluetooth HAL service can only accept one client, and that in normal conditions 
-that client is the Android's bluetooth stack, it is required to first shut down the 
+Since the Bluetooth HAL service can only accept one client, and that in normal conditions
+that client is the Android's bluetooth stack, it is required to first shut down the
 Android bluetooth stack process.
 
 !!! tip "Checking if the Bluetooth process is running"
@@ -79,7 +93,33 @@ Airplane Mode, then rebooting. The bluetooth process should, in theory, not rest
     $ adb shell cmd bluetooth_manager disable
     ```
 
-### Starting the app
+### Running as a command line app
+
+You push the built APK to a temporary location on the phone's filesystem, then launch the command
+line executable with an `adb shell` command.
+
+!!! tip "Pushing the executable"
+    ```bash
+    $ adb push app/build/outputs/apk/release/app-release-unsigned.apk /data/local/tmp/remotehci.apk
+    ```
+    Do this every time you rebuild. Alternatively, you can push the `debug` APK instead:
+    ```bash
+    $ adb push app/build/outputs/apk/debug/app-debug.apk /data/local/tmp/remotehci.apk
+    ```
+
+!!! tip "Start the proxy from the command line"
+    ```bash
+    adb shell "CLASSPATH=/data/local/tmp/remotehci.apk app_process /system/bin com.github.google.bumble.remotehci.CommandLineInterface"
+    ```
+    This will run the proxy, listening on the default TCP port.
+    If you want a different port, pass it as a command line parameter
+
+!!! tip "Start the proxy from the command line with a specific TCP port"
+    ```bash
+    adb shell "CLASSPATH=/data/local/tmp/remotehci.apk app_process /system/bin com.github.google.bumble.remotehci.CommandLineInterface 12345"
+    ```
+
+### Running as a normal app
 You can start the app from the Android launcher, from Android Studio, or with `adb`
 
 #### Launching from the launcher
@@ -103,11 +143,11 @@ automatically start the proxy, and/or set the port number.
 
 #### Selecting a TCP port
 The RemoteHCI app's main activity has a "TCP Port" setting where you can change the port on
-which the proxy is accepting connections. If the default value isn't suitable, you can 
+which the proxy is accepting connections. If the default value isn't suitable, you can
 change it there (you can also use the special value 0 to let the OS assign a port number for you).
 
 ### Connecting to the proxy
-To connect the Bumble stack to the proxy, you need to be able to reach the phone's network 
+To connect the Bumble stack to the proxy, you need to be able to reach the phone's network
 stack. This can be done over the phone's WiFi connection, or, alternatively, using an `adb`
 TCP forward (which should be faster than over WiFi).
 
@@ -116,7 +156,7 @@ TCP forward (which should be faster than over WiFi).
     ```bash
     $ adb forward tcp:<outside-port> tcp:<inside-port>
     ```
-    Where ``<outside-port>`` is the port number for a listening socket on your laptop or 
+    Where ``<outside-port>`` is the port number for a listening socket on your laptop or
     desktop machine, and <inside-port> is the TCP port selected in the app's user interface.
     Those two ports may be the same, of course.
     For example, with the default TCP port 9993:
@@ -125,7 +165,7 @@ TCP forward (which should be faster than over WiFi).
     ```
 
 Once you've ensured that you can reach the proxy's TCP port on the phone, either directly or
-via an `adb` forward, you can then use it as a Bumble transport, using the transport name: 
+via an `adb` forward, you can then use it as a Bumble transport, using the transport name:
 ``tcp-client:<host>:<port>`` syntax.
 
 !!! example "Connecting a Bumble client"

docs/mkdocs/src/transports/usb.md

@@ -10,6 +10,7 @@ The moniker for a USB transport is either:
   * `usb:<vendor>:<product>`
   * `usb:<vendor>:<product>/<serial-number>`
   * `usb:<vendor>:<product>#<index>`
+  * `usb:<bus>-<port_numbers>`
 
 with `<index>` as a 0-based index (0 being the first one) to select amongst all the matching devices when there are more than one.
 In the `usb:<index>` form, matching devices are the ones supporting Bluetooth HCI, as declared by their Class, Subclass and Protocol.
@@ -17,6 +18,8 @@ In the `usb:<vendor>:<product>#<index>` form, matching devices are the ones with
 
 `<vendor>` and `<product>` are a vendor ID and product ID in hexadecimal.
 
+with `<port_numbers>` as a list of all port numbers from root separated with dots `.`
+
 In addition, if the moniker ends with the symbol "!", the device will be used in "forced" mode:
 the first USB interface of the device will be used, regardless of the interface class/subclass.
 This may be useful for some devices that use a custom class/subclass but may nonetheless work as-is.
@@ -37,6 +40,9 @@ This may be useful for some devices that use a custom class/subclass but may non
     `usb:0B05:17CB!`
     The BT USB dongle vendor=0B05 and product=17CB, in "forced" mode.
 
+    `usb:3-3.4.1`
+    The BT USB dongle on bus 3 on port path 3, 4, 1.
+
 
 ## Alternative
 The library includes two different implementations of the USB transport, implemented using different python bindings for `libusb`.

examples/async_runner.py

@@ -25,6 +25,7 @@ from bumble.utils import AsyncRunner
 my_work_queue1 = AsyncRunner.WorkQueue()
 my_work_queue2 = AsyncRunner.WorkQueue(create_task=False)
 
+
 # -----------------------------------------------------------------------------
 @AsyncRunner.run_in_task()
 async def func1(x, y):
@@ -60,7 +61,7 @@ async def func4(x, y):
 
 
 # -----------------------------------------------------------------------------
-async def main():
+async def main() -> None:
     print("MAIN: start, loop=", asyncio.get_running_loop())
     print("MAIN: invoke func1")
     func1(1, 2)

examples/avrcp_as_sink.html

@@ -0,0 +1,274 @@
+<html>
+
+<head>
+    <style>
+        * {
+            font-family: sans-serif;
+        }
+    </style>
+</head>
+<body>
+    Server Port <input id="port" type="text" value="8989"></input> <button id="connectButton" onclick="connect()">Connect</button><br>
+    <div id="socketState"></div>
+    <br>
+    <div id="buttons"></div><br>
+    <hr>
+    <button onclick="onGetPlayStatusButtonClicked()">Get Play Status</button><br>
+    <div id="getPlayStatusResponseTable"></div>
+    <hr>
+    <button onclick="onGetElementAttributesButtonClicked()">Get Element Attributes</button><br>
+    <div id="getElementAttributesResponseTable"></div>
+    <hr>
+    <table>
+        <tr>
+            <b>VOLUME</b>:
+            <button onclick="onVolumeDownButtonClicked()">-</button>
+            <button onclick="onVolumeUpButtonClicked()">+</button>&nbsp;
+            <span id="volumeText"></span><br>
+        </tr>
+        <tr>
+            <td><b>PLAYBACK STATUS</b></td><td><span id="playbackStatusText"></span></td>
+        </tr>
+        <tr>
+            <td><b>POSITION</b></td><td><span id="positionText"></span></td>
+        </tr>
+        <tr>
+            <td><b>TRACK</b></td><td><span id="trackText"></span></td>
+        </tr>
+        <tr>
+            <td><b>ADDRESSED PLAYER</b></td><td><span id="addressedPlayerText"></span></td>
+        </tr>
+        <tr>
+            <td><b>UID COUNTER</b></td><td><span id="uidCounterText"></span></td>
+        </tr>
+        <tr>
+            <td><b>SUPPORTED EVENTS</b></td><td><span id="supportedEventsText"></span></td>
+        </tr>
+        <tr>
+            <td><b>PLAYER SETTINGS</b></td><td><div id="playerSettingsTable"></div></td>
+        </tr>
+    </table>
+    <script>
+        const portInput = document.getElementById("port")
+        const connectButton = document.getElementById("connectButton")
+        const socketState = document.getElementById("socketState")
+        const volumeText = document.getElementById("volumeText")
+        const positionText = document.getElementById("positionText")
+        const trackText = document.getElementById("trackText")
+        const playbackStatusText = document.getElementById("playbackStatusText")
+        const addressedPlayerText = document.getElementById("addressedPlayerText")
+        const uidCounterText = document.getElementById("uidCounterText")
+        const supportedEventsText = document.getElementById("supportedEventsText")
+        const playerSettingsTable = document.getElementById("playerSettingsTable")
+        const getPlayStatusResponseTable = document.getElementById("getPlayStatusResponseTable")
+        const getElementAttributesResponseTable = document.getElementById("getElementAttributesResponseTable")
+        let socket
+        let volume = 0
+
+        const keyNames = [
+            "SELECT",
+            "UP",
+            "DOWN",
+            "LEFT",
+            "RIGHT",
+            "RIGHT_UP",
+            "RIGHT_DOWN",
+            "LEFT_UP",
+            "LEFT_DOWN",
+            "ROOT_MENU",
+            "SETUP_MENU",
+            "CONTENTS_MENU",
+            "FAVORITE_MENU",
+            "EXIT",
+            "NUMBER_0",
+            "NUMBER_1",
+            "NUMBER_2",
+            "NUMBER_3",
+            "NUMBER_4",
+            "NUMBER_5",
+            "NUMBER_6",
+            "NUMBER_7",
+            "NUMBER_8",
+            "NUMBER_9",
+            "DOT",
+            "ENTER",
+            "CLEAR",
+            "CHANNEL_UP",
+            "CHANNEL_DOWN",
+            "PREVIOUS_CHANNEL",
+            "SOUND_SELECT",
+            "INPUT_SELECT",
+            "DISPLAY_INFORMATION",
+            "HELP",
+            "PAGE_UP",
+            "PAGE_DOWN",
+            "POWER",
+            "VOLUME_UP",
+            "VOLUME_DOWN",
+            "MUTE",
+            "PLAY",
+            "STOP",
+            "PAUSE",
+            "RECORD",
+            "REWIND",
+            "FAST_FORWARD",
+            "EJECT",
+            "FORWARD",
+            "BACKWARD",
+            "ANGLE",
+            "SUBPICTURE",
+            "F1",
+            "F2",
+            "F3",
+            "F4",
+            "F5",
+        ]
+
+        document.addEventListener('keydown', onKeyDown)
+        document.addEventListener('keyup', onKeyUp)
+
+        const buttons = document.getElementById("buttons")
+        keyNames.forEach(name => {
+            const button = document.createElement("BUTTON")
+            button.appendChild(document.createTextNode(name))
+            button.addEventListener("mousedown", event => {
+                send({type: 'send-key-down', key: name})
+            })
+            button.addEventListener("mouseup", event => {
+                send({type: 'send-key-up', key: name})
+            })
+            buttons.appendChild(button)
+        })
+
+        updateVolume(0)
+
+        function connect() {
+            socket = new WebSocket(`ws://localhost:${portInput.value}`);
+            socket.onopen = _ => {
+                socketState.innerText = 'OPEN'
+                connectButton.disabled = true
+            }
+            socket.onclose = _ => {
+                socketState.innerText = 'CLOSED'
+                connectButton.disabled = false
+            }
+            socket.onerror = (error) => {
+                socketState.innerText = 'ERROR'
+                console.log(`ERROR: ${error}`)
+                connectButton.disabled = false
+            }
+            socket.onmessage = (message) => {
+                onMessage(JSON.parse(message.data))
+            }
+        }
+
+        function send(message) {
+            if (socket && socket.readyState == WebSocket.OPEN) {
+                socket.send(JSON.stringify(message))
+            }
+        }
+
+        function hmsText(position) {
+            const h_1 = 1000 * 60 * 60
+            const h = Math.floor(position / h_1)
+            position -= h * h_1
+            const m_1 = 1000 * 60
+            const m = Math.floor(position / m_1)
+            position -= m * m_1
+            const s_1 = 1000
+            const s = Math.floor(position / s_1)
+            position -= s * s_1
+
+            return `${h}:${m.toString().padStart(2, "0")}:${s.toString().padStart(2, "0")}:${position}`
+        }
+
+        function setTableHead(table, columns) {
+            let thead = table.createTHead()
+            let row = thead.insertRow()
+            for (let column of columns) {
+                let th = document.createElement("th")
+                let text = document.createTextNode(column)
+                th.appendChild(text)
+                row.appendChild(th)
+            }
+        }
+
+        function createTable(rows) {
+            const table = document.createElement("table")
+
+            if (rows.length != 0) {
+                columns = Object.keys(rows[0])
+                setTableHead(table, columns)
+            }
+            for (let element of rows) {
+                let row = table.insertRow()
+                for (key in element) {
+                    let cell = row.insertCell()
+                    let text = document.createTextNode(element[key])
+                    cell.appendChild(text)
+                }
+            }
+            return table
+        }
+
+        function onMessage(message) {
+            console.log(message)
+            if (message.type == "set-volume") {
+                updateVolume(message.params.volume)
+            } else if (message.type == "supported-events") {
+                supportedEventsText.innerText = JSON.stringify(message.params.events)
+            } else if (message.type == "playback-position-changed") {
+                positionText.innerText = hmsText(message.params.position)
+            } else if (message.type == "playback-status-changed") {
+                playbackStatusText.innerText = message.params.status
+            } else if (message.type == "player-settings-changed") {
+                playerSettingsTable.replaceChildren(message.params.settings)
+            } else if (message.type == "track-changed") {
+                trackText.innerText = message.params.identifier
+            } else if (message.type == "addressed-player-changed") {
+                addressedPlayerText.innerText = JSON.stringify(message.params.player)
+            } else if (message.type == "uids-changed") {
+                uidCounterText.innerText = message.params.uid_counter
+            } else if (message.type == "get-play-status-response") {
+                getPlayStatusResponseTable.replaceChildren(message.params)
+            } else if (message.type == "get-element-attributes-response") {
+                getElementAttributesResponseTable.replaceChildren(createTable(message.params))
+            }
+        }
+
+        function updateVolume(newVolume) {
+            volume = newVolume
+            volumeText.innerText = `${volume} (${Math.round(100*volume/0x7F)}%)`
+        }
+
+        function onKeyDown(event) {
+            console.log(event)
+            send({ type: 'send-key-down', key: event.key })
+        }
+
+        function onKeyUp(event) {
+            console.log(event)
+            send({ type: 'send-key-up', key: event.key })
+        }
+
+        function onVolumeUpButtonClicked() {
+            updateVolume(Math.min(volume + 5, 0x7F))
+            send({ type: 'set-volume', volume })
+        }
+
+        function onVolumeDownButtonClicked() {
+            updateVolume(Math.max(volume - 5, 0))
+            send({ type: 'set-volume', volume })
+        }
+
+        function onGetPlayStatusButtonClicked() {
+            send({ type: 'get-play-status', volume })
+        }
+
+        function onGetElementAttributesButtonClicked() {
+            send({ type: 'get-element-attributes' })
+        }
+</script>
+</body>
+
+</html>

examples/battery_client.py

@@ -21,23 +21,29 @@ import os
 import logging
 from bumble.colors import color
 from bumble.device import Device
+from bumble.hci import Address
 from bumble.transport import open_transport
 from bumble.profiles.battery_service import BatteryServiceProxy
 
 
 # -----------------------------------------------------------------------------
-async def main():
+async def main() -> None:
     if len(sys.argv) != 3:
         print('Usage: battery_client.py <transport-spec> <bluetooth-address>')
         print('example: battery_client.py usb:0 E1:CA:72:48:C4:E8')
         return
 
     print('<<< connecting to HCI...')
-    async with await open_transport(sys.argv[1]) as (hci_source, hci_sink):
+    async with await open_transport(sys.argv[1]) as hci_transport:
         print('<<< connected')
 
         # Create and start a device
-        device = Device.with_hci('Bumble', 'F0:F1:F2:F3:F4:F5', hci_source, hci_sink)
+        device = Device.with_hci(
+            'Bumble',
+            Address('F0:F1:F2:F3:F4:F5'),
+            hci_transport.source,
+            hci_transport.sink,
+        )
         await device.power_on()
 
         # Connect to the peer

examples/battery_server.py

@@ -29,14 +29,16 @@ from bumble.profiles.battery_service import BatteryService
 
 
 # -----------------------------------------------------------------------------
-async def main():
+async def main() -> None:
     if len(sys.argv) != 3:
         print('Usage: python battery_server.py <device-config> <transport-spec>')
         print('example: python battery_server.py device1.json usb:0')
         return
 
-    async with await open_transport_or_link(sys.argv[2]) as (hci_source, hci_sink):
-        device = Device.from_config_file_with_hci(sys.argv[1], hci_source, hci_sink)
+    async with await open_transport_or_link(sys.argv[2]) as hci_transport:
+        device = Device.from_config_file_with_hci(
+            sys.argv[1], hci_transport.source, hci_transport.sink
+        )
 
         # Add a Battery Service to the GATT sever
         battery_service = BatteryService(lambda _: random.randint(0, 100))

examples/device_information_client.py

@@ -21,12 +21,13 @@ import os
 import logging
 from bumble.colors import color
 from bumble.device import Device, Peer
+from bumble.hci import Address
 from bumble.profiles.device_information_service import DeviceInformationServiceProxy
 from bumble.transport import open_transport
 
 
 # -----------------------------------------------------------------------------
-async def main():
+async def main() -> None:
     if len(sys.argv) != 3:
         print(
             'Usage: device_information_client.py <transport-spec> <bluetooth-address>'
@@ -35,11 +36,16 @@ async def main():
         return
 
     print('<<< connecting to HCI...')
-    async with await open_transport(sys.argv[1]) as (hci_source, hci_sink):
+    async with await open_transport(sys.argv[1]) as hci_transport:
         print('<<< connected')
 
         # Create and start a device
-        device = Device.with_hci('Bumble', 'F0:F1:F2:F3:F4:F5', hci_source, hci_sink)
+        device = Device.with_hci(
+            'Bumble',
+            Address('F0:F1:F2:F3:F4:F5'),
+            hci_transport.source,
+            hci_transport.sink,
+        )
         await device.power_on()
 
         # Connect to the peer

examples/device_information_server.py

@@ -28,14 +28,16 @@ from bumble.profiles.device_information_service import DeviceInformationService
 
 
 # -----------------------------------------------------------------------------
-async def main():
+async def main() -> None:
     if len(sys.argv) != 3:
         print('Usage: python device_info_server.py <device-config> <transport-spec>')
         print('example: python device_info_server.py device1.json usb:0')
         return
 
-    async with await open_transport_or_link(sys.argv[2]) as (hci_source, hci_sink):
-        device = Device.from_config_file_with_hci(sys.argv[1], hci_source, hci_sink)
+    async with await open_transport_or_link(sys.argv[2]) as hci_transport:
+        device = Device.from_config_file_with_hci(
+            sys.argv[1], hci_transport.source, hci_transport.sink
+        )
 
         # Add a Device Information Service to the GATT sever
         device_information_service = DeviceInformationService(
@@ -64,7 +66,7 @@ async def main():
         # Go!
         await device.power_on()
         await device.start_advertising(auto_restart=True)
-        await hci_source.wait_for_termination()
+        await hci_transport.source.wait_for_termination()
 
 
 # -----------------------------------------------------------------------------

examples/heart_rate_client.py

@@ -21,23 +21,29 @@ import os
 import logging
 from bumble.colors import color
 from bumble.device import Device
+from bumble.hci import Address
 from bumble.transport import open_transport
 from bumble.profiles.heart_rate_service import HeartRateServiceProxy
 
 
 # -----------------------------------------------------------------------------
-async def main():
+async def main() -> None:
     if len(sys.argv) != 3:
         print('Usage: heart_rate_client.py <transport-spec> <bluetooth-address>')
         print('example: heart_rate_client.py usb:0 E1:CA:72:48:C4:E8')
         return
 
     print('<<< connecting to HCI...')
-    async with await open_transport(sys.argv[1]) as (hci_source, hci_sink):
+    async with await open_transport(sys.argv[1]) as hci_transport:
         print('<<< connected')
 
         # Create and start a device
-        device = Device.with_hci('Bumble', 'F0:F1:F2:F3:F4:F5', hci_source, hci_sink)
+        device = Device.with_hci(
+            'Bumble',
+            Address('F0:F1:F2:F3:F4:F5'),
+            hci_transport.source,
+            hci_transport.sink,
+        )
         await device.power_on()
 
         # Connect to the peer

examples/heart_rate_server.py

@@ -33,14 +33,16 @@ from bumble.utils import AsyncRunner
 
 
 # -----------------------------------------------------------------------------
-async def main():
+async def main() -> None:
     if len(sys.argv) != 3:
         print('Usage: python heart_rate_server.py <device-config> <transport-spec>')
         print('example: python heart_rate_server.py device1.json usb:0')
         return
 
-    async with await open_transport_or_link(sys.argv[2]) as (hci_source, hci_sink):
-        device = Device.from_config_file_with_hci(sys.argv[1], hci_source, hci_sink)
+    async with await open_transport_or_link(sys.argv[2]) as hci_transport:
+        device = Device.from_config_file_with_hci(
+            sys.argv[1], hci_transport.source, hci_transport.sink
+        )
 
         # Keep track of accumulated expended energy
         energy_start_time = time.time()

examples/hfp_gateway.html

@@ -0,0 +1,350 @@
+<html data-bs-theme="dark">
+
+<head>
+    <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.2/dist/css/bootstrap.min.css" rel="stylesheet"
+        integrity="sha384-T3c6CoIi6uLrA9TneNEoa7RxnatzjcDSCmG1MXxSR1GAsXEV/Dwwykc2MPK8M2HN" crossorigin="anonymous">
+    <script src="https://unpkg.com/pcm-player"></script>
+</head>
+
+<body>
+    <nav class="navbar navbar-dark bg-primary">
+        <div class="container">
+            <span class="navbar-brand mb-0 h1">Bumble HFP Audio Gateway</span>
+        </div>
+    </nav>
+    <br>
+
+    <div class="container">
+
+        <label class="form-label">Send AT Response</label>
+        <div class="input-group mb-3">
+            <input type="text" class="form-control" placeholder="AT Response" aria-label="AT response" id="at_response">
+            <button class="btn btn-primary" type="button"
+                onclick="send_at_response(document.getElementById('at_response').value)">Send</button>
+        </div>
+
+        <div class="row">
+            <div class="col-3">
+                <label class="form-label">Speaker Volume</label>
+                <div class="input-group mb-3 col-auto">
+                    <input type="text" class="form-control" placeholder="0 - 15" aria-label="Speaker Volume"
+                        id="speaker_volume">
+                    <button class="btn btn-primary" type="button"
+                        onclick="send_at_response(`+VGS: ${document.getElementById('speaker_volume').value}`)">Set</button>
+                </div>
+            </div>
+            <div class="col-3">
+                <label class="form-label">Mic Volume</label>
+                <div class="input-group mb-3 col-auto">
+                    <input type="text" class="form-control" placeholder="0 - 15" aria-label="Mic Volume"
+                        id="mic_volume">
+                    <button class="btn btn-primary" type="button"
+                        onclick="send_at_response(`+VGM: ${document.getElementById('mic_volume').value}`)">Set</button>
+                </div>
+            </div>
+            <div class="col-3">
+                <label class="form-label">Browser Gain</label>
+                <input type="range" class="form-range" id="browser-gain" min="0" max="2" value="1" step="0.1" onchange="setGain()">
+            </div>
+        </div>
+
+        <div class="row">
+            <div class="col-auto">
+                <div class="input-group mb-3">
+                    <span class="input-group-text">Codec</span>
+
+                    <select class="form-select" id="codec">
+                        <option selected value="1">CVSD</option>
+                        <option value="2">MSBC</option>
+                    </select>
+                </div>
+            </div>
+
+            <div class="col-auto">
+                <button class="btn btn-primary" onclick="negotiate_codec()">Negotiate Codec</button>
+            </div>
+            <div class="col-auto">
+                <button class="btn btn-primary" onclick="connect_sco()">Connect SCO</button>
+            </div>
+            <div class="col-auto">
+                <button class="btn btn-primary" onclick="disconnect_sco()">Disconnect SCO</button>
+            </div>
+            <div class="col-auto">
+                <button class="btn btn-danger" onclick="connectAudio()">Connect Audio</button>
+            </div>
+        </div>
+
+        <hr>
+
+        <div class="row">
+            <h4>AG Indicators</h2>
+                <div class="col-3">
+                    <label class="form-label">call</label>
+                    <div class="input-group mb-3 col-auto">
+                        <select class="form-select" id="call">
+                            <option selected value="0">Inactive</option>
+                            <option value="1">Active</option>
+                        </select>
+                        <button class="btn btn-primary" type="button" onclick="update_ag_indicator('call')">Set</button>
+                    </div>
+                </div>
+                <div class="col-3">
+                    <label class="form-label">callsetup</label>
+                    <div class="input-group mb-3 col-auto">
+                        <select class="form-select" id="callsetup">
+                            <option selected value="0">Idle</option>
+                            <option value="1">Incoming</option>
+                            <option value="2">Outgoing</option>
+                            <option value="3">Remote Alerted</option>
+                        </select>
+                        <button class="btn btn-primary" type="button"
+                            onclick="update_ag_indicator('callsetup')">Set</button>
+                    </div>
+                </div>
+                <div class="col-3">
+                    <label class="form-label">callheld</label>
+                    <div class="input-group mb-3 col-auto">
+                        <select class="form-select" id="callsetup">
+                            <option selected value="0">0</option>
+                            <option value="1">1</option>
+                            <option value="2">2</option>
+                        </select>
+                        <button class="btn btn-primary" type="button"
+                            onclick="update_ag_indicator('callheld')">Set</button>
+                    </div>
+                </div>
+                <div class="col-3">
+                    <label class="form-label">signal</label>
+                    <div class="input-group mb-3 col-auto">
+                        <select class="form-select" id="signal">
+                            <option selected value="0">0</option>
+                            <option value="1">1</option>
+                            <option value="2">2</option>
+                            <option value="3">3</option>
+                            <option value="4">4</option>
+                            <option value="5">5</option>
+                        </select>
+                        <button class="btn btn-primary" type="button"
+                            onclick="update_ag_indicator('signal')">Set</button>
+                    </div>
+                </div>
+                <div class="col-3">
+                    <label class="form-label">roam</label>
+                    <div class="input-group mb-3 col-auto">
+                        <select class="form-select" id="roam">
+                            <option selected value="0">0</option>
+                            <option value="1">1</option>
+                        </select>
+                        <button class="btn btn-primary" type="button" onclick="update_ag_indicator('roam')">Set</button>
+                    </div>
+                </div>
+                <div class="col-3">
+                    <label class="form-label">battchg</label>
+                    <div class="input-group mb-3 col-auto">
+                        <select class="form-select" id="battchg">
+                            <option selected value="0">0</option>
+                            <option value="1">1</option>
+                            <option value="2">2</option>
+                            <option value="3">3</option>
+                            <option value="4">4</option>
+                            <option value="5">5</option>
+                        </select>
+                        <button class="btn btn-primary" type="button"
+                            onclick="update_ag_indicator('battchg')">Set</button>
+                    </div>
+                </div>
+                <div class="col-3">
+                    <label class="form-label">service</label>
+                    <div class="input-group mb-3 col-auto">
+                        <select class="form-select" id="service">
+                            <option selected value="0">0</option>
+                            <option value="1">1</option>
+                        </select>
+                        <button class="btn btn-primary" type="button"
+                            onclick="update_ag_indicator('service')">Set</button>
+                    </div>
+                </div>
+        </div>
+
+        <hr>
+
+        <button class="btn btn-primary" onclick="send_at_response('+BVRA: 1')">Start Voice Assistant</button>
+        <button class="btn btn-primary" onclick="send_at_response('+BVRA: 0')">Stop Voice Assistant</button>
+
+        <hr>
+
+
+        <h4>Calls</h4>
+        <div id="call-lists">
+            <template id="call-template">
+                <div class="row call-row">
+                    <div class="input-group mb-3">
+                        <label class="input-group-text">Index</label>
+                        <input class="form-control call-index" value="1">
+
+                        <label class="input-group-text">Number</label>
+                        <input class="form-control call-number">
+
+                        <label class="input-group-text">Direction</label>
+                        <select class="form-select call-direction">
+                            <option selected value="0">Originated</option>
+                            <option value="1">Terminated</option>
+                        </select>
+
+                        <label class="input-group-text">Status</label>
+                        <select class="form-select call-status">
+                            <option value="0">ACTIVE</option>
+                            <option value="1">HELD</option>
+                            <option value="2">DIALING</option>
+                            <option value="3">ALERTING</option>
+                            <option value="4">INCOMING</option>
+                            <option value="5">WAITING</option>
+                        </select>
+                        <button class="btn btn-primary call-remover">❌</button>
+                    </div>
+                </div>
+            </template>
+        </div>
+
+        <button class="btn btn-primary" onclick="add_call()">➕ Add Call</button>
+        <button class="btn btn-primary" onclick="update_calls()">🗘 Update Calls</button>
+
+        <hr>
+
+        <div id="socketStateContainer" class="bg-body-tertiary p-3 rounded-2">
+            <h3>Log</h3>
+            <code id="log" style="white-space: pre-line;"></code>
+        </div>
+    </div>
+
+
+    <script>
+        let atResponseInput = document.getElementById("at_response")
+        let gainInput = document.getElementById('browser-gain')
+        let log = document.getElementById("log")
+        let socket = new WebSocket('ws://localhost:8888');
+        let sampleRate = 0;
+        let player;
+
+        socket.binaryType = "arraybuffer";
+        socket.onopen = _ => {
+            log.textContent += 'SOCKET OPEN\n'
+        }
+        socket.onclose = _ => {
+            log.textContent += 'SOCKET CLOSED\n'
+        }
+        socket.onerror = (error) => {
+            log.textContent += 'SOCKET ERROR\n'
+            console.log(`ERROR: ${error}`)
+        }
+        socket.onmessage = function (message) {
+            if (typeof message.data === 'string' || message.data instanceof String) {
+                log.textContent += `<-- ${event.data}\n`
+                const jsonMessage = JSON.parse(event.data)
+
+                if (jsonMessage.type == 'speaker_volume') {
+                    document.getElementById('speaker_volume').value = jsonMessage.level;
+                } else if (jsonMessage.type == 'microphone_volume') {
+                    document.getElementById('microphone_volume').value = jsonMessage.level;
+                } else if (jsonMessage.type == 'sco_state_change') {
+                    sampleRate = jsonMessage.sample_rate;
+                    console.log(sampleRate);
+                    if (player != null) {
+                        player = new PCMPlayer({
+                            inputCodec: 'Int16',
+                            channels: 1,
+                            sampleRate: sampleRate,
+                            flushTime: 7.5,
+                        });
+                        player.volume(gainInput.value);
+                    }
+                }
+            } else {
+                // BINARY audio data.
+                if (player == null) return;
+                player.feed(message.data);
+            }
+        };
+
+        function send(message) {
+            if (socket && socket.readyState == WebSocket.OPEN) {
+                let jsonMessage = JSON.stringify(message)
+                log.textContent += `--> ${jsonMessage}\n`
+                socket.send(jsonMessage)
+            } else {
+                log.textContent += 'NOT CONNECTED\n'
+            }
+        }
+
+        function send_at_response(response) {
+            send({ type: 'at_response', response: response })
+        }
+
+        function update_ag_indicator(indicator) {
+            const value = document.getElementById(indicator).value
+            send({ type: 'ag_indicator', indicator: indicator, value: value })
+        }
+
+        function connect_sco() {
+            send({ type: 'connect_sco' })
+        }
+
+        function negotiate_codec() {
+            const codec = document.getElementById('codec').value
+            send({ type: 'negotiate_codec', codec: codec })
+        }
+
+        function disconnect_sco() {
+            send({ type: 'disconnect_sco' })
+        }
+
+        function add_call() {
+            let callLists = document.getElementById('call-lists');
+            let template = document.getElementById('call-template');
+
+            let newNode = document.importNode(template.content, true);
+            newNode.querySelector('.call-remover').onclick = function (event) {
+                event.target.closest('.call-row').remove();
+            }
+            callLists.appendChild(newNode);
+        }
+
+        function update_calls() {
+            let callLists = document.getElementById('call-lists');
+            send({
+                type: 'update_calls',
+                calls: Array.from(
+                    callLists.querySelectorAll('.call-row')).map(
+                        function (element) {
+                            return {
+                                index: element.querySelector('.call-index').value,
+                                number: element.querySelector('.call-number').value,
+                                direction: element.querySelector('.call-direction').value,
+                                status: element.querySelector('.call-status').value,
+                            }
+                        }
+                    ),
+            }
+            )
+        }
+
+        function connectAudio() {
+            player = new PCMPlayer({
+                inputCodec: 'Int16',
+                channels: 1,
+                sampleRate: sampleRate,
+                flushTime: 7.5,
+            });
+            player.volume(gainInput.value);
+        }
+
+        function setGain() {
+            if (player != null) {
+                player.volume(gainInput.value);
+            }
+        }
+    </script>
+    </div>
+</body>
+
+</html>

examples/hfp_gateway.json

@@ -1,4 +1,5 @@
 {
     "name": "Bumble Phone",
-    "class_of_device": 6291980
+    "class_of_device": 6291980,
+    "keystore": "JsonKeyStore"
 }

examples/hfp_handsfree.html

@@ -1,79 +1,132 @@
-<html>
-    <head>
-        <style>
-* {
-    font-family: sans-serif;
-}
+<html data-bs-theme="dark">
 
-label {
-    display: block;
-}
+<head>
+    <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.2/dist/css/bootstrap.min.css" rel="stylesheet"
+        integrity="sha384-T3c6CoIi6uLrA9TneNEoa7RxnatzjcDSCmG1MXxSR1GAsXEV/Dwwykc2MPK8M2HN" crossorigin="anonymous">
+</head>
+
+<body>
+    <nav class="navbar navbar-dark bg-primary">
+        <div class="container">
+            <span class="navbar-brand mb-0 h1">Bumble Handsfree</span>
+        </div>
+    </nav>
+    <br>
+
+    <div class="container">
+
+        <label class="form-label">Server Port</label>
+        <div class="input-group mb-3">
+            <input type="text" class="form-control" aria-label="Port Number" value="8989" id="port">
+            <button class="btn btn-primary" type="button" onclick="connect()">Connect</button>
+        </div>
+
+        <label class="form-label">Dial Phone Number</label>
+        <div class="input-group mb-3">
+            <input type="text" class="form-control" placeholder="Phone Number" aria-label="Phone Number"
+                id="dial_number">
+            <button class="btn btn-primary" type="button"
+                onclick="send_at_command(`ATD${dialNumberInput.value}`)">Dial</button>
+        </div>
+
+        <label class="form-label">Send AT Command</label>
+        <div class="input-group mb-3">
+            <input type="text" class="form-control" placeholder="AT Command" aria-label="AT command" id="at_command">
+            <button class="btn btn-primary" type="button"
+                onclick="send_at_command(document.getElementById('at_command').value)">Send</button>
+        </div>
+
+        <div class="row">
+            <div class="col-auto">
+                <label class="form-label">Battery Level</label>
+                <div class="input-group mb-3">
+                    <input type="text" class="form-control" placeholder="0 - 100" aria-label="Battery Level"
+                        id="battery_level">
+                    <button class="btn btn-primary" type="button"
+                        onclick="send_at_command(`AT+BIEV=2,${document.getElementById('battery_level').value}`)">Set</button>
+                </div>
+            </div>
+            <div class="col-auto">
+                <label class="form-label">Speaker Volume</label>
+                <div class="input-group mb-3 col-auto">
+                    <input type="text" class="form-control" placeholder="0 - 15" aria-label="Speaker Volume"
+                        id="speaker_volume">
+                    <button class="btn btn-primary" type="button"
+                        onclick="send_at_command(`AT+VGS=${document.getElementById('speaker_volume').value}`)">Set</button>
+                </div>
+            </div>
+            <div class="col-auto">
+                <label class="form-label">Mic Volume</label>
+                <div class="input-group mb-3 col-auto">
+                    <input type="text" class="form-control" placeholder="0 - 15" aria-label="Mic Volume"
+                        id="mic_volume">
+                    <button class="btn btn-primary" type="button"
+                        onclick="send_at_command(`AT+VGM=${document.getElementById('mic_volume').value}`)">Set</button>
+                </div>
+            </div>
+        </div>
+
+        <button class="btn btn-primary" onclick="send_at_command('ATA')">Answer</button>
+        <button class="btn btn-primary" onclick="send_at_command('AT+CHUP')">Hang Up</button>
+        <button class="btn btn-primary" onclick="send_at_command('AT+BLDN')">Redial</button>
+        <button class="btn btn-primary" onclick="send({ type: 'query_call'})">Get Call Status</button>
+
+        <br><br>
+
+        <button class="btn btn-primary" onclick="send_at_command('AT+BVRA=1')">Start Voice Assistant</button>
+        <button class="btn btn-primary" onclick="send_at_command('AT+BVRA=0')">Stop Voice Assistant</button>
 
-input, label {
-    margin: .4rem 0;
-}
-        </style>
-    </head>
-    <body>
-        Server Port <input id="port" type="text" value="8989"></input> <button onclick="connect()">Connect</button><br>
-        AT Command <input type="text" id="at_command" required size="10"> <button onclick="send_at_command()">Send</button><br>
-        Dial Phone Number <input type="text" id="dial_number" required size="10"> <button onclick="dial()">Dial</button><br>
-        <button onclick="answer()">Answer</button>
-        <button onclick="hangup()">Hang Up</button>
-        <button onclick="start_voice_assistant()">Start Voice Assistant</button>
-        <button onclick="stop_voice_assistant()">Stop Voice Assistant</button>
         <hr>
-        <div id="socketState"></div>
-        <script>
+
+        <div id="socketStateContainer" class="bg-body-tertiary p-3 rounded-2">
+            <h3>Log</h3>
+            <code id="log" style="white-space: pre-line;"></code>
+        </div>
+    </div>
+
+
+    <script>
         let portInput = document.getElementById("port")
         let atCommandInput = document.getElementById("at_command")
-        let dialNumberInput = document.getElementById("dial_number")
-        let socketState = document.getElementById("socketState")
+        let log = document.getElementById("log")
         let socket
 
         function connect() {
             socket = new WebSocket(`ws://localhost:${portInput.value}`);
             socket.onopen = _ => {
-                socketState.innerText = 'OPEN'
+                log.textContent += 'OPEN\n'
             }
             socket.onclose = _ => {
-                socketState.innerText = 'CLOSED'
+                log.textContent += 'CLOSED\n'
             }
             socket.onerror = (error) => {
-                socketState.innerText = 'ERROR'
+                log.textContent += 'ERROR\n'
                 console.log(`ERROR: ${error}`)
             }
+            socket.onmessage = (event) => {
+                log.textContent += `<-- ${event.data}\n`
+                let volume_state = JSON.parse(event.data)
+                volumeSetting.value = volume_state.volume_setting
+                changeCounter.value = volume_state.change_counter
+                muted.checked = volume_state.muted ? true : false
+            }
         }
 
         function send(message) {
             if (socket && socket.readyState == WebSocket.OPEN) {
-                socket.send(JSON.stringify(message))
+                let jsonMessage = JSON.stringify(message)
+                log.textContent += `--> ${jsonMessage}\n`
+                socket.send(jsonMessage)
+            } else {
+                log.textContent += 'NOT CONNECTED\n'
             }
         }
 
-        function send_at_command() {
-            send({ type:'at_command', command: atCommandInput.value })
+        function send_at_command(command) {
+            send({ type: 'at_command', 'command': command })
         }
+    </script>
+    </div>
+</body>
 
-        function answer() {
-            send({ type:'at_command', command: 'ATA' })
-        }
-
-        function hangup() {
-            send({ type:'at_command', command: 'AT+CHUP' })
-        }
-
-        function dial() {
-            send({ type:'at_command', command: `ATD${dialNumberInput.value}` })
-        }
-
-        function start_voice_assistant() {
-            send(({ type:'at_command', command: 'AT+BVRA=1' }))
-        }
-
-        function stop_voice_assistant() {
-            send(({ type:'at_command', command: 'AT+BVRA=0' }))
-        }
-</script>
-    </body>
-</html>
+</html>

examples/hid_keyboard.json

@@ -0,0 +1,5 @@
+{
+    "name": "Bumble HID Keyboard",
+    "class_of_device": 9664,
+    "keystore": "JsonKeyStore"
+}

examples/keyboard.html

@@ -40,9 +40,9 @@
                 }
             }
             function onMouseMove(event) {
-                //console.log(event.clientX, event.clientY)
-                mouseInfo.innerText = `MOUSE: x=${event.clientX}, y=${event.clientY}`
-                send({ type:'mousemove', x: event.clientX, y: event.clientY })
+                //console.log(event.movementX, event.movementY)
+                mouseInfo.innerText = `MOUSE: x=${event.movementX}, y=${event.movementY}`
+                send({ type:'mousemove', x: event.movementX, y: event.movementY })
             }
 
             function onKeyDown(event) {

examples/keyboard.py

@@ -416,7 +416,7 @@ async def keyboard_device(device, command):
 
 
 # -----------------------------------------------------------------------------
-async def main():
+async def main() -> None:
     if len(sys.argv) < 4:
         print(
             'Usage: python keyboard.py <device-config> <transport-spec> <command>'
@@ -434,9 +434,11 @@ async def main():
         )
         return
 
-    async with await open_transport_or_link(sys.argv[2]) as (hci_source, hci_sink):
+    async with await open_transport_or_link(sys.argv[2]) as hci_transport:
         # Create a device to manage the host
-        device = Device.from_config_file_with_hci(sys.argv[1], hci_source, hci_sink)
+        device = Device.from_config_file_with_hci(
+            sys.argv[1], hci_transport.source, hci_transport.sink
+        )
 
         command = sys.argv[3]
         if command == 'connect':

examples/leaudio.json

@@ -1,5 +1,7 @@
 {
     "name": "Bumble-LEA",
     "keystore": "JsonKeyStore",
+    "address": "F0:F1:F2:F3:F4:FA",
+    "class_of_device": 2376708,
     "advertising_interval": 100
 }

examples/leaudio_with_classic.json

@@ -0,0 +1,9 @@
+{
+    "name": "Bumble-LEA",
+    "keystore": "JsonKeyStore",
+    "address": "F0:F1:F2:F3:F4:FA",
+    "classic_enabled": true,
+    "cis_enabled": true,
+    "class_of_device": 2376708,
+    "advertising_interval": 100
+}

examples/run_a2dp_info.py

@@ -139,18 +139,20 @@ async def find_a2dp_service(connection):
 
 
 # -----------------------------------------------------------------------------
-async def main():
+async def main() -> None:
     if len(sys.argv) < 4:
         print('Usage: run_a2dp_info.py <device-config> <transport-spec> <bt-addr>')
         print('example: run_a2dp_info.py classic1.json usb:0 14:7D:DA:4E:53:A8')
         return
 
     print('<<< connecting to HCI...')
-    async with await open_transport_or_link(sys.argv[2]) as (hci_source, hci_sink):
+    async with await open_transport_or_link(sys.argv[2]) as hci_transport:
         print('<<< connected')
 
         # Create a device
-        device = Device.from_config_file_with_hci(sys.argv[1], hci_source, hci_sink)
+        device = Device.from_config_file_with_hci(
+            sys.argv[1], hci_transport.source, hci_transport.sink
+        )
         device.classic_enabled = True
 
         # Start the controller
@@ -187,7 +189,7 @@ async def main():
         client = await AVDTP_Protocol.connect(connection, avdtp_version)
 
         # Discover all endpoints on the remote device
-        endpoints = await client.discover_remote_endpoints()
+        endpoints = list(await client.discover_remote_endpoints())
         print(f'@@@ Found {len(endpoints)} endpoints')
         for endpoint in endpoints:
             print('@@@', endpoint)

examples/run_a2dp_sink.py

@@ -19,6 +19,7 @@ import asyncio
 import sys
 import os
 import logging
+from typing import Any, Dict
 
 from bumble.device import Device
 from bumble.transport import open_transport_or_link
@@ -41,7 +42,7 @@ from bumble.a2dp import (
     SbcMediaCodecInformation,
 )
 
-Context = {'output': None}
+Context: Dict[Any, Any] = {'output': None}
 
 
 # -----------------------------------------------------------------------------
@@ -104,7 +105,7 @@ def on_rtp_packet(packet):
 
 
 # -----------------------------------------------------------------------------
-async def main():
+async def main() -> None:
     if len(sys.argv) < 4:
         print(
             'Usage: run_a2dp_sink.py <device-config> <transport-spec> <sbc-file> '
@@ -114,14 +115,16 @@ async def main():
         return
 
     print('<<< connecting to HCI...')
-    async with await open_transport_or_link(sys.argv[2]) as (hci_source, hci_sink):
+    async with await open_transport_or_link(sys.argv[2]) as hci_transport:
         print('<<< connected')
 
         with open(sys.argv[3], 'wb') as sbc_file:
             Context['output'] = sbc_file
 
             # Create a device
-            device = Device.from_config_file_with_hci(sys.argv[1], hci_source, hci_sink)
+            device = Device.from_config_file_with_hci(
+                sys.argv[1], hci_transport.source, hci_transport.sink
+            )
             device.classic_enabled = True
 
             # Setup the SDP to expose the sink service
@@ -162,7 +165,7 @@ async def main():
                 await device.set_discoverable(True)
                 await device.set_connectable(True)
 
-            await hci_source.wait_for_termination()
+            await hci_transport.source.wait_for_termination()
 
 
 # -----------------------------------------------------------------------------

examples/run_a2dp_source.py

@@ -74,7 +74,7 @@ def codec_capabilities():
 # -----------------------------------------------------------------------------
 def on_avdtp_connection(read_function, protocol):
     packet_source = SbcPacketSource(
-        read_function, protocol.l2cap_channel.mtu, codec_capabilities()
+        read_function, protocol.l2cap_channel.peer_mtu, codec_capabilities()
     )
     packet_pump = MediaPacketPump(packet_source.packets)
     protocol.add_source(packet_source.codec_capabilities, packet_pump)
@@ -98,7 +98,7 @@ async def stream_packets(read_function, protocol):
 
     # Stream the packets
     packet_source = SbcPacketSource(
-        read_function, protocol.l2cap_channel.mtu, codec_capabilities()
+        read_function, protocol.l2cap_channel.peer_mtu, codec_capabilities()
     )
     packet_pump = MediaPacketPump(packet_source.packets)
     source = protocol.add_source(packet_source.codec_capabilities, packet_pump)
@@ -114,7 +114,7 @@ async def stream_packets(read_function, protocol):
 
 
 # -----------------------------------------------------------------------------
-async def main():
+async def main() -> None:
     if len(sys.argv) < 4:
         print(
             'Usage: run_a2dp_source.py <device-config> <transport-spec> <sbc-file> '
@@ -126,11 +126,13 @@ async def main():
         return
 
     print('<<< connecting to HCI...')
-    async with await open_transport_or_link(sys.argv[2]) as (hci_source, hci_sink):
+    async with await open_transport_or_link(sys.argv[2]) as hci_transport:
         print('<<< connected')
 
         # Create a device
-        device = Device.from_config_file_with_hci(sys.argv[1], hci_source, hci_sink)
+        device = Device.from_config_file_with_hci(
+            sys.argv[1], hci_transport.source, hci_transport.sink
+        )
         device.classic_enabled = True
 
         # Setup the SDP to expose the SRC service
@@ -186,7 +188,7 @@ async def main():
                 await device.set_discoverable(True)
                 await device.set_connectable(True)
 
-            await hci_source.wait_for_termination()
+            await hci_transport.source.wait_for_termination()
 
 
 # -----------------------------------------------------------------------------

examples/run_advertiser.py

@@ -19,14 +19,16 @@ import asyncio
 import logging
 import sys
 import os
+import struct
+
+from bumble.core import AdvertisingData
 from bumble.device import AdvertisingType, Device
 from bumble.hci import Address
-
 from bumble.transport import open_transport_or_link
 
 
 # -----------------------------------------------------------------------------
-async def main():
+async def main() -> None:
     if len(sys.argv) < 3:
         print(
             'Usage: run_advertiser.py <config-file> <transport-spec> [type] [address]'
@@ -48,13 +50,25 @@ async def main():
         target = None
 
     print('<<< connecting to HCI...')
-    async with await open_transport_or_link(sys.argv[2]) as (hci_source, hci_sink):
+    async with await open_transport_or_link(sys.argv[2]) as hci_transport:
         print('<<< connected')
 
-        device = Device.from_config_file_with_hci(sys.argv[1], hci_source, hci_sink)
+        device = Device.from_config_file_with_hci(
+            sys.argv[1], hci_transport.source, hci_transport.sink
+        )
+
+        if advertising_type.is_scannable:
+            device.scan_response_data = bytes(
+                AdvertisingData(
+                    [
+                        (AdvertisingData.APPEARANCE, struct.pack('<H', 0x0340)),
+                    ]
+                )
+            )
+
         await device.power_on()
         await device.start_advertising(advertising_type=advertising_type, target=target)
-        await hci_source.wait_for_termination()
+        await hci_transport.source.wait_for_termination()
 
 
 # -----------------------------------------------------------------------------

examples/run_asha_sink.py

@@ -49,7 +49,7 @@ ASHA_LE_PSM_OUT_CHARACTERISTIC = UUID(
 
 
 # -----------------------------------------------------------------------------
-async def main():
+async def main() -> None:
     if len(sys.argv) != 4:
         print(
             'Usage: python run_asha_sink.py <device-config> <transport-spec> '
@@ -60,8 +60,10 @@ async def main():
 
     audio_out = open(sys.argv[3], 'wb')
 
-    async with await open_transport_or_link(sys.argv[2]) as (hci_source, hci_sink):
-        device = Device.from_config_file_with_hci(sys.argv[1], hci_source, hci_sink)
+    async with await open_transport_or_link(sys.argv[2]) as hci_transport:
+        device = Device.from_config_file_with_hci(
+            sys.argv[1], hci_transport.source, hci_transport.sink
+        )
 
         # Handler for audio control commands
         def on_audio_control_point_write(_connection, value):
@@ -197,7 +199,7 @@ async def main():
         await device.power_on()
         await device.start_advertising(auto_restart=True)
 
-        await hci_source.wait_for_termination()
+        await hci_transport.source.wait_for_termination()
 
 
 # -----------------------------------------------------------------------------

examples/run_avrcp.py

@@ -0,0 +1,410 @@
+# Copyright 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.
+
+# -----------------------------------------------------------------------------
+# Imports
+# -----------------------------------------------------------------------------
+from __future__ import annotations
+import asyncio
+import json
+import sys
+import os
+import logging
+import websockets
+
+from bumble.device import Device
+from bumble.transport import open_transport_or_link
+from bumble.core import BT_BR_EDR_TRANSPORT
+from bumble import avc
+from bumble import avrcp
+from bumble import avdtp
+from bumble import a2dp
+from bumble import utils
+
+
+logger = logging.getLogger(__name__)
+
+
+# -----------------------------------------------------------------------------
+def sdp_records():
+    a2dp_sink_service_record_handle = 0x00010001
+    avrcp_controller_service_record_handle = 0x00010002
+    avrcp_target_service_record_handle = 0x00010003
+    # pylint: disable=line-too-long
+    return {
+        a2dp_sink_service_record_handle: a2dp.make_audio_sink_service_sdp_records(
+            a2dp_sink_service_record_handle
+        ),
+        avrcp_controller_service_record_handle: avrcp.make_controller_service_sdp_records(
+            avrcp_controller_service_record_handle
+        ),
+        avrcp_target_service_record_handle: avrcp.make_target_service_sdp_records(
+            avrcp_controller_service_record_handle
+        ),
+    }
+
+
+# -----------------------------------------------------------------------------
+def codec_capabilities():
+    return avdtp.MediaCodecCapabilities(
+        media_type=avdtp.AVDTP_AUDIO_MEDIA_TYPE,
+        media_codec_type=a2dp.A2DP_SBC_CODEC_TYPE,
+        media_codec_information=a2dp.SbcMediaCodecInformation.from_lists(
+            sampling_frequencies=[48000, 44100, 32000, 16000],
+            channel_modes=[
+                a2dp.SBC_MONO_CHANNEL_MODE,
+                a2dp.SBC_DUAL_CHANNEL_MODE,
+                a2dp.SBC_STEREO_CHANNEL_MODE,
+                a2dp.SBC_JOINT_STEREO_CHANNEL_MODE,
+            ],
+            block_lengths=[4, 8, 12, 16],
+            subbands=[4, 8],
+            allocation_methods=[
+                a2dp.SBC_LOUDNESS_ALLOCATION_METHOD,
+                a2dp.SBC_SNR_ALLOCATION_METHOD,
+            ],
+            minimum_bitpool_value=2,
+            maximum_bitpool_value=53,
+        ),
+    )
+
+
+# -----------------------------------------------------------------------------
+def on_avdtp_connection(server):
+    # Add a sink endpoint to the server
+    sink = server.add_sink(codec_capabilities())
+    sink.on('rtp_packet', on_rtp_packet)
+
+
+# -----------------------------------------------------------------------------
+def on_rtp_packet(packet):
+    print(f'RTP: {packet}')
+
+
+# -----------------------------------------------------------------------------
+def on_avrcp_start(avrcp_protocol: avrcp.Protocol, websocket_server: WebSocketServer):
+    async def get_supported_events():
+        events = await avrcp_protocol.get_supported_events()
+        print("SUPPORTED EVENTS:", events)
+        websocket_server.send_message(
+            {
+                "type": "supported-events",
+                "params": {"events": [event.name for event in events]},
+            }
+        )
+
+        if avrcp.EventId.TRACK_CHANGED in events:
+            utils.AsyncRunner.spawn(monitor_track_changed())
+
+        if avrcp.EventId.PLAYBACK_STATUS_CHANGED in events:
+            utils.AsyncRunner.spawn(monitor_playback_status())
+
+        if avrcp.EventId.PLAYBACK_POS_CHANGED in events:
+            utils.AsyncRunner.spawn(monitor_playback_position())
+
+        if avrcp.EventId.PLAYER_APPLICATION_SETTING_CHANGED in events:
+            utils.AsyncRunner.spawn(monitor_player_application_settings())
+
+        if avrcp.EventId.AVAILABLE_PLAYERS_CHANGED in events:
+            utils.AsyncRunner.spawn(monitor_available_players())
+
+        if avrcp.EventId.ADDRESSED_PLAYER_CHANGED in events:
+            utils.AsyncRunner.spawn(monitor_addressed_player())
+
+        if avrcp.EventId.UIDS_CHANGED in events:
+            utils.AsyncRunner.spawn(monitor_uids())
+
+        if avrcp.EventId.VOLUME_CHANGED in events:
+            utils.AsyncRunner.spawn(monitor_volume())
+
+    utils.AsyncRunner.spawn(get_supported_events())
+
+    async def monitor_track_changed():
+        async for identifier in avrcp_protocol.monitor_track_changed():
+            print("TRACK CHANGED:", identifier.hex())
+            websocket_server.send_message(
+                {"type": "track-changed", "params": {"identifier": identifier.hex()}}
+            )
+
+    async def monitor_playback_status():
+        async for playback_status in avrcp_protocol.monitor_playback_status():
+            print("PLAYBACK STATUS CHANGED:", playback_status.name)
+            websocket_server.send_message(
+                {
+                    "type": "playback-status-changed",
+                    "params": {"status": playback_status.name},
+                }
+            )
+
+    async def monitor_playback_position():
+        async for playback_position in avrcp_protocol.monitor_playback_position(
+            playback_interval=1
+        ):
+            print("PLAYBACK POSITION CHANGED:", playback_position)
+            websocket_server.send_message(
+                {
+                    "type": "playback-position-changed",
+                    "params": {"position": playback_position},
+                }
+            )
+
+    async def monitor_player_application_settings():
+        async for settings in avrcp_protocol.monitor_player_application_settings():
+            print("PLAYER APPLICATION SETTINGS:", settings)
+            settings_as_dict = [
+                {"attribute": setting.attribute_id.name, "value": setting.value_id.name}
+                for setting in settings
+            ]
+            websocket_server.send_message(
+                {
+                    "type": "player-settings-changed",
+                    "params": {"settings": settings_as_dict},
+                }
+            )
+
+    async def monitor_available_players():
+        async for _ in avrcp_protocol.monitor_available_players():
+            print("AVAILABLE PLAYERS CHANGED")
+            websocket_server.send_message(
+                {"type": "available-players-changed", "params": {}}
+            )
+
+    async def monitor_addressed_player():
+        async for player in avrcp_protocol.monitor_addressed_player():
+            print("ADDRESSED PLAYER CHANGED")
+            websocket_server.send_message(
+                {
+                    "type": "addressed-player-changed",
+                    "params": {
+                        "player": {
+                            "player_id": player.player_id,
+                            "uid_counter": player.uid_counter,
+                        }
+                    },
+                }
+            )
+
+    async def monitor_uids():
+        async for uid_counter in avrcp_protocol.monitor_uids():
+            print("UIDS CHANGED")
+            websocket_server.send_message(
+                {
+                    "type": "uids-changed",
+                    "params": {
+                        "uid_counter": uid_counter,
+                    },
+                }
+            )
+
+    async def monitor_volume():
+        async for volume in avrcp_protocol.monitor_volume():
+            print("VOLUME CHANGED:", volume)
+            websocket_server.send_message(
+                {"type": "volume-changed", "params": {"volume": volume}}
+            )
+
+
+# -----------------------------------------------------------------------------
+class WebSocketServer:
+    def __init__(
+        self, avrcp_protocol: avrcp.Protocol, avrcp_delegate: Delegate
+    ) -> None:
+        self.socket = None
+        self.delegate = None
+        self.avrcp_protocol = avrcp_protocol
+        self.avrcp_delegate = avrcp_delegate
+
+    async def start(self) -> None:
+        # pylint: disable-next=no-member
+        await websockets.serve(self.serve, 'localhost', 8989)  # type: ignore
+
+    async def serve(self, socket, _path) -> None:
+        print('### WebSocket connected')
+        self.socket = socket
+        while True:
+            try:
+                message = await socket.recv()
+                print('Received: ', str(message))
+
+                parsed = json.loads(message)
+                message_type = parsed['type']
+                if message_type == 'send-key-down':
+                    await self.on_send_key_down(parsed)
+                elif message_type == 'send-key-up':
+                    await self.on_send_key_up(parsed)
+                elif message_type == 'set-volume':
+                    await self.on_set_volume(parsed)
+                elif message_type == 'get-play-status':
+                    await self.on_get_play_status()
+                elif message_type == 'get-element-attributes':
+                    await self.on_get_element_attributes()
+            except websockets.exceptions.ConnectionClosedOK:
+                self.socket = None
+                break
+
+    async def on_send_key_down(self, message: dict) -> None:
+        key = avc.PassThroughFrame.OperationId[message["key"]]
+        await self.avrcp_protocol.send_key_event(key, True)
+
+    async def on_send_key_up(self, message: dict) -> None:
+        key = avc.PassThroughFrame.OperationId[message["key"]]
+        await self.avrcp_protocol.send_key_event(key, False)
+
+    async def on_set_volume(self, message: dict) -> None:
+        volume = message["volume"]
+        self.avrcp_delegate.volume = volume
+        self.avrcp_protocol.notify_volume_changed(volume)
+
+    async def on_get_play_status(self) -> None:
+        play_status = await self.avrcp_protocol.get_play_status()
+        self.send_message(
+            {
+                "type": "get-play-status-response",
+                "params": {
+                    "song_length": play_status.song_length,
+                    "song_position": play_status.song_position,
+                    "play_status": play_status.play_status.name,
+                },
+            }
+        )
+
+    async def on_get_element_attributes(self) -> None:
+        attributes = await self.avrcp_protocol.get_element_attributes(
+            0,
+            [
+                avrcp.MediaAttributeId.TITLE,
+                avrcp.MediaAttributeId.ARTIST_NAME,
+                avrcp.MediaAttributeId.ALBUM_NAME,
+                avrcp.MediaAttributeId.TRACK_NUMBER,
+                avrcp.MediaAttributeId.TOTAL_NUMBER_OF_TRACKS,
+                avrcp.MediaAttributeId.GENRE,
+                avrcp.MediaAttributeId.PLAYING_TIME,
+                avrcp.MediaAttributeId.DEFAULT_COVER_ART,
+            ],
+        )
+        self.send_message(
+            {
+                "type": "get-element-attributes-response",
+                "params": [
+                    {
+                        "attribute_id": attribute.attribute_id.name,
+                        "attribute_value": attribute.attribute_value,
+                    }
+                    for attribute in attributes
+                ],
+            }
+        )
+
+    def send_message(self, message: dict) -> None:
+        if self.socket is None:
+            print("no socket, dropping message")
+            return
+        serialized = json.dumps(message)
+        utils.AsyncRunner.spawn(self.socket.send(serialized))
+
+
+# -----------------------------------------------------------------------------
+class Delegate(avrcp.Delegate):
+    def __init__(self):
+        super().__init__(
+            [avrcp.EventId.VOLUME_CHANGED, avrcp.EventId.PLAYBACK_STATUS_CHANGED]
+        )
+        self.websocket_server = None
+
+    async def set_absolute_volume(self, volume: int) -> None:
+        await super().set_absolute_volume(volume)
+        if self.websocket_server is not None:
+            self.websocket_server.send_message(
+                {"type": "set-volume", "params": {"volume": volume}}
+            )
+
+
+# -----------------------------------------------------------------------------
+async def main() -> None:
+    if len(sys.argv) < 3:
+        print(
+            'Usage: run_avrcp_controller.py <device-config> <transport-spec> '
+            '<sbc-file> [<bt-addr>]'
+        )
+        print('example: run_avrcp_controller.py classic1.json usb:0')
+        return
+
+    print('<<< connecting to HCI...')
+    async with await open_transport_or_link(sys.argv[2]) as hci_transport:
+        print('<<< connected')
+
+        # Create a device
+        device = Device.from_config_file_with_hci(
+            sys.argv[1], hci_transport.source, hci_transport.sink
+        )
+        device.classic_enabled = True
+
+        # Setup the SDP to expose the sink service
+        device.sdp_service_records = sdp_records()
+
+        # Start the controller
+        await device.power_on()
+
+        # Create a listener to wait for AVDTP connections
+        listener = avdtp.Listener(avdtp.Listener.create_registrar(device))
+        listener.on('connection', on_avdtp_connection)
+
+        avrcp_delegate = Delegate()
+        avrcp_protocol = avrcp.Protocol(avrcp_delegate)
+        avrcp_protocol.listen(device)
+
+        websocket_server = WebSocketServer(avrcp_protocol, avrcp_delegate)
+        avrcp_delegate.websocket_server = websocket_server
+        avrcp_protocol.on(
+            "start", lambda: on_avrcp_start(avrcp_protocol, websocket_server)
+        )
+        await websocket_server.start()
+
+        if len(sys.argv) >= 5:
+            # Connect to the peer
+            target_address = sys.argv[4]
+            print(f'=== Connecting to {target_address}...')
+            connection = await device.connect(
+                target_address, transport=BT_BR_EDR_TRANSPORT
+            )
+            print(f'=== Connected to {connection.peer_address}!')
+
+            # Request authentication
+            print('*** Authenticating...')
+            await connection.authenticate()
+            print('*** Authenticated')
+
+            # Enable encryption
+            print('*** Enabling encryption...')
+            await connection.encrypt()
+            print('*** Encryption on')
+
+            server = await avdtp.Protocol.connect(connection)
+            listener.set_server(connection, server)
+            sink = server.add_sink(codec_capabilities())
+            sink.on('rtp_packet', on_rtp_packet)
+
+            await avrcp_protocol.connect(connection)
+
+        else:
+            # Start being discoverable and connectable
+            await device.set_discoverable(True)
+            await device.set_connectable(True)
+
+        await asyncio.get_event_loop().create_future()
+
+
+# -----------------------------------------------------------------------------
+logging.basicConfig(level=os.environ.get('BUMBLE_LOGLEVEL', 'DEBUG').upper())
+asyncio.run(main())

examples/run_cig_setup.py

@@ -22,10 +22,11 @@ import os
 from bumble.device import (
     Device,
     Connection,
+    AdvertisingParameters,
+    AdvertisingEventProperties,
 )
 from bumble.hci import (
     OwnAddressType,
-    HCI_LE_Set_Extended_Advertising_Parameters_Command,
 )
 
 from bumble.transport import open_transport_or_link
@@ -61,12 +62,7 @@ async def main() -> None:
     devices[1].cis_enabled = True
 
     await asyncio.gather(*[device.power_on() for device in devices])
-    await devices[0].start_extended_advertising(
-        advertising_properties=(
-            HCI_LE_Set_Extended_Advertising_Parameters_Command.AdvertisingProperties.CONNECTABLE_ADVERTISING
-        ),
-        own_address_type=OwnAddressType.PUBLIC,
-    )
+    advertising_set = await devices[0].create_advertising_set()
 
     connection = await devices[1].connect(
         devices[0].public_address, own_address_type=OwnAddressType.PUBLIC

examples/run_classic_connect.py

@@ -32,7 +32,7 @@ from bumble.sdp import (
 
 
 # -----------------------------------------------------------------------------
-async def main():
+async def main() -> None:
     if len(sys.argv) < 3:
         print(
             'Usage: run_classic_connect.py <device-config> <transport-spec> '
@@ -42,11 +42,13 @@ async def main():
         return
 
     print('<<< connecting to HCI...')
-    async with await open_transport_or_link(sys.argv[2]) as (hci_source, hci_sink):
+    async with await open_transport_or_link(sys.argv[2]) as hci_transport:
         print('<<< connected')
 
         # Create a device
-        device = Device.from_config_file_with_hci(sys.argv[1], hci_source, hci_sink)
+        device = Device.from_config_file_with_hci(
+            sys.argv[1], hci_transport.source, hci_transport.sink
+        )
         device.classic_enabled = True
         device.le_enabled = False
         await device.power_on()

examples/run_classic_discoverable.py

@@ -91,18 +91,20 @@ SDP_SERVICE_RECORDS = {
 
 
 # -----------------------------------------------------------------------------
-async def main():
+async def main() -> None:
     if len(sys.argv) < 3:
         print('Usage: run_classic_discoverable.py <device-config> <transport-spec>')
         print('example: run_classic_discoverable.py classic1.json usb:04b4:f901')
         return
 
     print('<<< connecting to HCI...')
-    async with await open_transport_or_link(sys.argv[2]) as (hci_source, hci_sink):
+    async with await open_transport_or_link(sys.argv[2]) as hci_transport:
         print('<<< connected')
 
         # Create a device
-        device = Device.from_config_file_with_hci(sys.argv[1], hci_source, hci_sink)
+        device = Device.from_config_file_with_hci(
+            sys.argv[1], hci_transport.source, hci_transport.sink
+        )
         device.classic_enabled = True
         device.sdp_service_records = SDP_SERVICE_RECORDS
         await device.power_on()
@@ -111,7 +113,7 @@ async def main():
         await device.set_discoverable(True)
         await device.set_connectable(True)
 
-        await hci_source.wait_for_termination()
+        await hci_transport.source.wait_for_termination()
 
 
 # -----------------------------------------------------------------------------

examples/run_classic_discovery.py

@@ -20,8 +20,8 @@ import sys
 import os
 import logging
 from bumble.colors import color
-
 from bumble.device import Device
+from bumble.hci import Address
 from bumble.transport import open_transport_or_link
 from bumble.core import DeviceClass
 
@@ -53,22 +53,27 @@ class DiscoveryListener(Device.Listener):
 
 
 # -----------------------------------------------------------------------------
-async def main():
+async def main() -> None:
     if len(sys.argv) != 2:
         print('Usage: run_classic_discovery.py <transport-spec>')
         print('example: run_classic_discovery.py usb:04b4:f901')
         return
 
     print('<<< connecting to HCI...')
-    async with await open_transport_or_link(sys.argv[1]) as (hci_source, hci_sink):
+    async with await open_transport_or_link(sys.argv[1]) as hci_transport:
         print('<<< connected')
 
-        device = Device.with_hci('Bumble', 'F0:F1:F2:F3:F4:F5', hci_source, hci_sink)
+        device = Device.with_hci(
+            'Bumble',
+            Address('F0:F1:F2:F3:F4:F5'),
+            hci_transport.source,
+            hci_transport.sink,
+        )
         device.listener = DiscoveryListener()
         await device.power_on()
         await device.start_discovery()
 
-        await hci_source.wait_for_termination()
+        await hci_transport.source.wait_for_termination()
 
 
 # -----------------------------------------------------------------------------