fix spacing_type

Make bumble work on Android using briefcase/chaquopy

.devcontainer/devcontainer.json

@@ -0,0 +1,30 @@
+// For format details, see https://aka.ms/devcontainer.json. For config options, see the
+// README at: https://github.com/devcontainers/templates/tree/main/src/python
+{
+	// Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile
+    "image": "mcr.microsoft.com/devcontainers/universal:2",
+
+	// Features to add to the dev container. More info: https://containers.dev/features.
+	// "features": {},
+
+	// Use 'forwardPorts' to make a list of ports inside the container available locally.
+	// "forwardPorts": [],
+
+	// Use 'postCreateCommand' to run commands after the container is created.
+    "postCreateCommand": 
+        "python -m pip install '.[build,test,development,documentation]'",
+
+    // Configure tool-specific properties.
+    "customizations": {
+        // Configure properties specific to VS Code.
+        "vscode": {
+            // Add the IDs of extensions you want installed when the container is created.
+            "extensions": [
+                "ms-python.python"
+            ]
+        }
+    }
+
+	// Uncomment to connect as root instead. More info: https://aka.ms/dev-containers-non-root.
+	// "remoteUser": "root"
+}

.github/ci-gradle.properties

@@ -0,0 +1,26 @@
+#
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://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.
+#
+
+org.gradle.configureondemand=true
+org.gradle.caching=true
+org.gradle.parallel=true
+
+# Declare we support AndroidX
+android.useAndroidX=true
+
+org.gradle.jvmargs=-Xmx4608m -XX:MaxMetaspaceSize=1536m -XX:+HeapDumpOnOutOfMemoryError
+
+kotlin.compiler.execution.strategy=in-process

.github/workflows/code-check.yml

@@ -6,6 +6,8 @@ on:
     branches: [ main ]
   pull_request:
     branches: [ main ]
+  workflow_dispatch:
+    branches: [main]
 
 permissions:
   contents: read
@@ -14,18 +16,22 @@ jobs:
   check:
     name: Check Code
     runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13.0", "3.14"]
+      fail-fast: false
 
     steps:
     - name: Check out from Git
-      uses: actions/checkout@v3
+      uses: actions/checkout@v6
     - name: Get history and tags for SCM versioning to work
       run: |
         git fetch --prune --unshallow
         git fetch --depth=1 origin +refs/tags/*:refs/tags/*
     - name: Set up Python
-      uses: actions/setup-python@v3
+      uses: actions/setup-python@v6
       with:
-        python-version: '3.10'
+        python-version: ${{ matrix.python-version }}
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip

.github/workflows/codeql-analysis.yml

@@ -17,6 +17,8 @@ on:
   pull_request:
     # The branches below must be a subset of the branches above
     branches: [ main ]
+  workflow_dispatch:
+    branches: [main]
   schedule:
     - cron: '39 21 * * 4'
 
@@ -38,7 +40,7 @@ jobs:
 
     steps:
     - name: Checkout repository
-      uses: actions/checkout@v3
+      uses: actions/checkout@v6
 
     # Initializes the CodeQL tools for scanning.
     - name: Initialize CodeQL

.github/workflows/gradle-btbench.yml

@@ -0,0 +1,37 @@
+name: Gradle Android Build & test
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+    paths:
+      - 'extras/android/BtBench/**'
+  workflow_dispatch:
+    branches: [main]
+    paths:
+      - 'extras/android/BtBench/**'
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 40
+
+    steps:
+      - name: Check out from Git
+        uses: actions/checkout@v6
+
+      - name: Set up JDK
+        uses: actions/setup-java@v5
+        with:
+          distribution: 'zulu'
+          java-version: 17
+
+      - name: Setup Gradle
+        uses: gradle/actions/setup-gradle@v3
+
+      - name: Build with Gradle
+        run: cd extras/android/BtBench && ./gradlew build

.github/workflows/python-avatar.yml

@@ -0,0 +1,52 @@
+name: Python Avatar
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+  workflow_dispatch:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Avatar [${{ matrix.shard }}]
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        shard: [
+           1/24,  2/24,  3/24,  4/24,
+           5/24,  6/24,  7/24,  8/24,
+           9/24, 10/24, 11/24, 12/24,
+          13/24, 14/24, 15/24, 16/24,
+          17/24, 18/24, 19/24, 20/24,
+          21/24, 22/24, 23/24, 24/24,
+        ]
+    steps:
+      - uses: actions/checkout@v6
+      - name: Set Up Python 3.11
+        uses: actions/setup-python@v6
+        with:
+          python-version: 3.11
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install .[avatar]
+      - name: Rootcanal
+        run: nohup python -m rootcanal > rootcanal.log &
+      - name: Test
+        run: |
+          avatar --list | grep -Ev '^=' > test-names.txt
+          timeout 5m avatar --test-beds bumble.bumbles --tests $(split test-names.txt -n l/${{ matrix.shard }})
+      - name: Rootcanal Logs
+        if: always()
+        run: cat rootcanal.log
+      - name: Upload Mobly logs
+        if: always()
+        uses: actions/upload-artifact@v6
+        with:
+          name: mobly-logs-${{ strategy.job-index }}
+          path: /tmp/logs/mobly/bumble.bumbles/

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

@@ -6,28 +6,30 @@ on:
     branches: [ main ]
   pull_request:
     branches: [ main ]
+  workflow_dispatch:
+    branches: [main]
 
 permissions:
   contents: read
 
 jobs:
   build:
-
-    runs-on: ubuntu-latest
+    runs-on: ${{ matrix.os }}
     strategy:
       matrix:
-        python-version: ["3.8", "3.9", "3.10"]
+        os: ['ubuntu-latest', 'macos-latest', 'windows-latest']
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
       fail-fast: false
 
     steps:
     - name: Check out from Git
-      uses: actions/checkout@v3
+      uses: actions/checkout@v6
     - name: Get history and tags for SCM versioning to work
       run: |
         git fetch --prune --unshallow
         git fetch --depth=1 origin +refs/tags/*:refs/tags/*
     - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v4
+      uses: actions/setup-python@v6
       with:
         python-version: ${{ matrix.python-version }}
     - name: Install dependencies
@@ -41,3 +43,43 @@ jobs:
       run: |
         inv build
         inv build.mkdocs
+
+  build-rust:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        # Rust runtime doesn't support 3.14 yet.
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+        rust-version: [ "1.80.0", "1.91.0" ]
+      fail-fast: false
+    steps:
+      - name: Check out from Git
+        uses: actions/checkout@v6
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install Python dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install ".[build,test,development,documentation]"
+      - name: Install Rust toolchain
+        uses: actions-rust-lang/setup-rust-toolchain@v1
+        with:
+          components: clippy,rustfmt
+          toolchain: ${{ matrix.rust-version }}
+      - name: Install Rust dependencies
+        run: cargo install cargo-all-features --version 1.11.0  # allows building/testing combinations of features
+      - name: Check License Headers
+        run: cd rust && cargo run --features dev-tools --bin file-header check-all
+      - name: Rust Build
+        run: cd rust && cargo build --all-targets && cargo build-all-features
+      # Lints after build so what clippy needs is already built
+      - name: Rust Lints
+        run: cd rust && cargo fmt --check && cargo clippy --all-targets -- --deny warnings && cargo clippy --all-features --all-targets -- --deny warnings
+      - name: Rust Tests
+        run: cd rust && cargo test-all-features
+      # At some point, hook up publishing the binary. For now, just make sure it builds.
+      # Once we're ready to publish binaries, this should be built with `--release`.
+      - name: Build Bumble CLI
+        run: cd rust && cargo build --features bumble-tools --bin bumble

.github/workflows/python-publish.yml

@@ -14,13 +14,13 @@ jobs:
 
     steps:
     - name: Check out from Git
-      uses: actions/checkout@v3
+      uses: actions/checkout@v6
     - name: Get history and tags for SCM versioning to work
       run: |
         git fetch --prune --unshallow
         git fetch --depth=1 origin +refs/tags/*:refs/tags/*
     - name: Set up Python
-      uses: actions/setup-python@v3
+      uses: actions/setup-python@v6
       with:
         python-version: '3.10'
     - name: Install dependencies
@@ -31,7 +31,7 @@ jobs:
       run: python -m build
     - name: Publish package to PyPI
       if: github.event_name == 'release' && startsWith(github.ref, 'refs/tags')
-      uses: pypa/gh-action-pypi-publish@release/v1
+      uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e  # release/v1.13
       with:
         user: __token__
         password: ${{ secrets.PYPI_API_TOKEN }}

.gitignore

@@ -6,6 +6,17 @@ 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/
+# macOS
+.DS_Store
+._*

.vscode/settings.json

@@ -1,6 +1,7 @@
 {
     "cSpell.words": [
         "Abortable",
+        "aiohttp",
         "altsetting",
         "ansiblue",
         "ansicyan",
@@ -9,10 +10,16 @@
         "ansired",
         "ansiyellow",
         "appendleft",
+        "ascs",
         "ASHA",
         "asyncio",
         "ATRAC",
+        "auracast",
+        "avctp",
         "avdtp",
+        "avrcp",
+        "biginfo",
+        "bigs",
         "bitpool",
         "bitstruct",
         "BSCP",
@@ -21,7 +28,10 @@
         "cccds",
         "cmac",
         "CONNECTIONLESS",
+        "csip",
+        "csis",
         "csrcs",
+        "CVSD",
         "datagram",
         "DATALINK",
         "delayreport",
@@ -29,6 +39,9 @@
         "deregistration",
         "dhkey",
         "diversifier",
+        "ediv",
+        "endianness",
+        "ESCO",
         "Fitbit",
         "GATTLINK",
         "HANDSFREE",
@@ -36,15 +49,24 @@
         "keyup",
         "levelname",
         "libc",
+        "liblc",
         "libusb",
+        "maxs",
         "MITM",
+        "MSBC",
         "NDIS",
+        "netsim",
         "NONBLOCK",
         "NONCONN",
         "OXIMETER",
+        "PDUS",
         "popleft",
+        "PRAND",
+        "prefs",
+        "protobuf",
         "psms",
         "pyee",
+        "Pyodide",
         "pyusb",
         "rfcomm",
         "ROHC",
@@ -52,6 +74,7 @@
         "SEID",
         "seids",
         "SERV",
+        "SIRK",
         "ssrc",
         "strerror",
         "subband",
@@ -61,8 +84,11 @@
         "substates",
         "tobytes",
         "tsep",
+        "UNMUTE",
+        "unmuted",
         "usbmodem",
         "vhci",
+        "wasmtime",
         "websockets",
         "xcursor",
         "ycursor"
@@ -76,5 +102,10 @@
         "."
     ],
     "python.testing.unittestEnabled": false,
-    "python.testing.pytestEnabled": true
+    "python.testing.pytestEnabled": true,
+    "python-envs.defaultEnvManager": "ms-python.python:system",
+    "python-envs.pythonProjects": [],
+    "nrf-connect.applications": [
+        "${workspaceFolder}/extras/zephyr/hci_usb"
+    ]
 }

README.md

@@ -50,7 +50,7 @@ Bumble is easiest to use with a dedicated USB dongle.
 This is because internal Bluetooth interfaces tend to be locked down by the operating system.
 You can use the [usb_probe](/docs/mkdocs/src/apps_and_tools/usb_probe.md) tool (all platforms) or `lsusb` (Linux or macOS) to list the available USB devices on your system.
 
-See the [USB Transport](/docs/mkdocs/src/transports/usb.md) page for details on how to refer to USB devices. Also, if your are on a mac, see [these instructions](docs/mkdocs/src/platforms/macos.md).
+See the [USB Transport](/docs/mkdocs/src/transports/usb.md) page for details on how to refer to USB devices. Also, if you are on a mac, see [these instructions](docs/mkdocs/src/platforms/macos.md).
 
 ## License
 

apps/README.md

@@ -12,9 +12,6 @@ Apps
 ## `show.py`
 Parse a file with HCI packets and print the details of each packet in a human readable form
 
-## `link_relay.py`
-Simple WebSocket relay for virtual RemoteLink instances to communicate with each other through.
-
 ## `hci_bridge.py`
 This app acts as a simple bridge between two HCI transports, with a host on one side and
 a controller on the other. All the HCI packets bridged between the two are printed on the console

apps/ble_rpa_tool.py

@@ -0,0 +1,64 @@
+# 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

@@ -22,53 +22,55 @@
 import asyncio
 import logging
 import os
-import random
 import re
-import humanize
-from typing import Optional, Union
 from collections import OrderedDict
 
 import click
+import humanize
 from prettytable import PrettyTable
-
 from prompt_toolkit import Application
-from prompt_toolkit.history import FileHistory
 from prompt_toolkit.completion import Completer, Completion, NestedCompleter
-from prompt_toolkit.key_binding import KeyBindings
-from prompt_toolkit.formatted_text import ANSI
-from prompt_toolkit.styles import Style
-from prompt_toolkit.filters import Condition
-from prompt_toolkit.widgets import TextArea, Frame
-from prompt_toolkit.widgets.toolbars import FormattedTextToolbar
 from prompt_toolkit.data_structures import Point
+from prompt_toolkit.filters import Condition
+from prompt_toolkit.formatted_text import ANSI
+from prompt_toolkit.history import FileHistory
+from prompt_toolkit.key_binding import KeyBindings
 from prompt_toolkit.layout import (
-    Layout,
-    HSplit,
-    Window,
     CompletionsMenu,
-    Float,
-    FormattedTextControl,
-    FloatContainer,
     ConditionalContainer,
     Dimension,
+    Float,
+    FloatContainer,
+    FormattedTextControl,
+    HSplit,
+    Layout,
+    Window,
 )
+from prompt_toolkit.styles import Style
+from prompt_toolkit.widgets import Frame, TextArea
+from prompt_toolkit.widgets.toolbars import FormattedTextToolbar
 
-from bumble import __version__
 import bumble.core
-from bumble import colors
-from bumble.core import UUID, AdvertisingData, BT_LE_TRANSPORT
-from bumble.device import ConnectionParametersPreferences, Device, Connection, Peer
-from bumble.utils import AsyncRunner
-from bumble.transport import open_transport_or_link
-from bumble.gatt import Characteristic, Service, CharacteristicDeclaration, Descriptor
+from bumble import __version__, colors
+from bumble.core import UUID, AdvertisingData
+from bumble.device import (
+    Connection,
+    ConnectionParametersPreferences,
+    ConnectionPHY,
+    Device,
+    Peer,
+)
+from bumble.gatt import Characteristic, CharacteristicDeclaration, Descriptor, Service
 from bumble.gatt_client import CharacteristicProxy
 from bumble.hci import (
-    HCI_Constant,
     HCI_LE_1M_PHY,
     HCI_LE_2M_PHY,
     HCI_LE_CODED_PHY,
+    Address,
+    HCI_Constant,
 )
-
+from bumble.transport import open_transport
+from bumble.utils import AsyncRunner
 
 # -----------------------------------------------------------------------------
 # Constants
@@ -123,7 +125,8 @@ def parse_phys(phys):
 # Console App
 # -----------------------------------------------------------------------------
 class ConsoleApp:
-    connected_peer: Optional[Peer]
+    connected_peer: Peer | None
+    connection_phy: ConnectionPHY | None
 
     def __init__(self):
         self.known_addresses = set()
@@ -131,6 +134,7 @@ class ConsoleApp:
         self.known_local_attributes = []
         self.device = None
         self.connected_peer = None
+        self.connection_phy = None
         self.top_tab = 'device'
         self.monitor_rssi = False
         self.connection_rssi = None
@@ -283,17 +287,13 @@ class ConsoleApp:
     async def run_async(self, device_config, transport):
         rssi_monitoring_task = asyncio.create_task(self.rssi_monitor_loop())
 
-        async with await open_transport_or_link(transport) as (hci_source, hci_sink):
+        async with await open_transport(transport) as (hci_source, hci_sink):
             if device_config:
                 self.device = Device.from_config_file_with_hci(
                     device_config, hci_source, hci_sink
                 )
             else:
-                random_address = (
-                    f"{random.randint(192,255):02X}"  # address is static random
-                )
-                for random_byte in random.sample(range(255), 5):
-                    random_address += f":{random_byte:02X}"
+                random_address = Address.generate_static_address()
                 self.append_to_log(f"Setting random address: {random_address}")
                 self.device = Device.with_hci(
                     'Bumble', random_address, hci_source, hci_sink
@@ -331,14 +331,14 @@ class ConsoleApp:
             elif self.connected_peer:
                 connection = self.connected_peer.connection
                 connection_parameters = (
-                    f'{connection.parameters.connection_interval}/'
+                    f'{connection.parameters.connection_interval:.2f}/'
                     f'{connection.parameters.peripheral_latency}/'
-                    f'{connection.parameters.supervision_timeout}'
+                    f'{connection.parameters.supervision_timeout:.2f}'
                 )
-                if connection.transport == BT_LE_TRANSPORT:
+                if self.connection_phy is not None:
                     phy_state = (
-                        f' RX={le_phy_name(connection.phy.rx_phy)}/'
-                        f'TX={le_phy_name(connection.phy.tx_phy)}'
+                        f' RX={le_phy_name(self.connection_phy.rx_phy)}/'
+                        f'TX={le_phy_name(self.connection_phy.tx_phy)}'
                     )
                 else:
                     phy_state = ''
@@ -503,21 +503,9 @@ class ConsoleApp:
             self.show_error('not connected')
             return
 
-        # Discover all services, characteristics and descriptors
-        self.append_to_output('discovering services...')
-        await self.connected_peer.discover_services()
-        self.append_to_output(
-            f'found {len(self.connected_peer.services)} services,'
-            ' discovering characteristics...'
-        )
-        await self.connected_peer.discover_characteristics()
-        self.append_to_output('found characteristics, discovering descriptors...')
-        for service in self.connected_peer.services:
-            for characteristic in service.characteristics:
-                await self.connected_peer.discover_descriptors(characteristic)
-        self.append_to_output('discovery completed')
-
-        self.show_remote_services(self.connected_peer.services)
+        self.append_to_output('Service Discovery starting...')
+        await self.connected_peer.discover_all()
+        self.append_to_output('Service Discovery done!')
 
     async def discover_attributes(self):
         if not self.connected_peer:
@@ -531,7 +519,7 @@ class ConsoleApp:
 
         self.show_attributes(attributes)
 
-    def find_remote_characteristic(self, param) -> Optional[CharacteristicProxy]:
+    def find_remote_characteristic(self, param) -> CharacteristicProxy | None:
         if not self.connected_peer:
             return None
         parts = param.split('.')
@@ -553,9 +541,7 @@ class ConsoleApp:
 
         return None
 
-    def find_local_attribute(
-        self, param
-    ) -> Optional[Union[Characteristic, Descriptor]]:
+    def find_local_attribute(self, param) -> Characteristic | Descriptor | None:
         parts = param.split('.')
         if len(parts) == 3:
             service_uuid = UUID(parts[0])
@@ -669,11 +655,12 @@ class ConsoleApp:
         self.append_to_output('connecting...')
 
         try:
-            await self.device.connect(
+            connection = await self.device.connect(
                 params[0],
                 connection_parameters_preferences=connection_parameters_preferences,
                 timeout=DEFAULT_CONNECTION_TIMEOUT,
             )
+            self.connection_phy = await connection.get_phy()
             self.top_tab = 'services'
         except bumble.core.TimeoutError:
             self.show_error('connection timed out')
@@ -777,7 +764,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 +783,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
 
@@ -853,8 +840,8 @@ class ConsoleApp:
 
         phy = await self.connected_peer.connection.get_phy()
         self.append_to_output(
-            f'PHY: RX={HCI_Constant.le_phy_name(phy[0])}, '
-            f'TX={HCI_Constant.le_phy_name(phy[1])}'
+            f'PHY: RX={HCI_Constant.le_phy_name(phy.rx_phy)}, '
+            f'TX={HCI_Constant.le_phy_name(phy.tx_phy)}'
         )
 
     async def do_request_mtu(self, params):
@@ -944,7 +931,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):
@@ -1091,10 +1078,9 @@ class DeviceListener(Device.Listener, Connection.Listener):
             f'{self.app.connected_peer.connection.parameters}'
         )
 
-    def on_connection_phy_update(self):
-        self.app.append_to_output(
-            f'connection phy update: {self.app.connected_peer.connection.phy}'
-        )
+    def on_connection_phy_update(self, phy):
+        self.app.connection_phy = phy
+        self.app.append_to_output(f'connection phy update: {phy}')
 
     def on_connection_att_mtu_update(self):
         self.app.append_to_output(
@@ -1107,9 +1093,7 @@ class DeviceListener(Device.Listener, Connection.Listener):
             if self.app.connected_peer.connection.is_encrypted
             else 'not encrypted'
         )
-        self.app.append_to_output(
-            'connection encryption change: ' f'{encryption_state}'
-        )
+        self.app.append_to_output(f'connection encryption change: {encryption_state}')
 
     def on_connection_data_length_change(self):
         self.app.append_to_output(
@@ -1172,7 +1156,7 @@ class ScanResult:
             name = ''
 
         # Remove any '/P' qualifier suffix from the address string
-        address_str = str(self.address).replace('/P', '')
+        address_str = self.address.to_string(with_type_qualifier=False)
 
         # RSSI bar
         bar_string = rssi_bar(self.rssi)

apps/controller_info.py

@@ -16,120 +16,246 @@
 # Imports
 # -----------------------------------------------------------------------------
 import asyncio
-import os
-import logging
-import click
-from bumble.company_ids import COMPANY_IDENTIFIERS
+import time
 
+import click
+
+import bumble.logging
 from bumble.colors import color
+from bumble.company_ids import COMPANY_IDENTIFIERS
 from bumble.core import name_or_number
 from bumble.hci import (
-    map_null_terminated_utf8_string,
-    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_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_V2_COMMAND,
     HCI_LE_READ_MAXIMUM_DATA_LENGTH_COMMAND,
+    HCI_LE_READ_MINIMUM_SUPPORTED_CONNECTION_INTERVAL_COMMAND,
+    HCI_LE_READ_SUGGESTED_DEFAULT_DATA_LENGTH_COMMAND,
+    HCI_READ_BD_ADDR_COMMAND,
+    HCI_READ_BUFFER_SIZE_COMMAND,
+    HCI_READ_LOCAL_NAME_COMMAND,
+    HCI_Command,
+    HCI_LE_Read_Buffer_Size_Command,
+    HCI_LE_Read_Buffer_Size_V2_Command,
     HCI_LE_Read_Maximum_Data_Length_Command,
-    HCI_LE_READ_NUMBER_OF_SUPPORTED_ADVERTISING_SETS_COMMAND,
-    HCI_LE_Read_Number_Of_Supported_Advertising_Sets_Command,
-    HCI_LE_READ_MAXIMUM_ADVERTISING_DATA_LENGTH_COMMAND,
-    HCI_LE_Read_Maximum_Advertising_Data_Length_Command,
+    HCI_LE_Read_Minimum_Supported_Connection_Interval_Command,
+    HCI_LE_Read_Suggested_Default_Data_Length_Command,
+    HCI_Read_BD_ADDR_Command,
+    HCI_Read_Buffer_Size_Command,
+    HCI_Read_Local_Name_Command,
+    HCI_Read_Local_Supported_Codecs_Command,
+    HCI_Read_Local_Supported_Codecs_V2_Command,
+    HCI_Read_Local_Version_Information_Command,
+    LeFeature,
+    SpecificationVersion,
+    map_null_terminated_utf8_string,
 )
 from bumble.host import Host
-from bumble.transport import open_transport_or_link
+from bumble.transport import open_transport
 
 
 # -----------------------------------------------------------------------------
-def command_succeeded(response):
-    if isinstance(response, HCI_Command_Status_Event):
-        return response.status == HCI_SUCCESS
-    if isinstance(response, HCI_Command_Complete_Event):
-        return response.return_parameters.status == HCI_SUCCESS
-    return False
-
-
-# -----------------------------------------------------------------------------
-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):
-            print()
-            print(
-                color('Classic Address:', 'yellow'), response.return_parameters.bd_addr
-            )
+        response1 = await host.send_sync_command(HCI_Read_BD_ADDR_Command())
+        print()
+        print(
+            color('Public Address:', 'yellow'),
+            response1.bd_addr.to_string(False),
+        )
 
     if host.supports_command(HCI_READ_LOCAL_NAME_COMMAND):
-        response = await host.send_command(HCI_Read_Local_Name_Command())
-        if command_succeeded(response):
-            print()
-            print(
-                color('Local Name:', 'yellow'),
-                map_null_terminated_utf8_string(response.return_parameters.local_name),
-            )
+        response2 = await host.send_sync_command(HCI_Read_Local_Name_Command())
+        print()
+        print(
+            color('Local Name:', 'yellow'),
+            map_null_terminated_utf8_string(response2.local_name),
+        )
 
 
 # -----------------------------------------------------------------------------
-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):
-        response = await host.send_command(
-            HCI_LE_Read_Number_Of_Supported_Advertising_Sets_Command()
-        )
-        if command_succeeded(response):
-            print(
-                color('LE Number Of Supported Advertising Sets:', 'yellow'),
-                response.return_parameters.num_supported_advertising_sets,
-                '\n',
-            )
+    print(
+        color('LE Number Of Supported Advertising Sets:', 'yellow'),
+        host.number_of_supported_advertising_sets,
+        '\n',
+    )
 
-    if host.supports_command(HCI_LE_READ_MAXIMUM_ADVERTISING_DATA_LENGTH_COMMAND):
-        response = await host.send_command(
-            HCI_LE_Read_Maximum_Advertising_Data_Length_Command()
-        )
-        if command_succeeded(response):
-            print(
-                color('LE Maximum Advertising Data Length:', 'yellow'),
-                response.return_parameters.max_advertising_data_length,
-                '\n',
-            )
+    print(
+        color('LE Maximum Advertising Data Length:', 'yellow'),
+        host.maximum_advertising_data_length,
+        '\n',
+    )
 
     if host.supports_command(HCI_LE_READ_MAXIMUM_DATA_LENGTH_COMMAND):
-        response = await host.send_command(HCI_LE_Read_Maximum_Data_Length_Command())
-        if command_succeeded(response):
+        response1 = await host.send_sync_command(
+            HCI_LE_Read_Maximum_Data_Length_Command()
+        )
+        print(
+            color('LE Maximum Data Length:', 'yellow'),
+            (
+                f'tx:{response1.supported_max_tx_octets}/'
+                f'{response1.supported_max_tx_time}, '
+                f'rx:{response1.supported_max_rx_octets}/'
+                f'{response1.supported_max_rx_time}'
+            ),
+        )
+
+    if host.supports_command(HCI_LE_READ_SUGGESTED_DEFAULT_DATA_LENGTH_COMMAND):
+        response2 = await host.send_sync_command(
+            HCI_LE_Read_Suggested_Default_Data_Length_Command()
+        )
+        print(
+            color('LE Suggested Default Data Length:', 'yellow'),
+            f'{response2.suggested_max_tx_octets}/'
+            f'{response2.suggested_max_tx_time}',
+            '\n',
+        )
+
+    if host.supports_command(HCI_LE_READ_MINIMUM_SUPPORTED_CONNECTION_INTERVAL_COMMAND):
+        response3 = await host.send_sync_command(
+            HCI_LE_Read_Minimum_Supported_Connection_Interval_Command()
+        )
+        print(
+            color('LE Minimum Supported Connection Interval:', 'yellow'),
+            f'{response3.minimum_supported_connection_interval * 125} µs',
+        )
+        for group in range(len(response3.group_min)):
             print(
-                color('Maximum Data Length:', 'yellow'),
-                (
-                    f'tx:{response.return_parameters.supported_max_tx_octets}/'
-                    f'{response.return_parameters.supported_max_tx_time}, '
-                    f'rx:{response.return_parameters.supported_max_rx_octets}/'
-                    f'{response.return_parameters.supported_max_rx_time}'
-                ),
+                f'  Group {group}: '
+                f'{response3.group_min[group] * 125} µs to '
+                f'{response3.group_max[group] * 125} µs '
+                'by increments of '
+                f'{response3.group_stride[group] * 125} µs',
                 '\n',
             )
 
     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_flow_control_info(host: Host) -> None:
+    print()
+
+    if host.supports_command(HCI_READ_BUFFER_SIZE_COMMAND):
+        response1 = await host.send_sync_command(HCI_Read_Buffer_Size_Command())
+        print(
+            color('ACL Flow Control:', 'yellow'),
+            f'{response1.hc_total_num_acl_data_packets} '
+            f'packets of size {response1.hc_acl_data_packet_length}',
+        )
+
+    if host.supports_command(HCI_LE_READ_BUFFER_SIZE_V2_COMMAND):
+        response2 = await host.send_sync_command(HCI_LE_Read_Buffer_Size_V2_Command())
+        print(
+            color('LE ACL Flow Control:', 'yellow'),
+            f'{response2.total_num_le_acl_data_packets} '
+            f'packets of size {response2.le_acl_data_packet_length}',
+        )
+        print(
+            color('LE ISO Flow Control:', 'yellow'),
+            f'{response2.total_num_iso_data_packets} '
+            f'packets of size {response2.iso_data_packet_length}',
+        )
+    elif host.supports_command(HCI_LE_READ_BUFFER_SIZE_COMMAND):
+        response3 = await host.send_sync_command(HCI_LE_Read_Buffer_Size_Command())
+        print(
+            color('LE ACL Flow Control:', 'yellow'),
+            f'{response3.total_num_le_acl_data_packets} '
+            f'packets of size {response3.le_acl_data_packet_length}',
+        )
+
+
+# -----------------------------------------------------------------------------
+async def get_codecs_info(host: Host) -> None:
+    print()
+
+    if host.supports_command(HCI_Read_Local_Supported_Codecs_V2_Command.op_code):
+        response1 = await host.send_sync_command(
+            HCI_Read_Local_Supported_Codecs_V2_Command()
+        )
+        print(color('Codecs:', 'yellow'))
+
+        for codec_id, transport in zip(
+            response1.standard_codec_ids,
+            response1.standard_codec_transports,
+        ):
+            print(f'  {codec_id.name} - {transport.name}')
+
+        for vendor_codec_id, vendor_transport in zip(
+            response1.vendor_specific_codec_ids,
+            response1.vendor_specific_codec_transports,
+        ):
+            company = name_or_number(COMPANY_IDENTIFIERS, vendor_codec_id >> 16)
+            print(f'  {company} / {vendor_codec_id & 0xFFFF} - {vendor_transport.name}')
+
+        if not response1.standard_codec_ids:
+            print('  No standard codecs')
+        if not response1.vendor_specific_codec_ids:
+            print('  No Vendor-specific codecs')
+
+    if host.supports_command(HCI_Read_Local_Supported_Codecs_Command.op_code):
+        response2 = await host.send_sync_command(
+            HCI_Read_Local_Supported_Codecs_Command()
+        )
+        print(color('Codecs (BR/EDR):', 'yellow'))
+        for codec_id in response2.standard_codec_ids:
+            print(f'  {codec_id.name}')
+
+        for vendor_codec_id in response2.vendor_specific_codec_ids:
+            company = name_or_number(COMPANY_IDENTIFIERS, vendor_codec_id >> 16)
+            print(f'  {company} / {vendor_codec_id & 0xFFFF}')
+
+        if not response2.standard_codec_ids:
+            print('  No standard codecs')
+        if not response2.vendor_specific_codec_ids:
+            print('  No Vendor-specific codecs')
+
+
+# -----------------------------------------------------------------------------
+async def async_main(
+    latency_probes, latency_probe_interval, latency_probe_command, transport
+):
     print('<<< connecting to HCI...')
-    async with await open_transport_or_link(transport) as (hci_source, hci_sink):
+    async with await open_transport(transport) as (hci_source, hci_sink):
         print('<<< connected')
 
         host = Host(hci_source, hci_sink)
         await host.reset()
 
+        # Measure the latency if requested
+        # (we add an extra probe at the start, that we ignore, just to ensure that
+        # the transport is primed)
+        latencies = []
+        if latency_probes:
+            if latency_probe_command:
+                probe_hci_command = HCI_Command.from_bytes(
+                    bytes.fromhex(latency_probe_command)
+                )
+            else:
+                probe_hci_command = HCI_Read_Local_Version_Information_Command()
+
+            for iteration in range(1 + latency_probes):
+                if latency_probe_interval:
+                    await asyncio.sleep(latency_probe_interval / 1000)
+                start = time.time()
+                await host.send_command(probe_hci_command)
+                if iteration:
+                    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},'
+                ),
+                [f'{latency:.4}' for latency in latencies],
+                '\n',
+            )
+
         # Print version
         print(color('Version:', 'yellow'))
         print(
@@ -138,14 +264,20 @@ async def async_main(transport):
         )
         print(
             color('  HCI Version:   ', 'green'),
-            name_or_number(HCI_VERSION_NAMES, host.local_version.hci_version),
+            SpecificationVersion(host.local_version.hci_version).name,
+        )
+        print(
+            color('  HCI Subversion:', 'green'),
+            f'0x{host.local_version.hci_subversion:04x}',
         )
-        print(color('  HCI Subversion:', 'green'), host.local_version.hci_subversion)
         print(
             color('  LMP Version:   ', 'green'),
-            name_or_number(LMP_VERSION_NAMES, host.local_version.lmp_version),
+            SpecificationVersion(host.local_version.lmp_version).name,
+        )
+        print(
+            color('  LMP Subversion:', 'green'),
+            f'0x{host.local_version.lmp_subversion:04x}',
         )
-        print(color('  LMP Subversion:', 'green'), host.local_version.lmp_subversion)
 
         # Get the Classic info
         await get_classic_info(host)
@@ -153,19 +285,49 @@ async def async_main(transport):
         # Get the LE info
         await get_le_info(host)
 
+        # Print the flow control info
+        await get_flow_control_info(host)
+
+        # Get codec info
+        await get_codecs_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.option(
+    '--latency-probe-interval',
+    metavar='INTERVAL',
+    type=int,
+    help='Interval between latency probes (milliseconds)',
+)
+@click.option(
+    '--latency-probe-command',
+    metavar='COMMAND_HEX',
+    help=(
+        'Probe command (HCI Command packet bytes, in hex. Use 0177FC00 for'
+        ' a loopback test with the HCI remote proxy app)'
+    ),
+)
 @click.argument('transport')
-def main(transport):
-    logging.basicConfig(level=os.environ.get('BUMBLE_LOGLEVEL', 'WARNING').upper())
-    asyncio.run(async_main(transport))
+def main(latency_probes, latency_probe_interval, latency_probe_command, transport):
+    bumble.logging.setup_basic_logging()
+    asyncio.run(
+        async_main(
+            latency_probes, latency_probe_interval, latency_probe_command, transport
+        )
+    )
 
 
 # -----------------------------------------------------------------------------

apps/controller_loopback.py

@@ -0,0 +1,206 @@
+# 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 time
+
+import click
+
+import bumble.logging
+from bumble.colors import color
+from bumble.hci import (
+    HCI_READ_LOOPBACK_MODE_COMMAND,
+    HCI_WRITE_LOOPBACK_MODE_COMMAND,
+    HCI_Read_Loopback_Mode_Command,
+    HCI_Write_Loopback_Mode_Command,
+    LoopbackMode,
+)
+from bumble.host import Host
+from bumble.transport import open_transport
+
+
+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: int | None = 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) -> None:
+        """Run a loopback throughput test"""
+        print(color('>>> Connecting to HCI...', 'green'))
+        async with await open_transport(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
+
+            packet_queue = (
+                host.acl_packet_queue
+                if host.acl_packet_queue
+                else host.le_acl_packet_queue
+            )
+            if packet_queue is None:
+                print(color('!!! No packet queue', 'red'))
+                return
+            max_packet_size = 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_sync_command(
+                HCI_Write_Loopback_Mode_Command(loopback_mode=LoopbackMode.LOCAL),
+            )
+
+            print(color('### Checking loopback mode', 'blue'))
+            response = await host.send_sync_command(HCI_Read_Loopback_Mode_Command())
+            if response.loopback_mode != loopback_mode:
+                print(color('!!! Loopback mode mismatch', 'red'))
+                return
+
+            await self.connection_event.wait()
+            assert self.connection_handle is not None
+            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):
+    bumble.logging.setup_basic_logging()
+    loopback = Loopback(packet_size, packet_count, transport)
+    asyncio.run(loopback.run())
+
+
+# -----------------------------------------------------------------------------
+if __name__ == '__main__':
+    main()

apps/controllers.py

@@ -15,14 +15,13 @@
 # -----------------------------------------------------------------------------
 # Imports
 # -----------------------------------------------------------------------------
-import logging
 import asyncio
 import sys
-import os
 
+import bumble.logging
 from bumble.controller import Controller
 from bumble.link import LocalLink
-from bumble.transport import open_transport_or_link
+from bumble.transport import open_transport
 
 
 # -----------------------------------------------------------------------------
@@ -42,7 +41,7 @@ async def async_main():
     transports = []
     controllers = []
     for index, transport_name in enumerate(sys.argv[1:]):
-        transport = await open_transport_or_link(transport_name)
+        transport = await open_transport(transport_name)
         transports.append(transport)
         controller = Controller(
             f'C{index}',
@@ -62,7 +61,7 @@ async def async_main():
 
 # -----------------------------------------------------------------------------
 def main():
-    logging.basicConfig(level=os.environ.get('BUMBLE_LOGLEVEL', 'INFO').upper())
+    bumble.logging.setup_basic_logging()
     asyncio.run(async_main())
 
 

apps/device_info.py

@@ -0,0 +1,274 @@
+# Copyright 2021-2022 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# -----------------------------------------------------------------------------
+# Imports
+# -----------------------------------------------------------------------------
+import asyncio
+from collections.abc import Callable, Iterable
+
+import click
+
+import bumble.logging
+from bumble.colors import color
+from bumble.core import ProtocolError
+from bumble.device import Device, Peer
+from bumble.gatt import Service
+from bumble.profiles.battery_service import BatteryServiceProxy
+from bumble.profiles.device_information_service import DeviceInformationServiceProxy
+from bumble.profiles.gap import GenericAccessServiceProxy
+from bumble.profiles.pacs import PublishedAudioCapabilitiesServiceProxy
+from bumble.profiles.tmap import TelephonyAndMediaAudioServiceProxy
+from bumble.profiles.vcs import VolumeControlServiceProxy
+from bumble.transport import open_transport
+
+
+# -----------------------------------------------------------------------------
+async def try_show(function: Callable, *args, **kwargs) -> None:
+    try:
+        await function(*args, **kwargs)
+    except ProtocolError as error:
+        print(color('ERROR:', 'red'), error)
+
+
+# -----------------------------------------------------------------------------
+def show_services(services: Iterable[Service]) -> None:
+    for service in services:
+        print(color(str(service), 'cyan'))
+
+        for characteristic in service.characteristics:
+            print(color('  ' + str(characteristic), 'magenta'))
+
+
+# -----------------------------------------------------------------------------
+async def show_gap_information(
+    gap_service: GenericAccessServiceProxy,
+):
+    print(color('### Generic Access Profile', 'yellow'))
+
+    if gap_service.device_name:
+        print(
+            color(' Device Name:', 'green'),
+            await gap_service.device_name.read_value(),
+        )
+
+    if gap_service.appearance:
+        print(
+            color(' Appearance: ', 'green'),
+            await gap_service.appearance.read_value(),
+        )
+
+    print()
+
+
+# -----------------------------------------------------------------------------
+async def show_device_information(
+    device_information_service: DeviceInformationServiceProxy,
+):
+    print(color('### Device Information', 'yellow'))
+
+    if device_information_service.manufacturer_name:
+        print(
+            color('  Manufacturer Name:', 'green'),
+            await device_information_service.manufacturer_name.read_value(),
+        )
+
+    if device_information_service.model_number:
+        print(
+            color('  Model Number:     ', 'green'),
+            await device_information_service.model_number.read_value(),
+        )
+
+    if device_information_service.serial_number:
+        print(
+            color('  Serial Number:    ', 'green'),
+            await device_information_service.serial_number.read_value(),
+        )
+
+    if device_information_service.firmware_revision:
+        print(
+            color('  Firmware Revision:', 'green'),
+            await device_information_service.firmware_revision.read_value(),
+        )
+
+    print()
+
+
+# -----------------------------------------------------------------------------
+async def show_battery_level(
+    battery_service: BatteryServiceProxy,
+):
+    print(color('### Battery Information', 'yellow'))
+
+    if battery_service.battery_level:
+        print(
+            color('  Battery Level:', 'green'),
+            await battery_service.battery_level.read_value(),
+        )
+
+    print()
+
+
+# -----------------------------------------------------------------------------
+async def show_tmas(
+    tmas: TelephonyAndMediaAudioServiceProxy,
+):
+    print(color('### Telephony And Media Audio Service', 'yellow'))
+
+    if tmas.role:
+        role = await tmas.role.read_value()
+        print(color('  Role:', 'green'), role)
+
+    print()
+
+
+# -----------------------------------------------------------------------------
+async def show_pacs(pacs: PublishedAudioCapabilitiesServiceProxy) -> None:
+    print(color('### Published Audio Capabilities Service', 'yellow'))
+
+    contexts = await pacs.available_audio_contexts.read_value()
+    print(color('  Available Audio Contexts:', 'green'), contexts)
+
+    contexts = await pacs.supported_audio_contexts.read_value()
+    print(color('  Supported Audio Contexts:', 'green'), contexts)
+
+    if pacs.sink_pac:
+        pac = await pacs.sink_pac.read_value()
+        print(color('  Sink PAC:                ', 'green'), pac)
+
+    if pacs.sink_audio_locations:
+        audio_locations = await pacs.sink_audio_locations.read_value()
+        print(color('  Sink Audio Locations:    ', 'green'), audio_locations)
+
+    if pacs.source_pac:
+        pac = await pacs.source_pac.read_value()
+        print(color('  Source PAC:              ', 'green'), pac)
+
+    if pacs.source_audio_locations:
+        audio_locations = await pacs.source_audio_locations.read_value()
+        print(color('  Source Audio Locations:  ', 'green'), audio_locations)
+
+    print()
+
+
+# -----------------------------------------------------------------------------
+async def show_vcs(vcs: VolumeControlServiceProxy) -> None:
+    print(color('### Volume Control Service', 'yellow'))
+
+    volume_state = await vcs.volume_state.read_value()
+    print(color('  Volume State:', 'green'), volume_state)
+
+    volume_flags = await vcs.volume_flags.read_value()
+    print(color('  Volume Flags:', 'green'), volume_flags)
+
+
+# -----------------------------------------------------------------------------
+async def show_device_info(peer, done: asyncio.Future | None) -> None:
+    try:
+        # Discover all services
+        print(color('### Discovering Services and Characteristics', 'magenta'))
+        await peer.discover_services()
+        for service in peer.services:
+            await service.discover_characteristics()
+
+        print(color('=== Services ===', 'yellow'))
+        show_services(peer.services)
+        print()
+
+        if gap_service := peer.create_service_proxy(GenericAccessServiceProxy):
+            await try_show(show_gap_information, gap_service)
+
+        if device_information_service := peer.create_service_proxy(
+            DeviceInformationServiceProxy
+        ):
+            await try_show(show_device_information, device_information_service)
+
+        if battery_service := peer.create_service_proxy(BatteryServiceProxy):
+            await try_show(show_battery_level, battery_service)
+
+        if tmas := peer.create_service_proxy(TelephonyAndMediaAudioServiceProxy):
+            await try_show(show_tmas, tmas)
+
+        if pacs := peer.create_service_proxy(PublishedAudioCapabilitiesServiceProxy):
+            await try_show(show_pacs, pacs)
+
+        if vcs := peer.create_service_proxy(VolumeControlServiceProxy):
+            await try_show(show_vcs, vcs)
+
+        if done is not None:
+            done.set_result(None)
+    except asyncio.CancelledError:
+        print(color('!!! Operation canceled', 'red'))
+
+
+# -----------------------------------------------------------------------------
+async def async_main(device_config, encrypt, transport, address_or_name):
+    async with await open_transport(transport) as (hci_source, hci_sink):
+        # Create a device
+        if device_config:
+            device = Device.from_config_file_with_hci(
+                device_config, hci_source, hci_sink
+            )
+        else:
+            device = Device.with_hci(
+                'Bumble', 'F0:F1:F2:F3:F4:F5', hci_source, hci_sink
+            )
+        await device.power_on()
+
+        if address_or_name:
+            # Connect to the target peer
+            print(color('>>> Connecting...', 'green'))
+            connection = await device.connect(address_or_name)
+            print(color('>>> Connected', 'green'))
+
+            # Encrypt the connection if required
+            if encrypt:
+                print(color('+++ Encrypting connection...', 'blue'))
+                await connection.encrypt()
+                print(color('+++ Encryption established', 'blue'))
+
+            await show_device_info(Peer(connection), None)
+        else:
+            # Wait for a connection
+            done = asyncio.get_running_loop().create_future()
+            device.on(
+                'connection',
+                lambda connection: asyncio.create_task(
+                    show_device_info(Peer(connection), done)
+                ),
+            )
+            await device.start_advertising(auto_restart=True)
+
+            print(color('### Waiting for connection...', 'blue'))
+            await done
+
+
+# -----------------------------------------------------------------------------
+@click.command()
+@click.option('--device-config', help='Device configuration', type=click.Path())
+@click.option('--encrypt', help='Encrypt the connection', is_flag=True, default=False)
+@click.argument('transport')
+@click.argument('address-or-name', required=False)
+def main(device_config, encrypt, transport, address_or_name):
+    """
+    Dump the GATT database on a remote device. If ADDRESS_OR_NAME is not specified,
+    wait for an incoming connection.
+    """
+    bumble.logging.setup_basic_logging()
+    asyncio.run(async_main(device_config, encrypt, transport, address_or_name))
+
+
+# -----------------------------------------------------------------------------
+if __name__ == '__main__':
+    main()

apps/gatt_dump.py

@@ -16,15 +16,15 @@
 # Imports
 # -----------------------------------------------------------------------------
 import asyncio
-import os
-import logging
+
 import click
 
 import bumble.core
+import bumble.logging
 from bumble.colors import color
 from bumble.device import Device, Peer
 from bumble.gatt import show_services
-from bumble.transport import open_transport_or_link
+from bumble.transport import open_transport
 
 
 # -----------------------------------------------------------------------------
@@ -60,8 +60,7 @@ async def dump_gatt_db(peer, done):
 
 # -----------------------------------------------------------------------------
 async def async_main(device_config, encrypt, transport, address_or_name):
-    async with await open_transport_or_link(transport) as (hci_source, hci_sink):
-
+    async with await open_transport(transport) as (hci_source, hci_sink):
         # Create a device
         if device_config:
             device = Device.from_config_file_with_hci(
@@ -75,11 +74,15 @@ async def async_main(device_config, encrypt, transport, address_or_name):
 
         if address_or_name:
             # Connect to the target peer
+            print(color('>>> Connecting...', 'green'))
             connection = await device.connect(address_or_name)
+            print(color('>>> Connected', 'green'))
 
             # Encrypt the connection if required
             if encrypt:
+                print(color('+++ Encrypting connection...', 'blue'))
                 await connection.encrypt()
+                print(color('+++ Encryption established', 'blue'))
 
             await dump_gatt_db(Peer(connection), None)
         else:
@@ -108,7 +111,7 @@ def main(device_config, encrypt, transport, address_or_name):
     Dump the GATT database on a remote device. If ADDRESS_OR_NAME is not specified,
     wait for an incoming connection.
     """
-    logging.basicConfig(level=os.environ.get('BUMBLE_LOGLEVEL', 'INFO').upper())
+    bumble.logging.setup_basic_logging()
     asyncio.run(async_main(device_config, encrypt, transport, address_or_name))
 
 

apps/gg_bridge.py

@@ -16,19 +16,19 @@
 # Imports
 # -----------------------------------------------------------------------------
 import asyncio
-import os
 import struct
-import logging
+
 import click
 
+import bumble.logging
+from bumble import l2cap
 from bumble.colors import color
-from bumble.device import Device, Peer
 from bumble.core import AdvertisingData
-from bumble.gatt import Service, Characteristic, CharacteristicValue
-from bumble.utils import AsyncRunner
-from bumble.transport import open_transport_or_link
+from bumble.device import Device, Peer
+from bumble.gatt import Characteristic, CharacteristicValue, Service
 from bumble.hci import HCI_Constant
-
+from bumble.transport import open_transport
+from bumble.utils import AsyncRunner
 
 # -----------------------------------------------------------------------------
 # Constants
@@ -204,7 +204,7 @@ class GattlinkHubBridge(GattlinkL2capEndpoint, Device.Listener):
 
 # -----------------------------------------------------------------------------
 class GattlinkNodeBridge(GattlinkL2capEndpoint, Device.Listener):
-    def __init__(self, device):
+    def __init__(self, device: Device):
         super().__init__()
         self.device = device
         self.peer = None
@@ -218,7 +218,12 @@ class GattlinkNodeBridge(GattlinkL2capEndpoint, Device.Listener):
 
         # Listen for incoming L2CAP CoC connections
         psm = 0xFB
-        device.register_l2cap_channel_server(0xFB, self.on_coc)
+        device.create_l2cap_server(
+            spec=l2cap.LeCreditBasedChannelSpec(
+                psm=0xFB,
+            ),
+            handler=self.on_coc,
+        )
         print(f'### Listening for CoC connection on PSM {psm}')
 
         # Setup the Gattlink service
@@ -228,7 +233,7 @@ class GattlinkNodeBridge(GattlinkL2capEndpoint, Device.Listener):
             Characteristic.WRITEABLE,
             CharacteristicValue(write=self.on_rx_write),
         )
-        self.tx_characteristic = Characteristic(
+        self.tx_characteristic: Characteristic[bytes] = Characteristic(
             GG_GATTLINK_TX_CHARACTERISTIC_UUID,
             Characteristic.Properties.NOTIFY,
             Characteristic.READABLE,
@@ -319,7 +324,7 @@ async def run(
     receive_port,
 ):
     print('<<< connecting to HCI...')
-    async with await open_transport_or_link(hci_transport) as (hci_source, hci_sink):
+    async with await open_transport(hci_transport) as (hci_source, hci_sink):
         print('<<< connected')
 
         # Instantiate a bridge object
@@ -377,6 +382,7 @@ def main(
     receive_host,
     receive_port,
 ):
+    bumble.logging.setup_basic_logging('WARNING')
     asyncio.run(
         run(
             hci_transport,
@@ -391,6 +397,5 @@ def main(
 
 
 # -----------------------------------------------------------------------------
-logging.basicConfig(level=os.environ.get('BUMBLE_LOGLEVEL', 'WARNING').upper())
 if __name__ == '__main__':
     main()

apps/hci_bridge.py

@@ -12,14 +12,15 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+import asyncio
+
 # -----------------------------------------------------------------------------
 # Imports
 # -----------------------------------------------------------------------------
 import logging
-import asyncio
-import os
 import sys
 
+import bumble.logging
 from bumble import hci, transport
 from bumble.bridge import HCI_Bridge
 
@@ -46,14 +47,14 @@ async def async_main():
         return
 
     print('>>> connecting to HCI...')
-    async with await transport.open_transport_or_link(sys.argv[1]) as (
+    async with await transport.open_transport(sys.argv[1]) as (
         hci_host_source,
         hci_host_sink,
     ):
         print('>>> connected')
 
         print('>>> connecting to HCI...')
-        async with await transport.open_transport_or_link(sys.argv[2]) as (
+        async with await transport.open_transport(sys.argv[2]) as (
             hci_controller_source,
             hci_controller_sink,
         ):
@@ -83,7 +84,7 @@ async def async_main():
                         return_parameters=bytes([hci.HCI_SUCCESS]),
                     )
                     # Return a packet with 'respond to sender' set to True
-                    return (response.to_bytes(), True)
+                    return (bytes(response), True)
 
                 return None
 
@@ -100,7 +101,7 @@ async def async_main():
 
 # -----------------------------------------------------------------------------
 def main():
-    logging.basicConfig(level=os.environ.get('BUMBLE_LOGLEVEL', 'INFO').upper())
+    bumble.logging.setup_basic_logging()
     asyncio.run(async_main())
 
 

apps/l2cap_bridge.py

@@ -16,15 +16,16 @@
 # Imports
 # -----------------------------------------------------------------------------
 import asyncio
-import logging
-import os
+
 import click
 
+import bumble.logging
+from bumble import l2cap
 from bumble.colors import color
-from bumble.transport import open_transport_or_link
 from bumble.device import Device
-from bumble.utils import FlowControlAsyncPipe
 from bumble.hci import HCI_Constant
+from bumble.transport import open_transport
+from bumble.utils import FlowControlAsyncPipe
 
 
 # -----------------------------------------------------------------------------
@@ -47,16 +48,17 @@ class ServerBridge:
         self.tcp_host = tcp_host
         self.tcp_port = tcp_port
 
-    async def start(self, device):
-        # Listen for incoming L2CAP CoC connections
-        device.register_l2cap_channel_server(
-            psm=self.psm,
-            server=self.on_coc,
-            max_credits=self.max_credits,
-            mtu=self.mtu,
-            mps=self.mps,
+    async def start(self, device: Device) -> None:
+        # 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_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
@@ -105,7 +107,7 @@ class ServerBridge:
                             asyncio.create_task(self.pipe.l2cap_channel.disconnect())
 
                     def data_received(self, data):
-                        print(f'<<< Received on TCP: {len(data)}')
+                        print(color(f'<<< [TCP DATA]: {len(data)} bytes', 'blue'))
                         self.pipe.l2cap_channel.write(data)
 
                 try:
@@ -123,11 +125,12 @@ class ServerBridge:
                     await self.l2cap_channel.disconnect()
 
             def on_l2cap_close(self):
+                print(color('*** L2CAP channel closed', 'red'))
                 self.l2cap_channel = None
                 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'))
@@ -182,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)
 
@@ -194,11 +197,13 @@ class ClientBridge:
             # Connect a new L2CAP channel
             print(color(f'>>> Opening L2CAP channel on PSM = {self.psm}', 'yellow'))
             try:
-                l2cap_channel = await connection.open_l2cap_channel(
-                    psm=self.psm,
-                    max_credits=self.max_credits,
-                    mtu=self.mtu,
-                    mps=self.mps,
+                l2cap_channel = await connection.create_l2cap_channel(
+                    spec=l2cap.LeCreditBasedChannelSpec(
+                        psm=self.psm,
+                        max_credits=self.max_credits,
+                        mtu=self.mtu,
+                        mps=self.mps,
+                    )
                 )
                 print(color('*** L2CAP channel:', 'cyan'), l2cap_channel)
             except Exception as error:
@@ -206,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
@@ -253,7 +258,7 @@ class ClientBridge:
 # -----------------------------------------------------------------------------
 async def run(device_config, hci_transport, bridge):
     print('<<< connecting to HCI...')
-    async with await open_transport_or_link(hci_transport) as (hci_source, hci_sink):
+    async with await open_transport(hci_transport) as (hci_source, hci_sink):
         print('<<< connected')
 
         device = Device.from_config_file_with_hci(device_config, hci_source, hci_sink)
@@ -271,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(
@@ -295,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
 
 
 # -----------------------------------------------------------------------------
@@ -345,6 +356,6 @@ def client(context, bluetooth_address, tcp_host, tcp_port):
 
 
 # -----------------------------------------------------------------------------
-logging.basicConfig(level=os.environ.get('BUMBLE_LOGLEVEL', 'WARNING').upper())
 if __name__ == '__main__':
+    bumble.logging.setup_basic_logging('WARNING')
     cli(obj={})  # pylint: disable=no-value-for-parameter

apps/lea_unicast/app.py

@@ -0,0 +1,453 @@
+# 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 functools
+import json
+import logging
+import pathlib
+import wave
+import weakref
+from importlib import resources
+
+try:
+    import lc3  # type: ignore  # pylint: disable=E0401
+except ImportError as e:
+    raise ImportError("Try `python -m pip install \".[lc3]\"`.") from e
+
+import aiohttp.web
+import click
+
+import bumble
+import bumble.logging
+from bumble import data_types, utils
+from bumble.colors import color
+from bumble.core import AdvertisingData
+from bumble.device import AdvertisingParameters, CisLink, Device, DeviceConfiguration
+from bumble.hci import Address, CodecID, CodingFormat, HCI_IsoDataPacket
+from bumble.profiles import ascs, bap, pacs
+from bumble.transport import open_transport
+
+# -----------------------------------------------------------------------------
+# Logging
+# -----------------------------------------------------------------------------
+logger = logging.getLogger(__name__)
+
+# -----------------------------------------------------------------------------
+# Constants
+# -----------------------------------------------------------------------------
+DEFAULT_UI_PORT = 7654
+DEFAULT_PCM_BYTES_PER_SAMPLE = 2
+
+
+def _sink_pac_record() -> pacs.PacRecord:
+    return pacs.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() -> pacs.PacRecord:
+    return pacs.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,
+        ),
+    )
+
+
+decoder: lc3.Decoder | None = None
+encoding_config: bap.CodecSpecificConfiguration | None = None
+
+
+async def lc3_source_task(
+    filename: str,
+    sdu_length: int,
+    frame_duration_us: int,
+    device: Device,
+    cis_link: CisLink,
+) -> None:
+    logger.info(
+        "lc3_source_task filename=%s, sdu_length=%d, frame_duration=%.1f",
+        filename,
+        sdu_length,
+        frame_duration_us / 1000,
+    )
+    with wave.open(filename, 'rb') as wav:
+        bits_per_sample = wav.getsampwidth() * 8
+
+        encoder: lc3.Encoder | None = None
+
+        while True:
+            next_round = datetime.datetime.now() + datetime.timedelta(
+                microseconds=frame_duration_us
+            )
+            if not encoder:
+                if (
+                    encoding_config
+                    and (frame_duration := encoding_config.frame_duration)
+                    and (sampling_frequency := encoding_config.sampling_frequency)
+                    and (
+                        audio_channel_allocation := encoding_config.audio_channel_allocation
+                    )
+                ):
+                    logger.info("Use %s", encoding_config)
+                    encoder = lc3.Encoder(
+                        frame_duration_us=frame_duration.us,
+                        sample_rate_hz=sampling_frequency.hz,
+                        num_channels=audio_channel_allocation.channel_count,
+                        input_sample_rate_hz=wav.getframerate(),
+                    )
+            else:
+                sdu = encoder.encode(
+                    pcm=wav.readframes(encoder.get_frame_samples()),
+                    num_bytes=sdu_length,
+                    bit_depth=bits_per_sample,
+                )
+                cis_link.write(sdu)
+
+            sleep_time = next_round - datetime.datetime.now()
+            await asyncio.sleep(sleep_time.total_seconds() * 0.9)
+
+
+# -----------------------------------------------------------------------------
+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: str | None,
+        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'),
+                    identity_address_type=Address.RANDOM_DEVICE_ADDRESS,
+                    eatt_enabled=True,
+                )
+
+            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(
+                pacs.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_service = ascs.AudioStreamControlService(
+                self.device, sink_ase_id=[1], source_ase_id=[2]
+            )
+            self.device.add_service(ascs_service)
+
+            advertising_data = bytes(
+                AdvertisingData(
+                    [
+                        data_types.CompleteLocalName(device_config.name),
+                        data_types.Flags(
+                            AdvertisingData.Flags.LE_GENERAL_DISCOVERABLE_MODE
+                            | AdvertisingData.Flags.BR_EDR_NOT_SUPPORTED
+                        ),
+                        data_types.IncompleteListOf16BitServiceUUIDs(
+                            [pacs.PublishedAudioCapabilitiesService.UUID]
+                        ),
+                    ]
+                )
+            ) + bytes(bap.UnicastServerAdvertisingData())
+
+            def on_pdu(pdu: HCI_IsoDataPacket, ase: ascs.AseStateMachine):
+                codec_config = ase.codec_specific_configuration
+                if (
+                    not isinstance(codec_config, bap.CodecSpecificConfiguration)
+                    or codec_config.frame_duration is None
+                    or codec_config.audio_channel_allocation is None
+                    or decoder is None
+                    or not pdu.iso_sdu_fragment
+                ):
+                    return
+                pcm = decoder.decode(
+                    pdu.iso_sdu_fragment, bit_depth=DEFAULT_PCM_BYTES_PER_SAMPLE * 8
+                )
+                utils.cancel_on_event(
+                    self.device, 'disconnection', self.ui_server.send_audio(pcm)
+                )
+
+            def on_ase_state_change(ase: ascs.AseStateMachine) -> None:
+                codec_config = ase.codec_specific_configuration
+                if ase.state == ascs.AseStateMachine.State.STREAMING:
+                    if ase.role == ascs.AudioRole.SOURCE:
+                        if (
+                            not isinstance(codec_config, bap.CodecSpecificConfiguration)
+                            or ase.cis_link is None
+                            or codec_config.octets_per_codec_frame is None
+                            or codec_config.frame_duration is None
+                            or codec_config.codec_frames_per_sdu is None
+                        ):
+                            return
+                        utils.cancel_on_event(
+                            ase.cis_link,
+                            '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_link=ase.cis_link,
+                            ),
+                        )
+                    else:
+                        if not ase.cis_link:
+                            return
+                        ase.cis_link.sink = functools.partial(on_pdu, ase=ase)
+                elif ase.state == ascs.AseStateMachine.State.CODEC_CONFIGURED:
+                    if (
+                        not isinstance(codec_config, bap.CodecSpecificConfiguration)
+                        or codec_config.sampling_frequency is None
+                        or codec_config.frame_duration is None
+                        or codec_config.audio_channel_allocation is None
+                    ):
+                        return
+                    if ase.role == ascs.AudioRole.SOURCE:
+                        global encoding_config
+                        encoding_config = codec_config
+                    else:
+                        global decoder
+                        decoder = lc3.Decoder(
+                            frame_duration_us=codec_config.frame_duration.us,
+                            sample_rate_hz=codec_config.sampling_frequency.hz,
+                            num_channels=codec_config.audio_channel_allocation.channel_count,
+                        )
+
+            for ase in ascs_service.ase_state_machines.values():
+                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():
+    bumble.logging.setup_basic_logging()
+    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/link_relay/link_relay.py

@@ -1,289 +0,0 @@
-# Copyright 2021-2022 Google LLC
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#      https://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-
-# ----------------------------------------------------------------------------
-# Imports
-# ----------------------------------------------------------------------------
-import sys
-import logging
-import json
-import asyncio
-import argparse
-import uuid
-import os
-from urllib.parse import urlparse
-import websockets
-
-from bumble.colors import color
-
-# -----------------------------------------------------------------------------
-# Logging
-# -----------------------------------------------------------------------------
-logger = logging.getLogger(__name__)
-
-
-# ----------------------------------------------------------------------------
-# Constants
-# ----------------------------------------------------------------------------
-DEFAULT_RELAY_PORT = 10723
-
-
-# ----------------------------------------------------------------------------
-# Utils
-# ----------------------------------------------------------------------------
-def error_to_json(error):
-    return json.dumps({'error': error})
-
-
-def error_to_result(error):
-    return f'result:{error_to_json(error)}'
-
-
-async def broadcast_message(message, connections):
-    # Send to all the connections
-    tasks = [connection.send_message(message) for connection in connections]
-    if tasks:
-        await asyncio.gather(*tasks)
-
-
-# ----------------------------------------------------------------------------
-# Connection class
-# ----------------------------------------------------------------------------
-class Connection:
-    """
-    A Connection represents a client connected to the relay over a websocket
-    """
-
-    def __init__(self, room, websocket):
-        self.room = room
-        self.websocket = websocket
-        self.address = str(uuid.uuid4())
-
-    async def send_message(self, message):
-        try:
-            logger.debug(color(f'->{self.address}: {message}', 'yellow'))
-            return await self.websocket.send(message)
-        except websockets.exceptions.WebSocketException as error:
-            logger.info(f'! client "{self}" disconnected: {error}')
-            await self.cleanup()
-
-    async def send_error(self, error):
-        return await self.send_message(f'result:{error_to_json(error)}')
-
-    async def receive_message(self):
-        try:
-            message = await self.websocket.recv()
-            logger.debug(color(f'<-{self.address}: {message}', 'blue'))
-            return message
-        except websockets.exceptions.WebSocketException as error:
-            logger.info(color(f'! client "{self}" disconnected: {error}', 'red'))
-            await self.cleanup()
-
-    async def cleanup(self):
-        if self.room:
-            await self.room.remove_connection(self)
-
-    def set_address(self, address):
-        logger.info(f'Connection address changed: {self.address} -> {address}')
-        self.address = address
-
-    def __str__(self):
-        return (
-            f'Connection(address="{self.address}", '
-            f'client={self.websocket.remote_address[0]}:'
-            f'{self.websocket.remote_address[1]})'
-        )
-
-
-# ----------------------------------------------------------------------------
-# Room class
-# ----------------------------------------------------------------------------
-class Room:
-    """
-    A Room is a collection of bridged connections
-    """
-
-    def __init__(self, relay, name):
-        self.relay = relay
-        self.name = name
-        self.observers = []
-        self.connections = []
-
-    async def add_connection(self, connection):
-        logger.info(f'New participant in {self.name}: {connection}')
-        self.connections.append(connection)
-        await self.broadcast_message(connection, f'joined:{connection.address}')
-
-    async def remove_connection(self, connection):
-        if connection in self.connections:
-            self.connections.remove(connection)
-            await self.broadcast_message(connection, f'left:{connection.address}')
-
-    def find_connections_by_address(self, address):
-        return [c for c in self.connections if c.address == address]
-
-    async def bridge_connection(self, connection):
-        while True:
-            # Wait for a message
-            message = await connection.receive_message()
-
-            # Skip empty messages
-            if message is None:
-                return
-
-            # Parse the message to decide how to handle it
-            if message.startswith('@'):
-                # This is a targeted message
-                await self.on_targeted_message(connection, message)
-            elif message.startswith('/'):
-                # This is an RPC request
-                await self.on_rpc_request(connection, message)
-            else:
-                await connection.send_message(
-                    f'result:{error_to_json("error: invalid message")}'
-                )
-
-    async def broadcast_message(self, sender, message):
-        '''
-        Send to all connections in the room except back to the sender
-        '''
-        await broadcast_message(message, [c for c in self.connections if c != sender])
-
-    async def on_rpc_request(self, connection, message):
-        command, *params = message.split(' ', 1)
-        if handler := getattr(
-            self, f'on_{command[1:].lower().replace("-","_")}_command', None
-        ):
-            try:
-                result = await handler(connection, params)
-            except Exception as error:
-                result = error_to_result(error)
-        else:
-            result = error_to_result('unknown command')
-
-        await connection.send_message(result or 'result:{}')
-
-    async def on_targeted_message(self, connection, message):
-        target, *payload = message.split(' ', 1)
-        if not payload:
-            return error_to_json('missing arguments')
-        payload = payload[0]
-        target = target[1:]
-
-        # Determine what targets to send to
-        if target == '*':
-            # Send to all connections in the room except the connection from which the
-            # message was received
-            connections = [c for c in self.connections if c != connection]
-        else:
-            connections = self.find_connections_by_address(target)
-            if not connections:
-                # Unicast with no recipient, let the sender know
-                await connection.send_message(f'unreachable:{target}')
-
-        # Send to targets
-        await broadcast_message(f'message:{connection.address}/{payload}', connections)
-
-    async def on_set_address_command(self, connection, params):
-        if not params:
-            return error_to_result('missing address')
-
-        current_address = connection.address
-        new_address = params[0]
-        connection.set_address(new_address)
-        await self.broadcast_message(
-            connection, f'address-changed:from={current_address},to={new_address}'
-        )
-
-
-# ----------------------------------------------------------------------------
-class Relay:
-    """
-    A relay accepts connections with the following url: ws://<hostname>/<room>.
-    Participants in a room can communicate with each other
-    """
-
-    def __init__(self, port):
-        self.port = port
-        self.rooms = {}
-        self.observers = []
-
-    def start(self):
-        logger.info(f'Starting Relay on port {self.port}')
-
-        # pylint: disable-next=no-member
-        return websockets.serve(self.serve, '0.0.0.0', self.port, ping_interval=None)
-
-    async def serve_as_controller(self, connection):
-        pass
-
-    async def serve(self, websocket, path):
-        logger.debug(f'New connection with path {path}')
-
-        # Parse the path
-        parsed = urlparse(path)
-
-        # Check if this is a controller client
-        if parsed.path == '/':
-            return await self.serve_as_controller(Connection('', websocket))
-
-        # Find or create a room for this connection
-        room_name = parsed.path[1:].split('/')[0]
-        if room_name not in self.rooms:
-            self.rooms[room_name] = Room(self, room_name)
-        room = self.rooms[room_name]
-
-        # Add the connection to the room
-        connection = Connection(room, websocket)
-        await room.add_connection(connection)
-
-        # Bridge until the connection is closed
-        await room.bridge_connection(connection)
-
-
-# ----------------------------------------------------------------------------
-def main():
-    # Check the Python version
-    if sys.version_info < (3, 6, 1):
-        print('ERROR: Python 3.6.1 or higher is required')
-        sys.exit(1)
-
-    logging.basicConfig(level=os.environ.get('BUMBLE_LOGLEVEL', 'INFO').upper())
-
-    # Parse arguments
-    arg_parser = argparse.ArgumentParser(description='Bumble Link Relay')
-    arg_parser.add_argument('--log-level', default='INFO', help='logger level')
-    arg_parser.add_argument('--log-config', help='logger config file (YAML)')
-    arg_parser.add_argument(
-        '--port', type=int, default=DEFAULT_RELAY_PORT, help='Port to listen on'
-    )
-    args = arg_parser.parse_args()
-
-    # Setup logger
-    if args.log_config:
-        from logging import config  # pylint: disable=import-outside-toplevel
-
-        config.fileConfig(args.log_config)
-    else:
-        logging.basicConfig(level=getattr(logging, args.log_level.upper()))
-
-    # Start a relay
-    relay = Relay(args.port)
-    asyncio.get_event_loop().run_until_complete(relay.start())
-    asyncio.get_event_loop().run_forever()
-
-
-# ----------------------------------------------------------------------------
-if __name__ == '__main__':
-    main()

apps/link_relay/logging.yml

@@ -1,21 +0,0 @@
-[loggers]
-keys=root
-
-[handlers]
-keys=stream_handler
-
-[formatters]
-keys=formatter
-
-[logger_root]
-level=DEBUG
-handlers=stream_handler
-
-[handler_stream_handler]
-class=StreamHandler
-level=DEBUG
-formatter=formatter
-args=(sys.stderr,)
-
-[formatter_formatter]
-format=%(asctime)s %(name)-12s %(levelname)-8s %(message)s

apps/pair.py

@@ -15,42 +15,65 @@
 # -----------------------------------------------------------------------------
 # Imports
 # -----------------------------------------------------------------------------
+from __future__ import annotations
+
 import asyncio
-import os
 import logging
+import os
+
 import click
 from prompt_toolkit.shortcuts import PromptSession
 
+from bumble import data_types
+from bumble.a2dp import make_audio_sink_service_sdp_records
+from bumble.att import (
+    ATT_INSUFFICIENT_AUTHENTICATION_ERROR,
+    ATT_INSUFFICIENT_ENCRYPTION_ERROR,
+    ATT_Error,
+)
 from bumble.colors import color
+from bumble.core import (
+    UUID,
+    AdvertisingData,
+    Appearance,
+    DataType,
+    PhysicalTransport,
+    ProtocolError,
+)
 from bumble.device import Device, Peer
-from bumble.transport import open_transport_or_link
-from bumble.pairing import PairingDelegate, PairingConfig
-from bumble.smp import error_name as smp_error_name
-from bumble.keys import JsonKeyStore
-from bumble.core import ProtocolError
 from bumble.gatt import (
     GATT_DEVICE_NAME_CHARACTERISTIC,
     GATT_GENERIC_ACCESS_SERVICE,
-    Service,
+    GATT_HEART_RATE_MEASUREMENT_CHARACTERISTIC,
+    GATT_HEART_RATE_SERVICE,
     Characteristic,
-    CharacteristicValue,
-)
-from bumble.att import (
-    ATT_Error,
-    ATT_INSUFFICIENT_AUTHENTICATION_ERROR,
-    ATT_INSUFFICIENT_ENCRYPTION_ERROR,
+    Service,
 )
+from bumble.hci import OwnAddressType
+from bumble.keys import JsonKeyStore
+from bumble.pairing import OobData, PairingConfig, PairingDelegate
+from bumble.smp import OobContext, OobLegacyContext
+from bumble.smp import error_name as smp_error_name
+from bumble.transport import open_transport
+from bumble.utils import AsyncRunner
+
+# -----------------------------------------------------------------------------
+# Constants
+# -----------------------------------------------------------------------------
+POST_PAIRING_DELAY = 1
 
 
 # -----------------------------------------------------------------------------
 class Waiter:
-    instance = None
+    instance: Waiter | None = 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 and not self.done.done:
+            self.done.set_result(None)
 
     async def wait_until_terminated(self):
         return await self.done
@@ -60,7 +83,7 @@ class Waiter:
 class Delegate(PairingDelegate):
     def __init__(self, mode, connection, capability_string, do_prompt):
         super().__init__(
-            {
+            io_capability={
                 'keyboard': PairingDelegate.KEYBOARD_INPUT_ONLY,
                 'display': PairingDelegate.DISPLAY_OUTPUT_ONLY,
                 'display+keyboard': PairingDelegate.DISPLAY_OUTPUT_AND_KEYBOARD_INPUT,
@@ -157,10 +180,30 @@ class Delegate(PairingDelegate):
         self.print(f'### PIN: {number:0{digits}}')
         self.print('###-----------------------------------')
 
+    async def get_string(self, max_length: int):
+        await self.update_peer_name()
+
+        # Prompt a PIN (for legacy pairing in classic)
+        self.print('###-----------------------------------')
+        self.print(f'### Pairing with {self.peer_name}')
+        self.print('###-----------------------------------')
+        count = 0
+        while True:
+            response = await self.prompt('>>> Enter PIN (1-6 chars):')
+            if len(response) == 0:
+                count += 1
+                if count > 3:
+                    self.print('too many tries, stopping the pairing')
+                    return None
+
+                self.print('no PIN was entered, try again')
+                continue
+            return response
+
 
 # -----------------------------------------------------------------------------
 async def get_peer_name(peer, mode):
-    if mode == 'classic':
+    if peer.connection.transport == PhysicalTransport.BR_EDR:
         return await peer.request_name()
 
     # Try to get the peer name from GATT
@@ -192,13 +235,14 @@ def read_with_error(connection):
     raise ATT_Error(ATT_INSUFFICIENT_AUTHENTICATION_ERROR)
 
 
-def write_with_error(connection, _value):
-    if not connection.is_encrypted:
-        raise ATT_Error(ATT_INSUFFICIENT_ENCRYPTION_ERROR)
-
-    if not AUTHENTICATION_ERROR_RETURNED[1]:
-        AUTHENTICATION_ERROR_RETURNED[1] = True
-        raise ATT_Error(ATT_INSUFFICIENT_AUTHENTICATION_ERROR)
+# -----------------------------------------------------------------------------
+def sdp_records():
+    service_record_handle = 0x00010001
+    return {
+        service_record_handle: make_audio_sink_service_sdp_records(
+            service_record_handle
+        )
+    }
 
 
 # -----------------------------------------------------------------------------
@@ -206,13 +250,19 @@ def on_connection(connection, request):
     print(color(f'<<< Connection: {connection}', 'green'))
 
     # Listen for pairing events
-    connection.on('pairing_start', on_pairing_start)
-    connection.on('pairing', lambda keys: on_pairing(connection.peer_address, keys))
-    connection.on('pairing_failure', on_pairing_failure)
+    connection.on(connection.EVENT_PAIRING_START, on_pairing_start)
+    connection.on(connection.EVENT_PAIRING, lambda keys: on_pairing(connection, keys))
+    connection.on(
+        connection.EVENT_CLASSIC_PAIRING, lambda: on_classic_pairing(connection)
+    )
+    connection.on(
+        connection.EVENT_PAIRING_FAILURE,
+        lambda reason: on_pairing_failure(connection, reason),
+    )
 
     # Listen for encryption changes
     connection.on(
-        'connection_encryption_change',
+        connection.EVENT_CONNECTION_ENCRYPTION_CHANGE,
         lambda: on_connection_encryption_change(connection),
     )
 
@@ -242,42 +292,67 @@ def on_pairing_start():
 
 
 # -----------------------------------------------------------------------------
-def on_pairing(address, keys):
+@AsyncRunner.run_in_task()
+async def on_pairing(connection, keys):
     print(color('***-----------------------------------', 'cyan'))
-    print(color(f'*** Paired! (peer identity={address})', 'cyan'))
+    print(color(f'*** Paired! (peer identity={connection.peer_address})', 'cyan'))
     keys.print(prefix=color('*** ', 'cyan'))
     print(color('***-----------------------------------', 'cyan'))
+    await asyncio.sleep(POST_PAIRING_DELAY)
+    await connection.disconnect()
     Waiter.instance.terminate()
 
 
 # -----------------------------------------------------------------------------
-def on_pairing_failure(reason):
+@AsyncRunner.run_in_task()
+async def on_classic_pairing(connection):
+    print(color('***-----------------------------------', 'cyan'))
+    print(
+        color(
+            f'*** Paired [Classic]! (peer identity={connection.peer_address})', 'cyan'
+        )
+    )
+    print(color('***-----------------------------------', 'cyan'))
+    await asyncio.sleep(POST_PAIRING_DELAY)
+    Waiter.instance.terminate()
+
+
+# -----------------------------------------------------------------------------
+@AsyncRunner.run_in_task()
+async def on_pairing_failure(connection, reason):
     print(color('***-----------------------------------', 'red'))
     print(color(f'*** Pairing failed: {smp_error_name(reason)}', 'red'))
     print(color('***-----------------------------------', 'red'))
+    await connection.disconnect()
     Waiter.instance.terminate()
 
 
 # -----------------------------------------------------------------------------
 async def pair(
-    mode,
-    sc,
-    mitm,
-    bond,
-    ctkd,
-    io,
-    prompt,
-    request,
-    print_keys,
-    keystore_file,
-    device_config,
-    hci_transport,
-    address_or_name,
+    mode: str,
+    sc: bool,
+    mitm: bool,
+    bond: bool,
+    ctkd: bool,
+    advertising_address: str,
+    identity_address: str,
+    linger: bool,
+    io: str,
+    oob: str,
+    prompt: bool,
+    request: bool,
+    print_keys: bool,
+    keystore_file: str,
+    advertise_service_uuids: str,
+    advertise_appearance: str,
+    device_config: str,
+    hci_transport: str,
+    address_or_name: str,
 ):
-    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):
+    async with await open_transport(hci_transport) as (hci_source, hci_sink):
         print('<<< connected')
 
         # Create a device to manage the host
@@ -285,29 +360,33 @@ async def pair(
 
         # Expose a GATT characteristic that can be used to trigger pairing by
         # responding with an authentication error when read
-        if mode == 'le':
+        if mode in ('le', 'dual'):
             device.add_service(
                 Service(
-                    '50DB505C-8AC4-4738-8448-3B1D9CC09CC5',
+                    GATT_HEART_RATE_SERVICE,
                     [
                         Characteristic(
-                            '552957FB-CF1F-4A31-9535-E78847E1A714',
-                            Characteristic.Properties.READ
-                            | Characteristic.Properties.WRITE,
-                            Characteristic.READABLE | Characteristic.WRITEABLE,
-                            CharacteristicValue(
-                                read=read_with_error, write=write_with_error
-                            ),
+                            GATT_HEART_RATE_MEASUREMENT_CHARACTERISTIC,
+                            Characteristic.Properties.READ,
+                            Characteristic.READ_REQUIRES_AUTHENTICATION,
+                            bytes(1),
                         )
                     ],
                 )
             )
 
-        # Select LE or Classic
-        if mode == 'classic':
+        # LE and Classic support
+        if mode in ('classic', 'dual'):
             device.classic_enabled = True
-            device.le_enabled = False
             device.classic_smp_enabled = ctkd
+        if mode in ('le', 'dual'):
+            device.le_enabled = True
+        if mode == 'dual':
+            device.le_simultaneous_enabled = True
+
+        # Setup SDP
+        if mode in ('classic', 'dual'):
+            device.sdp_service_records = sdp_records()
 
         # Get things going
         await device.power_on()
@@ -323,16 +402,74 @@ async def pair(
             await device.keystore.print(prefix=color('@@@ ', 'blue'))
             print(color('@@@-----------------------------------', 'blue'))
 
+        # Create an OOB context if needed
+        if oob:
+            our_oob_context = OobContext()
+            legacy_context: OobLegacyContext | None
+            if oob == '-':
+                shared_data = None
+                legacy_context = OobLegacyContext()
+            else:
+                oob_data = OobData.from_ad(
+                    AdvertisingData.from_bytes(bytes.fromhex(oob))
+                )
+                shared_data = oob_data.shared_data
+                legacy_context = oob_data.legacy_context
+                if legacy_context is None and not sc:
+                    print(color('OOB pairing in legacy mode requires TK', 'red'))
+                    return
+
+            oob_contexts = PairingConfig.OobConfig(
+                our_context=our_oob_context,
+                peer_data=shared_data,
+                legacy_context=legacy_context,
+            )
+            print(color('@@@-----------------------------------', 'yellow'))
+            print(color('@@@ OOB Data:', 'yellow'))
+            if shared_data is None:
+                oob_data = OobData(
+                    address=device.random_address,
+                    shared_data=our_oob_context.share(),
+                    legacy_context=(None if sc else legacy_context),
+                )
+                print(
+                    color(
+                        f'@@@   SHARE: {bytes(oob_data.to_ad()).hex()}',
+                        'yellow',
+                    )
+                )
+            if legacy_context:
+                print(color(f'@@@   TK={legacy_context.tk.hex()}', 'yellow'))
+            print(color('@@@-----------------------------------', 'yellow'))
+        else:
+            oob_contexts = None
+
         # Set up a pairing config factory
+        if identity_address == 'public':
+            identity_address_type = PairingConfig.AddressType.PUBLIC
+        elif identity_address == 'random':
+            identity_address_type = PairingConfig.AddressType.RANDOM
+        else:
+            identity_address_type = None
         device.pairing_config_factory = lambda connection: PairingConfig(
-            sc, mitm, bond, Delegate(mode, connection, io, prompt)
+            sc=sc,
+            mitm=mitm,
+            bonding=bond,
+            oob=oob_contexts,
+            identity_address_type=identity_address_type,
+            delegate=Delegate(mode, connection, io, prompt),
         )
 
         # Connect to a peer or wait for a connection
         device.on('connection', lambda connection: on_connection(connection, request))
         if address_or_name is not None:
             print(color(f'=== Connecting to {address_or_name}...', 'green'))
-            connection = await device.connect(address_or_name)
+            connection = await device.connect(
+                address_or_name,
+                transport=(
+                    PhysicalTransport.LE if mode == 'le' else PhysicalTransport.BR_EDR
+                ),
+            )
 
             if not request:
                 try:
@@ -340,18 +477,99 @@ async def pair(
                         await connection.pair()
                     else:
                         await connection.authenticate()
-                    return
                 except ProtocolError as error:
                     print(color(f'Pairing failed: {error}', 'red'))
-                    return
+
         else:
-            if mode == 'le':
-                # Advertise so that peers can find us and connect
-                await device.start_advertising(auto_restart=True)
-            else:
+            if mode in ('le', 'dual'):
+                # Advertise so that peers can find us and connect.
+                # Include the heart rate service UUID in the advertisement data
+                # so that devices like iPhones can show this device in their
+                # Bluetooth selector.
+                service_uuids_16 = []
+                service_uuids_32 = []
+                service_uuids_128 = []
+                if advertise_service_uuids:
+                    for uuid in advertise_service_uuids:
+                        uuid = uuid.replace("-", "")
+                        if len(uuid) == 4:
+                            service_uuids_16.append(UUID(uuid))
+                        elif len(uuid) == 8:
+                            service_uuids_32.append(UUID(uuid))
+                        elif len(uuid) == 32:
+                            service_uuids_128.append(UUID(uuid))
+                        else:
+                            print(color('Invalid UUID format', 'red'))
+                            return
+                else:
+                    service_uuids_16.append(GATT_HEART_RATE_SERVICE)
+
+                flags = AdvertisingData.Flags.LE_LIMITED_DISCOVERABLE_MODE
+                if mode == 'le':
+                    flags |= AdvertisingData.Flags.BR_EDR_NOT_SUPPORTED
+                if mode == 'dual':
+                    flags |= AdvertisingData.Flags.SIMULTANEOUS_LE_BR_EDR_CAPABLE
+
+                advertising_data_types: list[DataType] = [
+                    data_types.Flags(flags),
+                    data_types.CompleteLocalName('Bumble'),
+                ]
+                if service_uuids_16:
+                    advertising_data_types.append(
+                        data_types.IncompleteListOf16BitServiceUUIDs(service_uuids_16)
+                    )
+                if service_uuids_32:
+                    advertising_data_types.append(
+                        data_types.IncompleteListOf32BitServiceUUIDs(service_uuids_32)
+                    )
+                if service_uuids_128:
+                    advertising_data_types.append(
+                        data_types.IncompleteListOf128BitServiceUUIDs(service_uuids_128)
+                    )
+
+                if advertise_appearance:
+                    advertise_appearance = advertise_appearance.upper()
+                    try:
+                        appearance = data_types.Appearance.from_int(
+                            int(advertise_appearance)
+                        )
+                    except ValueError:
+                        category, subcategory = advertise_appearance.split('/')
+                        try:
+                            category_enum = Appearance.Category[category]
+                        except ValueError:
+                            print(
+                                color(f'Invalid appearance category {category}', 'red')
+                            )
+                            return
+                        subcategory_class = Appearance.SUBCATEGORY_CLASSES[
+                            category_enum
+                        ]
+                        try:
+                            subcategory_enum = subcategory_class[subcategory]
+                        except ValueError:
+                            print(color(f'Invalid subcategory {subcategory}', 'red'))
+                            return
+                        appearance = data_types.Appearance(
+                            category_enum, subcategory_enum
+                        )
+
+                    advertising_data_types.append(appearance)
+                device.advertising_data = bytes(AdvertisingData(advertising_data_types))
+                await device.start_advertising(
+                    auto_restart=True,
+                    own_address_type=(
+                        OwnAddressType.PUBLIC
+                        if advertising_address == 'public'
+                        else OwnAddressType.RANDOM
+                    ),
+                )
+
+            if mode in ('classic', 'dual'):
                 # Become discoverable and connectable
                 await device.set_discoverable(True)
                 await device.set_connectable(True)
+                print(color('Ready for connections on', 'blue'), device.public_address)
 
         # Run until the user asks to exit
         await Waiter.instance.wait_until_terminated()
@@ -371,7 +589,10 @@ class LogHandler(logging.Handler):
 # -----------------------------------------------------------------------------
 @click.command()
 @click.option(
-    '--mode', type=click.Choice(['le', 'classic']), default='le', show_default=True
+    '--mode',
+    type=click.Choice(['le', 'classic', 'dual']),
+    default='le',
+    show_default=True,
 )
 @click.option(
     '--sc',
@@ -393,6 +614,15 @@ class LogHandler(logging.Handler):
     help='Enable CTKD',
     show_default=True,
 )
+@click.option(
+    '--advertising-address',
+    type=click.Choice(['random', 'public']),
+)
+@click.option(
+    '--identity-address',
+    type=click.Choice(['random', 'public']),
+)
+@click.option('--linger', default=False, is_flag=True, help='Linger after pairing')
 @click.option(
     '--io',
     type=click.Choice(
@@ -401,6 +631,14 @@ class LogHandler(logging.Handler):
     default='display+keyboard',
     show_default=True,
 )
+@click.option(
+    '--oob',
+    metavar='<oob-data-hex>',
+    help=(
+        'Use OOB pairing with this data from the peer '
+        '(use "-" to enable OOB without peer data)'
+    ),
+)
 @click.option('--prompt', is_flag=True, help='Prompt to accept/reject pairing request')
 @click.option(
     '--request', is_flag=True, help='Request that the connecting peer initiate pairing'
@@ -408,26 +646,43 @@ class LogHandler(logging.Handler):
 @click.option('--print-keys', is_flag=True, help='Print the bond keys before pairing')
 @click.option(
     '--keystore-file',
-    metavar='<filename>',
+    metavar='FILENAME',
     help='File in which to store the pairing keys',
 )
+@click.option(
+    '--advertise-service-uuid',
+    metavar="UUID",
+    multiple=True,
+    help="Advertise a GATT service UUID (may be specified more than once)",
+)
+@click.option(
+    '--advertise-appearance',
+    metavar='APPEARANCE',
+    help='Advertise an Appearance ID (int value or string)',
+)
 @click.argument('device-config')
 @click.argument('hci_transport')
 @click.argument('address-or-name', required=False)
 def main(
-    mode,
-    sc,
-    mitm,
-    bond,
-    ctkd,
-    io,
-    prompt,
-    request,
-    print_keys,
-    keystore_file,
-    device_config,
-    hci_transport,
-    address_or_name,
+    mode: str,
+    sc: bool,
+    mitm: bool,
+    bond: bool,
+    ctkd: bool,
+    advertising_address: str,
+    identity_address: str,
+    linger: bool,
+    io: str,
+    oob: str,
+    prompt: bool,
+    request: bool,
+    print_keys: bool,
+    keystore_file: str,
+    advertise_service_uuid: str,
+    advertise_appearance: str,
+    device_config: str,
+    hci_transport: str,
+    address_or_name: str,
 ):
     # Setup logging
     log_handler = LogHandler()
@@ -443,11 +698,17 @@ def main(
             mitm,
             bond,
             ctkd,
+            advertising_address,
+            identity_address,
+            linger,
             io,
+            oob,
             prompt,
             request,
             print_keys,
             keystore_file,
+            advertise_service_uuid,
+            advertise_appearance,
             device_config,
             hci_transport,
             address_or_name,

apps/pandora_server.py

@@ -1,8 +1,11 @@
 import asyncio
-import click
+import json
 import logging
+from typing import Any
 
-from bumble.pandora import PandoraDevice, serve
+import click
+
+from bumble.pandora import Config, PandoraDevice, serve
 
 BUMBLE_SERVER_GRPC_PORT = 7999
 ROOTCANAL_PORT_CUTTLEFISH = 7300
@@ -16,14 +19,33 @@ ROOTCANAL_PORT_CUTTLEFISH = 7300
 @click.option(
     '--transport',
     help='HCI transport',
-    default=f'tcp-client:127.0.0.1:<rootcanal-port>',
+    default='tcp-client:127.0.0.1:<rootcanal-port>',
 )
-def main(grpc_port: int, rootcanal_port: int, transport: str) -> None:
+@click.option(
+    '--config',
+    help='Bumble json configuration file',
+)
+def main(grpc_port: int, rootcanal_port: int, transport: str, config: str) -> None:
     if '<rootcanal-port>' in transport:
         transport = transport.replace('<rootcanal-port>', str(rootcanal_port))
-    device = PandoraDevice({'transport': transport})
+
+    bumble_config = retrieve_config(config)
+    bumble_config.setdefault('transport', transport)
+    device = PandoraDevice(bumble_config)
+
+    server_config = Config()
+    server_config.load_from_dict(bumble_config.get('server', {}))
+
     logging.basicConfig(level=logging.DEBUG)
-    asyncio.run(serve(device, port=grpc_port))
+    asyncio.run(serve(device, config=server_config, port=grpc_port))
+
+
+def retrieve_config(config: str) -> dict[str, Any]:
+    if not config:
+        return {}
+
+    with open(config) as f:
+        return json.load(f)
 
 
 if __name__ == '__main__':

apps/player/player.py

@@ -0,0 +1,602 @@
+# Copyright 2024 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# -----------------------------------------------------------------------------
+# Imports
+# -----------------------------------------------------------------------------
+from __future__ import annotations
+
+import asyncio
+import logging
+
+import click
+
+import bumble.logging
+from bumble.a2dp import (
+    A2DP_MPEG_2_4_AAC_CODEC_TYPE,
+    A2DP_NON_A2DP_CODEC_TYPE,
+    A2DP_SBC_CODEC_TYPE,
+    AacFrame,
+    AacMediaCodecInformation,
+    AacPacketSource,
+    AacParser,
+    OpusMediaCodecInformation,
+    OpusPacket,
+    OpusPacketSource,
+    OpusParser,
+    SbcFrame,
+    SbcMediaCodecInformation,
+    SbcPacketSource,
+    SbcParser,
+    make_audio_source_service_sdp_records,
+)
+from bumble.avdtp import (
+    AVDTP_AUDIO_MEDIA_TYPE,
+    AVDTP_DELAY_REPORTING_SERVICE_CATEGORY,
+    MediaCodecCapabilities,
+    MediaPacketPump,
+    find_avdtp_service_with_connection,
+)
+from bumble.avdtp import Protocol as AvdtpProtocol
+from bumble.avrcp import Protocol as AvrcpProtocol
+from bumble.colors import color
+from bumble.core import AdvertisingData, DeviceClass, PhysicalTransport
+from bumble.core import ConnectionError as BumbleConnectionError
+from bumble.device import Connection, Device, DeviceConfiguration
+from bumble.hci import HCI_CONNECTION_ALREADY_EXISTS_ERROR, Address, HCI_Constant
+from bumble.pairing import PairingConfig
+from bumble.transport import open_transport
+from bumble.utils import AsyncRunner
+
+# -----------------------------------------------------------------------------
+# Logging
+# -----------------------------------------------------------------------------
+logger = logging.getLogger(__name__)
+
+
+# -----------------------------------------------------------------------------
+def a2dp_source_sdp_records():
+    service_record_handle = 0x00010001
+    return {
+        service_record_handle: make_audio_source_service_sdp_records(
+            service_record_handle
+        )
+    }
+
+
+# -----------------------------------------------------------------------------
+async def sbc_codec_capabilities(read_function) -> MediaCodecCapabilities:
+    sbc_parser = SbcParser(read_function)
+    sbc_frame: SbcFrame
+    async for sbc_frame in sbc_parser.frames:
+        # We only need the first frame
+        print(color(f"SBC format: {sbc_frame}", "cyan"))
+        break
+
+    channel_mode = [
+        SbcMediaCodecInformation.ChannelMode.MONO,
+        SbcMediaCodecInformation.ChannelMode.DUAL_CHANNEL,
+        SbcMediaCodecInformation.ChannelMode.STEREO,
+        SbcMediaCodecInformation.ChannelMode.JOINT_STEREO,
+    ][sbc_frame.channel_mode]
+    block_length = {
+        4: SbcMediaCodecInformation.BlockLength.BL_4,
+        8: SbcMediaCodecInformation.BlockLength.BL_8,
+        12: SbcMediaCodecInformation.BlockLength.BL_12,
+        16: SbcMediaCodecInformation.BlockLength.BL_16,
+    }[sbc_frame.block_count]
+    subbands = {
+        4: SbcMediaCodecInformation.Subbands.S_4,
+        8: SbcMediaCodecInformation.Subbands.S_8,
+    }[sbc_frame.subband_count]
+    allocation_method = [
+        SbcMediaCodecInformation.AllocationMethod.LOUDNESS,
+        SbcMediaCodecInformation.AllocationMethod.SNR,
+    ][sbc_frame.allocation_method]
+    return MediaCodecCapabilities(
+        media_type=AVDTP_AUDIO_MEDIA_TYPE,
+        media_codec_type=A2DP_SBC_CODEC_TYPE,
+        media_codec_information=SbcMediaCodecInformation(
+            sampling_frequency=SbcMediaCodecInformation.SamplingFrequency.from_int(
+                sbc_frame.sampling_frequency
+            ),
+            channel_mode=channel_mode,
+            block_length=block_length,
+            subbands=subbands,
+            allocation_method=allocation_method,
+            minimum_bitpool_value=2,
+            maximum_bitpool_value=40,
+        ),
+    )
+
+
+# -----------------------------------------------------------------------------
+async def aac_codec_capabilities(read_function) -> MediaCodecCapabilities:
+    aac_parser = AacParser(read_function)
+    aac_frame: AacFrame
+    async for aac_frame in aac_parser.frames:
+        # We only need the first frame
+        print(color(f"AAC format: {aac_frame}", "cyan"))
+        break
+
+    sampling_frequency = AacMediaCodecInformation.SamplingFrequency.from_int(
+        aac_frame.sampling_frequency
+    )
+    channels = (
+        AacMediaCodecInformation.Channels.MONO
+        if aac_frame.channel_configuration == 1
+        else AacMediaCodecInformation.Channels.STEREO
+    )
+
+    return MediaCodecCapabilities(
+        media_type=AVDTP_AUDIO_MEDIA_TYPE,
+        media_codec_type=A2DP_MPEG_2_4_AAC_CODEC_TYPE,
+        media_codec_information=AacMediaCodecInformation(
+            object_type=AacMediaCodecInformation.ObjectType.MPEG_2_AAC_LC,
+            sampling_frequency=sampling_frequency,
+            channels=channels,
+            vbr=1,
+            bitrate=128000,
+        ),
+    )
+
+
+# -----------------------------------------------------------------------------
+async def opus_codec_capabilities(read_function) -> MediaCodecCapabilities:
+    opus_parser = OpusParser(read_function)
+    opus_packet: OpusPacket
+    async for opus_packet in opus_parser.packets:
+        # We only need the first packet
+        print(color(f"Opus format: {opus_packet}", "cyan"))
+        break
+
+    if opus_packet.channel_mode == OpusPacket.ChannelMode.MONO:
+        channel_mode = OpusMediaCodecInformation.ChannelMode.MONO
+    elif opus_packet.channel_mode == OpusPacket.ChannelMode.STEREO:
+        channel_mode = OpusMediaCodecInformation.ChannelMode.STEREO
+    else:
+        channel_mode = OpusMediaCodecInformation.ChannelMode.DUAL_MONO
+
+    if opus_packet.duration == 10:
+        frame_size = OpusMediaCodecInformation.FrameSize.FS_10MS
+    else:
+        frame_size = OpusMediaCodecInformation.FrameSize.FS_20MS
+
+    return MediaCodecCapabilities(
+        media_type=AVDTP_AUDIO_MEDIA_TYPE,
+        media_codec_type=A2DP_NON_A2DP_CODEC_TYPE,
+        media_codec_information=OpusMediaCodecInformation(
+            channel_mode=channel_mode,
+            sampling_frequency=OpusMediaCodecInformation.SamplingFrequency.SF_48000,
+            frame_size=frame_size,
+        ),
+    )
+
+
+# -----------------------------------------------------------------------------
+class Player:
+    def __init__(
+        self,
+        transport: str,
+        device_config: str | None,
+        authenticate: bool,
+        encrypt: bool,
+    ) -> None:
+        self.transport = transport
+        self.device_config = device_config
+        self.authenticate = authenticate
+        self.encrypt = encrypt
+        self.avrcp_protocol: AvrcpProtocol | None = None
+        self.done: asyncio.Event | None
+
+    async def run(self, workload) -> None:
+        self.done = asyncio.Event()
+        try:
+            await self._run(workload)
+        except Exception as error:
+            print(color(f"!!! ERROR: {error}", "red"))
+
+    async def _run(self, workload) -> None:
+        async with await open_transport(self.transport) as (hci_source, hci_sink):
+            # Create a device
+            device_config = DeviceConfiguration()
+            if self.device_config:
+                device_config.load_from_file(self.device_config)
+            else:
+                device_config.name = "Bumble Player"
+                device_config.class_of_device = DeviceClass.pack_class_of_device(
+                    DeviceClass.AUDIO_SERVICE_CLASS,
+                    DeviceClass.AUDIO_VIDEO_MAJOR_DEVICE_CLASS,
+                    DeviceClass.AUDIO_VIDEO_UNCATEGORIZED_MINOR_DEVICE_CLASS,
+                )
+                device_config.keystore = "JsonKeyStore"
+
+            device_config.classic_enabled = True
+            device_config.le_enabled = False
+            device_config.le_simultaneous_enabled = False
+            device_config.classic_sc_enabled = False
+            device_config.classic_smp_enabled = False
+            device = Device.from_config_with_hci(device_config, hci_source, hci_sink)
+
+            # Setup the SDP records to expose the SRC service
+            device.sdp_service_records = a2dp_source_sdp_records()
+
+            # Setup AVRCP
+            self.avrcp_protocol = AvrcpProtocol()
+            self.avrcp_protocol.listen(device)
+
+            # Don't require MITM when pairing.
+            device.pairing_config_factory = lambda connection: PairingConfig(mitm=False)
+
+            # Start the controller
+            await device.power_on()
+
+            # Print some of the config/properties
+            print(
+                "Player Bluetooth Address:",
+                color(
+                    device.public_address.to_string(with_type_qualifier=False),
+                    "yellow",
+                ),
+            )
+
+            # Listen for connections
+            device.on("connection", self.on_bluetooth_connection)
+
+            # Run the workload
+            try:
+                await workload(device)
+            except BumbleConnectionError as error:
+                if error.error_code == HCI_CONNECTION_ALREADY_EXISTS_ERROR:
+                    print(color("Connection already established", "blue"))
+                else:
+                    print(color(f"Failed to connect: {error}", "red"))
+
+            # Wait until it is time to exit
+            assert self.done is not None
+            await asyncio.wait(
+                [hci_source.terminated, asyncio.ensure_future(self.done.wait())],
+                return_when=asyncio.FIRST_COMPLETED,
+            )
+
+    def on_bluetooth_connection(self, connection: Connection) -> None:
+        print(color(f"--- Connected: {connection}", "cyan"))
+        connection.on("disconnection", self.on_bluetooth_disconnection)
+
+    def on_bluetooth_disconnection(self, reason) -> None:
+        print(color(f"--- Disconnected: {HCI_Constant.error_name(reason)}", "cyan"))
+        self.set_done()
+
+    async def connect(self, device: Device, address: str) -> Connection:
+        print(color(f"Connecting to {address}...", "green"))
+        connection = await device.connect(address, transport=PhysicalTransport.BR_EDR)
+
+        # Request authentication
+        if self.authenticate:
+            print(color("*** Authenticating...", "blue"))
+            await connection.authenticate()
+            print(color("*** Authenticated", "blue"))
+
+        # Enable encryption
+        if self.encrypt:
+            print(color("*** Enabling encryption...", "blue"))
+            await connection.encrypt()
+            print(color("*** Encryption on", "blue"))
+
+        return connection
+
+    async def create_avdtp_protocol(self, connection: Connection) -> AvdtpProtocol:
+        # Look for an A2DP service
+        avdtp_version = await find_avdtp_service_with_connection(connection)
+        if not avdtp_version:
+            raise RuntimeError("no A2DP service found")
+
+        print(color(f"AVDTP Version: {avdtp_version}"))
+
+        # Create a client to interact with the remote device
+        return await AvdtpProtocol.connect(connection, avdtp_version)
+
+    async def stream_packets(
+        self,
+        protocol: AvdtpProtocol,
+        codec_type: int,
+        vendor_id: int,
+        codec_id: int,
+        packet_source: SbcPacketSource | AacPacketSource | OpusPacketSource,
+        codec_capabilities: MediaCodecCapabilities,
+    ):
+        # Discover all endpoints on the remote device
+        endpoints = await protocol.discover_remote_endpoints()
+        for endpoint in endpoints:
+            print('@@@', endpoint)
+
+        # Select a sink
+        sink = protocol.find_remote_sink_by_codec(
+            AVDTP_AUDIO_MEDIA_TYPE, codec_type, vendor_id, codec_id
+        )
+        if sink is None:
+            print(color('!!! no compatible sink found', 'red'))
+            return
+        print(f'### Selected sink: {sink.seid}')
+
+        # Check if the sink supports delay reporting
+        delay_reporting = False
+        for capability in sink.capabilities:
+            if capability.service_category == AVDTP_DELAY_REPORTING_SERVICE_CATEGORY:
+                delay_reporting = True
+                break
+
+        def on_delay_report(delay: int):
+            print(color(f"*** DELAY REPORT: {delay}", "blue"))
+
+        # Adjust the codec capabilities for certain codecs
+        for capability in sink.capabilities:
+            if isinstance(capability, MediaCodecCapabilities):
+                if isinstance(
+                    codec_capabilities.media_codec_information, SbcMediaCodecInformation
+                ) and isinstance(
+                    capability.media_codec_information, SbcMediaCodecInformation
+                ):
+                    codec_capabilities.media_codec_information.minimum_bitpool_value = (
+                        capability.media_codec_information.minimum_bitpool_value
+                    )
+                    codec_capabilities.media_codec_information.maximum_bitpool_value = (
+                        capability.media_codec_information.maximum_bitpool_value
+                    )
+                    print(color("Source media codec:", "green"), codec_capabilities)
+
+        # Stream the packets
+        packet_pump = MediaPacketPump(packet_source.packets)
+        source = protocol.add_source(codec_capabilities, packet_pump, delay_reporting)
+        source.on("delay_report", on_delay_report)
+        stream = await protocol.create_stream(source, sink)
+        await stream.start()
+
+        await packet_pump.wait_for_completion()
+
+    async def discover(self, device: Device) -> None:
+        @device.listens_to("inquiry_result")
+        def on_inquiry_result(
+            address: Address, class_of_device: int, data: AdvertisingData, rssi: int
+        ) -> None:
+            (
+                service_classes,
+                major_device_class,
+                minor_device_class,
+            ) = DeviceClass.split_class_of_device(class_of_device)
+            separator = "\n  "
+            print(f">>> {color(address.to_string(False), 'yellow')}:")
+            print(f"  Device Class (raw): {class_of_device:06X}")
+            major_class_name = DeviceClass.major_device_class_name(major_device_class)
+            print(f"  Device Major Class: {major_class_name}")
+            minor_class_name = DeviceClass.minor_device_class_name(
+                major_device_class, minor_device_class
+            )
+            print(f"  Device Minor Class: {minor_class_name}")
+            print(
+                "  Device Services: "
+                f"{', '.join(DeviceClass.service_class_labels(service_classes))}"
+            )
+            print(f"  RSSI: {rssi}")
+            if data.ad_structures:
+                print(f"  {data.to_string(separator)}")
+
+        await device.start_discovery()
+
+    async def pair(self, device: Device, address: str) -> None:
+        print(color(f"Connecting to {address}...", "green"))
+        connection = await device.connect(address, transport=PhysicalTransport.BR_EDR)
+
+        print(color("Pairing...", "magenta"))
+        await connection.authenticate()
+        print(color("Pairing completed", "magenta"))
+        self.set_done()
+
+    async def inquire(self, device: Device, address: str) -> None:
+        connection = await self.connect(device, address)
+        avdtp_protocol = await self.create_avdtp_protocol(connection)
+
+        # Discover the remote endpoints
+        endpoints = await avdtp_protocol.discover_remote_endpoints()
+        print(f'@@@ Found {len(list(endpoints))} endpoints')
+        for endpoint in endpoints:
+            print('@@@', endpoint)
+
+        self.set_done()
+
+    async def play(
+        self,
+        device: Device,
+        address: str | None,
+        audio_format: str,
+        audio_file: str,
+    ) -> None:
+        if audio_format == "auto":
+            if audio_file.endswith(".sbc"):
+                audio_format = "sbc"
+            elif audio_file.endswith(".aac") or audio_file.endswith(".adts"):
+                audio_format = "aac"
+            elif audio_file.endswith(".ogg"):
+                audio_format = "opus"
+            else:
+                raise ValueError("Unable to determine audio format from file extension")
+
+        device.on(
+            "connection",
+            lambda connection: AsyncRunner.spawn(on_connection(connection)),
+        )
+
+        async def on_connection(connection: Connection):
+            avdtp_protocol = await self.create_avdtp_protocol(connection)
+
+            with open(audio_file, 'rb') as input_file:
+                # NOTE: this should be using asyncio file reading, but blocking reads
+                # are good enough for this command line app.
+                async def read_audio_data(byte_count):
+                    return input_file.read(byte_count)
+
+                # Obtain the codec capabilities from the stream
+                packet_source: SbcPacketSource | AacPacketSource | OpusPacketSource
+                vendor_id = 0
+                codec_id = 0
+                if audio_format == "sbc":
+                    codec_type = A2DP_SBC_CODEC_TYPE
+                    codec_capabilities = await sbc_codec_capabilities(read_audio_data)
+                    packet_source = SbcPacketSource(
+                        read_audio_data,
+                        avdtp_protocol.l2cap_channel.peer_mtu,
+                    )
+                elif audio_format == "aac":
+                    codec_type = A2DP_MPEG_2_4_AAC_CODEC_TYPE
+                    codec_capabilities = await aac_codec_capabilities(read_audio_data)
+                    packet_source = AacPacketSource(
+                        read_audio_data,
+                        avdtp_protocol.l2cap_channel.peer_mtu,
+                    )
+                else:
+                    codec_type = A2DP_NON_A2DP_CODEC_TYPE
+                    vendor_id = OpusMediaCodecInformation.VENDOR_ID
+                    codec_id = OpusMediaCodecInformation.CODEC_ID
+                    codec_capabilities = await opus_codec_capabilities(read_audio_data)
+                    packet_source = OpusPacketSource(
+                        read_audio_data,
+                        avdtp_protocol.l2cap_channel.peer_mtu,
+                    )
+
+                # Rewind to the start
+                input_file.seek(0)
+
+                try:
+                    await self.stream_packets(
+                        avdtp_protocol,
+                        codec_type,
+                        vendor_id,
+                        codec_id,
+                        packet_source,
+                        codec_capabilities,
+                    )
+                except Exception as error:
+                    print(color(f"!!! Error while streaming: {error}", "red"))
+
+            self.set_done()
+
+        if address:
+            await self.connect(device, address)
+        else:
+            print(color("Waiting for an incoming connection...", "magenta"))
+
+    def set_done(self) -> None:
+        if self.done:
+            self.done.set()
+
+
+# -----------------------------------------------------------------------------
+def create_player(context) -> Player:
+    return Player(
+        transport=context.obj["hci_transport"],
+        device_config=context.obj["device_config"],
+        authenticate=context.obj["authenticate"],
+        encrypt=context.obj["encrypt"],
+    )
+
+
+# -----------------------------------------------------------------------------
+@click.group()
+@click.pass_context
+@click.option("--hci-transport", metavar="TRANSPORT", required=True)
+@click.option("--device-config", metavar="FILENAME", help="Device configuration file")
+@click.option(
+    "--authenticate",
+    is_flag=True,
+    help="Request authentication when connecting",
+    default=False,
+)
+@click.option(
+    "--encrypt", is_flag=True, help="Request encryption when connecting", default=True
+)
+def player_cli(ctx, hci_transport, device_config, authenticate, encrypt):
+    ctx.ensure_object(dict)
+    ctx.obj["hci_transport"] = hci_transport
+    ctx.obj["device_config"] = device_config
+    ctx.obj["authenticate"] = authenticate
+    ctx.obj["encrypt"] = encrypt
+
+
+@player_cli.command("discover")
+@click.pass_context
+def discover(context):
+    """Discover speakers or headphones"""
+    player = create_player(context)
+    asyncio.run(player.run(player.discover))
+
+
+@player_cli.command("inquire")
+@click.pass_context
+@click.argument(
+    "address",
+    metavar="ADDRESS",
+)
+def inquire(context, address):
+    """Connect to a speaker or headphone and inquire about their capabilities"""
+    player = create_player(context)
+    asyncio.run(player.run(lambda device: player.inquire(device, address)))
+
+
+@player_cli.command("pair")
+@click.pass_context
+@click.argument(
+    "address",
+    metavar="ADDRESS",
+)
+def pair(context, address):
+    """Pair with a speaker or headphone"""
+    player = create_player(context)
+    asyncio.run(player.run(lambda device: player.pair(device, address)))
+
+
+@player_cli.command("play")
+@click.pass_context
+@click.option(
+    "--connect",
+    "address",
+    metavar="ADDRESS",
+    help="Address or name to connect to",
+)
+@click.option(
+    "-f",
+    "--audio-format",
+    type=click.Choice(["auto", "sbc", "aac", "opus"]),
+    help="Audio file format (use 'auto' to infer the format from the file extension)",
+    default="auto",
+)
+@click.argument("audio_file")
+def play(context, address, audio_format, audio_file):
+    """Play and audio file"""
+    player = create_player(context)
+    asyncio.run(
+        player.run(
+            lambda device: player.play(device, address, audio_format, audio_file)
+        )
+    )
+
+
+# -----------------------------------------------------------------------------
+def main():
+    bumble.logging.setup_basic_logging("WARNING")
+    player_cli()
+
+
+# -----------------------------------------------------------------------------
+if __name__ == "__main__":
+    main()  # pylint: disable=no-value-for-parameter

apps/rfcomm_bridge.py

@@ -0,0 +1,513 @@
+# 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 time
+
+import click
+
+import bumble.logging
+from bumble import core, hci, rfcomm, transport, utils
+from bumble.colors import color
+from bumble.device import Connection, Device, DeviceConfiguration
+
+# -----------------------------------------------------------------------------
+# 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: Device | None = None
+        self.channel = channel
+        self.uuid = uuid
+        self.tcp_host = tcp_host
+        self.tcp_port = tcp_port
+        self.rfcomm_channel: rfcomm.DLC | None = None
+        self.tcp_tracer: Tracer | None
+        self.rfcomm_tracer: Tracer | None
+
+        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,
+        authenticate: bool,
+        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.authenticate = authenticate
+        self.encrypt = encrypt
+        self.device: Device | None = None
+        self.connection: Connection | None = None
+        self.rfcomm_client: rfcomm.Client | None
+        self.rfcomm_mux: rfcomm.Multiplexer | None
+        self.tcp_connected: bool = False
+
+        self.tcp_tracer: Tracer | None
+        self.rfcomm_tracer: Tracer | None
+
+        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.PhysicalTransport.BR_EDR
+        )
+        print(color(f"@@@ Bluetooth connection: {self.connection}", "blue"))
+        self.connection.on("disconnection", self.on_disconnection)
+
+        if self.authenticate:
+            print(color("@@@ Authenticating Bluetooth connection", "blue"))
+            await self.connection.authenticate()
+            print(color("@@@ Bluetooth connection authenticated", "blue"))
+
+        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(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("--authenticate", is_flag=True, help="Authenticate the connection")
+@click.option("--encrypt", is_flag=True, help="Encrypt the connection")
+def client(context, bluetooth_address, tcp_host, tcp_port, authenticate, encrypt):
+    bridge = ClientBridge(
+        context.obj["channel"],
+        context.obj["uuid"],
+        context.obj["trace"],
+        bluetooth_address,
+        tcp_host,
+        tcp_port,
+        authenticate,
+        encrypt,
+    )
+    asyncio.run(run(context.obj["device_config"], context.obj["hci_transport"], bridge))
+
+
+# -----------------------------------------------------------------------------
+if __name__ == "__main__":
+    bumble.logging.setup_basic_logging("WARNING")
+    cli(obj={})  # pylint: disable=no-value-for-parameter

apps/scan.py

@@ -16,17 +16,17 @@
 # Imports
 # -----------------------------------------------------------------------------
 import asyncio
-import os
-import logging
+
 import click
 
+import bumble.logging
+from bumble import data_types
 from bumble.colors import color
-from bumble.device import Device
-from bumble.transport import open_transport_or_link
+from bumble.device import Advertisement, Device
+from bumble.hci import HCI_LE_1M_PHY, HCI_LE_CODED_PHY, Address, HCI_Constant
 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.transport import open_transport
 
 
 # -----------------------------------------------------------------------------
@@ -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:
@@ -90,13 +95,22 @@ class AdvertisementPrinter:
         else:
             phy_info = ''
 
+        details = separator.join(
+            [
+                data_type.to_string(use_label=True)
+                for data_type in data_types.data_types_from_advertising_data(
+                    advertisement.data
+                )
+            ]
+        )
+
         print(
             f'>>> {color(address, address_color)} '
             f'[{color(address_type_string, type_color)}]{address_qualifier}'
             f'{resolution_qualifier}:{separator}'
             f'{phy_info}'
             f'RSSI:{advertisement.rssi:4} {rssi_bar}{separator}'
-            f'{advertisement.data.to_string(separator)}\n'
+            f'{details}\n'
         )
 
     def on_advertisement(self, advertisement):
@@ -116,12 +130,13 @@ async def scan(
     phy,
     filter_duplicates,
     raw,
+    irks,
     keystore_file,
     device_config,
     transport,
 ):
     print('<<< connecting to HCI...')
-    async with await open_transport_or_link(transport) as (hci_source, hci_sink):
+    async with await open_transport(transport) as (hci_source, hci_sink):
         print('<<< connected')
 
         if device_config:
@@ -140,9 +155,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 +214,22 @@ 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,11 +239,12 @@ def main(
     phy,
     filter_duplicates,
     raw,
+    irk,
     keystore_file,
     device_config,
     transport,
 ):
-    logging.basicConfig(level=os.environ.get('BUMBLE_LOGLEVEL', 'WARNING').upper())
+    bumble.logging.setup_basic_logging('WARNING')
     asyncio.run(
         scan(
             min_rssi,
@@ -212,6 +254,7 @@ def main(
             phy,
             filter_duplicates,
             raw,
+            irk,
             keystore_file,
             device_config,
             transport,

apps/show.py

@@ -15,15 +15,27 @@
 # -----------------------------------------------------------------------------
 # Imports
 # -----------------------------------------------------------------------------
+import datetime
+import importlib
+import logging
 import struct
+
 import click
 
-from bumble.colors import color
+import bumble.logging
 from bumble import hci
-from bumble.transport.common import PacketReader
+from bumble.colors import color
 from bumble.helpers import PacketTracer
+from bumble.transport.common import PacketReader
+
+# -----------------------------------------------------------------------------
+# 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}")
 
 
 # -----------------------------------------------------------------------------
@@ -102,33 +143,49 @@ class SnoopPacketReader:
     default='h4',
     help='Format of the input file',
 )
+@click.option(
+    '--vendor',
+    type=click.Choice(['android', 'zephyr']),
+    multiple=True,
+    help='Support vendor-specific commands (list one or more)',
+)
 @click.argument('filename')
 # pylint: disable=redefined-builtin
-def main(format, filename):
+def main(format, vendor, filename):
+    for vendor_name in vendor:
+        if vendor_name == 'android':
+            # Prevent being deleted by linter.
+            importlib.import_module('bumble.vendor.android.hci')
+        elif vendor_name == 'zephyr':
+            importlib.import_module('bumble.vendor.zephyr.hci')
+
     input = open(filename, 'rb')
     if format == 'h4':
         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__':
+    bumble.logging.setup_basic_logging('WARNING')
     main()  # pylint: disable=no-value-for-parameter

apps/speaker/logo.svg

@@ -0,0 +1,42 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?> <!-- Created with Vectornator for iOS (http://vectornator.io/) --><!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<svg height="100%" style="fill-rule:nonzero;clip-rule:evenodd;stroke-linecap:round;stroke-linejoin:round;" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns="http://www.w3.org/2000/svg" xml:space="preserve" width="100%" xmlns:vectornator="http://vectornator.io" version="1.1" viewBox="0 0 745 744.634">
+<metadata>
+<vectornator:setting key="DimensionsVisible" value="1"/>
+<vectornator:setting key="PencilOnly" value="0"/>
+<vectornator:setting key="SnapToPoints" value="0"/>
+<vectornator:setting key="OutlineMode" value="0"/>
+<vectornator:setting key="CMYKEnabledKey" value="0"/>
+<vectornator:setting key="RulersVisible" value="1"/>
+<vectornator:setting key="SnapToEdges" value="0"/>
+<vectornator:setting key="GuidesVisible" value="1"/>
+<vectornator:setting key="DisplayWhiteBackground" value="0"/>
+<vectornator:setting key="doHistoryDisabled" value="0"/>
+<vectornator:setting key="SnapToGuides" value="1"/>
+<vectornator:setting key="TimeLapseWatermarkDisabled" value="0"/>
+<vectornator:setting key="Units" value="Pixels"/>
+<vectornator:setting key="DynamicGuides" value="0"/>
+<vectornator:setting key="IsolateActiveLayer" value="0"/>
+<vectornator:setting key="SnapToGrid" value="0"/>
+</metadata>
+<defs/>
+<g id="Layer 1" vectornator:layerName="Layer 1">
+<path stroke="#000000" stroke-width="18.6464" d="M368.753+729.441L58.8847+550.539L58.8848+192.734L368.753+13.8313L678.621+192.734L678.621+550.539L368.753+729.441Z" fill="#0082fc" stroke-linecap="butt" fill-opacity="0.307489" opacity="1" stroke-linejoin="round"/>
+<g opacity="1">
+<g opacity="1">
+<path stroke="#000000" stroke-width="20" d="M292.873+289.256L442.872+289.256L442.872+539.254L292.873+539.254L292.873+289.256Z" fill="#fcd100" stroke-linecap="butt" opacity="1" stroke-linejoin="round"/>
+<path stroke="#000000" stroke-width="20" d="M292.873+289.256C292.873+247.835+326.452+214.257+367.873+214.257C409.294+214.257+442.872+247.835+442.872+289.256C442.872+330.677+409.294+364.256+367.873+364.256C326.452+364.256+292.873+330.677+292.873+289.256Z" fill="#fcd100" stroke-linecap="butt" opacity="1" stroke-linejoin="round"/>
+<path stroke="#000000" stroke-width="20" d="M292.873+539.254C292.873+497.833+326.452+464.255+367.873+464.255C409.294+464.255+442.872+497.833+442.872+539.254C442.872+580.675+409.294+614.254+367.873+614.254C326.452+614.254+292.873+580.675+292.873+539.254Z" fill="#fcd100" stroke-linecap="butt" opacity="1" stroke-linejoin="round"/>
+<path stroke="#0082fc" stroke-width="0.1" d="M302.873+289.073L432.872+289.073L432.872+539.072L302.873+539.072L302.873+289.073Z" fill="#fcd100" stroke-linecap="butt" opacity="1" stroke-linejoin="round"/>
+</g>
+<path stroke="#000000" stroke-width="0.1" d="M103.161+309.167L226.956+443.903L366.671+309.604L103.161+309.167Z" fill="#0082fc" stroke-linecap="round" opacity="1" stroke-linejoin="round"/>
+<path stroke="#000000" stroke-width="0.1" d="M383.411+307.076L508.887+440.112L650.5+307.507L383.411+307.076Z" fill="#0082fc" stroke-linecap="round" opacity="1" stroke-linejoin="round"/>
+<path stroke="#000000" stroke-width="20" d="M522.045+154.808L229.559+448.882L83.8397+300.104L653.666+302.936L511.759+444.785L223.101+156.114" fill="none" stroke-linecap="round" opacity="1" stroke-linejoin="round"/>
+<path stroke="#000000" stroke-width="61.8698" d="M295.857+418.738L438.9+418.738" fill="none" stroke-linecap="butt" opacity="1" stroke-linejoin="round"/>
+<path stroke="#000000" stroke-width="61.8698" d="M295.857+521.737L438.9+521.737" fill="none" stroke-linecap="butt" opacity="1" stroke-linejoin="round"/>
+<g opacity="1">
+<path stroke="#0082fc" stroke-width="0.1" d="M367.769+667.024L367.821+616.383L403.677+616.336C383.137+626.447+368.263+638.69+367.769+667.024Z" fill="#000000" stroke-linecap="butt" opacity="1" stroke-linejoin="round"/>
+<path stroke="#0082fc" stroke-width="0.1" d="M367.836+667.024L367.784+616.383L331.928+616.336C352.468+626.447+367.341+638.69+367.836+667.024Z" fill="#000000" stroke-linecap="butt" opacity="1" stroke-linejoin="round"/>
+</g>
+</g>
+</g>
+</svg>

apps/speaker/speaker.css

@@ -0,0 +1,76 @@
+body, h1, h2, h3, h4, h5, h6 {
+    font-family: sans-serif;
+}
+
+#controlsDiv {
+    margin: 6px;
+}
+
+#connectionText {
+    background-color: rgb(239, 89, 75);
+    border: none;
+    border-radius: 4px;
+    padding: 8px;
+    display: inline-block;
+    margin: 4px;
+}
+
+#startButton {
+    padding: 4px;
+    margin: 6px;
+}
+
+#fftCanvas {
+    border-radius: 16px;
+    margin: 6px;
+}
+
+#bandwidthCanvas {
+    border: grey;
+    border-style: solid;
+    border-radius: 8px;
+    margin: 6px;
+}
+
+#streamStateText {
+    background-color: rgb(93, 165, 93);
+    border: none;
+    border-radius: 8px;
+    padding: 10px 20px;
+    display: inline-block;
+    margin: 6px;
+}
+
+#connectionStateText {
+    background-color: rgb(112, 146, 206);
+    border: none;
+    border-radius: 8px;
+    padding: 10px 20px;
+    display: inline-block;
+    margin: 6px;
+}
+
+#propertiesTable {
+    border: grey;
+    border-style: solid;
+    border-radius: 4px;
+    padding: 4px;
+    margin: 6px;
+    margin-left: 0;
+}
+
+th, td {
+    padding-left: 6px;
+    padding-right: 6px;
+}
+
+.properties td:nth-child(even) {
+    background-color: #d6eeee;
+    font-family: monospace;
+}
+
+.properties td:nth-child(odd) {
+    font-weight: bold;
+}
+
+.properties tr td:nth-child(2) { width: 150px; }

apps/speaker/speaker.html

@@ -0,0 +1,35 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Bumble Speaker</title>
+  <script src="speaker.js"></script>
+  <link rel="stylesheet" href="speaker.css">
+</head>
+<body>
+  <h1><img src="logo.svg" width=100 height=100 style="vertical-align:middle" alt=""/>Bumble Virtual Speaker</h1>
+  <div id="connectionText"></div>
+  <div id="speaker">
+    <table><tr>
+      <td>
+        <table id="propertiesTable" class="properties">
+          <tr><td>Codec</td><td><span id="codecText"></span></td></tr>
+          <tr><td>Packets</td><td><span id="packetsReceivedText"></span></td></tr>
+          <tr><td>Bytes</td><td><span id="bytesReceivedText"></span></td></tr>
+          <tr><td>Bitrate</td><td><span id="bitrate"></span></td></tr>
+        </table>
+      </td>
+      <td>
+        <canvas id="bandwidthCanvas" width="500", height="100">Bandwidth Graph</canvas>
+      </td>
+    </tr></table>
+    <span id="streamStateText">IDLE</span>
+    <span id="connectionStateText">NOT CONNECTED</span>
+    <div id="controlsDiv">
+        <button id="audioOnButton">Audio On</button>
+        <span id="audioSupportMessageText"></span>
+    </div>
+    <canvas id="fftCanvas" width="1024", height="300">Audio Frequencies Animation</canvas>
+    <audio id="audio"></audio>
+  </div>
+</body>
+</html>

apps/speaker/speaker.js

@@ -0,0 +1,366 @@
+(function () {
+    'use strict';
+
+const channelUrl = ((window.location.protocol === "https:") ? "wss://" : "ws://") + window.location.host + "/channel";
+let channelSocket;
+let connectionText;
+let codecText;
+let packetsReceivedText;
+let bytesReceivedText;
+let bitrateText;
+let streamStateText;
+let connectionStateText;
+let controlsDiv;
+let audioOnButton;
+let audioDecoder;
+let audioCodec;
+let audioContext;
+let audioAnalyzer;
+let audioFrequencyBinCount;
+let audioFrequencyData;
+let nextAudioStartPosition = 0;
+let audioStartTime = 0;
+let packetsReceived = 0;
+let bytesReceived = 0;
+let audioState = "stopped";
+let streamState = "IDLE";
+let audioSupportMessageText;
+let fftCanvas;
+let fftCanvasContext;
+let bandwidthCanvas;
+let bandwidthCanvasContext;
+let bandwidthBinCount;
+let bandwidthBins = [];
+let bitrateSamples = [];
+
+const FFT_WIDTH = 800;
+const FFT_HEIGHT = 256;
+const BANDWIDTH_WIDTH = 500;
+const BANDWIDTH_HEIGHT = 100;
+const BITRATE_WINDOW = 30;
+
+function init() {
+    initUI();
+    initAudioContext();
+    initAnalyzer();
+
+    connect();
+}
+
+function initUI() {
+    controlsDiv = document.getElementById("controlsDiv");
+    controlsDiv.style.visibility = "hidden";
+    connectionText = document.getElementById("connectionText");
+    audioOnButton = document.getElementById("audioOnButton");
+    codecText = document.getElementById("codecText");
+    packetsReceivedText = document.getElementById("packetsReceivedText");
+    bytesReceivedText = document.getElementById("bytesReceivedText");
+    bitrateText = document.getElementById("bitrate");
+    streamStateText = document.getElementById("streamStateText");
+    connectionStateText = document.getElementById("connectionStateText");
+    audioSupportMessageText = document.getElementById("audioSupportMessageText");
+
+    audioOnButton.onclick = () => startAudio();
+
+    setConnectionText("");
+
+    requestAnimationFrame(onAnimationFrame);
+}
+
+function initAudioContext() {
+    audioContext = new AudioContext();
+    audioContext.onstatechange = () => console.log("AudioContext state:", audioContext.state);
+}
+
+function initAnalyzer() {
+    fftCanvas = document.getElementById("fftCanvas");
+    fftCanvas.width = FFT_WIDTH
+    fftCanvas.height = FFT_HEIGHT
+    fftCanvasContext = fftCanvas.getContext('2d');
+    fftCanvasContext.fillStyle = "rgb(0, 0, 0)";
+    fftCanvasContext.fillRect(0, 0, FFT_WIDTH, FFT_HEIGHT);
+
+    bandwidthCanvas = document.getElementById("bandwidthCanvas");
+    bandwidthCanvas.width = BANDWIDTH_WIDTH
+    bandwidthCanvas.height = BANDWIDTH_HEIGHT
+    bandwidthCanvasContext = bandwidthCanvas.getContext('2d');
+    bandwidthCanvasContext.fillStyle = "rgb(255, 255, 255)";
+    bandwidthCanvasContext.fillRect(0, 0, BANDWIDTH_WIDTH, BANDWIDTH_HEIGHT);
+    bandwidthBinCount = BANDWIDTH_WIDTH / 2;
+    bandwidthBins = [];
+    bitrateSamples = [];
+
+    audioAnalyzer = audioContext.createAnalyser();
+    audioAnalyzer.fftSize = 128;
+    audioFrequencyBinCount = audioAnalyzer.frequencyBinCount;
+    audioFrequencyData = new Uint8Array(audioFrequencyBinCount);
+
+    audioAnalyzer.connect(audioContext.destination)
+}
+
+function setConnectionText(message) {
+    connectionText.innerText = message;
+    if (message.length == 0) {
+        connectionText.style.display = "none";
+    } else {
+        connectionText.style.display = "inline-block";
+    }
+}
+
+function setStreamState(state) {
+    streamState = state;
+    streamStateText.innerText = streamState;
+}
+
+function onAnimationFrame() {
+    // FFT
+    if (audioAnalyzer !== undefined) {
+        audioAnalyzer.getByteFrequencyData(audioFrequencyData);
+        fftCanvasContext.fillStyle = "rgb(0, 0, 0)";
+        fftCanvasContext.fillRect(0, 0, FFT_WIDTH, FFT_HEIGHT);
+        const barCount = audioFrequencyBinCount;
+        const barWidth = (FFT_WIDTH / audioFrequencyBinCount) - 1;
+        for (let bar = 0; bar < barCount; bar++) {
+            const barHeight = audioFrequencyData[bar];
+            fftCanvasContext.fillStyle = `rgb(${barHeight / 256 * 200 + 50}, 50, ${50 + 2 * bar})`;
+            fftCanvasContext.fillRect(bar * (barWidth + 1), FFT_HEIGHT - barHeight, barWidth, barHeight);
+        }
+    }
+
+    // Bandwidth
+    bandwidthCanvasContext.fillStyle = "rgb(255, 255, 255)";
+    bandwidthCanvasContext.fillRect(0, 0, BANDWIDTH_WIDTH, BANDWIDTH_HEIGHT);
+    bandwidthCanvasContext.fillStyle = `rgb(100, 100, 100)`;
+    for (let t = 0; t < bandwidthBins.length; t++) {
+        const bytesReceived = bandwidthBins[t]
+        const lineHeight = (bytesReceived / 1000) * BANDWIDTH_HEIGHT;
+        bandwidthCanvasContext.fillRect(t * 2, BANDWIDTH_HEIGHT - lineHeight, 2, lineHeight);
+    }
+
+    // Display again at the next frame
+    requestAnimationFrame(onAnimationFrame);
+}
+
+async function startAudio() {
+    try {
+        console.log("starting audio...");
+        audioOnButton.disabled = true;
+        audioState = "starting";
+        audioContext.resume();
+        console.log("audio started");
+        audioState = "playing";
+    } catch(error) {
+        console.error(`play failed: ${error}`);
+        audioState = "stopped";
+        audioOnButton.disabled = false;
+    }
+}
+
+function onDecodedAudio(audioData) {
+    const bufferSource = audioContext.createBufferSource()
+
+    const now = audioContext.currentTime;
+    let nextAudioStartTime = audioStartTime + (nextAudioStartPosition / audioData.sampleRate);
+    if (nextAudioStartTime < now) {
+        console.log("starting new audio time base")
+        audioStartTime = now;
+        nextAudioStartTime = now;
+        nextAudioStartPosition = 0;
+    } else {
+        console.log(`audio buffer scheduled in ${nextAudioStartTime - now}`)
+    }
+
+    const audioBuffer = audioContext.createBuffer(
+        audioData.numberOfChannels,
+        audioData.numberOfFrames,
+        audioData.sampleRate
+    );
+
+    for (let channel = 0; channel < audioData.numberOfChannels; channel++) {
+        audioData.copyTo(
+            audioBuffer.getChannelData(channel),
+            {
+                planeIndex: channel,
+                format: "f32-planar"
+            }
+        )
+    }
+
+    bufferSource.buffer = audioBuffer;
+    bufferSource.connect(audioAnalyzer)
+    bufferSource.start(nextAudioStartTime);
+    nextAudioStartPosition += audioData.numberOfFrames;
+}
+
+function onCodecError(error) {
+    console.log("Codec error:", error)
+}
+
+async function onAudioPacket(packet) {
+    packetsReceived += 1;
+    packetsReceivedText.innerText = packetsReceived;
+    bytesReceived += packet.byteLength;
+    bytesReceivedText.innerText = bytesReceived;
+
+    bandwidthBins[bandwidthBins.length] = packet.byteLength;
+    if (bandwidthBins.length > bandwidthBinCount) {
+        bandwidthBins.shift();
+    }
+    bitrateSamples[bitrateSamples.length] = {ts: Date.now(), bytes: packet.byteLength}
+    if (bitrateSamples.length > BITRATE_WINDOW) {
+        bitrateSamples.shift();
+    }
+    if (bitrateSamples.length >= 2) {
+        const windowBytes = bitrateSamples.reduce((accumulator, x) => accumulator + x.bytes, 0) - bitrateSamples[0].bytes;
+        const elapsed = bitrateSamples[bitrateSamples.length-1].ts - bitrateSamples[0].ts;
+        const bitrate = Math.floor(8 * windowBytes / elapsed)
+        bitrateText.innerText = `${bitrate} kb/s`
+    }
+
+    if (audioState == "stopped") {
+        return;
+    }
+
+    if (audioDecoder === undefined) {
+        let audioConfig;
+        if (audioCodec == 'aac') {
+            audioConfig = {
+                codec: 'mp4a.40.2',
+                sampleRate: 44100, // ignored
+                numberOfChannels: 2, // ignored
+            }
+        } else if (audioCodec == 'opus') {
+            audioConfig = {
+                codec: 'opus',
+                sampleRate: 48000, // ignored
+                numberOfChannels: 2, // ignored
+            }
+        }
+        audioDecoder = new AudioDecoder({ output: onDecodedAudio, error: onCodecError });
+        audioDecoder.configure(audioConfig)
+    }
+
+    const encodedAudio = new EncodedAudioChunk({
+        type: "key",
+        data: packet,
+        timestamp: 0,
+        transfer: [packet],
+    });
+
+    audioDecoder.decode(encodedAudio);
+}
+
+function onChannelOpen() {
+    console.log('channel OPEN');
+    setConnectionText("");
+    controlsDiv.style.visibility = "visible";
+
+    // Handshake with the backend.
+    sendMessage({
+        type: "hello"
+    });
+}
+
+function onChannelClose() {
+    console.log('channel CLOSED');
+    setConnectionText("Connection to CLI app closed, restart it and reload this page.");
+    controlsDiv.style.visibility = "hidden";
+}
+
+function onChannelError(error) {
+    console.log(`channel ERROR: ${error}`);
+    setConnectionText(`Connection to CLI app error ({${error}}), restart it and reload this page.`);
+    controlsDiv.style.visibility = "hidden";
+}
+
+function onChannelMessage(message) {
+    if (typeof message.data === 'string' || message.data instanceof String) {
+        // JSON message.
+        const jsonMessage = JSON.parse(message.data);
+        console.log(`channel MESSAGE: ${message.data}`);
+
+        // Dispatch the message.
+        const handlerName = `on${jsonMessage.type.charAt(0).toUpperCase()}${jsonMessage.type.slice(1)}Message`
+        const handler = messageHandlers[handlerName];
+        if (handler !== undefined) {
+            const params = jsonMessage.params;
+            if (params === undefined) {
+                params = {};
+            }
+            handler(params);
+        } else {
+            console.warn(`unhandled message: ${jsonMessage.type}`)
+        }
+    } else {
+        // BINARY audio data.
+        onAudioPacket(message.data);
+    }
+}
+
+async function onHelloMessage(params) {
+    codecText.innerText = params.codec;
+
+    if (params.codec == "aac" || params.codec == "opus") {
+        audioCodec = params.codec
+        audioSupportMessageText.innerText = "";
+        audioSupportMessageText.style.display = "none";
+    } else {
+        audioOnButton.disabled = true;
+        audioSupportMessageText.innerText = "Only AAC and Opus can be played, audio will be disabled";
+        audioSupportMessageText.style.display = "inline-block";
+    }
+
+    if (params.streamState) {
+        setStreamState(params.streamState);
+    }
+}
+
+function onStartMessage(params) {
+    setStreamState("STARTED");
+}
+
+function onStopMessage(params) {
+    setStreamState("STOPPED");
+}
+
+function onSuspendMessage(params) {
+    setStreamState("SUSPENDED");
+}
+
+function onConnectionMessage(params) {
+    connectionStateText.innerText = `CONNECTED: ${params.peer_name} (${params.peer_address})`;
+}
+
+function onDisconnectionMessage(params) {
+    connectionStateText.innerText = "DISCONNECTED";
+}
+
+function sendMessage(message) {
+    channelSocket.send(JSON.stringify(message));
+}
+
+function connect() {
+    console.log("connecting to CLI app");
+
+    channelSocket = new WebSocket(channelUrl);
+    channelSocket.binaryType = "arraybuffer";
+    channelSocket.onopen = onChannelOpen;
+    channelSocket.onclose = onChannelClose;
+    channelSocket.onerror = onChannelError;
+    channelSocket.onmessage = onChannelMessage;
+}
+
+const messageHandlers = {
+    onHelloMessage,
+    onStartMessage,
+    onStopMessage,
+    onSuspendMessage,
+    onConnectionMessage,
+    onDisconnectionMessage
+}
+
+window.onload = (event) => {
+    init();
+}
+
+}());

apps/speaker/speaker.py

@@ -0,0 +1,841 @@
+# 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 asyncio
+import asyncio.subprocess
+import enum
+import json
+import logging
+import pathlib
+import subprocess
+import weakref
+from importlib import resources
+
+import aiohttp
+import click
+from aiohttp import web
+
+import bumble
+import bumble.logging
+from bumble.a2dp import (
+    A2DP_MPEG_2_4_AAC_CODEC_TYPE,
+    A2DP_NON_A2DP_CODEC_TYPE,
+    A2DP_SBC_CODEC_TYPE,
+    AacMediaCodecInformation,
+    OpusMediaCodecInformation,
+    SbcMediaCodecInformation,
+    make_audio_sink_service_sdp_records,
+)
+from bumble.avdtp import (
+    AVDTP_AUDIO_MEDIA_TYPE,
+    Listener,
+    MediaCodecCapabilities,
+    Protocol,
+)
+from bumble.codecs import AacAudioRtpPacket
+from bumble.colors import color
+from bumble.core import CommandTimeoutError, PhysicalTransport
+from bumble.device import Connection, Device, DeviceConfiguration
+from bumble.hci import HCI_StatusError
+from bumble.pairing import PairingConfig
+from bumble.rtp import MediaPacket
+from bumble.sdp import ServiceAttribute
+from bumble.transport import open_transport
+from bumble.utils import AsyncRunner
+
+# -----------------------------------------------------------------------------
+# Logging
+# -----------------------------------------------------------------------------
+logger = logging.getLogger(__name__)
+
+
+# -----------------------------------------------------------------------------
+# Constants
+# -----------------------------------------------------------------------------
+DEFAULT_UI_PORT = 7654
+
+
+# -----------------------------------------------------------------------------
+class AudioExtractor:
+    @staticmethod
+    def create(codec: str):
+        if codec == 'aac':
+            return AacAudioExtractor()
+        if codec == 'sbc':
+            return SbcAudioExtractor()
+        if codec == 'opus':
+            return OpusAudioExtractor()
+
+    def extract_audio(self, packet: MediaPacket) -> bytes:
+        raise NotImplementedError()
+
+
+# -----------------------------------------------------------------------------
+class AacAudioExtractor:
+    def extract_audio(self, packet: MediaPacket) -> bytes:
+        return AacAudioRtpPacket.from_bytes(packet.payload).to_adts()
+
+
+# -----------------------------------------------------------------------------
+class SbcAudioExtractor:
+    def extract_audio(self, packet: MediaPacket) -> bytes:
+        # header = packet.payload[0]
+        # fragmented = header >> 7
+        # start = (header >> 6) & 0x01
+        # last = (header >> 5) & 0x01
+        # number_of_frames = header & 0x0F
+
+        # TODO: support fragmented payloads
+        return packet.payload[1:]
+
+
+# -----------------------------------------------------------------------------
+class OpusAudioExtractor:
+    def extract_audio(self, packet: MediaPacket) -> bytes:
+        # TODO: parse fields
+        return packet.payload[1:]
+
+
+# -----------------------------------------------------------------------------
+class Output:
+    async def start(self) -> None:
+        pass
+
+    async def stop(self) -> None:
+        pass
+
+    async def suspend(self) -> None:
+        pass
+
+    async def on_connection(self, connection: Connection) -> None:
+        pass
+
+    async def on_disconnection(self, reason: int) -> None:
+        pass
+
+    def on_rtp_packet(self, packet: MediaPacket) -> None:
+        pass
+
+
+# -----------------------------------------------------------------------------
+class FileOutput(Output):
+    filename: str
+    codec: str
+    extractor: AudioExtractor
+
+    def __init__(self, filename, codec):
+        self.filename = filename
+        self.codec = codec
+        self.file = open(filename, 'wb')
+        self.extractor = AudioExtractor.create(codec)
+
+    def on_rtp_packet(self, packet: MediaPacket) -> None:
+        self.file.write(self.extractor.extract_audio(packet))
+
+
+# -----------------------------------------------------------------------------
+class QueuedOutput(Output):
+    MAX_QUEUE_SIZE = 32768
+
+    packets: asyncio.Queue
+    extractor: AudioExtractor
+    packet_pump_task: asyncio.Task | None
+    started: bool
+
+    def __init__(self, extractor):
+        self.extractor = extractor
+        self.packets = asyncio.Queue()
+        self.packet_pump_task = None
+        self.started = False
+
+    async def start(self):
+        if self.started:
+            return
+
+        self.packet_pump_task = asyncio.create_task(self.pump_packets())
+
+    async def pump_packets(self):
+        while True:
+            packet = await self.packets.get()
+            await self.on_audio_packet(packet)
+
+    async def on_audio_packet(self, packet: bytes) -> None:
+        pass
+
+    def on_rtp_packet(self, packet: MediaPacket) -> None:
+        if self.packets.qsize() > self.MAX_QUEUE_SIZE:
+            logger.debug("queue full, dropping")
+            return
+
+        self.packets.put_nowait(self.extractor.extract_audio(packet))
+
+
+# -----------------------------------------------------------------------------
+class WebSocketOutput(QueuedOutput):
+    def __init__(self, codec, send_audio, send_message):
+        super().__init__(AudioExtractor.create(codec))
+        self.send_audio = send_audio
+        self.send_message = send_message
+
+    async def on_connection(self, connection: Connection) -> None:
+        try:
+            await connection.request_remote_name()
+        except HCI_StatusError:
+            pass
+        peer_name = '' if connection.peer_name is None else connection.peer_name
+        peer_address = connection.peer_address.to_string(False)
+        await self.send_message(
+            'connection',
+            peer_address=peer_address,
+            peer_name=peer_name,
+        )
+
+    async def on_disconnection(self, reason) -> None:
+        await self.send_message('disconnection')
+
+    async def on_audio_packet(self, packet: bytes) -> None:
+        await self.send_audio(packet)
+
+    async def start(self):
+        await super().start()
+        await self.send_message('start')
+
+    async def stop(self):
+        await super().stop()
+        await self.send_message('stop')
+
+    async def suspend(self):
+        await super().suspend()
+        await self.send_message('suspend')
+
+
+# -----------------------------------------------------------------------------
+class FfplayOutput(QueuedOutput):
+    MAX_QUEUE_SIZE = 32768
+
+    subprocess: asyncio.subprocess.Process | None
+    ffplay_task: asyncio.Task | None
+
+    def __init__(self, codec: str) -> None:
+        super().__init__(AudioExtractor.create(codec))
+        self.subprocess = None
+        self.ffplay_task = None
+        self.codec = codec
+
+    async def start(self):
+        if self.started:
+            return
+
+        await super().start()
+
+        self.subprocess = await asyncio.create_subprocess_shell(
+            f'ffplay -probesize 32 -f {self.codec} pipe:0',
+            stdin=asyncio.subprocess.PIPE,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+        )
+
+        self.ffplay_task = asyncio.create_task(self.monitor_ffplay())
+
+    async def stop(self):
+        # TODO
+        pass
+
+    async def suspend(self):
+        # TODO
+        pass
+
+    async def monitor_ffplay(self):
+        async def read_stream(name, stream):
+            while True:
+                data = await stream.read()
+                logger.debug(f'{name}:', data)
+
+        await asyncio.wait(
+            [
+                asyncio.create_task(
+                    read_stream('[ffplay stdout]', self.subprocess.stdout)
+                ),
+                asyncio.create_task(
+                    read_stream('[ffplay stderr]', self.subprocess.stderr)
+                ),
+                asyncio.create_task(self.subprocess.wait()),
+            ]
+        )
+        logger.debug("FFPLAY done")
+
+    async def on_audio_packet(self, packet):
+        try:
+            self.subprocess.stdin.write(packet)
+        except Exception:
+            logger.warning('!!!! exception while sending audio to ffplay pipe')
+
+
+# -----------------------------------------------------------------------------
+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 = web.Application()
+        app.add_routes(
+            [
+                web.get('/', self.get_static),
+                web.get('/speaker.html', self.get_static),
+                web.get('/speaker.js', self.get_static),
+                web.get('/speaker.css', self.get_static),
+                web.get('/logo.svg', self.get_static),
+                web.get('/channel', self.get_channel),
+            ]
+        )
+
+        runner = web.AppRunner(app)
+        await runner.setup()
+        site = 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 = '/speaker.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.speaker")
+            .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 = 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:
+    class StreamState(enum.Enum):
+        IDLE = 0
+        STOPPED = 1
+        STARTED = 2
+        SUSPENDED = 3
+
+    def __init__(
+        self,
+        device_config,
+        transport,
+        codec,
+        sampling_frequencies,
+        bitrate,
+        vbr,
+        discover,
+        outputs,
+        ui_port,
+    ):
+        self.device_config = device_config
+        self.transport = transport
+        self.codec = codec
+        self.sampling_frequencies = sampling_frequencies
+        self.bitrate = bitrate
+        self.vbr = vbr
+        self.discover = discover
+        self.ui_port = ui_port
+        self.device = None
+        self.connection = None
+        self.listener = None
+        self.packets_received = 0
+        self.bytes_received = 0
+        self.stream_state = Speaker.StreamState.IDLE
+        self.outputs = []
+        for output in outputs:
+            if output == '@ffplay':
+                self.outputs.append(FfplayOutput(codec))
+                continue
+
+            # Default to FileOutput
+            self.outputs.append(FileOutput(output, codec))
+
+        # Create an HTTP server for the UI
+        self.ui_server = UiServer(speaker=self, port=ui_port)
+
+    def sdp_records(self) -> dict[int, list[ServiceAttribute]]:
+        service_record_handle = 0x00010001
+        return {
+            service_record_handle: make_audio_sink_service_sdp_records(
+                service_record_handle
+            )
+        }
+
+    def codec_capabilities(self) -> MediaCodecCapabilities:
+        if self.codec == 'aac':
+            return self.aac_codec_capabilities()
+
+        if self.codec == 'sbc':
+            return self.sbc_codec_capabilities()
+
+        if self.codec == 'opus':
+            return self.opus_codec_capabilities()
+
+        raise RuntimeError('unsupported codec')
+
+    def aac_codec_capabilities(self) -> MediaCodecCapabilities:
+        supported_sampling_frequencies = AacMediaCodecInformation.SamplingFrequency(0)
+        for sampling_frequency in self.sampling_frequencies or [
+            8000,
+            11025,
+            12000,
+            16000,
+            22050,
+            24000,
+            32000,
+            44100,
+            48000,
+        ]:
+            supported_sampling_frequencies |= (
+                AacMediaCodecInformation.SamplingFrequency.from_int(sampling_frequency)
+            )
+        return MediaCodecCapabilities(
+            media_type=AVDTP_AUDIO_MEDIA_TYPE,
+            media_codec_type=A2DP_MPEG_2_4_AAC_CODEC_TYPE,
+            media_codec_information=AacMediaCodecInformation(
+                object_type=AacMediaCodecInformation.ObjectType.MPEG_2_AAC_LC,
+                sampling_frequency=supported_sampling_frequencies,
+                channels=AacMediaCodecInformation.Channels.MONO
+                | AacMediaCodecInformation.Channels.STEREO,
+                vbr=1 if self.vbr else 0,
+                bitrate=self.bitrate or 256000,
+            ),
+        )
+
+    def sbc_codec_capabilities(self) -> MediaCodecCapabilities:
+        supported_sampling_frequencies = SbcMediaCodecInformation.SamplingFrequency(0)
+        for sampling_frequency in self.sampling_frequencies or [
+            16000,
+            32000,
+            44100,
+            48000,
+        ]:
+            supported_sampling_frequencies |= (
+                SbcMediaCodecInformation.SamplingFrequency.from_int(sampling_frequency)
+            )
+        return MediaCodecCapabilities(
+            media_type=AVDTP_AUDIO_MEDIA_TYPE,
+            media_codec_type=A2DP_SBC_CODEC_TYPE,
+            media_codec_information=SbcMediaCodecInformation(
+                sampling_frequency=supported_sampling_frequencies,
+                channel_mode=SbcMediaCodecInformation.ChannelMode.MONO
+                | SbcMediaCodecInformation.ChannelMode.DUAL_CHANNEL
+                | SbcMediaCodecInformation.ChannelMode.STEREO
+                | SbcMediaCodecInformation.ChannelMode.JOINT_STEREO,
+                block_length=SbcMediaCodecInformation.BlockLength.BL_4
+                | SbcMediaCodecInformation.BlockLength.BL_8
+                | SbcMediaCodecInformation.BlockLength.BL_12
+                | SbcMediaCodecInformation.BlockLength.BL_16,
+                subbands=SbcMediaCodecInformation.Subbands.S_4
+                | SbcMediaCodecInformation.Subbands.S_8,
+                allocation_method=SbcMediaCodecInformation.AllocationMethod.LOUDNESS
+                | SbcMediaCodecInformation.AllocationMethod.SNR,
+                minimum_bitpool_value=2,
+                maximum_bitpool_value=53,
+            ),
+        )
+
+    def opus_codec_capabilities(self) -> MediaCodecCapabilities:
+        supported_sampling_frequencies = OpusMediaCodecInformation.SamplingFrequency(0)
+        for sampling_frequency in self.sampling_frequencies or [48000]:
+            supported_sampling_frequencies |= (
+                OpusMediaCodecInformation.SamplingFrequency.from_int(sampling_frequency)
+            )
+        return MediaCodecCapabilities(
+            media_type=AVDTP_AUDIO_MEDIA_TYPE,
+            media_codec_type=A2DP_NON_A2DP_CODEC_TYPE,
+            media_codec_information=OpusMediaCodecInformation(
+                frame_size=OpusMediaCodecInformation.FrameSize.FS_10MS
+                | OpusMediaCodecInformation.FrameSize.FS_20MS,
+                channel_mode=OpusMediaCodecInformation.ChannelMode.MONO
+                | OpusMediaCodecInformation.ChannelMode.STEREO
+                | OpusMediaCodecInformation.ChannelMode.DUAL_MONO,
+                sampling_frequency=supported_sampling_frequencies,
+            ),
+        )
+
+    async def dispatch_to_outputs(self, function):
+        for output in self.outputs:
+            await function(output)
+
+    def on_bluetooth_connection(self, connection):
+        print(f'Connection: {connection}')
+        self.connection = connection
+        connection.on('disconnection', self.on_bluetooth_disconnection)
+        AsyncRunner.spawn(
+            self.dispatch_to_outputs(lambda output: output.on_connection(connection))
+        )
+
+    def on_bluetooth_disconnection(self, reason):
+        print(f'Disconnection ({reason})')
+        self.connection = None
+        AsyncRunner.spawn(self.advertise())
+        AsyncRunner.spawn(
+            self.dispatch_to_outputs(lambda output: output.on_disconnection(reason))
+        )
+
+    def on_avdtp_connection(self, protocol):
+        print('Audio Stream Open')
+
+        # Add a sink endpoint to the server
+        sink = protocol.add_sink(self.codec_capabilities())
+        sink.on('start', self.on_sink_start)
+        sink.on('stop', self.on_sink_stop)
+        sink.on('suspend', self.on_sink_suspend)
+        sink.on('configuration', lambda: self.on_sink_configuration(sink.configuration))
+        sink.on('rtp_packet', self.on_rtp_packet)
+        sink.on('rtp_channel_open', self.on_rtp_channel_open)
+        sink.on('rtp_channel_close', self.on_rtp_channel_close)
+
+        # Listen for close events
+        protocol.on('close', self.on_avdtp_close)
+
+        # Discover all endpoints on the remote device is requested
+        if self.discover:
+            AsyncRunner.spawn(self.discover_remote_endpoints(protocol))
+
+    def on_avdtp_close(self):
+        print("Audio Stream Closed")
+
+    def on_sink_start(self):
+        print("Sink Started\u001b[0K")
+        self.stream_state = self.StreamState.STARTED
+        AsyncRunner.spawn(self.dispatch_to_outputs(lambda output: output.start()))
+
+    def on_sink_stop(self):
+        print("Sink Stopped\u001b[0K")
+        self.stream_state = self.StreamState.STOPPED
+        AsyncRunner.spawn(self.dispatch_to_outputs(lambda output: output.stop()))
+
+    def on_sink_suspend(self):
+        print("Sink Suspended\u001b[0K")
+        self.stream_state = self.StreamState.SUSPENDED
+        AsyncRunner.spawn(self.dispatch_to_outputs(lambda output: output.suspend()))
+
+    def on_sink_configuration(self, config):
+        print("Sink Configuration:")
+        print('\n'.join(["  " + str(capability) for capability in config]))
+
+    def on_rtp_channel_open(self):
+        print("RTP Channel Open")
+
+    def on_rtp_channel_close(self):
+        print("RTP Channel Closed")
+        self.stream_state = self.StreamState.IDLE
+
+    def on_rtp_packet(self, packet):
+        self.packets_received += 1
+        self.bytes_received += len(packet.payload)
+        print(
+            f'[{self.bytes_received} bytes in {self.packets_received} packets] {packet}',
+            end='\r',
+        )
+
+        for output in self.outputs:
+            output.on_rtp_packet(packet)
+
+    async def advertise(self):
+        await self.device.set_discoverable(True)
+        await self.device.set_connectable(True)
+
+    async def connect(self, address):
+        # Connect to the source
+        print(f'=== Connecting to {address}...')
+        connection = await self.device.connect(
+            address, transport=PhysicalTransport.BR_EDR
+        )
+        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')
+
+        protocol = await Protocol.connect(connection)
+        self.listener.set_server(connection, protocol)
+        self.on_avdtp_connection(protocol)
+
+    async def discover_remote_endpoints(self, protocol):
+        endpoints = await protocol.discover_remote_endpoints()
+        print(f'@@@ Found {len(endpoints)} endpoints')
+        for endpoint in endpoints:
+            print('@@@', endpoint)
+
+    async def run(self, connect_address):
+        await self.ui_server.start_http()
+        self.outputs.append(
+            WebSocketOutput(
+                self.codec, self.ui_server.send_audio, self.ui_server.send_message
+            )
+        )
+
+        async with await open_transport(self.transport) as (hci_source, hci_sink):
+            # Create a device
+            device_config = DeviceConfiguration()
+            if self.device_config:
+                device_config.load_from_file(self.device_config)
+            else:
+                device_config.name = "Bumble Speaker"
+                device_config.class_of_device = 0x240414
+                device_config.keystore = "JsonKeyStore"
+
+            device_config.classic_enabled = True
+            device_config.le_enabled = False
+            self.device = Device.from_config_with_hci(
+                device_config, hci_source, hci_sink
+            )
+
+            # Setup the SDP to expose the sink service
+            self.device.sdp_service_records = self.sdp_records()
+
+            # Don't require MITM when pairing.
+            self.device.pairing_config_factory = lambda connection: PairingConfig(
+                mitm=False
+            )
+
+            # Start the controller
+            await self.device.power_on()
+
+            # Print some of the config/properties
+            print("Speaker Name:", color(device_config.name, 'yellow'))
+            print(
+                "Speaker Bluetooth Address:",
+                color(
+                    self.device.public_address.to_string(with_type_qualifier=False),
+                    'yellow',
+                ),
+            )
+
+            # Listen for Bluetooth connections
+            self.device.on('connection', self.on_bluetooth_connection)
+
+            # Create a listener to wait for AVDTP connections
+            self.listener = Listener.for_device(self.device)
+            self.listener.on('connection', self.on_avdtp_connection)
+
+            print(f'Speaker ready to play, codec={color(self.codec, "cyan")}')
+
+            if connect_address:
+                # Connect to the source
+                try:
+                    await self.connect(connect_address)
+                except CommandTimeoutError:
+                    print(color("Connection timed out", "red"))
+                    return
+            else:
+                # Start being discoverable and connectable
+                print("Waiting for connection...")
+                await self.advertise()
+
+            await hci_source.wait_for_termination()
+
+        for output in self.outputs:
+            await output.stop()
+
+
+# -----------------------------------------------------------------------------
+@click.group()
+@click.pass_context
+def speaker_cli(ctx, device_config):
+    ctx.ensure_object(dict)
+    ctx.obj['device_config'] = device_config
+
+
+@click.command()
+@click.option(
+    '--codec',
+    type=click.Choice(['sbc', 'aac', 'opus']),
+    default='aac',
+    show_default=True,
+)
+@click.option(
+    '--sampling-frequency',
+    metavar='SAMPLING-FREQUENCY',
+    type=int,
+    multiple=True,
+    help='Enable a sampling frequency (may be specified more than once)',
+)
+@click.option(
+    '--bitrate',
+    metavar='BITRATE',
+    type=int,
+    help='Supported bitrate (AAC only)',
+)
+@click.option(
+    '--vbr/--no-vbr', is_flag=True, default=True, help='Enable VBR (AAC only)'
+)
+@click.option(
+    '--discover', is_flag=True, help='Discover remote endpoints once connected'
+)
+@click.option(
+    '--output',
+    multiple=True,
+    metavar='NAME',
+    help=(
+        'Send audio to this named output '
+        '(may be used more than once for multiple outputs)'
+    ),
+)
+@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(
+    '--connect',
+    'connect_address',
+    metavar='ADDRESS_OR_NAME',
+    help='Address or name to connect to',
+)
+@click.option('--device-config', metavar='FILENAME', help='Device configuration file')
+@click.argument('transport')
+def speaker(
+    transport,
+    codec,
+    sampling_frequency,
+    bitrate,
+    vbr,
+    connect_address,
+    discover,
+    output,
+    ui_port,
+    device_config,
+):
+    """Run the speaker."""
+
+    if '@ffplay' in output:
+        # Check if ffplay is installed
+        try:
+            subprocess.run(['ffplay', '-version'], capture_output=True, check=True)
+        except FileNotFoundError:
+            print(
+                color('ffplay not installed, @ffplay output will be disabled', 'yellow')
+            )
+            output = list(filter(lambda x: x != '@ffplay', output))
+
+    asyncio.run(
+        Speaker(
+            device_config,
+            transport,
+            codec,
+            sampling_frequency,
+            bitrate,
+            vbr,
+            discover,
+            output,
+            ui_port,
+        ).run(connect_address)
+    )
+
+
+# -----------------------------------------------------------------------------
+def main():
+    bumble.logging.setup_basic_logging('WARNING')
+    speaker()
+
+
+# -----------------------------------------------------------------------------
+if __name__ == "__main__":
+    main()  # pylint: disable=no-value-for-parameter

apps/unbond.py

@@ -16,14 +16,15 @@
 # Imports
 # -----------------------------------------------------------------------------
 import asyncio
-import os
-import logging
+
 import click
 
+import bumble.logging
 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:
@@ -67,7 +68,7 @@ def main(keystore_file, hci_transport, device_config, address):
     instantiated.
     If no address is passed, the existing pairing keys for all addresses are printed.
     """
-    logging.basicConfig(level=os.environ.get('BUMBLE_LOGLEVEL', 'INFO').upper())
+    bumble.logging.setup_basic_logging()
 
     if not keystore_file and not hci_transport:
         print('either --keystore-file or --hci-transport must be specified.')

apps/usb_probe.py

@@ -26,15 +26,15 @@
 # -----------------------------------------------------------------------------
 # Imports
 # -----------------------------------------------------------------------------
-import os
-import logging
+from typing import Any
+
 import click
 import usb1
 
+import bumble.logging
 from bumble.colors import color
 from bumble.transport.usb import load_libusb
 
-
 # -----------------------------------------------------------------------------
 # Constants
 # -----------------------------------------------------------------------------
@@ -168,13 +168,16 @@ def is_bluetooth_hci(device):
 # -----------------------------------------------------------------------------
 @click.command()
 @click.option('--verbose', is_flag=True, default=False, help='Print more details')
-def main(verbose):
-    logging.basicConfig(level=os.environ.get('BUMBLE_LOGLEVEL', 'WARNING').upper())
+@click.option('--hci-only', is_flag=True, default=False, help='only show HCI device')
+@click.option('--manufacturer', help='filter by manufacturer')
+@click.option('--product', help='filter by product')
+def main(verbose: bool, manufacturer: str, product: str, hci_only: bool):
+    bumble.logging.setup_basic_logging('WARNING')
 
     load_libusb()
     with usb1.USBContext() as context:
         bluetooth_device_count = 0
-        devices = {}
+        devices: dict[tuple[Any, Any], list[str | None]] = {}
 
         for device in context.getDeviceIterator(skip_on_error=True):
             device_class = device.getDeviceClass()
@@ -236,6 +239,14 @@ def main(verbose):
                         f'{basic_transport_name}/{device_serial_number}'
                     )
 
+            # Filter
+            if product and device_product != product:
+                continue
+            if manufacturer and device_manufacturer != manufacturer:
+                continue
+            if not is_bluetooth_hci(device) and hci_only:
+                continue
+
             # Print the results
             print(
                 color(

bumble/at.py

@@ -0,0 +1,90 @@
+# 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.
+
+
+from bumble import core
+
+
+class AtParsingError(core.InvalidPacketError):
+    """Error raised when parsing AT commands fails."""
+
+
+def tokenize_parameters(buffer: bytes) -> list[bytes]:
+    """Split input parameters into tokens.
+    Removes space characters outside of double quote blocks:
+    T-rec-V-25 - 5.2.1 Command line general format: "Space characters (IA5 2/0)
+    are ignored [..], unless they are embedded in numeric or string constants"
+    Raises AtParsingError in case of invalid input string."""
+
+    tokens = []
+    in_quotes = False
+    token = bytearray()
+    for b in buffer:
+        char = bytearray([b])
+
+        if in_quotes:
+            token.extend(char)
+            if char == b'"':
+                in_quotes = False
+                tokens.append(token[1:-1])
+                token = bytearray()
+        else:
+            if char == b' ':
+                pass
+            elif char == b',' or char == b')':
+                tokens.append(token)
+                tokens.append(char)
+                token = bytearray()
+            elif char == b'(':
+                if len(token) > 0:
+                    raise AtParsingError("open_paren following regular character")
+                tokens.append(char)
+            elif char == b'"':
+                if len(token) > 0:
+                    raise AtParsingError("quote following regular character")
+                in_quotes = True
+                token.extend(char)
+            else:
+                token.extend(char)
+
+    tokens.append(token)
+    return [bytes(token) for token in tokens if len(token) > 0]
+
+
+def parse_parameters(buffer: bytes) -> list[bytes | list]:
+    """Parse the parameters using the comma and parenthesis separators.
+    Raises AtParsingError in case of invalid input string."""
+
+    tokens = tokenize_parameters(buffer)
+    accumulator: list[list] = [[]]
+    current: bytes | list = b''
+
+    for token in tokens:
+        if token == b',':
+            accumulator[-1].append(current)
+            current = b''
+        elif token == b'(':
+            accumulator.append([])
+        elif token == b')':
+            if len(accumulator) < 2:
+                raise AtParsingError("close_paren without matching open_paren")
+            accumulator[-1].append(current)
+            current = accumulator.pop()
+        else:
+            current = token
+
+    accumulator[-1].append(current)
+    if len(accumulator) > 1:
+        raise AtParsingError("missing close_paren")
+    return accumulator[0]

bumble/audio/__init__.py

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

bumble/audio/io.py

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

bumble/avc.py

@@ -0,0 +1,523 @@
+# 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 bumble import core, utils
+
+
+# -----------------------------------------------------------------------------
+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(utils.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 core.InvalidArgumentError(
+                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 core.InvalidPacketError("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 or subunit_id == 7:
+            opcode_offset = 2
+        elif subunit_id == 5:
+            # Extended to the next byte
+            extension = data[2]
+            if extension == 0:
+                raise core.InvalidPacketError("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 core.InvalidPacketError("reserved subunit ID")
+        else:
+            raise core.InvalidPacketError("invalid 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: 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(utils.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(utils.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(utils.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 core.InvalidArgumentError("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,286 @@
+# 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 logging
+import struct
+from collections.abc import Callable
+from enum import IntEnum
+
+from bumble import core, l2cap
+from bumble.colors import color
+
+# -----------------------------------------------------------------------------
+# 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:
+            logger.exception(color("!!! exception in callback", "red"))
+
+        self.reset()
+
+
+# -----------------------------------------------------------------------------
+class Protocol:
+    CommandHandler = Callable[[int, bytes], None]
+    command_handlers: dict[int, CommandHandler]  # Command handlers, by PID
+    ResponseHandler = Callable[[int, bytes | None], 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(l2cap_channel.EVENT_OPEN, self.on_l2cap_channel_open)
+        l2cap_channel.on(l2cap_channel.EVENT_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
+
+            self.command_handlers[pid](transaction_label, payload)
+        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.
+            response_payload = None if ipid else payload
+            self.response_handlers[pid](transaction_label, response_payload)
+
+    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.write(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(
+            f">>> AVCTP ipid: transaction_label={transaction_label}, 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 core.InvalidArgumentError("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 core.InvalidArgumentError("response handler not registered")
+        del self.response_handlers[pid]

bumble/bridge.py

@@ -17,8 +17,8 @@
 # -----------------------------------------------------------------------------
 import logging
 
-from .hci import HCI_Packet
-from .helpers import PacketTracer
+from bumble.hci import HCI_Packet
+from bumble.helpers import PacketTracer
 
 # -----------------------------------------------------------------------------
 # Logging

bumble/codecs.py

@@ -0,0 +1,533 @@
+# 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
+
+from dataclasses import dataclass
+
+from typing_extensions import Self
+
+from bumble import core
+
+
+# -----------------------------------------------------------------------------
+class BitReader:
+    """Simple but not optimized bit stream reader."""
+
+    data: bytes
+    bytes_position: int
+    bit_position: int
+    cache: int
+    bits_cached: int
+
+    def __init__(self, data: bytes):
+        self.data = data
+        self.byte_position = 0
+        self.bit_position = 0
+        self.cache = 0
+        self.bits_cached = 0
+
+    def read(self, bits: int) -> int:
+        """ "Read up to 32 bits."""
+
+        if bits > 32:
+            raise core.InvalidArgumentError('maximum read size is 32')
+
+        if self.bits_cached >= bits:
+            # We have enough bits.
+            self.bits_cached -= bits
+            self.bit_position += bits
+            return (self.cache >> self.bits_cached) & ((1 << bits) - 1)
+
+        # Read more cache, up to 32 bits
+        feed_bytes = self.data[self.byte_position : self.byte_position + 4]
+        feed_size = len(feed_bytes)
+        feed_int = int.from_bytes(feed_bytes, byteorder='big')
+        if 8 * feed_size + self.bits_cached < bits:
+            raise core.InvalidArgumentError('trying to read past the data')
+        self.byte_position += feed_size
+
+        # Combine the new cache and the old cache
+        cache = self.cache & ((1 << self.bits_cached) - 1)
+        new_bits = bits - self.bits_cached
+        self.bits_cached = 8 * feed_size - new_bits
+        result = (feed_int >> self.bits_cached) | (cache << new_bits)
+        self.cache = feed_int
+
+        self.bit_position += bits
+        return result
+
+    def read_bytes(self, count: int):
+        if self.bit_position + 8 * count > 8 * len(self.data):
+            raise core.InvalidArgumentError('not enough data')
+
+        if self.bit_position % 8:
+            # Not byte aligned
+            result = bytearray(count)
+            for i in range(count):
+                result[i] = self.read(8)
+            return bytes(result)
+
+        # Byte aligned
+        self.byte_position = self.bit_position // 8
+        self.bits_cached = 0
+        self.cache = 0
+        offset = self.bit_position // 8
+        self.bit_position += 8 * count
+        return self.data[offset : offset + count]
+
+    def bits_left(self) -> int:
+        return (8 * len(self.data)) - self.bit_position
+
+    def skip(self, bits: int) -> None:
+        # Slow, but simple...
+        while bits:
+            if bits > 32:
+                self.read(32)
+                bits -= 32
+            else:
+                self.read(bits)
+                break
+
+
+# -----------------------------------------------------------------------------
+class BitWriter:
+    """Simple but not optimized bit stream writer."""
+
+    data: int
+    bit_count: int
+
+    def __init__(self) -> None:
+        self.data = 0
+        self.bit_count = 0
+
+    def write(self, value: int, bit_count: int) -> None:
+        self.data = (self.data << bit_count) | value
+        self.bit_count += bit_count
+
+    def write_bytes(self, data: bytes) -> None:
+        bit_count = 8 * len(data)
+        self.data = (self.data << bit_count) | int.from_bytes(data, 'big')
+        self.bit_count += bit_count
+
+    def __bytes__(self) -> bytes:
+        return (self.data << ((8 - (self.bit_count % 8)) % 8)).to_bytes(
+            (self.bit_count + 7) // 8, 'big'
+        )
+
+
+# -----------------------------------------------------------------------------
+class AacAudioRtpPacket:
+    """AAC payload encapsulated in an RTP packet payload"""
+
+    audio_mux_element: AudioMuxElement
+
+    @staticmethod
+    def read_latm_value(reader: BitReader) -> int:
+        bytes_for_value = reader.read(2)
+        value = 0
+        for _ in range(bytes_for_value + 1):
+            value = value * 256 + reader.read(8)
+        return value
+
+    @staticmethod
+    def read_audio_object_type(reader: BitReader):
+        # GetAudioObjectType - ISO/EIC 14496-3 Table 1.16
+        audio_object_type = reader.read(5)
+        if audio_object_type == 31:
+            audio_object_type = 32 + reader.read(6)
+
+        return audio_object_type
+
+    @dataclass
+    class GASpecificConfig:
+        audio_object_type: int
+        # NOTE: other fields not supported
+
+        @classmethod
+        def from_bits(
+            cls, reader: BitReader, channel_configuration: int, audio_object_type: int
+        ) -> Self:
+            # GASpecificConfig - ISO/EIC 14496-3 Table 4.1
+            reader.read(1)  # frame_length_flag
+            depends_on_core_coder = reader.read(1)
+            if depends_on_core_coder:
+                reader.read(14)  # core_coder_delay
+            extension_flag = reader.read(1)
+            if not channel_configuration:
+                raise core.InvalidPacketError('program_config_element not supported')
+            if audio_object_type in (6, 20):
+                reader.read(3)  # layer_nr
+            if extension_flag:
+                if audio_object_type == 22:
+                    reader.read(5)  # num_of_sub_frame
+                reader.read(11)  # layer_length
+                if audio_object_type in (17, 19, 20, 23):
+                    reader.read(1)  # aac_section_data_resilience_flags
+                    reader.read(1)  # aac_scale_factor_data_resilience_flags
+                    reader.read(1)  # aac_spectral_data_resilience_flags
+                extension_flag_3 = reader.read(1)
+                if extension_flag_3 == 1:
+                    raise core.InvalidPacketError('extensionFlag3 == 1 not supported')
+
+            return cls(audio_object_type)
+
+        def to_bits(self, writer: BitWriter) -> None:
+            assert self.audio_object_type in (1, 2)
+            writer.write(0, 1)  # frame_length_flag = 0
+            writer.write(0, 1)  # depends_on_core_coder = 0
+            writer.write(0, 1)  # extension_flag = 0
+
+    @dataclass
+    class AudioSpecificConfig:
+        audio_object_type: int
+        sampling_frequency_index: int
+        sampling_frequency: int
+        channel_configuration: int
+        ga_specific_config: AacAudioRtpPacket.GASpecificConfig
+        sbr_present_flag: int
+        ps_present_flag: int
+        extension_audio_object_type: int
+        extension_sampling_frequency_index: int
+        extension_sampling_frequency: int
+        extension_channel_configuration: int
+
+        SAMPLING_FREQUENCIES = [
+            96000,
+            88200,
+            64000,
+            48000,
+            44100,
+            32000,
+            24000,
+            22050,
+            16000,
+            12000,
+            11025,
+            8000,
+            7350,
+        ]
+
+        @classmethod
+        def for_simple_aac(
+            cls,
+            audio_object_type: int,
+            sampling_frequency: int,
+            channel_configuration: int,
+        ) -> Self:
+            if sampling_frequency not in cls.SAMPLING_FREQUENCIES:
+                raise ValueError(f'invalid sampling frequency {sampling_frequency}')
+
+            ga_specific_config = AacAudioRtpPacket.GASpecificConfig(audio_object_type)
+
+            return cls(
+                audio_object_type=audio_object_type,
+                sampling_frequency_index=cls.SAMPLING_FREQUENCIES.index(
+                    sampling_frequency
+                ),
+                sampling_frequency=sampling_frequency,
+                channel_configuration=channel_configuration,
+                ga_specific_config=ga_specific_config,
+                sbr_present_flag=0,
+                ps_present_flag=0,
+                extension_audio_object_type=0,
+                extension_sampling_frequency_index=0,
+                extension_sampling_frequency=0,
+                extension_channel_configuration=0,
+            )
+
+        @classmethod
+        def from_bits(cls, reader: BitReader) -> Self:
+            # AudioSpecificConfig - ISO/EIC 14496-3 Table 1.15
+            audio_object_type = AacAudioRtpPacket.read_audio_object_type(reader)
+            sampling_frequency_index = reader.read(4)
+            if sampling_frequency_index == 0xF:
+                sampling_frequency = reader.read(24)
+            else:
+                sampling_frequency = cls.SAMPLING_FREQUENCIES[sampling_frequency_index]
+            channel_configuration = reader.read(4)
+            sbr_present_flag = 0
+            ps_present_flag = 0
+            extension_sampling_frequency_index = 0
+            extension_sampling_frequency = 0
+            extension_channel_configuration = 0
+            extension_audio_object_type = 0
+            if audio_object_type in (5, 29):
+                extension_audio_object_type = 5
+                sbr_present_flag = 1
+                if audio_object_type == 29:
+                    ps_present_flag = 1
+                extension_sampling_frequency_index = reader.read(4)
+                if extension_sampling_frequency_index == 0xF:
+                    extension_sampling_frequency = reader.read(24)
+                else:
+                    extension_sampling_frequency = cls.SAMPLING_FREQUENCIES[
+                        extension_sampling_frequency_index
+                    ]
+                audio_object_type = AacAudioRtpPacket.read_audio_object_type(reader)
+                if audio_object_type == 22:
+                    extension_channel_configuration = reader.read(4)
+
+            if audio_object_type in (1, 2, 3, 4, 6, 7, 17, 19, 20, 21, 22, 23):
+                ga_specific_config = AacAudioRtpPacket.GASpecificConfig.from_bits(
+                    reader, channel_configuration, audio_object_type
+                )
+            else:
+                raise core.InvalidPacketError(
+                    f'audioObjectType {audio_object_type} not supported'
+                )
+
+            # if self.extension_audio_object_type != 5 and bits_to_decode >= 16:
+            #     sync_extension_type = reader.read(11)
+            #     if sync_extension_type == 0x2B7:
+            #         self.extension_audio_object_type = AacAudioRtpPacket.audio_object_type(reader)
+            #         if self.extension_audio_object_type == 5:
+            #             self.sbr_present_flag = reader.read(1)
+            #             if self.sbr_present_flag:
+            #                 self.extension_sampling_frequency_index = reader.read(4)
+            #                 if self.extension_sampling_frequency_index == 0xF:
+            #                     self.extension_sampling_frequency = reader.read(24)
+            #                 else:
+            #                     self.extension_sampling_frequency = self.SAMPLING_FREQUENCIES[self.extension_sampling_frequency_index]
+            #                 if bits_to_decode >= 12:
+            #                     sync_extension_type = reader.read(11)
+            #                     if sync_extension_type == 0x548:
+            #                         self.ps_present_flag = reader.read(1)
+            #         elif self.extension_audio_object_type == 22:
+            #             self.sbr_present_flag = reader.read(1)
+            #             if self.sbr_present_flag:
+            #                 self.extension_sampling_frequency_index = reader.read(4)
+            #                 if self.extension_sampling_frequency_index == 0xF:
+            #                     self.extension_sampling_frequency = reader.read(24)
+            #                 else:
+            #                     self.extension_sampling_frequency = self.SAMPLING_FREQUENCIES[self.extension_sampling_frequency_index]
+            #             self.extension_channel_configuration = reader.read(4)
+
+            return cls(
+                audio_object_type,
+                sampling_frequency_index,
+                sampling_frequency,
+                channel_configuration,
+                ga_specific_config,
+                sbr_present_flag,
+                ps_present_flag,
+                extension_audio_object_type,
+                extension_sampling_frequency_index,
+                extension_sampling_frequency,
+                extension_channel_configuration,
+            )
+
+        def to_bits(self, writer: BitWriter) -> None:
+            if self.sampling_frequency_index >= 15:
+                raise ValueError(
+                    f"unsupported sampling frequency index {self.sampling_frequency_index}"
+                )
+
+            if self.audio_object_type not in (1, 2):
+                raise ValueError(
+                    f"unsupported audio object type {self.audio_object_type} "
+                )
+
+            writer.write(self.audio_object_type, 5)
+            writer.write(self.sampling_frequency_index, 4)
+            writer.write(self.channel_configuration, 4)
+            self.ga_specific_config.to_bits(writer)
+
+    @dataclass
+    class StreamMuxConfig:
+        other_data_present: int
+        other_data_len_bits: int
+        audio_specific_config: AacAudioRtpPacket.AudioSpecificConfig
+
+        @classmethod
+        def from_bits(cls, reader: BitReader) -> Self:
+            # StreamMuxConfig - ISO/EIC 14496-3 Table 1.42
+            audio_mux_version = reader.read(1)
+            if audio_mux_version == 1:
+                audio_mux_version_a = reader.read(1)
+            else:
+                audio_mux_version_a = 0
+            if audio_mux_version_a != 0:
+                raise core.InvalidPacketError('audioMuxVersionA != 0 not supported')
+            if audio_mux_version == 1:
+                AacAudioRtpPacket.read_latm_value(reader)  # tara_buffer_fullness
+            # stream_cnt = 0
+            reader.read(1)  # all_streams_same_time_framing
+            reader.read(6)  # num_sub_frames
+            num_program = reader.read(4)
+            if num_program != 0:
+                raise core.InvalidPacketError('num_program != 0 not supported')
+            num_layer = reader.read(3)
+            if num_layer != 0:
+                raise core.InvalidPacketError('num_layer != 0 not supported')
+            if audio_mux_version == 0:
+                audio_specific_config = AacAudioRtpPacket.AudioSpecificConfig.from_bits(
+                    reader
+                )
+            else:
+                asc_len = AacAudioRtpPacket.read_latm_value(reader)
+                marker = reader.bit_position
+                audio_specific_config = AacAudioRtpPacket.AudioSpecificConfig.from_bits(
+                    reader
+                )
+                audio_specific_config_len = reader.bit_position - marker
+                if asc_len < audio_specific_config_len:
+                    raise core.InvalidPacketError('audio_specific_config_len > asc_len')
+                asc_len -= audio_specific_config_len
+                reader.skip(asc_len)
+            frame_length_type = reader.read(3)
+            if frame_length_type == 0:
+                reader.read(8)  # latm_buffer_fullness
+            elif frame_length_type == 1:
+                reader.read(9)  # frame_length
+            else:
+                raise core.InvalidPacketError(
+                    f'frame_length_type {frame_length_type} not supported'
+                )
+
+            other_data_present = reader.read(1)
+            other_data_len_bits = 0
+            if other_data_present:
+                if audio_mux_version == 1:
+                    other_data_len_bits = AacAudioRtpPacket.read_latm_value(reader)
+                else:
+                    while True:
+                        other_data_len_bits *= 256
+                        other_data_len_esc = reader.read(1)
+                        other_data_len_bits += reader.read(8)
+                        if other_data_len_esc == 0:
+                            break
+            crc_check_present = reader.read(1)
+            if crc_check_present:
+                reader.read(8)  # crc_checksum
+
+            return cls(other_data_present, other_data_len_bits, audio_specific_config)
+
+        def to_bits(self, writer: BitWriter) -> None:
+            writer.write(0, 1)  # audioMuxVersion = 0
+            writer.write(1, 1)  # allStreamsSameTimeFraming = 1
+            writer.write(0, 6)  # numSubFrames = 0
+            writer.write(0, 4)  # numProgram = 0
+            writer.write(0, 3)  # numLayer = 0
+            self.audio_specific_config.to_bits(writer)
+            writer.write(0, 3)  # frameLengthType = 0
+            writer.write(0, 8)  # latmBufferFullness = 0
+            writer.write(0, 1)  # otherDataPresent = 0
+            writer.write(0, 1)  # crcCheckPresent = 0
+
+    @dataclass
+    class AudioMuxElement:
+        stream_mux_config: AacAudioRtpPacket.StreamMuxConfig
+        payload: bytes
+
+        @classmethod
+        def from_bits(cls, reader: BitReader) -> Self:
+            # AudioMuxElement - ISO/EIC 14496-3 Table 1.41
+            # (only supports mux_config_present=1)
+            use_same_stream_mux = reader.read(1)
+            if use_same_stream_mux:
+                raise core.InvalidPacketError('useSameStreamMux == 1 not supported')
+            stream_mux_config = AacAudioRtpPacket.StreamMuxConfig.from_bits(reader)
+
+            # We only support:
+            # allStreamsSameTimeFraming == 1
+            # audioMuxVersionA == 0,
+            # numProgram == 0
+            # numSubFrames == 0
+            # numLayer == 0
+
+            mux_slot_length_bytes = 0
+            while True:
+                tmp = reader.read(8)
+                mux_slot_length_bytes += tmp
+                if tmp != 255:
+                    break
+
+            payload = reader.read_bytes(mux_slot_length_bytes)
+
+            if stream_mux_config.other_data_present:
+                reader.skip(stream_mux_config.other_data_len_bits)
+
+            # ByteAlign
+            while reader.bit_position % 8:
+                reader.read(1)
+
+            return cls(stream_mux_config, payload)
+
+        def to_bits(self, writer: BitWriter) -> None:
+            writer.write(0, 1)  # useSameStreamMux = 0
+            self.stream_mux_config.to_bits(writer)
+            mux_slot_length_bytes = len(self.payload)
+            while mux_slot_length_bytes > 255:
+                writer.write(255, 8)
+                mux_slot_length_bytes -= 255
+            writer.write(mux_slot_length_bytes, 8)
+            if mux_slot_length_bytes == 255:
+                writer.write(0, 8)
+            writer.write_bytes(self.payload)
+
+    @classmethod
+    def from_bytes(cls, data: bytes) -> Self:
+        # Parse the bit stream
+        reader = BitReader(data)
+        return cls(cls.AudioMuxElement.from_bits(reader))
+
+    @classmethod
+    def for_simple_aac(
+        cls, sampling_frequency: int, channel_configuration: int, payload: bytes
+    ) -> Self:
+        audio_specific_config = cls.AudioSpecificConfig.for_simple_aac(
+            2, sampling_frequency, channel_configuration
+        )
+        stream_mux_config = cls.StreamMuxConfig(0, 0, audio_specific_config)
+        audio_mux_element = cls.AudioMuxElement(stream_mux_config, payload)
+
+        return cls(audio_mux_element)
+
+    def to_adts(self):
+        # pylint: disable=line-too-long
+        sampling_frequency_index = (
+            self.audio_mux_element.stream_mux_config.audio_specific_config.sampling_frequency_index
+        )
+        channel_configuration = (
+            self.audio_mux_element.stream_mux_config.audio_specific_config.channel_configuration
+        )
+        frame_size = len(self.audio_mux_element.payload)
+        return (
+            bytes(
+                [
+                    0xFF,
+                    0xF1,  # 0xF9 (MPEG2)
+                    0x40
+                    | (sampling_frequency_index << 2)
+                    | (channel_configuration >> 2),
+                    ((channel_configuration & 0x3) << 6) | ((frame_size + 7) >> 11),
+                    ((frame_size + 7) >> 3) & 0xFF,
+                    (((frame_size + 7) << 5) & 0xFF) | 0x1F,
+                    0xFC,
+                ]
+            )
+            + self.audio_mux_element.payload
+        )
+
+    def __init__(self, audio_mux_element: AudioMuxElement) -> None:
+        self.audio_mux_element = audio_mux_element
+
+    def __bytes__(self) -> bytes:
+        writer = BitWriter()
+        self.audio_mux_element.to_bits(writer)
+        return bytes(writer)

bumble/colors.py

@@ -13,7 +13,10 @@
 # OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 
 from functools import partial
-from typing import List, Optional, Union
+
+
+class ColorError(ValueError):
+    """Error raised when a color spec is invalid."""
 
 
 # ANSI color names. There is also a "default"
@@ -34,7 +37,7 @@ STYLES = (
 )
 
 
-ColorSpec = Union[str, int]
+ColorSpec = str | int
 
 
 def _join(*values: ColorSpec) -> str:
@@ -52,16 +55,16 @@ def _color_code(spec: ColorSpec, base: int) -> str:
     elif isinstance(spec, int) and 0 <= spec <= 255:
         return _join(base + 8, 5, spec)
     else:
-        raise ValueError('Invalid color spec "%s"' % spec)
+        raise ColorError(f'Invalid color spec "{spec}"')
 
 
 def color(
     s: str,
-    fg: Optional[ColorSpec] = None,
-    bg: Optional[ColorSpec] = None,
-    style: Optional[str] = None,
+    fg: ColorSpec | None = None,
+    bg: ColorSpec | None = None,
+    style: str | None = None,
 ) -> str:
-    codes: List[ColorSpec] = []
+    codes: list[ColorSpec] = []
 
     if fg:
         codes.append(_color_code(fg, 30))
@@ -72,10 +75,10 @@ def color(
             if style_part in STYLES:
                 codes.append(STYLES.index(style_part))
             else:
-                raise ValueError('Invalid style "%s"' % style_part)
+                raise ColorError(f'Invalid style "{style_part}"')
 
     if codes:
-        return '\x1b[{0}m{1}\x1b[0m'.format(_join(*codes), s)
+        return f'\x1b[{_join(*codes)}m{s}\x1b[0m'
     else:
         return s
 

bumble/crypto.py

@@ -1,277 +0,0 @@
-# Copyright 2021-2022 Google LLC
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#      https://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-
-# -----------------------------------------------------------------------------
-# Crypto support
-#
-# See Bluetooth spec Vol 3, Part H - 2.2 CRYPTOGRAPHIC TOOLBOX
-# -----------------------------------------------------------------------------
-
-# -----------------------------------------------------------------------------
-# Imports
-# -----------------------------------------------------------------------------
-import logging
-import operator
-import platform
-
-if platform.system() != 'Emscripten':
-    import secrets
-    from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
-    from cryptography.hazmat.primitives.asymmetric.ec import (
-        generate_private_key,
-        ECDH,
-        EllipticCurvePublicNumbers,
-        EllipticCurvePrivateNumbers,
-        SECP256R1,
-    )
-    from cryptography.hazmat.primitives import cmac
-else:
-    # TODO: implement stubs
-    pass
-
-# -----------------------------------------------------------------------------
-# Logging
-# -----------------------------------------------------------------------------
-logger = logging.getLogger(__name__)
-
-
-# -----------------------------------------------------------------------------
-# Classes
-# -----------------------------------------------------------------------------
-class EccKey:
-    def __init__(self, private_key):
-        self.private_key = private_key
-
-    @classmethod
-    def generate(cls):
-        private_key = generate_private_key(SECP256R1())
-        return cls(private_key)
-
-    @classmethod
-    def from_private_key_bytes(cls, d_bytes, x_bytes, y_bytes):
-        d = int.from_bytes(d_bytes, byteorder='big', signed=False)
-        x = int.from_bytes(x_bytes, byteorder='big', signed=False)
-        y = int.from_bytes(y_bytes, byteorder='big', signed=False)
-        private_key = EllipticCurvePrivateNumbers(
-            d, EllipticCurvePublicNumbers(x, y, SECP256R1())
-        ).private_key()
-        return cls(private_key)
-
-    @property
-    def x(self):
-        return (
-            self.private_key.public_key()
-            .public_numbers()
-            .x.to_bytes(32, byteorder='big')
-        )
-
-    @property
-    def y(self):
-        return (
-            self.private_key.public_key()
-            .public_numbers()
-            .y.to_bytes(32, byteorder='big')
-        )
-
-    def dh(self, public_key_x, public_key_y):
-        x = int.from_bytes(public_key_x, byteorder='big', signed=False)
-        y = int.from_bytes(public_key_y, byteorder='big', signed=False)
-        public_key = EllipticCurvePublicNumbers(x, y, SECP256R1()).public_key()
-        shared_key = self.private_key.exchange(ECDH(), public_key)
-
-        return shared_key
-
-
-# -----------------------------------------------------------------------------
-# Functions
-# -----------------------------------------------------------------------------
-
-# -----------------------------------------------------------------------------
-def xor(x, y):
-    assert len(x) == len(y)
-    return bytes(map(operator.xor, x, y))
-
-
-# -----------------------------------------------------------------------------
-def r():
-    '''
-    Generate 16 bytes of random data
-    '''
-    return secrets.token_bytes(16)
-
-
-# -----------------------------------------------------------------------------
-def e(key, data):
-    '''
-    AES-128 ECB, expecting byte-swapped inputs and producing a byte-swapped output.
-
-    See Bluetooth spec Vol 3, Part H - 2.2.1 Security function e
-    '''
-
-    cipher = Cipher(algorithms.AES(bytes(reversed(key))), modes.ECB())
-    encryptor = cipher.encryptor()
-    return bytes(reversed(encryptor.update(bytes(reversed(data)))))
-
-
-# -----------------------------------------------------------------------------
-def ah(k, r):  # pylint: disable=redefined-outer-name
-    '''
-    See Bluetooth spec Vol 3, Part H - 2.2.2 Random Address Hash function ah
-    '''
-
-    padding = bytes(13)
-    r_prime = r + padding
-    return e(k, r_prime)[0:3]
-
-
-# -----------------------------------------------------------------------------
-def c1(k, r, preq, pres, iat, rat, ia, ra):  # pylint: disable=redefined-outer-name
-    '''
-    See Bluetooth spec, Vol 3, Part H - 2.2.3 Confirm value generation function c1 for
-    LE Legacy Pairing
-    '''
-
-    p1 = bytes([iat, rat]) + preq + pres
-    p2 = ra + ia + bytes([0, 0, 0, 0])
-    return e(k, xor(e(k, xor(r, p1)), p2))
-
-
-# -----------------------------------------------------------------------------
-def s1(k, r1, r2):
-    '''
-    See Bluetooth spec, Vol 3, Part H - 2.2.4 Key generation function s1 for LE Legacy
-    Pairing
-    '''
-
-    return e(k, r2[0:8] + r1[0:8])
-
-
-# -----------------------------------------------------------------------------
-def aes_cmac(m, k):
-    '''
-    See Bluetooth spec, Vol 3, Part H - 2.2.5 FunctionAES-CMAC
-
-    NOTE: the input and output of this internal function are in big-endian byte order
-    '''
-    mac = cmac.CMAC(algorithms.AES(k))
-    mac.update(m)
-    return mac.finalize()
-
-
-# -----------------------------------------------------------------------------
-def f4(u, v, x, z):
-    '''
-    See Bluetooth spec, Vol 3, Part H - 2.2.6 LE Secure Connections Confirm Value
-    Generation Function f4
-    '''
-    return bytes(
-        reversed(
-            aes_cmac(bytes(reversed(u)) + bytes(reversed(v)) + z, bytes(reversed(x)))
-        )
-    )
-
-
-# -----------------------------------------------------------------------------
-def f5(w, n1, n2, a1, a2):
-    '''
-    See Bluetooth spec, Vol 3, Part H - 2.2.7 LE Secure Connections Key Generation
-    Function f5
-
-    NOTE: this returns a tuple: (MacKey, LTK) in little-endian byte order
-    '''
-    salt = bytes.fromhex('6C888391AAF5A53860370BDB5A6083BE')
-    t = aes_cmac(bytes(reversed(w)), salt)
-    key_id = bytes([0x62, 0x74, 0x6C, 0x65])
-    return (
-        bytes(
-            reversed(
-                aes_cmac(
-                    bytes([0])
-                    + key_id
-                    + bytes(reversed(n1))
-                    + bytes(reversed(n2))
-                    + bytes(reversed(a1))
-                    + bytes(reversed(a2))
-                    + bytes([1, 0]),
-                    t,
-                )
-            )
-        ),
-        bytes(
-            reversed(
-                aes_cmac(
-                    bytes([1])
-                    + key_id
-                    + bytes(reversed(n1))
-                    + bytes(reversed(n2))
-                    + bytes(reversed(a1))
-                    + bytes(reversed(a2))
-                    + bytes([1, 0]),
-                    t,
-                )
-            )
-        ),
-    )
-
-
-# -----------------------------------------------------------------------------
-def f6(w, n1, n2, r, io_cap, a1, a2):  # pylint: disable=redefined-outer-name
-    '''
-    See Bluetooth spec, Vol 3, Part H - 2.2.8 LE Secure Connections Check Value
-    Generation Function f6
-    '''
-    return bytes(
-        reversed(
-            aes_cmac(
-                bytes(reversed(n1))
-                + bytes(reversed(n2))
-                + bytes(reversed(r))
-                + bytes(reversed(io_cap))
-                + bytes(reversed(a1))
-                + bytes(reversed(a2)),
-                bytes(reversed(w)),
-            )
-        )
-    )
-
-
-# -----------------------------------------------------------------------------
-def g2(u, v, x, y):
-    '''
-    See Bluetooth spec, Vol 3, Part H - 2.2.9 LE Secure Connections Numeric Comparison
-    Value Generation Function g2
-    '''
-    return int.from_bytes(
-        aes_cmac(
-            bytes(reversed(u)) + bytes(reversed(v)) + bytes(reversed(y)),
-            bytes(reversed(x)),
-        )[-4:],
-        byteorder='big',
-    )
-
-
-# -----------------------------------------------------------------------------
-def h6(w, key_id):
-    '''
-    See Bluetooth spec, Vol 3, Part H - 2.2.10 Link key conversion function h6
-    '''
-    return aes_cmac(key_id, w)
-
-
-# -----------------------------------------------------------------------------
-def h7(salt, w):
-    '''
-    See Bluetooth spec, Vol 3, Part H - 2.2.11 Link key conversion function h7
-    '''
-    return aes_cmac(w, salt)

bumble/crypto/__init__.py

@@ -0,0 +1,216 @@
+# Copyright 2021-2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License")
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# -----------------------------------------------------------------------------
+# Imports
+# -----------------------------------------------------------------------------
+from __future__ import annotations
+
+import logging
+import operator
+import secrets
+
+try:
+    from bumble.crypto.cryptography import EccKey, aes_cmac, e
+except ImportError:
+    logging.getLogger(__name__).debug(
+        "Unable to import cryptography, using built-in primitives."
+    )
+    from bumble.crypto.builtin import EccKey, aes_cmac, e  # type: ignore[assignment]
+
+_EccKey = EccKey  # For the linter only
+
+# -----------------------------------------------------------------------------
+# Logging
+# -----------------------------------------------------------------------------
+logger = logging.getLogger(__name__)
+
+
+# -----------------------------------------------------------------------------
+# Functions
+# -----------------------------------------------------------------------------
+
+
+# -----------------------------------------------------------------------------
+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)
+    return bytes(map(operator.xor, x, y))
+
+
+# -----------------------------------------------------------------------------
+def reverse(input: bytes) -> bytes:
+    '''
+    Returns bytes of input in reversed endianness.
+    '''
+    return input[::-1]
+
+
+# -----------------------------------------------------------------------------
+def r() -> bytes:
+    '''
+    Generate 16 bytes of random data
+    '''
+    return secrets.token_bytes(16)
+
+
+# -----------------------------------------------------------------------------
+def ah(k: bytes, r: bytes) -> bytes:  # pylint: disable=redefined-outer-name
+    '''
+    See Bluetooth spec Vol 3, Part H - 2.2.2 Random Address Hash function ah
+    '''
+
+    padding = bytes(13)
+    r_prime = r + padding
+    return e(k, r_prime)[0:3]
+
+
+# -----------------------------------------------------------------------------
+def c1(
+    k: bytes,
+    r: bytes,
+    preq: bytes,
+    pres: bytes,
+    iat: int,
+    rat: int,
+    ia: bytes,
+    ra: bytes,
+) -> bytes:  # pylint: disable=redefined-outer-name
+    '''
+    See Bluetooth spec, Vol 3, Part H - 2.2.3 Confirm value generation function c1 for
+    LE Legacy Pairing
+    '''
+
+    p1 = bytes([iat, rat]) + preq + pres
+    p2 = ra + ia + bytes([0, 0, 0, 0])
+    return e(k, xor(e(k, xor(r, p1)), p2))
+
+
+# -----------------------------------------------------------------------------
+def s1(k: bytes, r1: bytes, r2: bytes) -> bytes:
+    '''
+    See Bluetooth spec, Vol 3, Part H - 2.2.4 Key generation function s1 for LE Legacy
+    Pairing
+    '''
+
+    return e(k, r2[0:8] + r1[0:8])
+
+
+# -----------------------------------------------------------------------------
+def f4(u: bytes, v: bytes, x: bytes, z: bytes) -> bytes:
+    '''
+    See Bluetooth spec, Vol 3, Part H - 2.2.6 LE Secure Connections Confirm Value
+    Generation Function f4
+    '''
+    return reverse(aes_cmac(reverse(u) + reverse(v) + z, reverse(x)))
+
+
+# -----------------------------------------------------------------------------
+def f5(w: bytes, n1: bytes, n2: bytes, a1: bytes, a2: bytes) -> tuple[bytes, bytes]:
+    '''
+    See Bluetooth spec, Vol 3, Part H - 2.2.7 LE Secure Connections Key Generation
+    Function f5
+
+    NOTE: this returns a tuple: (MacKey, LTK) in little-endian byte order
+    '''
+    salt = bytes.fromhex('6C888391AAF5A53860370BDB5A6083BE')
+    t = aes_cmac(reverse(w), salt)
+    key_id = bytes([0x62, 0x74, 0x6C, 0x65])
+    return (
+        reverse(
+            aes_cmac(
+                bytes([0])
+                + key_id
+                + reverse(n1)
+                + reverse(n2)
+                + reverse(a1)
+                + reverse(a2)
+                + bytes([1, 0]),
+                t,
+            )
+        ),
+        reverse(
+            aes_cmac(
+                bytes([1])
+                + key_id
+                + reverse(n1)
+                + reverse(n2)
+                + reverse(a1)
+                + reverse(a2)
+                + bytes([1, 0]),
+                t,
+            )
+        ),
+    )
+
+
+# -----------------------------------------------------------------------------
+def f6(
+    w: bytes, n1: bytes, n2: bytes, r: bytes, io_cap: bytes, a1: bytes, a2: bytes
+) -> bytes:  # pylint: disable=redefined-outer-name
+    '''
+    See Bluetooth spec, Vol 3, Part H - 2.2.8 LE Secure Connections Check Value
+    Generation Function f6
+    '''
+    return reverse(
+        aes_cmac(
+            reverse(n1)
+            + reverse(n2)
+            + reverse(r)
+            + reverse(io_cap)
+            + reverse(a1)
+            + reverse(a2),
+            reverse(w),
+        )
+    )
+
+
+# -----------------------------------------------------------------------------
+def g2(u: bytes, v: bytes, x: bytes, y: bytes) -> int:
+    '''
+    See Bluetooth spec, Vol 3, Part H - 2.2.9 LE Secure Connections Numeric Comparison
+    Value Generation Function g2
+    '''
+    return int.from_bytes(
+        aes_cmac(
+            reverse(u) + reverse(v) + reverse(y),
+            reverse(x),
+        )[-4:],
+        byteorder='big',
+    )
+
+
+# -----------------------------------------------------------------------------
+def h6(w: bytes, key_id: bytes) -> bytes:
+    '''
+    See Bluetooth spec, Vol 3, Part H - 2.2.10 Link key conversion function h6
+    '''
+    return reverse(aes_cmac(key_id, reverse(w)))
+
+
+# -----------------------------------------------------------------------------
+def h7(salt: bytes, w: bytes) -> bytes:
+    '''
+    See Bluetooth spec, Vol 3, Part H - 2.2.11 Link key conversion function h7
+    '''
+    return reverse(aes_cmac(reverse(w), salt))

bumble/crypto/builtin.py

@@ -0,0 +1,646 @@
+# Copyright 2021-2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License")
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# The implementation is modified from:
+# * AES - https://github.com/ricmoo/pyaes by Richard Moore under MIT License
+# * CMAC - https://github.com/pycrypto/pycrypto by contributors under pycrypto License.
+
+
+# -----------------------------------------------------------------------------
+# Built-in implementation of cryptography primitives.
+#
+# Note: It's very dangerous to use this library in the real world.
+# -----------------------------------------------------------------------------
+from __future__ import annotations
+
+import copy
+import dataclasses
+import functools
+import secrets
+import struct
+
+from bumble import core
+
+
+def _compact_word(word: bytes) -> int:
+    return int.from_bytes(word, "big")
+
+
+def _shift_bytes(bs: bytes, xor_lsb: int = 0) -> bytes:
+    return ((int.from_bytes(bs, "big") << 1) ^ xor_lsb).to_bytes(len(bs) + 1, "big")[1:]
+
+
+def _xor(a: bytes, b: bytes) -> bytes:
+    return bytes(x ^ y for x, y in zip(a, b))
+
+
+# Based *largely* on the Rijndael implementation
+# See: http://csrc.nist.gov/publications/FIPS/FIPS197/FIPS-197.pdf
+class _AES:
+    '''Encapsulates the AES block cipher.
+
+    You generally should not need this. Use the AESModeOfOperation classes
+    below instead.'''
+
+    # fmt: off
+    # Number of rounds by key size
+    _NUMBER_OF_ROUNDS = {16: 10, 24: 12, 32: 14}
+
+    # Round constant words
+    _RCON = [ 0x01, 0x02, 0x04, 0x08, 0x10, 0x20, 0x40, 0x80, 0x1b, 0x36, 0x6c, 0xd8, 0xab, 0x4d, 0x9a, 0x2f, 0x5e, 0xbc, 0x63, 0xc6, 0x97, 0x35, 0x6a, 0xd4, 0xb3, 0x7d, 0xfa, 0xef, 0xc5, 0x91 ]
+
+    # S-box and Inverse S-box (S is for Substitution)
+    _S = [ 0x63, 0x7c, 0x77, 0x7b, 0xf2, 0x6b, 0x6f, 0xc5, 0x30, 0x01, 0x67, 0x2b, 0xfe, 0xd7, 0xab, 0x76, 0xca, 0x82, 0xc9, 0x7d, 0xfa, 0x59, 0x47, 0xf0, 0xad, 0xd4, 0xa2, 0xaf, 0x9c, 0xa4, 0x72, 0xc0, 0xb7, 0xfd, 0x93, 0x26, 0x36, 0x3f, 0xf7, 0xcc, 0x34, 0xa5, 0xe5, 0xf1, 0x71, 0xd8, 0x31, 0x15, 0x04, 0xc7, 0x23, 0xc3, 0x18, 0x96, 0x05, 0x9a, 0x07, 0x12, 0x80, 0xe2, 0xeb, 0x27, 0xb2, 0x75, 0x09, 0x83, 0x2c, 0x1a, 0x1b, 0x6e, 0x5a, 0xa0, 0x52, 0x3b, 0xd6, 0xb3, 0x29, 0xe3, 0x2f, 0x84, 0x53, 0xd1, 0x00, 0xed, 0x20, 0xfc, 0xb1, 0x5b, 0x6a, 0xcb, 0xbe, 0x39, 0x4a, 0x4c, 0x58, 0xcf, 0xd0, 0xef, 0xaa, 0xfb, 0x43, 0x4d, 0x33, 0x85, 0x45, 0xf9, 0x02, 0x7f, 0x50, 0x3c, 0x9f, 0xa8, 0x51, 0xa3, 0x40, 0x8f, 0x92, 0x9d, 0x38, 0xf5, 0xbc, 0xb6, 0xda, 0x21, 0x10, 0xff, 0xf3, 0xd2, 0xcd, 0x0c, 0x13, 0xec, 0x5f, 0x97, 0x44, 0x17, 0xc4, 0xa7, 0x7e, 0x3d, 0x64, 0x5d, 0x19, 0x73, 0x60, 0x81, 0x4f, 0xdc, 0x22, 0x2a, 0x90, 0x88, 0x46, 0xee, 0xb8, 0x14, 0xde, 0x5e, 0x0b, 0xdb, 0xe0, 0x32, 0x3a, 0x0a, 0x49, 0x06, 0x24, 0x5c, 0xc2, 0xd3, 0xac, 0x62, 0x91, 0x95, 0xe4, 0x79, 0xe7, 0xc8, 0x37, 0x6d, 0x8d, 0xd5, 0x4e, 0xa9, 0x6c, 0x56, 0xf4, 0xea, 0x65, 0x7a, 0xae, 0x08, 0xba, 0x78, 0x25, 0x2e, 0x1c, 0xa6, 0xb4, 0xc6, 0xe8, 0xdd, 0x74, 0x1f, 0x4b, 0xbd, 0x8b, 0x8a, 0x70, 0x3e, 0xb5, 0x66, 0x48, 0x03, 0xf6, 0x0e, 0x61, 0x35, 0x57, 0xb9, 0x86, 0xc1, 0x1d, 0x9e, 0xe1, 0xf8, 0x98, 0x11, 0x69, 0xd9, 0x8e, 0x94, 0x9b, 0x1e, 0x87, 0xe9, 0xce, 0x55, 0x28, 0xdf, 0x8c, 0xa1, 0x89, 0x0d, 0xbf, 0xe6, 0x42, 0x68, 0x41, 0x99, 0x2d, 0x0f, 0xb0, 0x54, 0xbb, 0x16 ]
+    _S_INV =[ 0x52, 0x09, 0x6a, 0xd5, 0x30, 0x36, 0xa5, 0x38, 0xbf, 0x40, 0xa3, 0x9e, 0x81, 0xf3, 0xd7, 0xfb, 0x7c, 0xe3, 0x39, 0x82, 0x9b, 0x2f, 0xff, 0x87, 0x34, 0x8e, 0x43, 0x44, 0xc4, 0xde, 0xe9, 0xcb, 0x54, 0x7b, 0x94, 0x32, 0xa6, 0xc2, 0x23, 0x3d, 0xee, 0x4c, 0x95, 0x0b, 0x42, 0xfa, 0xc3, 0x4e, 0x08, 0x2e, 0xa1, 0x66, 0x28, 0xd9, 0x24, 0xb2, 0x76, 0x5b, 0xa2, 0x49, 0x6d, 0x8b, 0xd1, 0x25, 0x72, 0xf8, 0xf6, 0x64, 0x86, 0x68, 0x98, 0x16, 0xd4, 0xa4, 0x5c, 0xcc, 0x5d, 0x65, 0xb6, 0x92, 0x6c, 0x70, 0x48, 0x50, 0xfd, 0xed, 0xb9, 0xda, 0x5e, 0x15, 0x46, 0x57, 0xa7, 0x8d, 0x9d, 0x84, 0x90, 0xd8, 0xab, 0x00, 0x8c, 0xbc, 0xd3, 0x0a, 0xf7, 0xe4, 0x58, 0x05, 0xb8, 0xb3, 0x45, 0x06, 0xd0, 0x2c, 0x1e, 0x8f, 0xca, 0x3f, 0x0f, 0x02, 0xc1, 0xaf, 0xbd, 0x03, 0x01, 0x13, 0x8a, 0x6b, 0x3a, 0x91, 0x11, 0x41, 0x4f, 0x67, 0xdc, 0xea, 0x97, 0xf2, 0xcf, 0xce, 0xf0, 0xb4, 0xe6, 0x73, 0x96, 0xac, 0x74, 0x22, 0xe7, 0xad, 0x35, 0x85, 0xe2, 0xf9, 0x37, 0xe8, 0x1c, 0x75, 0xdf, 0x6e, 0x47, 0xf1, 0x1a, 0x71, 0x1d, 0x29, 0xc5, 0x89, 0x6f, 0xb7, 0x62, 0x0e, 0xaa, 0x18, 0xbe, 0x1b, 0xfc, 0x56, 0x3e, 0x4b, 0xc6, 0xd2, 0x79, 0x20, 0x9a, 0xdb, 0xc0, 0xfe, 0x78, 0xcd, 0x5a, 0xf4, 0x1f, 0xdd, 0xa8, 0x33, 0x88, 0x07, 0xc7, 0x31, 0xb1, 0x12, 0x10, 0x59, 0x27, 0x80, 0xec, 0x5f, 0x60, 0x51, 0x7f, 0xa9, 0x19, 0xb5, 0x4a, 0x0d, 0x2d, 0xe5, 0x7a, 0x9f, 0x93, 0xc9, 0x9c, 0xef, 0xa0, 0xe0, 0x3b, 0x4d, 0xae, 0x2a, 0xf5, 0xb0, 0xc8, 0xeb, 0xbb, 0x3c, 0x83, 0x53, 0x99, 0x61, 0x17, 0x2b, 0x04, 0x7e, 0xba, 0x77, 0xd6, 0x26, 0xe1, 0x69, 0x14, 0x63, 0x55, 0x21, 0x0c, 0x7d ] 
+
+    # Transformations for encryption
+    _T1 = [ 0xc66363a5, 0xf87c7c84, 0xee777799, 0xf67b7b8d, 0xfff2f20d, 0xd66b6bbd, 0xde6f6fb1, 0x91c5c554, 0x60303050, 0x02010103, 0xce6767a9, 0x562b2b7d, 0xe7fefe19, 0xb5d7d762, 0x4dababe6, 0xec76769a, 0x8fcaca45, 0x1f82829d, 0x89c9c940, 0xfa7d7d87, 0xeffafa15, 0xb25959eb, 0x8e4747c9, 0xfbf0f00b, 0x41adadec, 0xb3d4d467, 0x5fa2a2fd, 0x45afafea, 0x239c9cbf, 0x53a4a4f7, 0xe4727296, 0x9bc0c05b, 0x75b7b7c2, 0xe1fdfd1c, 0x3d9393ae, 0x4c26266a, 0x6c36365a, 0x7e3f3f41, 0xf5f7f702, 0x83cccc4f, 0x6834345c, 0x51a5a5f4, 0xd1e5e534, 0xf9f1f108, 0xe2717193, 0xabd8d873, 0x62313153, 0x2a15153f, 0x0804040c, 0x95c7c752, 0x46232365, 0x9dc3c35e, 0x30181828, 0x379696a1, 0x0a05050f, 0x2f9a9ab5, 0x0e070709, 0x24121236, 0x1b80809b, 0xdfe2e23d, 0xcdebeb26, 0x4e272769, 0x7fb2b2cd, 0xea75759f, 0x1209091b, 0x1d83839e, 0x582c2c74, 0x341a1a2e, 0x361b1b2d, 0xdc6e6eb2, 0xb45a5aee, 0x5ba0a0fb, 0xa45252f6, 0x763b3b4d, 0xb7d6d661, 0x7db3b3ce, 0x5229297b, 0xdde3e33e, 0x5e2f2f71, 0x13848497, 0xa65353f5, 0xb9d1d168, 0x00000000, 0xc1eded2c, 0x40202060, 0xe3fcfc1f, 0x79b1b1c8, 0xb65b5bed, 0xd46a6abe, 0x8dcbcb46, 0x67bebed9, 0x7239394b, 0x944a4ade, 0x984c4cd4, 0xb05858e8, 0x85cfcf4a, 0xbbd0d06b, 0xc5efef2a, 0x4faaaae5, 0xedfbfb16, 0x864343c5, 0x9a4d4dd7, 0x66333355, 0x11858594, 0x8a4545cf, 0xe9f9f910, 0x04020206, 0xfe7f7f81, 0xa05050f0, 0x783c3c44, 0x259f9fba, 0x4ba8a8e3, 0xa25151f3, 0x5da3a3fe, 0x804040c0, 0x058f8f8a, 0x3f9292ad, 0x219d9dbc, 0x70383848, 0xf1f5f504, 0x63bcbcdf, 0x77b6b6c1, 0xafdada75, 0x42212163, 0x20101030, 0xe5ffff1a, 0xfdf3f30e, 0xbfd2d26d, 0x81cdcd4c, 0x180c0c14, 0x26131335, 0xc3ecec2f, 0xbe5f5fe1, 0x359797a2, 0x884444cc, 0x2e171739, 0x93c4c457, 0x55a7a7f2, 0xfc7e7e82, 0x7a3d3d47, 0xc86464ac, 0xba5d5de7, 0x3219192b, 0xe6737395, 0xc06060a0, 0x19818198, 0x9e4f4fd1, 0xa3dcdc7f, 0x44222266, 0x542a2a7e, 0x3b9090ab, 0x0b888883, 0x8c4646ca, 0xc7eeee29, 0x6bb8b8d3, 0x2814143c, 0xa7dede79, 0xbc5e5ee2, 0x160b0b1d, 0xaddbdb76, 0xdbe0e03b, 0x64323256, 0x743a3a4e, 0x140a0a1e, 0x924949db, 0x0c06060a, 0x4824246c, 0xb85c5ce4, 0x9fc2c25d, 0xbdd3d36e, 0x43acacef, 0xc46262a6, 0x399191a8, 0x319595a4, 0xd3e4e437, 0xf279798b, 0xd5e7e732, 0x8bc8c843, 0x6e373759, 0xda6d6db7, 0x018d8d8c, 0xb1d5d564, 0x9c4e4ed2, 0x49a9a9e0, 0xd86c6cb4, 0xac5656fa, 0xf3f4f407, 0xcfeaea25, 0xca6565af, 0xf47a7a8e, 0x47aeaee9, 0x10080818, 0x6fbabad5, 0xf0787888, 0x4a25256f, 0x5c2e2e72, 0x381c1c24, 0x57a6a6f1, 0x73b4b4c7, 0x97c6c651, 0xcbe8e823, 0xa1dddd7c, 0xe874749c, 0x3e1f1f21, 0x964b4bdd, 0x61bdbddc, 0x0d8b8b86, 0x0f8a8a85, 0xe0707090, 0x7c3e3e42, 0x71b5b5c4, 0xcc6666aa, 0x904848d8, 0x06030305, 0xf7f6f601, 0x1c0e0e12, 0xc26161a3, 0x6a35355f, 0xae5757f9, 0x69b9b9d0, 0x17868691, 0x99c1c158, 0x3a1d1d27, 0x279e9eb9, 0xd9e1e138, 0xebf8f813, 0x2b9898b3, 0x22111133, 0xd26969bb, 0xa9d9d970, 0x078e8e89, 0x339494a7, 0x2d9b9bb6, 0x3c1e1e22, 0x15878792, 0xc9e9e920, 0x87cece49, 0xaa5555ff, 0x50282878, 0xa5dfdf7a, 0x038c8c8f, 0x59a1a1f8, 0x09898980, 0x1a0d0d17, 0x65bfbfda, 0xd7e6e631, 0x844242c6, 0xd06868b8, 0x824141c3, 0x299999b0, 0x5a2d2d77, 0x1e0f0f11, 0x7bb0b0cb, 0xa85454fc, 0x6dbbbbd6, 0x2c16163a ]
+    _T2 = [ 0xa5c66363, 0x84f87c7c, 0x99ee7777, 0x8df67b7b, 0x0dfff2f2, 0xbdd66b6b, 0xb1de6f6f, 0x5491c5c5, 0x50603030, 0x03020101, 0xa9ce6767, 0x7d562b2b, 0x19e7fefe, 0x62b5d7d7, 0xe64dabab, 0x9aec7676, 0x458fcaca, 0x9d1f8282, 0x4089c9c9, 0x87fa7d7d, 0x15effafa, 0xebb25959, 0xc98e4747, 0x0bfbf0f0, 0xec41adad, 0x67b3d4d4, 0xfd5fa2a2, 0xea45afaf, 0xbf239c9c, 0xf753a4a4, 0x96e47272, 0x5b9bc0c0, 0xc275b7b7, 0x1ce1fdfd, 0xae3d9393, 0x6a4c2626, 0x5a6c3636, 0x417e3f3f, 0x02f5f7f7, 0x4f83cccc, 0x5c683434, 0xf451a5a5, 0x34d1e5e5, 0x08f9f1f1, 0x93e27171, 0x73abd8d8, 0x53623131, 0x3f2a1515, 0x0c080404, 0x5295c7c7, 0x65462323, 0x5e9dc3c3, 0x28301818, 0xa1379696, 0x0f0a0505, 0xb52f9a9a, 0x090e0707, 0x36241212, 0x9b1b8080, 0x3ddfe2e2, 0x26cdebeb, 0x694e2727, 0xcd7fb2b2, 0x9fea7575, 0x1b120909, 0x9e1d8383, 0x74582c2c, 0x2e341a1a, 0x2d361b1b, 0xb2dc6e6e, 0xeeb45a5a, 0xfb5ba0a0, 0xf6a45252, 0x4d763b3b, 0x61b7d6d6, 0xce7db3b3, 0x7b522929, 0x3edde3e3, 0x715e2f2f, 0x97138484, 0xf5a65353, 0x68b9d1d1, 0x00000000, 0x2cc1eded, 0x60402020, 0x1fe3fcfc, 0xc879b1b1, 0xedb65b5b, 0xbed46a6a, 0x468dcbcb, 0xd967bebe, 0x4b723939, 0xde944a4a, 0xd4984c4c, 0xe8b05858, 0x4a85cfcf, 0x6bbbd0d0, 0x2ac5efef, 0xe54faaaa, 0x16edfbfb, 0xc5864343, 0xd79a4d4d, 0x55663333, 0x94118585, 0xcf8a4545, 0x10e9f9f9, 0x06040202, 0x81fe7f7f, 0xf0a05050, 0x44783c3c, 0xba259f9f, 0xe34ba8a8, 0xf3a25151, 0xfe5da3a3, 0xc0804040, 0x8a058f8f, 0xad3f9292, 0xbc219d9d, 0x48703838, 0x04f1f5f5, 0xdf63bcbc, 0xc177b6b6, 0x75afdada, 0x63422121, 0x30201010, 0x1ae5ffff, 0x0efdf3f3, 0x6dbfd2d2, 0x4c81cdcd, 0x14180c0c, 0x35261313, 0x2fc3ecec, 0xe1be5f5f, 0xa2359797, 0xcc884444, 0x392e1717, 0x5793c4c4, 0xf255a7a7, 0x82fc7e7e, 0x477a3d3d, 0xacc86464, 0xe7ba5d5d, 0x2b321919, 0x95e67373, 0xa0c06060, 0x98198181, 0xd19e4f4f, 0x7fa3dcdc, 0x66442222, 0x7e542a2a, 0xab3b9090, 0x830b8888, 0xca8c4646, 0x29c7eeee, 0xd36bb8b8, 0x3c281414, 0x79a7dede, 0xe2bc5e5e, 0x1d160b0b, 0x76addbdb, 0x3bdbe0e0, 0x56643232, 0x4e743a3a, 0x1e140a0a, 0xdb924949, 0x0a0c0606, 0x6c482424, 0xe4b85c5c, 0x5d9fc2c2, 0x6ebdd3d3, 0xef43acac, 0xa6c46262, 0xa8399191, 0xa4319595, 0x37d3e4e4, 0x8bf27979, 0x32d5e7e7, 0x438bc8c8, 0x596e3737, 0xb7da6d6d, 0x8c018d8d, 0x64b1d5d5, 0xd29c4e4e, 0xe049a9a9, 0xb4d86c6c, 0xfaac5656, 0x07f3f4f4, 0x25cfeaea, 0xafca6565, 0x8ef47a7a, 0xe947aeae, 0x18100808, 0xd56fbaba, 0x88f07878, 0x6f4a2525, 0x725c2e2e, 0x24381c1c, 0xf157a6a6, 0xc773b4b4, 0x5197c6c6, 0x23cbe8e8, 0x7ca1dddd, 0x9ce87474, 0x213e1f1f, 0xdd964b4b, 0xdc61bdbd, 0x860d8b8b, 0x850f8a8a, 0x90e07070, 0x427c3e3e, 0xc471b5b5, 0xaacc6666, 0xd8904848, 0x05060303, 0x01f7f6f6, 0x121c0e0e, 0xa3c26161, 0x5f6a3535, 0xf9ae5757, 0xd069b9b9, 0x91178686, 0x5899c1c1, 0x273a1d1d, 0xb9279e9e, 0x38d9e1e1, 0x13ebf8f8, 0xb32b9898, 0x33221111, 0xbbd26969, 0x70a9d9d9, 0x89078e8e, 0xa7339494, 0xb62d9b9b, 0x223c1e1e, 0x92158787, 0x20c9e9e9, 0x4987cece, 0xffaa5555, 0x78502828, 0x7aa5dfdf, 0x8f038c8c, 0xf859a1a1, 0x80098989, 0x171a0d0d, 0xda65bfbf, 0x31d7e6e6, 0xc6844242, 0xb8d06868, 0xc3824141, 0xb0299999, 0x775a2d2d, 0x111e0f0f, 0xcb7bb0b0, 0xfca85454, 0xd66dbbbb, 0x3a2c1616 ]
+    _T3 = [ 0x63a5c663, 0x7c84f87c, 0x7799ee77, 0x7b8df67b, 0xf20dfff2, 0x6bbdd66b, 0x6fb1de6f, 0xc55491c5, 0x30506030, 0x01030201, 0x67a9ce67, 0x2b7d562b, 0xfe19e7fe, 0xd762b5d7, 0xabe64dab, 0x769aec76, 0xca458fca, 0x829d1f82, 0xc94089c9, 0x7d87fa7d, 0xfa15effa, 0x59ebb259, 0x47c98e47, 0xf00bfbf0, 0xadec41ad, 0xd467b3d4, 0xa2fd5fa2, 0xafea45af, 0x9cbf239c, 0xa4f753a4, 0x7296e472, 0xc05b9bc0, 0xb7c275b7, 0xfd1ce1fd, 0x93ae3d93, 0x266a4c26, 0x365a6c36, 0x3f417e3f, 0xf702f5f7, 0xcc4f83cc, 0x345c6834, 0xa5f451a5, 0xe534d1e5, 0xf108f9f1, 0x7193e271, 0xd873abd8, 0x31536231, 0x153f2a15, 0x040c0804, 0xc75295c7, 0x23654623, 0xc35e9dc3, 0x18283018, 0x96a13796, 0x050f0a05, 0x9ab52f9a, 0x07090e07, 0x12362412, 0x809b1b80, 0xe23ddfe2, 0xeb26cdeb, 0x27694e27, 0xb2cd7fb2, 0x759fea75, 0x091b1209, 0x839e1d83, 0x2c74582c, 0x1a2e341a, 0x1b2d361b, 0x6eb2dc6e, 0x5aeeb45a, 0xa0fb5ba0, 0x52f6a452, 0x3b4d763b, 0xd661b7d6, 0xb3ce7db3, 0x297b5229, 0xe33edde3, 0x2f715e2f, 0x84971384, 0x53f5a653, 0xd168b9d1, 0x00000000, 0xed2cc1ed, 0x20604020, 0xfc1fe3fc, 0xb1c879b1, 0x5bedb65b, 0x6abed46a, 0xcb468dcb, 0xbed967be, 0x394b7239, 0x4ade944a, 0x4cd4984c, 0x58e8b058, 0xcf4a85cf, 0xd06bbbd0, 0xef2ac5ef, 0xaae54faa, 0xfb16edfb, 0x43c58643, 0x4dd79a4d, 0x33556633, 0x85941185, 0x45cf8a45, 0xf910e9f9, 0x02060402, 0x7f81fe7f, 0x50f0a050, 0x3c44783c, 0x9fba259f, 0xa8e34ba8, 0x51f3a251, 0xa3fe5da3, 0x40c08040, 0x8f8a058f, 0x92ad3f92, 0x9dbc219d, 0x38487038, 0xf504f1f5, 0xbcdf63bc, 0xb6c177b6, 0xda75afda, 0x21634221, 0x10302010, 0xff1ae5ff, 0xf30efdf3, 0xd26dbfd2, 0xcd4c81cd, 0x0c14180c, 0x13352613, 0xec2fc3ec, 0x5fe1be5f, 0x97a23597, 0x44cc8844, 0x17392e17, 0xc45793c4, 0xa7f255a7, 0x7e82fc7e, 0x3d477a3d, 0x64acc864, 0x5de7ba5d, 0x192b3219, 0x7395e673, 0x60a0c060, 0x81981981, 0x4fd19e4f, 0xdc7fa3dc, 0x22664422, 0x2a7e542a, 0x90ab3b90, 0x88830b88, 0x46ca8c46, 0xee29c7ee, 0xb8d36bb8, 0x143c2814, 0xde79a7de, 0x5ee2bc5e, 0x0b1d160b, 0xdb76addb, 0xe03bdbe0, 0x32566432, 0x3a4e743a, 0x0a1e140a, 0x49db9249, 0x060a0c06, 0x246c4824, 0x5ce4b85c, 0xc25d9fc2, 0xd36ebdd3, 0xacef43ac, 0x62a6c462, 0x91a83991, 0x95a43195, 0xe437d3e4, 0x798bf279, 0xe732d5e7, 0xc8438bc8, 0x37596e37, 0x6db7da6d, 0x8d8c018d, 0xd564b1d5, 0x4ed29c4e, 0xa9e049a9, 0x6cb4d86c, 0x56faac56, 0xf407f3f4, 0xea25cfea, 0x65afca65, 0x7a8ef47a, 0xaee947ae, 0x08181008, 0xbad56fba, 0x7888f078, 0x256f4a25, 0x2e725c2e, 0x1c24381c, 0xa6f157a6, 0xb4c773b4, 0xc65197c6, 0xe823cbe8, 0xdd7ca1dd, 0x749ce874, 0x1f213e1f, 0x4bdd964b, 0xbddc61bd, 0x8b860d8b, 0x8a850f8a, 0x7090e070, 0x3e427c3e, 0xb5c471b5, 0x66aacc66, 0x48d89048, 0x03050603, 0xf601f7f6, 0x0e121c0e, 0x61a3c261, 0x355f6a35, 0x57f9ae57, 0xb9d069b9, 0x86911786, 0xc15899c1, 0x1d273a1d, 0x9eb9279e, 0xe138d9e1, 0xf813ebf8, 0x98b32b98, 0x11332211, 0x69bbd269, 0xd970a9d9, 0x8e89078e, 0x94a73394, 0x9bb62d9b, 0x1e223c1e, 0x87921587, 0xe920c9e9, 0xce4987ce, 0x55ffaa55, 0x28785028, 0xdf7aa5df, 0x8c8f038c, 0xa1f859a1, 0x89800989, 0x0d171a0d, 0xbfda65bf, 0xe631d7e6, 0x42c68442, 0x68b8d068, 0x41c38241, 0x99b02999, 0x2d775a2d, 0x0f111e0f, 0xb0cb7bb0, 0x54fca854, 0xbbd66dbb, 0x163a2c16 ]
+    _T4 = [ 0x6363a5c6, 0x7c7c84f8, 0x777799ee, 0x7b7b8df6, 0xf2f20dff, 0x6b6bbdd6, 0x6f6fb1de, 0xc5c55491, 0x30305060, 0x01010302, 0x6767a9ce, 0x2b2b7d56, 0xfefe19e7, 0xd7d762b5, 0xababe64d, 0x76769aec, 0xcaca458f, 0x82829d1f, 0xc9c94089, 0x7d7d87fa, 0xfafa15ef, 0x5959ebb2, 0x4747c98e, 0xf0f00bfb, 0xadadec41, 0xd4d467b3, 0xa2a2fd5f, 0xafafea45, 0x9c9cbf23, 0xa4a4f753, 0x727296e4, 0xc0c05b9b, 0xb7b7c275, 0xfdfd1ce1, 0x9393ae3d, 0x26266a4c, 0x36365a6c, 0x3f3f417e, 0xf7f702f5, 0xcccc4f83, 0x34345c68, 0xa5a5f451, 0xe5e534d1, 0xf1f108f9, 0x717193e2, 0xd8d873ab, 0x31315362, 0x15153f2a, 0x04040c08, 0xc7c75295, 0x23236546, 0xc3c35e9d, 0x18182830, 0x9696a137, 0x05050f0a, 0x9a9ab52f, 0x0707090e, 0x12123624, 0x80809b1b, 0xe2e23ddf, 0xebeb26cd, 0x2727694e, 0xb2b2cd7f, 0x75759fea, 0x09091b12, 0x83839e1d, 0x2c2c7458, 0x1a1a2e34, 0x1b1b2d36, 0x6e6eb2dc, 0x5a5aeeb4, 0xa0a0fb5b, 0x5252f6a4, 0x3b3b4d76, 0xd6d661b7, 0xb3b3ce7d, 0x29297b52, 0xe3e33edd, 0x2f2f715e, 0x84849713, 0x5353f5a6, 0xd1d168b9, 0x00000000, 0xeded2cc1, 0x20206040, 0xfcfc1fe3, 0xb1b1c879, 0x5b5bedb6, 0x6a6abed4, 0xcbcb468d, 0xbebed967, 0x39394b72, 0x4a4ade94, 0x4c4cd498, 0x5858e8b0, 0xcfcf4a85, 0xd0d06bbb, 0xefef2ac5, 0xaaaae54f, 0xfbfb16ed, 0x4343c586, 0x4d4dd79a, 0x33335566, 0x85859411, 0x4545cf8a, 0xf9f910e9, 0x02020604, 0x7f7f81fe, 0x5050f0a0, 0x3c3c4478, 0x9f9fba25, 0xa8a8e34b, 0x5151f3a2, 0xa3a3fe5d, 0x4040c080, 0x8f8f8a05, 0x9292ad3f, 0x9d9dbc21, 0x38384870, 0xf5f504f1, 0xbcbcdf63, 0xb6b6c177, 0xdada75af, 0x21216342, 0x10103020, 0xffff1ae5, 0xf3f30efd, 0xd2d26dbf, 0xcdcd4c81, 0x0c0c1418, 0x13133526, 0xecec2fc3, 0x5f5fe1be, 0x9797a235, 0x4444cc88, 0x1717392e, 0xc4c45793, 0xa7a7f255, 0x7e7e82fc, 0x3d3d477a, 0x6464acc8, 0x5d5de7ba, 0x19192b32, 0x737395e6, 0x6060a0c0, 0x81819819, 0x4f4fd19e, 0xdcdc7fa3, 0x22226644, 0x2a2a7e54, 0x9090ab3b, 0x8888830b, 0x4646ca8c, 0xeeee29c7, 0xb8b8d36b, 0x14143c28, 0xdede79a7, 0x5e5ee2bc, 0x0b0b1d16, 0xdbdb76ad, 0xe0e03bdb, 0x32325664, 0x3a3a4e74, 0x0a0a1e14, 0x4949db92, 0x06060a0c, 0x24246c48, 0x5c5ce4b8, 0xc2c25d9f, 0xd3d36ebd, 0xacacef43, 0x6262a6c4, 0x9191a839, 0x9595a431, 0xe4e437d3, 0x79798bf2, 0xe7e732d5, 0xc8c8438b, 0x3737596e, 0x6d6db7da, 0x8d8d8c01, 0xd5d564b1, 0x4e4ed29c, 0xa9a9e049, 0x6c6cb4d8, 0x5656faac, 0xf4f407f3, 0xeaea25cf, 0x6565afca, 0x7a7a8ef4, 0xaeaee947, 0x08081810, 0xbabad56f, 0x787888f0, 0x25256f4a, 0x2e2e725c, 0x1c1c2438, 0xa6a6f157, 0xb4b4c773, 0xc6c65197, 0xe8e823cb, 0xdddd7ca1, 0x74749ce8, 0x1f1f213e, 0x4b4bdd96, 0xbdbddc61, 0x8b8b860d, 0x8a8a850f, 0x707090e0, 0x3e3e427c, 0xb5b5c471, 0x6666aacc, 0x4848d890, 0x03030506, 0xf6f601f7, 0x0e0e121c, 0x6161a3c2, 0x35355f6a, 0x5757f9ae, 0xb9b9d069, 0x86869117, 0xc1c15899, 0x1d1d273a, 0x9e9eb927, 0xe1e138d9, 0xf8f813eb, 0x9898b32b, 0x11113322, 0x6969bbd2, 0xd9d970a9, 0x8e8e8907, 0x9494a733, 0x9b9bb62d, 0x1e1e223c, 0x87879215, 0xe9e920c9, 0xcece4987, 0x5555ffaa, 0x28287850, 0xdfdf7aa5, 0x8c8c8f03, 0xa1a1f859, 0x89898009, 0x0d0d171a, 0xbfbfda65, 0xe6e631d7, 0x4242c684, 0x6868b8d0, 0x4141c382, 0x9999b029, 0x2d2d775a, 0x0f0f111e, 0xb0b0cb7b, 0x5454fca8, 0xbbbbd66d, 0x16163a2c ]
+
+    # Transformations for decryption
+    _T5 = [ 0x51f4a750, 0x7e416553, 0x1a17a4c3, 0x3a275e96, 0x3bab6bcb, 0x1f9d45f1, 0xacfa58ab, 0x4be30393, 0x2030fa55, 0xad766df6, 0x88cc7691, 0xf5024c25, 0x4fe5d7fc, 0xc52acbd7, 0x26354480, 0xb562a38f, 0xdeb15a49, 0x25ba1b67, 0x45ea0e98, 0x5dfec0e1, 0xc32f7502, 0x814cf012, 0x8d4697a3, 0x6bd3f9c6, 0x038f5fe7, 0x15929c95, 0xbf6d7aeb, 0x955259da, 0xd4be832d, 0x587421d3, 0x49e06929, 0x8ec9c844, 0x75c2896a, 0xf48e7978, 0x99583e6b, 0x27b971dd, 0xbee14fb6, 0xf088ad17, 0xc920ac66, 0x7dce3ab4, 0x63df4a18, 0xe51a3182, 0x97513360, 0x62537f45, 0xb16477e0, 0xbb6bae84, 0xfe81a01c, 0xf9082b94, 0x70486858, 0x8f45fd19, 0x94de6c87, 0x527bf8b7, 0xab73d323, 0x724b02e2, 0xe31f8f57, 0x6655ab2a, 0xb2eb2807, 0x2fb5c203, 0x86c57b9a, 0xd33708a5, 0x302887f2, 0x23bfa5b2, 0x02036aba, 0xed16825c, 0x8acf1c2b, 0xa779b492, 0xf307f2f0, 0x4e69e2a1, 0x65daf4cd, 0x0605bed5, 0xd134621f, 0xc4a6fe8a, 0x342e539d, 0xa2f355a0, 0x058ae132, 0xa4f6eb75, 0x0b83ec39, 0x4060efaa, 0x5e719f06, 0xbd6e1051, 0x3e218af9, 0x96dd063d, 0xdd3e05ae, 0x4de6bd46, 0x91548db5, 0x71c45d05, 0x0406d46f, 0x605015ff, 0x1998fb24, 0xd6bde997, 0x894043cc, 0x67d99e77, 0xb0e842bd, 0x07898b88, 0xe7195b38, 0x79c8eedb, 0xa17c0a47, 0x7c420fe9, 0xf8841ec9, 0x00000000, 0x09808683, 0x322bed48, 0x1e1170ac, 0x6c5a724e, 0xfd0efffb, 0x0f853856, 0x3daed51e, 0x362d3927, 0x0a0fd964, 0x685ca621, 0x9b5b54d1, 0x24362e3a, 0x0c0a67b1, 0x9357e70f, 0xb4ee96d2, 0x1b9b919e, 0x80c0c54f, 0x61dc20a2, 0x5a774b69, 0x1c121a16, 0xe293ba0a, 0xc0a02ae5, 0x3c22e043, 0x121b171d, 0x0e090d0b, 0xf28bc7ad, 0x2db6a8b9, 0x141ea9c8, 0x57f11985, 0xaf75074c, 0xee99ddbb, 0xa37f60fd, 0xf701269f, 0x5c72f5bc, 0x44663bc5, 0x5bfb7e34, 0x8b432976, 0xcb23c6dc, 0xb6edfc68, 0xb8e4f163, 0xd731dcca, 0x42638510, 0x13972240, 0x84c61120, 0x854a247d, 0xd2bb3df8, 0xaef93211, 0xc729a16d, 0x1d9e2f4b, 0xdcb230f3, 0x0d8652ec, 0x77c1e3d0, 0x2bb3166c, 0xa970b999, 0x119448fa, 0x47e96422, 0xa8fc8cc4, 0xa0f03f1a, 0x567d2cd8, 0x223390ef, 0x87494ec7, 0xd938d1c1, 0x8ccaa2fe, 0x98d40b36, 0xa6f581cf, 0xa57ade28, 0xdab78e26, 0x3fadbfa4, 0x2c3a9de4, 0x5078920d, 0x6a5fcc9b, 0x547e4662, 0xf68d13c2, 0x90d8b8e8, 0x2e39f75e, 0x82c3aff5, 0x9f5d80be, 0x69d0937c, 0x6fd52da9, 0xcf2512b3, 0xc8ac993b, 0x10187da7, 0xe89c636e, 0xdb3bbb7b, 0xcd267809, 0x6e5918f4, 0xec9ab701, 0x834f9aa8, 0xe6956e65, 0xaaffe67e, 0x21bccf08, 0xef15e8e6, 0xbae79bd9, 0x4a6f36ce, 0xea9f09d4, 0x29b07cd6, 0x31a4b2af, 0x2a3f2331, 0xc6a59430, 0x35a266c0, 0x744ebc37, 0xfc82caa6, 0xe090d0b0, 0x33a7d815, 0xf104984a, 0x41ecdaf7, 0x7fcd500e, 0x1791f62f, 0x764dd68d, 0x43efb04d, 0xccaa4d54, 0xe49604df, 0x9ed1b5e3, 0x4c6a881b, 0xc12c1fb8, 0x4665517f, 0x9d5eea04, 0x018c355d, 0xfa877473, 0xfb0b412e, 0xb3671d5a, 0x92dbd252, 0xe9105633, 0x6dd64713, 0x9ad7618c, 0x37a10c7a, 0x59f8148e, 0xeb133c89, 0xcea927ee, 0xb761c935, 0xe11ce5ed, 0x7a47b13c, 0x9cd2df59, 0x55f2733f, 0x1814ce79, 0x73c737bf, 0x53f7cdea, 0x5ffdaa5b, 0xdf3d6f14, 0x7844db86, 0xcaaff381, 0xb968c43e, 0x3824342c, 0xc2a3405f, 0x161dc372, 0xbce2250c, 0x283c498b, 0xff0d9541, 0x39a80171, 0x080cb3de, 0xd8b4e49c, 0x6456c190, 0x7bcb8461, 0xd532b670, 0x486c5c74, 0xd0b85742 ]
+    _T6 = [ 0x5051f4a7, 0x537e4165, 0xc31a17a4, 0x963a275e, 0xcb3bab6b, 0xf11f9d45, 0xabacfa58, 0x934be303, 0x552030fa, 0xf6ad766d, 0x9188cc76, 0x25f5024c, 0xfc4fe5d7, 0xd7c52acb, 0x80263544, 0x8fb562a3, 0x49deb15a, 0x6725ba1b, 0x9845ea0e, 0xe15dfec0, 0x02c32f75, 0x12814cf0, 0xa38d4697, 0xc66bd3f9, 0xe7038f5f, 0x9515929c, 0xebbf6d7a, 0xda955259, 0x2dd4be83, 0xd3587421, 0x2949e069, 0x448ec9c8, 0x6a75c289, 0x78f48e79, 0x6b99583e, 0xdd27b971, 0xb6bee14f, 0x17f088ad, 0x66c920ac, 0xb47dce3a, 0x1863df4a, 0x82e51a31, 0x60975133, 0x4562537f, 0xe0b16477, 0x84bb6bae, 0x1cfe81a0, 0x94f9082b, 0x58704868, 0x198f45fd, 0x8794de6c, 0xb7527bf8, 0x23ab73d3, 0xe2724b02, 0x57e31f8f, 0x2a6655ab, 0x07b2eb28, 0x032fb5c2, 0x9a86c57b, 0xa5d33708, 0xf2302887, 0xb223bfa5, 0xba02036a, 0x5ced1682, 0x2b8acf1c, 0x92a779b4, 0xf0f307f2, 0xa14e69e2, 0xcd65daf4, 0xd50605be, 0x1fd13462, 0x8ac4a6fe, 0x9d342e53, 0xa0a2f355, 0x32058ae1, 0x75a4f6eb, 0x390b83ec, 0xaa4060ef, 0x065e719f, 0x51bd6e10, 0xf93e218a, 0x3d96dd06, 0xaedd3e05, 0x464de6bd, 0xb591548d, 0x0571c45d, 0x6f0406d4, 0xff605015, 0x241998fb, 0x97d6bde9, 0xcc894043, 0x7767d99e, 0xbdb0e842, 0x8807898b, 0x38e7195b, 0xdb79c8ee, 0x47a17c0a, 0xe97c420f, 0xc9f8841e, 0x00000000, 0x83098086, 0x48322bed, 0xac1e1170, 0x4e6c5a72, 0xfbfd0eff, 0x560f8538, 0x1e3daed5, 0x27362d39, 0x640a0fd9, 0x21685ca6, 0xd19b5b54, 0x3a24362e, 0xb10c0a67, 0x0f9357e7, 0xd2b4ee96, 0x9e1b9b91, 0x4f80c0c5, 0xa261dc20, 0x695a774b, 0x161c121a, 0x0ae293ba, 0xe5c0a02a, 0x433c22e0, 0x1d121b17, 0x0b0e090d, 0xadf28bc7, 0xb92db6a8, 0xc8141ea9, 0x8557f119, 0x4caf7507, 0xbbee99dd, 0xfda37f60, 0x9ff70126, 0xbc5c72f5, 0xc544663b, 0x345bfb7e, 0x768b4329, 0xdccb23c6, 0x68b6edfc, 0x63b8e4f1, 0xcad731dc, 0x10426385, 0x40139722, 0x2084c611, 0x7d854a24, 0xf8d2bb3d, 0x11aef932, 0x6dc729a1, 0x4b1d9e2f, 0xf3dcb230, 0xec0d8652, 0xd077c1e3, 0x6c2bb316, 0x99a970b9, 0xfa119448, 0x2247e964, 0xc4a8fc8c, 0x1aa0f03f, 0xd8567d2c, 0xef223390, 0xc787494e, 0xc1d938d1, 0xfe8ccaa2, 0x3698d40b, 0xcfa6f581, 0x28a57ade, 0x26dab78e, 0xa43fadbf, 0xe42c3a9d, 0x0d507892, 0x9b6a5fcc, 0x62547e46, 0xc2f68d13, 0xe890d8b8, 0x5e2e39f7, 0xf582c3af, 0xbe9f5d80, 0x7c69d093, 0xa96fd52d, 0xb3cf2512, 0x3bc8ac99, 0xa710187d, 0x6ee89c63, 0x7bdb3bbb, 0x09cd2678, 0xf46e5918, 0x01ec9ab7, 0xa8834f9a, 0x65e6956e, 0x7eaaffe6, 0x0821bccf, 0xe6ef15e8, 0xd9bae79b, 0xce4a6f36, 0xd4ea9f09, 0xd629b07c, 0xaf31a4b2, 0x312a3f23, 0x30c6a594, 0xc035a266, 0x37744ebc, 0xa6fc82ca, 0xb0e090d0, 0x1533a7d8, 0x4af10498, 0xf741ecda, 0x0e7fcd50, 0x2f1791f6, 0x8d764dd6, 0x4d43efb0, 0x54ccaa4d, 0xdfe49604, 0xe39ed1b5, 0x1b4c6a88, 0xb8c12c1f, 0x7f466551, 0x049d5eea, 0x5d018c35, 0x73fa8774, 0x2efb0b41, 0x5ab3671d, 0x5292dbd2, 0x33e91056, 0x136dd647, 0x8c9ad761, 0x7a37a10c, 0x8e59f814, 0x89eb133c, 0xeecea927, 0x35b761c9, 0xede11ce5, 0x3c7a47b1, 0x599cd2df, 0x3f55f273, 0x791814ce, 0xbf73c737, 0xea53f7cd, 0x5b5ffdaa, 0x14df3d6f, 0x867844db, 0x81caaff3, 0x3eb968c4, 0x2c382434, 0x5fc2a340, 0x72161dc3, 0x0cbce225, 0x8b283c49, 0x41ff0d95, 0x7139a801, 0xde080cb3, 0x9cd8b4e4, 0x906456c1, 0x617bcb84, 0x70d532b6, 0x74486c5c, 0x42d0b857 ]
+    _T7 = [ 0xa75051f4, 0x65537e41, 0xa4c31a17, 0x5e963a27, 0x6bcb3bab, 0x45f11f9d, 0x58abacfa, 0x03934be3, 0xfa552030, 0x6df6ad76, 0x769188cc, 0x4c25f502, 0xd7fc4fe5, 0xcbd7c52a, 0x44802635, 0xa38fb562, 0x5a49deb1, 0x1b6725ba, 0x0e9845ea, 0xc0e15dfe, 0x7502c32f, 0xf012814c, 0x97a38d46, 0xf9c66bd3, 0x5fe7038f, 0x9c951592, 0x7aebbf6d, 0x59da9552, 0x832dd4be, 0x21d35874, 0x692949e0, 0xc8448ec9, 0x896a75c2, 0x7978f48e, 0x3e6b9958, 0x71dd27b9, 0x4fb6bee1, 0xad17f088, 0xac66c920, 0x3ab47dce, 0x4a1863df, 0x3182e51a, 0x33609751, 0x7f456253, 0x77e0b164, 0xae84bb6b, 0xa01cfe81, 0x2b94f908, 0x68587048, 0xfd198f45, 0x6c8794de, 0xf8b7527b, 0xd323ab73, 0x02e2724b, 0x8f57e31f, 0xab2a6655, 0x2807b2eb, 0xc2032fb5, 0x7b9a86c5, 0x08a5d337, 0x87f23028, 0xa5b223bf, 0x6aba0203, 0x825ced16, 0x1c2b8acf, 0xb492a779, 0xf2f0f307, 0xe2a14e69, 0xf4cd65da, 0xbed50605, 0x621fd134, 0xfe8ac4a6, 0x539d342e, 0x55a0a2f3, 0xe132058a, 0xeb75a4f6, 0xec390b83, 0xefaa4060, 0x9f065e71, 0x1051bd6e, 0x8af93e21, 0x063d96dd, 0x05aedd3e, 0xbd464de6, 0x8db59154, 0x5d0571c4, 0xd46f0406, 0x15ff6050, 0xfb241998, 0xe997d6bd, 0x43cc8940, 0x9e7767d9, 0x42bdb0e8, 0x8b880789, 0x5b38e719, 0xeedb79c8, 0x0a47a17c, 0x0fe97c42, 0x1ec9f884, 0x00000000, 0x86830980, 0xed48322b, 0x70ac1e11, 0x724e6c5a, 0xfffbfd0e, 0x38560f85, 0xd51e3dae, 0x3927362d, 0xd9640a0f, 0xa621685c, 0x54d19b5b, 0x2e3a2436, 0x67b10c0a, 0xe70f9357, 0x96d2b4ee, 0x919e1b9b, 0xc54f80c0, 0x20a261dc, 0x4b695a77, 0x1a161c12, 0xba0ae293, 0x2ae5c0a0, 0xe0433c22, 0x171d121b, 0x0d0b0e09, 0xc7adf28b, 0xa8b92db6, 0xa9c8141e, 0x198557f1, 0x074caf75, 0xddbbee99, 0x60fda37f, 0x269ff701, 0xf5bc5c72, 0x3bc54466, 0x7e345bfb, 0x29768b43, 0xc6dccb23, 0xfc68b6ed, 0xf163b8e4, 0xdccad731, 0x85104263, 0x22401397, 0x112084c6, 0x247d854a, 0x3df8d2bb, 0x3211aef9, 0xa16dc729, 0x2f4b1d9e, 0x30f3dcb2, 0x52ec0d86, 0xe3d077c1, 0x166c2bb3, 0xb999a970, 0x48fa1194, 0x642247e9, 0x8cc4a8fc, 0x3f1aa0f0, 0x2cd8567d, 0x90ef2233, 0x4ec78749, 0xd1c1d938, 0xa2fe8cca, 0x0b3698d4, 0x81cfa6f5, 0xde28a57a, 0x8e26dab7, 0xbfa43fad, 0x9de42c3a, 0x920d5078, 0xcc9b6a5f, 0x4662547e, 0x13c2f68d, 0xb8e890d8, 0xf75e2e39, 0xaff582c3, 0x80be9f5d, 0x937c69d0, 0x2da96fd5, 0x12b3cf25, 0x993bc8ac, 0x7da71018, 0x636ee89c, 0xbb7bdb3b, 0x7809cd26, 0x18f46e59, 0xb701ec9a, 0x9aa8834f, 0x6e65e695, 0xe67eaaff, 0xcf0821bc, 0xe8e6ef15, 0x9bd9bae7, 0x36ce4a6f, 0x09d4ea9f, 0x7cd629b0, 0xb2af31a4, 0x23312a3f, 0x9430c6a5, 0x66c035a2, 0xbc37744e, 0xcaa6fc82, 0xd0b0e090, 0xd81533a7, 0x984af104, 0xdaf741ec, 0x500e7fcd, 0xf62f1791, 0xd68d764d, 0xb04d43ef, 0x4d54ccaa, 0x04dfe496, 0xb5e39ed1, 0x881b4c6a, 0x1fb8c12c, 0x517f4665, 0xea049d5e, 0x355d018c, 0x7473fa87, 0x412efb0b, 0x1d5ab367, 0xd25292db, 0x5633e910, 0x47136dd6, 0x618c9ad7, 0x0c7a37a1, 0x148e59f8, 0x3c89eb13, 0x27eecea9, 0xc935b761, 0xe5ede11c, 0xb13c7a47, 0xdf599cd2, 0x733f55f2, 0xce791814, 0x37bf73c7, 0xcdea53f7, 0xaa5b5ffd, 0x6f14df3d, 0xdb867844, 0xf381caaf, 0xc43eb968, 0x342c3824, 0x405fc2a3, 0xc372161d, 0x250cbce2, 0x498b283c, 0x9541ff0d, 0x017139a8, 0xb3de080c, 0xe49cd8b4, 0xc1906456, 0x84617bcb, 0xb670d532, 0x5c74486c, 0x5742d0b8 ]
+    _T8 = [ 0xf4a75051, 0x4165537e, 0x17a4c31a, 0x275e963a, 0xab6bcb3b, 0x9d45f11f, 0xfa58abac, 0xe303934b, 0x30fa5520, 0x766df6ad, 0xcc769188, 0x024c25f5, 0xe5d7fc4f, 0x2acbd7c5, 0x35448026, 0x62a38fb5, 0xb15a49de, 0xba1b6725, 0xea0e9845, 0xfec0e15d, 0x2f7502c3, 0x4cf01281, 0x4697a38d, 0xd3f9c66b, 0x8f5fe703, 0x929c9515, 0x6d7aebbf, 0x5259da95, 0xbe832dd4, 0x7421d358, 0xe0692949, 0xc9c8448e, 0xc2896a75, 0x8e7978f4, 0x583e6b99, 0xb971dd27, 0xe14fb6be, 0x88ad17f0, 0x20ac66c9, 0xce3ab47d, 0xdf4a1863, 0x1a3182e5, 0x51336097, 0x537f4562, 0x6477e0b1, 0x6bae84bb, 0x81a01cfe, 0x082b94f9, 0x48685870, 0x45fd198f, 0xde6c8794, 0x7bf8b752, 0x73d323ab, 0x4b02e272, 0x1f8f57e3, 0x55ab2a66, 0xeb2807b2, 0xb5c2032f, 0xc57b9a86, 0x3708a5d3, 0x2887f230, 0xbfa5b223, 0x036aba02, 0x16825ced, 0xcf1c2b8a, 0x79b492a7, 0x07f2f0f3, 0x69e2a14e, 0xdaf4cd65, 0x05bed506, 0x34621fd1, 0xa6fe8ac4, 0x2e539d34, 0xf355a0a2, 0x8ae13205, 0xf6eb75a4, 0x83ec390b, 0x60efaa40, 0x719f065e, 0x6e1051bd, 0x218af93e, 0xdd063d96, 0x3e05aedd, 0xe6bd464d, 0x548db591, 0xc45d0571, 0x06d46f04, 0x5015ff60, 0x98fb2419, 0xbde997d6, 0x4043cc89, 0xd99e7767, 0xe842bdb0, 0x898b8807, 0x195b38e7, 0xc8eedb79, 0x7c0a47a1, 0x420fe97c, 0x841ec9f8, 0x00000000, 0x80868309, 0x2bed4832, 0x1170ac1e, 0x5a724e6c, 0x0efffbfd, 0x8538560f, 0xaed51e3d, 0x2d392736, 0x0fd9640a, 0x5ca62168, 0x5b54d19b, 0x362e3a24, 0x0a67b10c, 0x57e70f93, 0xee96d2b4, 0x9b919e1b, 0xc0c54f80, 0xdc20a261, 0x774b695a, 0x121a161c, 0x93ba0ae2, 0xa02ae5c0, 0x22e0433c, 0x1b171d12, 0x090d0b0e, 0x8bc7adf2, 0xb6a8b92d, 0x1ea9c814, 0xf1198557, 0x75074caf, 0x99ddbbee, 0x7f60fda3, 0x01269ff7, 0x72f5bc5c, 0x663bc544, 0xfb7e345b, 0x4329768b, 0x23c6dccb, 0xedfc68b6, 0xe4f163b8, 0x31dccad7, 0x63851042, 0x97224013, 0xc6112084, 0x4a247d85, 0xbb3df8d2, 0xf93211ae, 0x29a16dc7, 0x9e2f4b1d, 0xb230f3dc, 0x8652ec0d, 0xc1e3d077, 0xb3166c2b, 0x70b999a9, 0x9448fa11, 0xe9642247, 0xfc8cc4a8, 0xf03f1aa0, 0x7d2cd856, 0x3390ef22, 0x494ec787, 0x38d1c1d9, 0xcaa2fe8c, 0xd40b3698, 0xf581cfa6, 0x7ade28a5, 0xb78e26da, 0xadbfa43f, 0x3a9de42c, 0x78920d50, 0x5fcc9b6a, 0x7e466254, 0x8d13c2f6, 0xd8b8e890, 0x39f75e2e, 0xc3aff582, 0x5d80be9f, 0xd0937c69, 0xd52da96f, 0x2512b3cf, 0xac993bc8, 0x187da710, 0x9c636ee8, 0x3bbb7bdb, 0x267809cd, 0x5918f46e, 0x9ab701ec, 0x4f9aa883, 0x956e65e6, 0xffe67eaa, 0xbccf0821, 0x15e8e6ef, 0xe79bd9ba, 0x6f36ce4a, 0x9f09d4ea, 0xb07cd629, 0xa4b2af31, 0x3f23312a, 0xa59430c6, 0xa266c035, 0x4ebc3774, 0x82caa6fc, 0x90d0b0e0, 0xa7d81533, 0x04984af1, 0xecdaf741, 0xcd500e7f, 0x91f62f17, 0x4dd68d76, 0xefb04d43, 0xaa4d54cc, 0x9604dfe4, 0xd1b5e39e, 0x6a881b4c, 0x2c1fb8c1, 0x65517f46, 0x5eea049d, 0x8c355d01, 0x877473fa, 0x0b412efb, 0x671d5ab3, 0xdbd25292, 0x105633e9, 0xd647136d, 0xd7618c9a, 0xa10c7a37, 0xf8148e59, 0x133c89eb, 0xa927eece, 0x61c935b7, 0x1ce5ede1, 0x47b13c7a, 0xd2df599c, 0xf2733f55, 0x14ce7918, 0xc737bf73, 0xf7cdea53, 0xfdaa5b5f, 0x3d6f14df, 0x44db8678, 0xaff381ca, 0x68c43eb9, 0x24342c38, 0xa3405fc2, 0x1dc37216, 0xe2250cbc, 0x3c498b28, 0x0d9541ff, 0xa8017139, 0x0cb3de08, 0xb4e49cd8, 0x56c19064, 0xcb84617b, 0x32b670d5, 0x6c5c7448, 0xb85742d0 ]
+
+    # Transformations for decryption key expansion
+    _U1 = [ 0x00000000, 0x0e090d0b, 0x1c121a16, 0x121b171d, 0x3824342c, 0x362d3927, 0x24362e3a, 0x2a3f2331, 0x70486858, 0x7e416553, 0x6c5a724e, 0x62537f45, 0x486c5c74, 0x4665517f, 0x547e4662, 0x5a774b69, 0xe090d0b0, 0xee99ddbb, 0xfc82caa6, 0xf28bc7ad, 0xd8b4e49c, 0xd6bde997, 0xc4a6fe8a, 0xcaaff381, 0x90d8b8e8, 0x9ed1b5e3, 0x8ccaa2fe, 0x82c3aff5, 0xa8fc8cc4, 0xa6f581cf, 0xb4ee96d2, 0xbae79bd9, 0xdb3bbb7b, 0xd532b670, 0xc729a16d, 0xc920ac66, 0xe31f8f57, 0xed16825c, 0xff0d9541, 0xf104984a, 0xab73d323, 0xa57ade28, 0xb761c935, 0xb968c43e, 0x9357e70f, 0x9d5eea04, 0x8f45fd19, 0x814cf012, 0x3bab6bcb, 0x35a266c0, 0x27b971dd, 0x29b07cd6, 0x038f5fe7, 0x0d8652ec, 0x1f9d45f1, 0x119448fa, 0x4be30393, 0x45ea0e98, 0x57f11985, 0x59f8148e, 0x73c737bf, 0x7dce3ab4, 0x6fd52da9, 0x61dc20a2, 0xad766df6, 0xa37f60fd, 0xb16477e0, 0xbf6d7aeb, 0x955259da, 0x9b5b54d1, 0x894043cc, 0x87494ec7, 0xdd3e05ae, 0xd33708a5, 0xc12c1fb8, 0xcf2512b3, 0xe51a3182, 0xeb133c89, 0xf9082b94, 0xf701269f, 0x4de6bd46, 0x43efb04d, 0x51f4a750, 0x5ffdaa5b, 0x75c2896a, 0x7bcb8461, 0x69d0937c, 0x67d99e77, 0x3daed51e, 0x33a7d815, 0x21bccf08, 0x2fb5c203, 0x058ae132, 0x0b83ec39, 0x1998fb24, 0x1791f62f, 0x764dd68d, 0x7844db86, 0x6a5fcc9b, 0x6456c190, 0x4e69e2a1, 0x4060efaa, 0x527bf8b7, 0x5c72f5bc, 0x0605bed5, 0x080cb3de, 0x1a17a4c3, 0x141ea9c8, 0x3e218af9, 0x302887f2, 0x223390ef, 0x2c3a9de4, 0x96dd063d, 0x98d40b36, 0x8acf1c2b, 0x84c61120, 0xaef93211, 0xa0f03f1a, 0xb2eb2807, 0xbce2250c, 0xe6956e65, 0xe89c636e, 0xfa877473, 0xf48e7978, 0xdeb15a49, 0xd0b85742, 0xc2a3405f, 0xccaa4d54, 0x41ecdaf7, 0x4fe5d7fc, 0x5dfec0e1, 0x53f7cdea, 0x79c8eedb, 0x77c1e3d0, 0x65daf4cd, 0x6bd3f9c6, 0x31a4b2af, 0x3fadbfa4, 0x2db6a8b9, 0x23bfa5b2, 0x09808683, 0x07898b88, 0x15929c95, 0x1b9b919e, 0xa17c0a47, 0xaf75074c, 0xbd6e1051, 0xb3671d5a, 0x99583e6b, 0x97513360, 0x854a247d, 0x8b432976, 0xd134621f, 0xdf3d6f14, 0xcd267809, 0xc32f7502, 0xe9105633, 0xe7195b38, 0xf5024c25, 0xfb0b412e, 0x9ad7618c, 0x94de6c87, 0x86c57b9a, 0x88cc7691, 0xa2f355a0, 0xacfa58ab, 0xbee14fb6, 0xb0e842bd, 0xea9f09d4, 0xe49604df, 0xf68d13c2, 0xf8841ec9, 0xd2bb3df8, 0xdcb230f3, 0xcea927ee, 0xc0a02ae5, 0x7a47b13c, 0x744ebc37, 0x6655ab2a, 0x685ca621, 0x42638510, 0x4c6a881b, 0x5e719f06, 0x5078920d, 0x0a0fd964, 0x0406d46f, 0x161dc372, 0x1814ce79, 0x322bed48, 0x3c22e043, 0x2e39f75e, 0x2030fa55, 0xec9ab701, 0xe293ba0a, 0xf088ad17, 0xfe81a01c, 0xd4be832d, 0xdab78e26, 0xc8ac993b, 0xc6a59430, 0x9cd2df59, 0x92dbd252, 0x80c0c54f, 0x8ec9c844, 0xa4f6eb75, 0xaaffe67e, 0xb8e4f163, 0xb6edfc68, 0x0c0a67b1, 0x02036aba, 0x10187da7, 0x1e1170ac, 0x342e539d, 0x3a275e96, 0x283c498b, 0x26354480, 0x7c420fe9, 0x724b02e2, 0x605015ff, 0x6e5918f4, 0x44663bc5, 0x4a6f36ce, 0x587421d3, 0x567d2cd8, 0x37a10c7a, 0x39a80171, 0x2bb3166c, 0x25ba1b67, 0x0f853856, 0x018c355d, 0x13972240, 0x1d9e2f4b, 0x47e96422, 0x49e06929, 0x5bfb7e34, 0x55f2733f, 0x7fcd500e, 0x71c45d05, 0x63df4a18, 0x6dd64713, 0xd731dcca, 0xd938d1c1, 0xcb23c6dc, 0xc52acbd7, 0xef15e8e6, 0xe11ce5ed, 0xf307f2f0, 0xfd0efffb, 0xa779b492, 0xa970b999, 0xbb6bae84, 0xb562a38f, 0x9f5d80be, 0x91548db5, 0x834f9aa8, 0x8d4697a3 ]
+    _U2 = [ 0x00000000, 0x0b0e090d, 0x161c121a, 0x1d121b17, 0x2c382434, 0x27362d39, 0x3a24362e, 0x312a3f23, 0x58704868, 0x537e4165, 0x4e6c5a72, 0x4562537f, 0x74486c5c, 0x7f466551, 0x62547e46, 0x695a774b, 0xb0e090d0, 0xbbee99dd, 0xa6fc82ca, 0xadf28bc7, 0x9cd8b4e4, 0x97d6bde9, 0x8ac4a6fe, 0x81caaff3, 0xe890d8b8, 0xe39ed1b5, 0xfe8ccaa2, 0xf582c3af, 0xc4a8fc8c, 0xcfa6f581, 0xd2b4ee96, 0xd9bae79b, 0x7bdb3bbb, 0x70d532b6, 0x6dc729a1, 0x66c920ac, 0x57e31f8f, 0x5ced1682, 0x41ff0d95, 0x4af10498, 0x23ab73d3, 0x28a57ade, 0x35b761c9, 0x3eb968c4, 0x0f9357e7, 0x049d5eea, 0x198f45fd, 0x12814cf0, 0xcb3bab6b, 0xc035a266, 0xdd27b971, 0xd629b07c, 0xe7038f5f, 0xec0d8652, 0xf11f9d45, 0xfa119448, 0x934be303, 0x9845ea0e, 0x8557f119, 0x8e59f814, 0xbf73c737, 0xb47dce3a, 0xa96fd52d, 0xa261dc20, 0xf6ad766d, 0xfda37f60, 0xe0b16477, 0xebbf6d7a, 0xda955259, 0xd19b5b54, 0xcc894043, 0xc787494e, 0xaedd3e05, 0xa5d33708, 0xb8c12c1f, 0xb3cf2512, 0x82e51a31, 0x89eb133c, 0x94f9082b, 0x9ff70126, 0x464de6bd, 0x4d43efb0, 0x5051f4a7, 0x5b5ffdaa, 0x6a75c289, 0x617bcb84, 0x7c69d093, 0x7767d99e, 0x1e3daed5, 0x1533a7d8, 0x0821bccf, 0x032fb5c2, 0x32058ae1, 0x390b83ec, 0x241998fb, 0x2f1791f6, 0x8d764dd6, 0x867844db, 0x9b6a5fcc, 0x906456c1, 0xa14e69e2, 0xaa4060ef, 0xb7527bf8, 0xbc5c72f5, 0xd50605be, 0xde080cb3, 0xc31a17a4, 0xc8141ea9, 0xf93e218a, 0xf2302887, 0xef223390, 0xe42c3a9d, 0x3d96dd06, 0x3698d40b, 0x2b8acf1c, 0x2084c611, 0x11aef932, 0x1aa0f03f, 0x07b2eb28, 0x0cbce225, 0x65e6956e, 0x6ee89c63, 0x73fa8774, 0x78f48e79, 0x49deb15a, 0x42d0b857, 0x5fc2a340, 0x54ccaa4d, 0xf741ecda, 0xfc4fe5d7, 0xe15dfec0, 0xea53f7cd, 0xdb79c8ee, 0xd077c1e3, 0xcd65daf4, 0xc66bd3f9, 0xaf31a4b2, 0xa43fadbf, 0xb92db6a8, 0xb223bfa5, 0x83098086, 0x8807898b, 0x9515929c, 0x9e1b9b91, 0x47a17c0a, 0x4caf7507, 0x51bd6e10, 0x5ab3671d, 0x6b99583e, 0x60975133, 0x7d854a24, 0x768b4329, 0x1fd13462, 0x14df3d6f, 0x09cd2678, 0x02c32f75, 0x33e91056, 0x38e7195b, 0x25f5024c, 0x2efb0b41, 0x8c9ad761, 0x8794de6c, 0x9a86c57b, 0x9188cc76, 0xa0a2f355, 0xabacfa58, 0xb6bee14f, 0xbdb0e842, 0xd4ea9f09, 0xdfe49604, 0xc2f68d13, 0xc9f8841e, 0xf8d2bb3d, 0xf3dcb230, 0xeecea927, 0xe5c0a02a, 0x3c7a47b1, 0x37744ebc, 0x2a6655ab, 0x21685ca6, 0x10426385, 0x1b4c6a88, 0x065e719f, 0x0d507892, 0x640a0fd9, 0x6f0406d4, 0x72161dc3, 0x791814ce, 0x48322bed, 0x433c22e0, 0x5e2e39f7, 0x552030fa, 0x01ec9ab7, 0x0ae293ba, 0x17f088ad, 0x1cfe81a0, 0x2dd4be83, 0x26dab78e, 0x3bc8ac99, 0x30c6a594, 0x599cd2df, 0x5292dbd2, 0x4f80c0c5, 0x448ec9c8, 0x75a4f6eb, 0x7eaaffe6, 0x63b8e4f1, 0x68b6edfc, 0xb10c0a67, 0xba02036a, 0xa710187d, 0xac1e1170, 0x9d342e53, 0x963a275e, 0x8b283c49, 0x80263544, 0xe97c420f, 0xe2724b02, 0xff605015, 0xf46e5918, 0xc544663b, 0xce4a6f36, 0xd3587421, 0xd8567d2c, 0x7a37a10c, 0x7139a801, 0x6c2bb316, 0x6725ba1b, 0x560f8538, 0x5d018c35, 0x40139722, 0x4b1d9e2f, 0x2247e964, 0x2949e069, 0x345bfb7e, 0x3f55f273, 0x0e7fcd50, 0x0571c45d, 0x1863df4a, 0x136dd647, 0xcad731dc, 0xc1d938d1, 0xdccb23c6, 0xd7c52acb, 0xe6ef15e8, 0xede11ce5, 0xf0f307f2, 0xfbfd0eff, 0x92a779b4, 0x99a970b9, 0x84bb6bae, 0x8fb562a3, 0xbe9f5d80, 0xb591548d, 0xa8834f9a, 0xa38d4697 ]
+    _U3 = [ 0x00000000, 0x0d0b0e09, 0x1a161c12, 0x171d121b, 0x342c3824, 0x3927362d, 0x2e3a2436, 0x23312a3f, 0x68587048, 0x65537e41, 0x724e6c5a, 0x7f456253, 0x5c74486c, 0x517f4665, 0x4662547e, 0x4b695a77, 0xd0b0e090, 0xddbbee99, 0xcaa6fc82, 0xc7adf28b, 0xe49cd8b4, 0xe997d6bd, 0xfe8ac4a6, 0xf381caaf, 0xb8e890d8, 0xb5e39ed1, 0xa2fe8cca, 0xaff582c3, 0x8cc4a8fc, 0x81cfa6f5, 0x96d2b4ee, 0x9bd9bae7, 0xbb7bdb3b, 0xb670d532, 0xa16dc729, 0xac66c920, 0x8f57e31f, 0x825ced16, 0x9541ff0d, 0x984af104, 0xd323ab73, 0xde28a57a, 0xc935b761, 0xc43eb968, 0xe70f9357, 0xea049d5e, 0xfd198f45, 0xf012814c, 0x6bcb3bab, 0x66c035a2, 0x71dd27b9, 0x7cd629b0, 0x5fe7038f, 0x52ec0d86, 0x45f11f9d, 0x48fa1194, 0x03934be3, 0x0e9845ea, 0x198557f1, 0x148e59f8, 0x37bf73c7, 0x3ab47dce, 0x2da96fd5, 0x20a261dc, 0x6df6ad76, 0x60fda37f, 0x77e0b164, 0x7aebbf6d, 0x59da9552, 0x54d19b5b, 0x43cc8940, 0x4ec78749, 0x05aedd3e, 0x08a5d337, 0x1fb8c12c, 0x12b3cf25, 0x3182e51a, 0x3c89eb13, 0x2b94f908, 0x269ff701, 0xbd464de6, 0xb04d43ef, 0xa75051f4, 0xaa5b5ffd, 0x896a75c2, 0x84617bcb, 0x937c69d0, 0x9e7767d9, 0xd51e3dae, 0xd81533a7, 0xcf0821bc, 0xc2032fb5, 0xe132058a, 0xec390b83, 0xfb241998, 0xf62f1791, 0xd68d764d, 0xdb867844, 0xcc9b6a5f, 0xc1906456, 0xe2a14e69, 0xefaa4060, 0xf8b7527b, 0xf5bc5c72, 0xbed50605, 0xb3de080c, 0xa4c31a17, 0xa9c8141e, 0x8af93e21, 0x87f23028, 0x90ef2233, 0x9de42c3a, 0x063d96dd, 0x0b3698d4, 0x1c2b8acf, 0x112084c6, 0x3211aef9, 0x3f1aa0f0, 0x2807b2eb, 0x250cbce2, 0x6e65e695, 0x636ee89c, 0x7473fa87, 0x7978f48e, 0x5a49deb1, 0x5742d0b8, 0x405fc2a3, 0x4d54ccaa, 0xdaf741ec, 0xd7fc4fe5, 0xc0e15dfe, 0xcdea53f7, 0xeedb79c8, 0xe3d077c1, 0xf4cd65da, 0xf9c66bd3, 0xb2af31a4, 0xbfa43fad, 0xa8b92db6, 0xa5b223bf, 0x86830980, 0x8b880789, 0x9c951592, 0x919e1b9b, 0x0a47a17c, 0x074caf75, 0x1051bd6e, 0x1d5ab367, 0x3e6b9958, 0x33609751, 0x247d854a, 0x29768b43, 0x621fd134, 0x6f14df3d, 0x7809cd26, 0x7502c32f, 0x5633e910, 0x5b38e719, 0x4c25f502, 0x412efb0b, 0x618c9ad7, 0x6c8794de, 0x7b9a86c5, 0x769188cc, 0x55a0a2f3, 0x58abacfa, 0x4fb6bee1, 0x42bdb0e8, 0x09d4ea9f, 0x04dfe496, 0x13c2f68d, 0x1ec9f884, 0x3df8d2bb, 0x30f3dcb2, 0x27eecea9, 0x2ae5c0a0, 0xb13c7a47, 0xbc37744e, 0xab2a6655, 0xa621685c, 0x85104263, 0x881b4c6a, 0x9f065e71, 0x920d5078, 0xd9640a0f, 0xd46f0406, 0xc372161d, 0xce791814, 0xed48322b, 0xe0433c22, 0xf75e2e39, 0xfa552030, 0xb701ec9a, 0xba0ae293, 0xad17f088, 0xa01cfe81, 0x832dd4be, 0x8e26dab7, 0x993bc8ac, 0x9430c6a5, 0xdf599cd2, 0xd25292db, 0xc54f80c0, 0xc8448ec9, 0xeb75a4f6, 0xe67eaaff, 0xf163b8e4, 0xfc68b6ed, 0x67b10c0a, 0x6aba0203, 0x7da71018, 0x70ac1e11, 0x539d342e, 0x5e963a27, 0x498b283c, 0x44802635, 0x0fe97c42, 0x02e2724b, 0x15ff6050, 0x18f46e59, 0x3bc54466, 0x36ce4a6f, 0x21d35874, 0x2cd8567d, 0x0c7a37a1, 0x017139a8, 0x166c2bb3, 0x1b6725ba, 0x38560f85, 0x355d018c, 0x22401397, 0x2f4b1d9e, 0x642247e9, 0x692949e0, 0x7e345bfb, 0x733f55f2, 0x500e7fcd, 0x5d0571c4, 0x4a1863df, 0x47136dd6, 0xdccad731, 0xd1c1d938, 0xc6dccb23, 0xcbd7c52a, 0xe8e6ef15, 0xe5ede11c, 0xf2f0f307, 0xfffbfd0e, 0xb492a779, 0xb999a970, 0xae84bb6b, 0xa38fb562, 0x80be9f5d, 0x8db59154, 0x9aa8834f, 0x97a38d46 ]
+    _U4 = [ 0x00000000, 0x090d0b0e, 0x121a161c, 0x1b171d12, 0x24342c38, 0x2d392736, 0x362e3a24, 0x3f23312a, 0x48685870, 0x4165537e, 0x5a724e6c, 0x537f4562, 0x6c5c7448, 0x65517f46, 0x7e466254, 0x774b695a, 0x90d0b0e0, 0x99ddbbee, 0x82caa6fc, 0x8bc7adf2, 0xb4e49cd8, 0xbde997d6, 0xa6fe8ac4, 0xaff381ca, 0xd8b8e890, 0xd1b5e39e, 0xcaa2fe8c, 0xc3aff582, 0xfc8cc4a8, 0xf581cfa6, 0xee96d2b4, 0xe79bd9ba, 0x3bbb7bdb, 0x32b670d5, 0x29a16dc7, 0x20ac66c9, 0x1f8f57e3, 0x16825ced, 0x0d9541ff, 0x04984af1, 0x73d323ab, 0x7ade28a5, 0x61c935b7, 0x68c43eb9, 0x57e70f93, 0x5eea049d, 0x45fd198f, 0x4cf01281, 0xab6bcb3b, 0xa266c035, 0xb971dd27, 0xb07cd629, 0x8f5fe703, 0x8652ec0d, 0x9d45f11f, 0x9448fa11, 0xe303934b, 0xea0e9845, 0xf1198557, 0xf8148e59, 0xc737bf73, 0xce3ab47d, 0xd52da96f, 0xdc20a261, 0x766df6ad, 0x7f60fda3, 0x6477e0b1, 0x6d7aebbf, 0x5259da95, 0x5b54d19b, 0x4043cc89, 0x494ec787, 0x3e05aedd, 0x3708a5d3, 0x2c1fb8c1, 0x2512b3cf, 0x1a3182e5, 0x133c89eb, 0x082b94f9, 0x01269ff7, 0xe6bd464d, 0xefb04d43, 0xf4a75051, 0xfdaa5b5f, 0xc2896a75, 0xcb84617b, 0xd0937c69, 0xd99e7767, 0xaed51e3d, 0xa7d81533, 0xbccf0821, 0xb5c2032f, 0x8ae13205, 0x83ec390b, 0x98fb2419, 0x91f62f17, 0x4dd68d76, 0x44db8678, 0x5fcc9b6a, 0x56c19064, 0x69e2a14e, 0x60efaa40, 0x7bf8b752, 0x72f5bc5c, 0x05bed506, 0x0cb3de08, 0x17a4c31a, 0x1ea9c814, 0x218af93e, 0x2887f230, 0x3390ef22, 0x3a9de42c, 0xdd063d96, 0xd40b3698, 0xcf1c2b8a, 0xc6112084, 0xf93211ae, 0xf03f1aa0, 0xeb2807b2, 0xe2250cbc, 0x956e65e6, 0x9c636ee8, 0x877473fa, 0x8e7978f4, 0xb15a49de, 0xb85742d0, 0xa3405fc2, 0xaa4d54cc, 0xecdaf741, 0xe5d7fc4f, 0xfec0e15d, 0xf7cdea53, 0xc8eedb79, 0xc1e3d077, 0xdaf4cd65, 0xd3f9c66b, 0xa4b2af31, 0xadbfa43f, 0xb6a8b92d, 0xbfa5b223, 0x80868309, 0x898b8807, 0x929c9515, 0x9b919e1b, 0x7c0a47a1, 0x75074caf, 0x6e1051bd, 0x671d5ab3, 0x583e6b99, 0x51336097, 0x4a247d85, 0x4329768b, 0x34621fd1, 0x3d6f14df, 0x267809cd, 0x2f7502c3, 0x105633e9, 0x195b38e7, 0x024c25f5, 0x0b412efb, 0xd7618c9a, 0xde6c8794, 0xc57b9a86, 0xcc769188, 0xf355a0a2, 0xfa58abac, 0xe14fb6be, 0xe842bdb0, 0x9f09d4ea, 0x9604dfe4, 0x8d13c2f6, 0x841ec9f8, 0xbb3df8d2, 0xb230f3dc, 0xa927eece, 0xa02ae5c0, 0x47b13c7a, 0x4ebc3774, 0x55ab2a66, 0x5ca62168, 0x63851042, 0x6a881b4c, 0x719f065e, 0x78920d50, 0x0fd9640a, 0x06d46f04, 0x1dc37216, 0x14ce7918, 0x2bed4832, 0x22e0433c, 0x39f75e2e, 0x30fa5520, 0x9ab701ec, 0x93ba0ae2, 0x88ad17f0, 0x81a01cfe, 0xbe832dd4, 0xb78e26da, 0xac993bc8, 0xa59430c6, 0xd2df599c, 0xdbd25292, 0xc0c54f80, 0xc9c8448e, 0xf6eb75a4, 0xffe67eaa, 0xe4f163b8, 0xedfc68b6, 0x0a67b10c, 0x036aba02, 0x187da710, 0x1170ac1e, 0x2e539d34, 0x275e963a, 0x3c498b28, 0x35448026, 0x420fe97c, 0x4b02e272, 0x5015ff60, 0x5918f46e, 0x663bc544, 0x6f36ce4a, 0x7421d358, 0x7d2cd856, 0xa10c7a37, 0xa8017139, 0xb3166c2b, 0xba1b6725, 0x8538560f, 0x8c355d01, 0x97224013, 0x9e2f4b1d, 0xe9642247, 0xe0692949, 0xfb7e345b, 0xf2733f55, 0xcd500e7f, 0xc45d0571, 0xdf4a1863, 0xd647136d, 0x31dccad7, 0x38d1c1d9, 0x23c6dccb, 0x2acbd7c5, 0x15e8e6ef, 0x1ce5ede1, 0x07f2f0f3, 0x0efffbfd, 0x79b492a7, 0x70b999a9, 0x6bae84bb, 0x62a38fb5, 0x5d80be9f, 0x548db591, 0x4f9aa883, 0x4697a38d ]
+    # fmt: on
+
+    def __init__(self, key: bytes) -> None:
+        if len(key) not in (16, 24, 32):
+            raise core.InvalidArgumentError(f'Invalid key size {len(key)}')
+
+        rounds = self._NUMBER_OF_ROUNDS[len(key)]
+
+        # Encryption round keys
+        self._ke = [[0] * 4 for i in range(rounds + 1)]
+
+        # Decryption round keys
+        self._kd = [[0] * 4 for i in range(rounds + 1)]
+
+        round_key_count = (rounds + 1) * 4
+        kc = len(key) // 4
+
+        # Convert the key into ints
+        tk = [struct.unpack('>i', key[i : i + 4])[0] for i in range(0, len(key), 4)]
+
+        # Copy values into round key arrays
+        for i in range(0, kc):
+            self._ke[i // 4][i % 4] = tk[i]
+            self._kd[rounds - (i // 4)][i % 4] = tk[i]
+
+        # Key expansion (FIPS-197 section 5.2)
+        r_con_pointer = 0
+        t = kc
+        while t < round_key_count:
+            tt = tk[kc - 1]
+            tk[0] ^= (
+                (self._S[(tt >> 16) & 0xFF] << 24)
+                ^ (self._S[(tt >> 8) & 0xFF] << 16)
+                ^ (self._S[tt & 0xFF] << 8)
+                ^ self._S[(tt >> 24) & 0xFF]
+                ^ (self._RCON[r_con_pointer] << 24)
+            )
+            r_con_pointer += 1
+
+            if kc != 8:
+                for i in range(1, kc):
+                    tk[i] ^= tk[i - 1]
+
+            # Key expansion for 256-bit keys is "slightly different" (FIPS-197)
+            else:
+                for i in range(1, kc // 2):
+                    tk[i] ^= tk[i - 1]
+                tt = tk[kc // 2 - 1]
+
+                tk[kc // 2] ^= (
+                    self._S[tt & 0xFF]
+                    ^ (self._S[(tt >> 8) & 0xFF] << 8)
+                    ^ (self._S[(tt >> 16) & 0xFF] << 16)
+                    ^ (self._S[(tt >> 24) & 0xFF] << 24)
+                )
+
+                for i in range(kc // 2 + 1, kc):
+                    tk[i] ^= tk[i - 1]
+
+            # Copy values into round key arrays
+            j = 0
+            while j < kc and t < round_key_count:
+                self._ke[t // 4][t % 4] = tk[j]
+                self._kd[rounds - (t // 4)][t % 4] = tk[j]
+                j += 1
+                t += 1
+
+        # Inverse-Cipher-ify the decryption round key (FIPS-197 section 5.3)
+        for r in range(1, rounds):
+            for j in range(0, 4):
+                tt = self._kd[r][j]
+                self._kd[r][j] = (
+                    self._U1[(tt >> 24) & 0xFF]
+                    ^ self._U2[(tt >> 16) & 0xFF]
+                    ^ self._U3[(tt >> 8) & 0xFF]
+                    ^ self._U4[tt & 0xFF]
+                )
+
+    def encrypt(self, plaintext: bytes) -> bytes:
+        """Encrypt a block of plain text using the AES block cipher."""
+
+        if len(plaintext) != 16:
+            raise core.InvalidArgumentError(f'wrong block length {len(plaintext)}')
+
+        rounds = len(self._ke) - 1
+        (s1, s2, s3) = [1, 2, 3]
+        a = [0, 0, 0, 0]
+
+        # Convert plaintext to (ints ^ key)
+        t = [
+            (_compact_word(plaintext[4 * i : 4 * i + 4]) ^ self._ke[0][i])
+            for i in range(0, 4)
+        ]
+
+        # Apply round transforms
+        for r in range(1, rounds):
+            for i in range(0, 4):
+                a[i] = (
+                    self._T1[(t[i] >> 24) & 0xFF]
+                    ^ self._T2[(t[(i + s1) % 4] >> 16) & 0xFF]
+                    ^ self._T3[(t[(i + s2) % 4] >> 8) & 0xFF]
+                    ^ self._T4[t[(i + s3) % 4] & 0xFF]
+                    ^ self._ke[r][i]
+                )
+            t = copy.copy(a)
+
+        # The last round is special
+        result = []
+        for i in range(0, 4):
+            tt = self._ke[rounds][i]
+            result.append((self._S[(t[i] >> 24) & 0xFF] ^ (tt >> 24)) & 0xFF)
+            result.append((self._S[(t[(i + s1) % 4] >> 16) & 0xFF] ^ (tt >> 16)) & 0xFF)
+            result.append((self._S[(t[(i + s2) % 4] >> 8) & 0xFF] ^ (tt >> 8)) & 0xFF)
+            result.append((self._S[t[(i + s3) % 4] & 0xFF] ^ tt) & 0xFF)
+
+        return bytes(result)
+
+    def decrypt(self, cipher_text: bytes) -> bytes:
+        """Decrypt a block of cipher text using the AES block cipher."""
+
+        if len(cipher_text) != 16:
+            raise core.InvalidArgumentError(f'wrong block length {len(cipher_text)}')
+
+        rounds = len(self._kd) - 1
+        (s1, s2, s3) = [3, 2, 1]
+        a = [0, 0, 0, 0]
+
+        # Convert ciphertext to (ints ^ key)
+        t = [
+            (_compact_word(cipher_text[4 * i : 4 * i + 4]) ^ self._kd[0][i])
+            for i in range(0, 4)
+        ]
+
+        # Apply round transforms
+        for r in range(1, rounds):
+            for i in range(0, 4):
+                a[i] = (
+                    self._T5[(t[i] >> 24) & 0xFF]
+                    ^ self._T6[(t[(i + s1) % 4] >> 16) & 0xFF]
+                    ^ self._T7[(t[(i + s2) % 4] >> 8) & 0xFF]
+                    ^ self._T8[t[(i + s3) % 4] & 0xFF]
+                    ^ self._kd[r][i]
+                )
+            t = copy.copy(a)
+
+        # The last round is special
+        result = []
+        for i in range(0, 4):
+            tt = self._kd[rounds][i]
+            result.append((self._S_INV[(t[i] >> 24) & 0xFF] ^ (tt >> 24)) & 0xFF)
+            result.append(
+                (self._S_INV[(t[(i + s1) % 4] >> 16) & 0xFF] ^ (tt >> 16)) & 0xFF
+            )
+            result.append(
+                (self._S_INV[(t[(i + s2) % 4] >> 8) & 0xFF] ^ (tt >> 8)) & 0xFF
+            )
+            result.append((self._S_INV[t[(i + s3) % 4] & 0xFF] ^ tt) & 0xFF)
+
+        return bytes(result)
+
+
+class _ECB:
+    def __init__(self, key: bytes):
+        self._aes = _AES(key)
+
+    def encrypt(self, plaintext: bytes) -> bytes:
+        return b"".join(
+            [
+                self._aes.encrypt(
+                    plaintext[offset : offset + 16].ljust(16, b"\x00")  # Pad 0.
+                )
+                for offset in range(0, len(plaintext), 16)
+            ]
+        )
+
+    def decrypt(self, cipher_text: bytes) -> bytes:
+        return b"".join(
+            [
+                self._aes.encrypt(cipher_text[offset : offset + 16])
+                for offset in range(0, len(cipher_text), 16)
+            ]
+        )
+
+
+class _CBC:
+    def __init__(self, key: bytes, iv: bytes = bytes(16)) -> None:
+        if len(iv) != 16:
+            raise core.InvalidArgumentError(
+                f'initialization vector must be 16 bytes, get {len(iv)}'
+            )
+        else:
+            self._last_cipher_block = iv
+        self._aes = _AES(key)
+
+    def encrypt(self, plaintext: bytes) -> bytes:
+        cipher_text = b""
+        for offset in range(0, len(plaintext), 16):
+            pre_cipher_block = _xor(
+                plaintext[offset : offset + 16], self._last_cipher_block
+            )
+            self._last_cipher_block = self._aes.encrypt(pre_cipher_block)
+            cipher_text += self._last_cipher_block
+        return cipher_text
+
+    def decrypt(self, cipher_text: bytes) -> bytes:
+        plaintext = b""
+        for offset in range(0, len(cipher_text), 16):
+            plaintext += _xor(
+                self._aes.decrypt(cipher_text[offset : offset + 16]),
+                self._last_cipher_block,
+            )
+            self._last_cipher_block = cipher_text[offset : offset + 16]
+
+        return plaintext
+
+
+class _CMAC:
+    def __init__(
+        self,
+        key: bytes,
+        msg: bytes = bytes(16),
+        mac_len: int = 16,
+        update_after_digest: bool = False,
+    ) -> None:
+        self.digest_size = mac_len
+        self._key = key
+        self._block_size = bs = 16
+        self._mac_tag: bytes | None = None
+        self._update_after_digest = update_after_digest
+
+        # Section 5.3 of NIST SP 800 38B and Appendix B
+        if bs == 8:
+            const_Rb = 0x1B
+            self._max_size = 8 * (2**21)
+        elif bs == 16:
+            const_Rb = 0x87
+            self._max_size = 16 * (2**48)
+        else:
+            raise core.InvalidArgumentError(
+                f"CMAC requires a cipher with a block size of 8 or 16 bytes, not {bs}"
+            )
+
+        # Compute sub-keys
+        zero_block = bytes(bs)
+        self._ecb = _ECB(key)
+        L = self._ecb.encrypt(zero_block)
+        if L[0] & 0x80:
+            self._k1 = _shift_bytes(L, const_Rb)
+        else:
+            self._k1 = _shift_bytes(L)
+        if self._k1[0] & 0x80:
+            self._k2 = _shift_bytes(self._k1, const_Rb)
+        else:
+            self._k2 = _shift_bytes(self._k1)
+
+        # Initialize CBC cipher with zero IV
+        self._cbc = _CBC(key, zero_block)
+
+        # Cache for outstanding data to authenticate
+        self._cache = bytearray(bs)
+        self._cache_n = 0
+
+        # Last piece of cipher text produced
+        self._last_ct = zero_block
+
+        # Last block that was encrypted with AES
+        self._last_pt: bytes | None = None
+
+        # Counter for total message size
+        self._data_size = 0
+
+        if msg:
+            self.update(msg)
+
+    def update(self, msg: bytes) -> _CMAC:
+        """Authenticate the next chunk of message.
+
+        Args:
+            data (byte string/byte array/memoryview): The next chunk of data
+        """
+
+        if self._mac_tag is not None and not self._update_after_digest:
+            raise core.InvalidStateError(
+                "update() cannot be called after digest() or verify()"
+            )
+
+        self._data_size += len(msg)
+        bs = self._block_size
+
+        if self._cache_n > 0:
+            filler = min(bs - self._cache_n, len(msg))
+            self._cache[self._cache_n : self._cache_n + filler] = msg[:filler]
+            self._cache_n += filler
+
+            if self._cache_n < bs:
+                return self
+
+            msg = msg[filler:]
+            self._update(self._cache)
+            self._cache_n = 0
+
+        remain = len(msg) % bs
+        if remain > 0:
+            self._update(msg[:-remain])
+            self._cache[:remain] = msg[-remain:]
+        else:
+            self._update(msg)
+        self._cache_n = remain
+        return self
+
+    def _update(self, data_block: bytes) -> None:
+        """Update a block aligned to the block boundary"""
+
+        bs = self._block_size
+        assert len(data_block) % bs == 0
+
+        if len(data_block) == 0:
+            return
+
+        ct = self._cbc.encrypt(data_block)
+        if len(data_block) == bs:
+            second_last = self._last_ct
+        else:
+            second_last = ct[-bs * 2 : -bs]
+        self._last_ct = ct[-bs:]
+        self._last_pt = _xor(second_last, data_block[-bs:])
+
+    def digest(self) -> bytes:
+        bs = self._block_size
+
+        if self._mac_tag is not None and not self._update_after_digest:
+            return self._mac_tag
+
+        if self._data_size > self._max_size:
+            raise core.InvalidArgumentError("MAC is unsafe for this message")
+
+        if self._cache_n == 0 and self._data_size > 0 and self._last_pt:
+            # Last block was full
+            pt = _xor(self._last_pt, self._k1)
+        else:
+            # Last block is partial (or message length is zero)
+            partial = self._cache[:]
+            partial[self._cache_n :] = b'\x80' + b'\x00' * (bs - self._cache_n - 1)
+            pt = _xor(_xor(self._last_ct, partial), self._k2)
+
+        self._mac_tag = self._ecb.encrypt(pt)[: self.digest_size]
+
+        return self._mac_tag
+
+
+# Define the original Point class for clarity and conversion purposes
+@dataclasses.dataclass
+class _Point:
+    """Represents a point on the elliptic curve in affine coordinates."""
+
+    curve: _EllipticCurve
+    x: int = 0
+    y: int = 0
+    infinite: bool = False
+
+
+@dataclasses.dataclass(frozen=True)
+class _JacobianPoint:
+    """Represents a point on the elliptic curve in Jacobian coordinates."""
+
+    curve: _EllipticCurve
+    x: int = 1  # For point at infinity (1:1:0)
+    y: int = 1
+    z: int = 0  # z = 0 indicates point at infinity
+
+    @classmethod
+    def point_at_infinity(cls, curve: _EllipticCurve) -> _JacobianPoint:
+        return _JacobianPoint(curve=curve, x=1, y=1, z=0)
+
+    @classmethod
+    def from_affine(cls, affine_point: _Point) -> _JacobianPoint:
+        if affine_point.infinite:
+            return _JacobianPoint.point_at_infinity(affine_point.curve)
+        # A simple conversion is (x, y, 1)
+        return _JacobianPoint(
+            curve=affine_point.curve, x=affine_point.x, y=affine_point.y, z=1
+        )
+
+    def to_affine(self) -> _Point:
+        if self.z == 0:
+            return _Point(infinite=True, curve=self.curve)
+
+        p = self.curve.p
+        inv_z = pow(self.z, -1, p)
+        affine_x = (self.x * inv_z**2) % p
+        affine_y = (self.y * inv_z**3) % p
+
+        return _Point(curve=self.curve, x=affine_x, y=affine_y, infinite=False)
+
+    def double(self) -> _JacobianPoint:
+        if self.z == 0 or self.y == 0:
+            return _JacobianPoint.point_at_infinity(self.curve)
+
+        s = 4 * self.x * self.y**2
+        m = 3 * self.x**2 + self.curve.a * self.z**4
+        x2 = m**2 - 2 * s
+        y2 = m * (s - x2) - 8 * self.y**4
+        z2 = 2 * self.y * self.z
+        p = self.curve.p
+
+        return _JacobianPoint(curve=self.curve, x=x2 % p, y=y2 % p, z=z2 % p)
+
+    def __add__(self, other: _JacobianPoint) -> _JacobianPoint:
+        if self.z == 0 and other.z == 0:
+            return _JacobianPoint.point_at_infinity(self.curve)
+        elif self.z == 0:
+            return other
+        elif other.z == 0:
+            return self
+
+        x1 = self.x
+        y1 = self.y
+        z1 = self.z
+        x2 = other.x
+        y2 = other.y
+        z2 = other.z
+        p = self.curve.p
+        u1 = (x1 * z2**2) % p
+        u2 = (x2 * z1**2) % p
+        s1 = (y1 * z2**3) % p
+        s2 = (y2 * z1**3) % p
+
+        if u1 == u2:
+            if s1 != s2:
+                return _JacobianPoint.point_at_infinity(self.curve)
+            else:
+                return self.double()
+        else:
+            h = u2 - u1
+            r = s2 - s1
+
+            h3 = h**3 % p
+            u1h2 = (u1 * h**2) % p
+            x3 = r**2 - h3 - 2 * u1h2
+            y3 = r * (u1h2 - x3) - s1 * h3
+            z3 = h * z1 * z2
+
+            return _JacobianPoint(self.curve, x3 % p, y3 % p, z3 % p)
+
+    def __mul__(self, k: int) -> _JacobianPoint:
+        addend = self
+        result = _JacobianPoint.point_at_infinity(self.curve)
+
+        while k > 0:
+            if k % 2 != 0:
+                result = result + addend
+            addend = addend.double()
+            k = k >> 1
+        return result
+
+    def __rmul__(self, k: int) -> _JacobianPoint:
+        return self * k
+
+
+@dataclasses.dataclass
+class _EllipticCurve:
+    p: int
+    a: int
+    b: int
+    n: int
+    g_x: int
+    g_y: int
+
+    _generator_jacobian: _JacobianPoint = dataclasses.field(init=False)
+
+    def __post_init__(self):
+        self._generator_jacobian = _JacobianPoint(
+            curve=self, x=self.g_x, y=self.g_y, z=1
+        )
+
+    @dataclasses.dataclass
+    class PrivateKey:
+        key: int
+        curve: _EllipticCurve
+
+    def generate_private_key(self) -> PrivateKey:
+        """Generates a random private key."""
+        return self.PrivateKey(key=secrets.randbelow(self.n), curve=self)
+
+    def generate_public_key(self, private_key: int) -> _Point:
+        """Generates a public key from a private key using Jacobian coordinates for scalar multiplication."""
+        public_key_jacobian = self._generator_jacobian * private_key
+        return public_key_jacobian.to_affine()
+
+    def ecdh_shared_secret(self, private_key: int, other_public_key: _Point) -> bytes:
+        """Computes the shared secret using ECDH."""
+        other_public_key_jacobian = _JacobianPoint.from_affine(other_public_key)
+        shared_point_jacobian = other_public_key_jacobian * private_key
+        shared_point_affine = shared_point_jacobian.to_affine()
+        if shared_point_affine.infinite:
+            raise core.InvalidPacketError(
+                "Shared secret calculation resulted in the point at infinite"
+            )
+        return shared_point_affine.x.to_bytes(32, 'big')
+
+    @classmethod
+    def SECP256R1(cls) -> _EllipticCurve:
+        p = 0xFFFFFFFF00000001000000000000000000000000FFFFFFFFFFFFFFFFFFFFFFFF
+        a = 0xFFFFFFFF00000001000000000000000000000000FFFFFFFFFFFFFFFFFFFFFFFC
+        b = 0x5AC635D8AA3A93E7B3EBBD55769886BC651D06B0CC53B0F63BCE3C3E27D2604B
+        n = 0xFFFFFFFF00000000FFFFFFFFFFFFFFFFBCE6FAADA7179E84F3B9CAC2FC632551  # Curve order
+        g_x = 0x6B17D1F2E12C4247F8BCE6E563A440F277037D812DEB33A0F4A13945D898C296
+        g_y = 0x4FE342E2FE1A7F9B8EE7EB4A7C0F9E162BCE33576B315ECECBB6406837BF51F5
+
+        return _EllipticCurve(p=p, a=a, b=b, n=n, g_x=g_x, g_y=g_y)
+
+
+class EccKey:
+    def __init__(self, private_key: _EllipticCurve.PrivateKey) -> None:
+        self.private_key = private_key
+
+    @functools.cached_property
+    def x(self) -> bytes:
+        return self.private_key.curve.generate_public_key(
+            self.private_key.key
+        ).x.to_bytes(32, byteorder='big')
+
+    @functools.cached_property
+    def y(self) -> bytes:
+        return self.private_key.curve.generate_public_key(
+            self.private_key.key
+        ).y.to_bytes(32, byteorder='big')
+
+    def dh(self, public_key_x: bytes, public_key_y: bytes) -> bytes:
+        x = int.from_bytes(public_key_x, byteorder='big', signed=False)
+        y = int.from_bytes(public_key_y, byteorder='big', signed=False)
+        return self.private_key.curve.ecdh_shared_secret(
+            self.private_key.key,
+            _Point(x=x, y=y, curve=self.private_key.curve),
+        )
+
+    @classmethod
+    def generate(cls) -> EccKey:
+        return EccKey(_EllipticCurve.SECP256R1().generate_private_key())
+
+    @classmethod
+    def from_private_key_bytes(cls, d_bytes: bytes) -> EccKey:
+        d = int.from_bytes(d_bytes, byteorder='big', signed=False)
+        return EccKey(_EllipticCurve.PrivateKey(d, _EllipticCurve.SECP256R1()))
+
+
+def e(key: bytes, data: bytes) -> bytes:
+    '''
+    AES-128 ECB, expecting byte-swapped inputs and producing a byte-swapped output.
+
+    See Bluetooth spec Vol 3, Part H - 2.2.1 Security function e
+    '''
+
+    return _ECB(key[::-1]).encrypt(data[::-1])[::-1]
+
+
+def aes_cmac(m: bytes, k: bytes) -> bytes:
+    '''
+    See Bluetooth spec, Vol 3, Part H - 2.2.5 FunctionAES-CMAC
+
+    NOTE: the input and output of this internal function are in big-endian byte order
+    '''
+    return _CMAC(key=k, msg=m).digest()

bumble/crypto/cryptography.py

@@ -0,0 +1,82 @@
+# Copyright 2021-2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License")
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import annotations
+
+import functools
+
+from cryptography.hazmat.primitives import ciphers, cmac
+from cryptography.hazmat.primitives.asymmetric import ec
+from cryptography.hazmat.primitives.ciphers import algorithms, modes
+
+
+def e(key: bytes, data: bytes) -> bytes:
+    '''
+    AES-128 ECB, expecting byte-swapped inputs and producing a byte-swapped output.
+
+    See Bluetooth spec Vol 3, Part H - 2.2.1 Security function e
+    '''
+
+    cipher = ciphers.Cipher(algorithms.AES(key[::-1]), modes.ECB())
+    encryptor = cipher.encryptor()
+    return encryptor.update(data[::-1])[::-1]
+
+
+class EccKey:
+    def __init__(self, private_key: ec.EllipticCurvePrivateKey) -> None:
+        self.private_key = private_key
+
+    @classmethod
+    def generate(cls) -> EccKey:
+        return EccKey(ec.generate_private_key(ec.SECP256R1()))
+
+    @classmethod
+    def from_private_key_bytes(cls, d_bytes: bytes) -> EccKey:
+        d = int.from_bytes(d_bytes, byteorder='big', signed=False)
+        return EccKey(ec.derive_private_key(d, ec.SECP256R1()))
+
+    @functools.cached_property
+    def x(self) -> bytes:
+        return (
+            self.private_key.public_key()
+            .public_numbers()
+            .x.to_bytes(32, byteorder='big')
+        )
+
+    @functools.cached_property
+    def y(self) -> bytes:
+        return (
+            self.private_key.public_key()
+            .public_numbers()
+            .y.to_bytes(32, byteorder='big')
+        )
+
+    def dh(self, public_key_x: bytes, public_key_y: bytes) -> bytes:
+        x = int.from_bytes(public_key_x, byteorder='big', signed=False)
+        y = int.from_bytes(public_key_y, byteorder='big', signed=False)
+        return self.private_key.exchange(
+            ec.ECDH(),
+            ec.EllipticCurvePublicNumbers(x, y, ec.SECP256R1()).public_key(),
+        )
+
+
+def aes_cmac(m: bytes, k: bytes) -> bytes:
+    '''
+    See Bluetooth spec, Vol 3, Part H - 2.2.5 FunctionAES-CMAC
+
+    NOTE: the input and output of this internal function are in big-endian byte order
+    '''
+    mac = cmac.CMAC(algorithms.AES(k))
+    mac.update(m)
+    return mac.finalize()

bumble/decoder.py

@@ -12,6 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+
 # -----------------------------------------------------------------------------
 # Constants
 # -----------------------------------------------------------------------------
@@ -149,7 +150,7 @@ QMF_COEFFS = [3, -11, 12, 32, -210, 951, 3876, -805, 362, -156, 53, -11]
 # -----------------------------------------------------------------------------
 # Classes
 # -----------------------------------------------------------------------------
-class G722Decoder(object):
+class G722Decoder:
     """G.722 decoder with bitrate 64kbit/s.
 
     For the Blocks in the sub-band decoders, please refer to the G.722
@@ -157,7 +158,7 @@ class G722Decoder(object):
     https://www.itu.int/rec/T-REC-G.722-201209-I
     """
 
-    def __init__(self):
+    def __init__(self) -> None:
         self._x = [0] * 24
         self._band = [Band(), Band()]
         # The initial value in BLOCK 3L
@@ -165,12 +166,12 @@ class G722Decoder(object):
         # The initial value in BLOCK 3H
         self._band[1].det = 8
 
-    def decode_frame(self, encoded_data) -> bytearray:
+    def decode_frame(self, encoded_data: bytes | bytearray) -> bytearray:
         result_array = bytearray(len(encoded_data) * 4)
         self.g722_decode(result_array, encoded_data)
         return result_array
 
-    def g722_decode(self, result_array, encoded_data) -> int:
+    def g722_decode(self, result_array, encoded_data: bytes | bytearray) -> int:
         """Decode the data frame using g722 decoder."""
         result_length = 0
 
@@ -198,14 +199,16 @@ class G722Decoder(object):
 
         return result_length
 
-    def update_decoded_result(self, xout, byte_length, byte_array) -> int:
+    def update_decoded_result(
+        self, xout: int, byte_length: int, byte_array: bytearray
+    ) -> int:
         result = (int)(xout >> 11)
         bytes_result = result.to_bytes(2, 'little', signed=True)
         byte_array[byte_length] = bytes_result[0]
         byte_array[byte_length + 1] = bytes_result[1]
         return byte_length + 2
 
-    def lower_sub_band_decoder(self, lower_bits) -> int:
+    def lower_sub_band_decoder(self, lower_bits: int) -> int:
         """Lower sub-band decoder for last six bits."""
 
         # Block 5L
@@ -258,7 +261,7 @@ class G722Decoder(object):
 
         return rlow
 
-    def higher_sub_band_decoder(self, higher_bits) -> int:
+    def higher_sub_band_decoder(self, higher_bits: int) -> int:
         """Higher sub-band decoder for first two bits."""
 
         # Block 2H
@@ -306,14 +309,14 @@ class G722Decoder(object):
 
 
 # -----------------------------------------------------------------------------
-class Band(object):
-    """Structure for G722 decode proccessing."""
+class Band:
+    """Structure for G722 decode processing."""
 
     s: int = 0
     nb: int = 0
     det: int = 0
 
-    def __init__(self):
+    def __init__(self) -> None:
         self._sp = 0
         self._sz = 0
         self._r = [0] * 3

bumble/drivers/__init__.py

@@ -0,0 +1,93 @@
+# Copyright 2021-2022 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""
+Drivers that can be used to customize the interaction between a host and a controller,
+like loading firmware after a cold start.
+"""
+
+# -----------------------------------------------------------------------------
+# Imports
+# -----------------------------------------------------------------------------
+from __future__ import annotations
+
+import logging
+import pathlib
+import platform
+from collections.abc import Iterable
+from typing import TYPE_CHECKING
+
+from bumble.drivers import intel, rtk
+from bumble.drivers.common import Driver
+
+if TYPE_CHECKING:
+    from bumble.host import Host
+
+# -----------------------------------------------------------------------------
+# Logging
+# -----------------------------------------------------------------------------
+logger = logging.getLogger(__name__)
+
+
+# -----------------------------------------------------------------------------
+# Functions
+# -----------------------------------------------------------------------------
+async def get_driver_for_host(host: Host) -> Driver | None:
+    """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.
+    """
+    driver_classes: dict[str, type[Driver]] = {"rtk": rtk.Driver, "intel": intel.Driver}
+    probe_list: Iterable[str]
+    if driver_name := host.hci_metadata.get("driver"):
+        # The "driver" metadata may include runtime options after a '/' (for example
+        # "intel/ddc=..."). Keep only the base driver name (the portion before the
+        # first slash) so it matches a key in driver_classes (e.g. "intel").
+        driver_name = driver_name.split("/")[0]
+        # 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
+
+
+def project_data_dir() -> pathlib.Path:
+    """
+    Returns:
+        A path to an OS-specific directory for bumble data. The directory is created if
+         it doesn't exist.
+    """
+    import platformdirs
+
+    if platform.system() == 'Darwin':
+        # platformdirs doesn't handle macOS right: it doesn't assemble a bundle id
+        # out of author & project
+        return platformdirs.user_data_path(
+            appname='com.google.bumble', ensure_exists=True
+        )
+    else:
+        # windows and linux don't use the com qualifier
+        return platformdirs.user_data_path(
+            appname='bumble', appauthor='google', ensure_exists=True
+        )

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

bumble/drivers/rtk.py

@@ -0,0 +1,735 @@
+# 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.
+"""
+Support for Realtek USB dongles.
+Based on various online bits of information, including the Linux kernel.
+(see `drivers/bluetooth/btrtl.c`)
+"""
+from __future__ import annotations
+
+import asyncio
+import enum
+import logging
+import math
+import os
+import pathlib
+import platform
+import struct
+import weakref
+
+# -----------------------------------------------------------------------------
+# Imports
+# -----------------------------------------------------------------------------
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+from bumble import core, hci
+from bumble.drivers import common
+
+if TYPE_CHECKING:
+    from bumble.host import Host
+
+# -----------------------------------------------------------------------------
+# Logging
+# -----------------------------------------------------------------------------
+logger = logging.getLogger(__name__)
+
+
+class RtkFirmwareError(core.BaseBumbleError):
+    """Error raised when RTK firmware initialization fails."""
+
+
+# -----------------------------------------------------------------------------
+# Constants
+# -----------------------------------------------------------------------------
+RTK_ROM_LMP_8723A = 0x1200
+RTK_ROM_LMP_8723B = 0x8723
+RTK_ROM_LMP_8821A = 0x8821
+RTK_ROM_LMP_8761A = 0x8761
+RTK_ROM_LMP_8822B = 0x8822
+RTK_ROM_LMP_8852A = 0x8852
+RTK_CONFIG_MAGIC = 0x8723AB55
+
+RTK_EPATCH_SIGNATURE = b"Realtech"
+
+RTK_FRAGMENT_LENGTH = 252
+
+RTK_FIRMWARE_DIR_ENV = "BUMBLE_RTK_FIRMWARE_DIR"
+RTK_LINUX_FIRMWARE_DIR = "/lib/firmware/rtl_bt"
+
+
+class RtlProjectId(enum.IntEnum):
+    PROJECT_ID_8723A = 0
+    PROJECT_ID_8723B = 1
+    PROJECT_ID_8821A = 2
+    PROJECT_ID_8761A = 3
+    PROJECT_ID_8822B = 8
+    PROJECT_ID_8723D = 9
+    PROJECT_ID_8821C = 10
+    PROJECT_ID_8822C = 13
+    PROJECT_ID_8761B = 14
+    PROJECT_ID_8852A = 18
+    PROJECT_ID_8852B = 20
+    PROJECT_ID_8852C = 25
+    PROJECT_ID_8761C = 51
+
+
+RTK_PROJECT_ID_TO_ROM = {
+    0: RTK_ROM_LMP_8723A,
+    1: RTK_ROM_LMP_8723B,
+    2: RTK_ROM_LMP_8821A,
+    3: RTK_ROM_LMP_8761A,
+    8: RTK_ROM_LMP_8822B,
+    9: RTK_ROM_LMP_8723B,
+    10: RTK_ROM_LMP_8821A,
+    13: RTK_ROM_LMP_8822B,
+    14: RTK_ROM_LMP_8761A,
+    18: RTK_ROM_LMP_8852A,
+    20: RTK_ROM_LMP_8852A,
+    25: RTK_ROM_LMP_8852A,
+    51: RTK_ROM_LMP_8761A,
+}
+
+# List of USB (VendorID, ProductID) for Realtek-based devices.
+RTK_USB_PRODUCTS = {
+    # Realtek 8723AE
+    (0x0930, 0x021D),
+    (0x13D3, 0x3394),
+    # Realtek 8723BE
+    (0x0489, 0xE085),
+    (0x0489, 0xE08B),
+    (0x04F2, 0xB49F),
+    (0x13D3, 0x3410),
+    (0x13D3, 0x3416),
+    (0x13D3, 0x3459),
+    (0x13D3, 0x3494),
+    # Realtek 8723BU
+    (0x7392, 0xA611),
+    # Realtek 8723DE
+    (0x0BDA, 0xB009),
+    (0x2FF8, 0xB011),
+    # Realtek 8761BUV
+    (0x0B05, 0x190E),
+    (0x0BDA, 0x8771),
+    (0x0BDA, 0x877B),
+    (0x0BDA, 0xA728),
+    (0x0BDA, 0xA729),
+    (0x2230, 0x0016),
+    (0x2357, 0x0604),
+    (0x2550, 0x8761),
+    (0x2B89, 0x8761),
+    (0x7392, 0xC611),
+    # Realtek 8761CUV
+    (0x0B05, 0x1BF6),
+    (0x0BDA, 0xC761),
+    (0x7392, 0xF611),
+    # Realtek 8821AE
+    (0x0B05, 0x17DC),
+    (0x13D3, 0x3414),
+    (0x13D3, 0x3458),
+    (0x13D3, 0x3461),
+    (0x13D3, 0x3462),
+    # Realtek 8821CE
+    (0x0BDA, 0xB00C),
+    (0x0BDA, 0xC822),
+    (0x13D3, 0x3529),
+    # Realtek 8822BE
+    (0x0B05, 0x185C),
+    (0x13D3, 0x3526),
+    # Realtek 8822CE
+    (0x04C5, 0x161F),
+    (0x04CA, 0x4005),
+    (0x0B05, 0x18EF),
+    (0x0BDA, 0xB00C),
+    (0x0BDA, 0xC123),
+    (0x0BDA, 0xC822),
+    (0x0CB5, 0xC547),
+    (0x1358, 0xC123),
+    (0x13D3, 0x3548),
+    (0x13D3, 0x3549),
+    (0x13D3, 0x3553),
+    (0x13D3, 0x3555),
+    (0x2FF8, 0x3051),
+    # Realtek 8822CU
+    (0x13D3, 0x3549),
+    # Realtek 8852AE
+    (0x04C5, 0x165C),
+    (0x04CA, 0x4006),
+    (0x0BDA, 0x2852),
+    (0x0BDA, 0x385A),
+    (0x0BDA, 0x4852),
+    (0x0BDA, 0xC852),
+    (0x0CB8, 0xC549),
+    # Realtek 8852BE
+    (0x0BDA, 0x887B),
+    (0x0CB8, 0xC559),
+    (0x13D3, 0x3571),
+    # Realtek 8852CE
+    (0x04C5, 0x1675),
+    (0x04CA, 0x4007),
+    (0x0CB8, 0xC558),
+    (0x13D3, 0x3586),
+    (0x13D3, 0x3587),
+    (0x13D3, 0x3592),
+}
+
+# -----------------------------------------------------------------------------
+# HCI Commands
+# -----------------------------------------------------------------------------
+HCI_RTK_READ_ROM_VERSION_COMMAND = hci.hci_vendor_command_op_code(0x6D)
+HCI_RTK_DOWNLOAD_COMMAND = hci.hci_vendor_command_op_code(0x20)
+HCI_RTK_DROP_FIRMWARE_COMMAND = hci.hci_vendor_command_op_code(0x66)
+hci.HCI_Command.register_commands(globals())
+
+
+@dataclass
+class HCI_RTK_Read_ROM_Version_ReturnParameters(hci.HCI_StatusReturnParameters):
+    version: int = field(metadata=hci.metadata(1))
+
+
+@hci.HCI_SyncCommand.sync_command(HCI_RTK_Read_ROM_Version_ReturnParameters)
+@dataclass
+class HCI_RTK_Read_ROM_Version_Command(
+    hci.HCI_SyncCommand[HCI_RTK_Read_ROM_Version_ReturnParameters]
+):
+    pass
+
+
+@dataclass
+class HCI_RTK_Download_ReturnParameters(hci.HCI_StatusReturnParameters):
+    index: int = field(metadata=hci.metadata(1))
+
+
+@hci.HCI_SyncCommand.sync_command(HCI_RTK_Download_ReturnParameters)
+@dataclass
+class HCI_RTK_Download_Command(hci.HCI_SyncCommand[HCI_RTK_Download_ReturnParameters]):
+    index: int = field(metadata=hci.metadata(1))
+    payload: bytes = field(metadata=hci.metadata(RTK_FRAGMENT_LENGTH))
+
+
+@hci.HCI_SyncCommand.sync_command(hci.HCI_GenericReturnParameters)
+@dataclass
+class HCI_RTK_Drop_Firmware_Command(
+    hci.HCI_SyncCommand[hci.HCI_GenericReturnParameters]
+):
+    pass
+
+
+# -----------------------------------------------------------------------------
+class Firmware:
+    def __init__(self, firmware):
+        extension_sig = bytes([0x51, 0x04, 0xFD, 0x77])
+
+        if not firmware.startswith(RTK_EPATCH_SIGNATURE):
+            raise RtkFirmwareError("Firmware does not start with epatch signature")
+
+        if not firmware.endswith(extension_sig):
+            raise RtkFirmwareError("Firmware does not end with extension sig")
+
+        # The firmware should start with a 14 byte header.
+        epatch_header_size = 14
+        if len(firmware) < epatch_header_size:
+            raise RtkFirmwareError("Firmware too short")
+
+        # Look for the "project ID", starting from the end.
+        offset = len(firmware) - len(extension_sig)
+        project_id = -1
+        while offset >= epatch_header_size:
+            length, opcode = firmware[offset - 2 : offset]
+            offset -= 2
+
+            if opcode == 0xFF:
+                # End
+                break
+
+            if length == 0:
+                raise RtkFirmwareError("Invalid 0-length instruction")
+
+            if opcode == 0 and length == 1:
+                project_id = firmware[offset - 1]
+                break
+
+            offset -= length
+
+        if project_id < 0:
+            raise RtkFirmwareError("Project ID not found")
+
+        self.project_id = project_id
+
+        # Read the patch tables info.
+        self.version, num_patches = struct.unpack("<IH", firmware[8:14])
+        self.patches = []
+
+        # The patches tables are laid out as:
+        # <ChipID_1><ChipID_2>...<ChipID_N>  (16 bits each)
+        # <PatchLength_1><PatchLength_2>...<PatchLength_N> (16 bits each)
+        # <PatchOffset_1><PatchOffset_2>...<PatchOffset_N> (32 bits each)
+        if epatch_header_size + 8 * num_patches > len(firmware):
+            raise RtkFirmwareError("Firmware too short")
+        chip_id_table_offset = epatch_header_size
+        patch_length_table_offset = chip_id_table_offset + 2 * num_patches
+        patch_offset_table_offset = chip_id_table_offset + 4 * num_patches
+        for patch_index in range(num_patches):
+            chip_id_offset = chip_id_table_offset + 2 * patch_index
+            (chip_id,) = struct.unpack_from("<H", firmware, chip_id_offset)
+            (patch_length,) = struct.unpack_from(
+                "<H", firmware, patch_length_table_offset + 2 * patch_index
+            )
+            (patch_offset,) = struct.unpack_from(
+                "<I", firmware, patch_offset_table_offset + 4 * patch_index
+            )
+            if patch_offset + patch_length > len(firmware):
+                raise RtkFirmwareError("Firmware too short")
+
+            # Get the SVN version for the patch
+            (svn_version,) = struct.unpack_from(
+                "<I", firmware, patch_offset + patch_length - 8
+            )
+
+            # Create a payload with the patch, replacing the last 4 bytes with
+            # the firmware version.
+            self.patches.append(
+                (
+                    chip_id,
+                    firmware[patch_offset : patch_offset + patch_length - 4]
+                    + struct.pack("<I", self.version),
+                    svn_version,
+                )
+            )
+
+
+class Driver(common.Driver):
+    @dataclass
+    class DriverInfo:
+        rom: int
+        hci: tuple[int, int]
+        config_needed: bool
+        has_rom_version: bool
+        has_msft_ext: bool = False
+        fw_name: str = ""
+        config_name: str = ""
+
+    POST_RESET_DELAY: float = 0.2
+
+    DRIVER_INFOS = [
+        # 8723A
+        DriverInfo(
+            rom=RTK_ROM_LMP_8723A,
+            hci=(0x0B, 0x06),
+            config_needed=False,
+            has_rom_version=False,
+            fw_name="rtl8723a_fw.bin",
+            config_name="",
+        ),
+        # 8723B
+        DriverInfo(
+            rom=RTK_ROM_LMP_8723B,
+            hci=(0x0B, 0x06),
+            config_needed=False,
+            has_rom_version=True,
+            fw_name="rtl8723b_fw.bin",
+            config_name="rtl8723b_config.bin",
+        ),
+        # 8723D
+        DriverInfo(
+            rom=RTK_ROM_LMP_8723B,
+            hci=(0x0D, 0x08),
+            config_needed=True,
+            has_rom_version=True,
+            fw_name="rtl8723d_fw.bin",
+            config_name="rtl8723d_config.bin",
+        ),
+        # 8821A
+        DriverInfo(
+            rom=RTK_ROM_LMP_8821A,
+            hci=(0x0A, 0x06),
+            config_needed=False,
+            has_rom_version=True,
+            fw_name="rtl8821a_fw.bin",
+            config_name="rtl8821a_config.bin",
+        ),
+        # 8821C
+        DriverInfo(
+            rom=RTK_ROM_LMP_8821A,
+            hci=(0x0C, 0x08),
+            config_needed=False,
+            has_rom_version=True,
+            has_msft_ext=True,
+            fw_name="rtl8821c_fw.bin",
+            config_name="rtl8821c_config.bin",
+        ),
+        # 8761A
+        DriverInfo(
+            rom=RTK_ROM_LMP_8761A,
+            hci=(0x0A, 0x06),
+            config_needed=False,
+            has_rom_version=True,
+            fw_name="rtl8761a_fw.bin",
+            config_name="rtl8761a_config.bin",
+        ),
+        # 8761BU
+        DriverInfo(
+            rom=RTK_ROM_LMP_8761A,
+            hci=(0x0B, 0x0A),
+            config_needed=False,
+            has_rom_version=True,
+            fw_name="rtl8761bu_fw.bin",
+            config_name="rtl8761bu_config.bin",
+        ),
+        # 8761CU
+        DriverInfo(
+            rom=RTK_ROM_LMP_8761A,
+            hci=(0x0E, 0x00),
+            config_needed=False,
+            has_rom_version=True,
+            fw_name="rtl8761cu_fw.bin",
+            config_name="rtl8761cu_config.bin",
+        ),
+        # 8822C
+        DriverInfo(
+            rom=RTK_ROM_LMP_8822B,
+            hci=(0x0C, 0x0A),
+            config_needed=False,
+            has_rom_version=True,
+            has_msft_ext=True,
+            fw_name="rtl8822cu_fw.bin",
+            config_name="rtl8822cu_config.bin",
+        ),
+        # 8822B
+        DriverInfo(
+            rom=RTK_ROM_LMP_8822B,
+            hci=(0x0B, 0x07),
+            config_needed=True,
+            has_rom_version=True,
+            has_msft_ext=True,
+            fw_name="rtl8822b_fw.bin",
+            config_name="rtl8822b_config.bin",
+        ),
+        # 8852A
+        DriverInfo(
+            rom=RTK_ROM_LMP_8852A,
+            hci=(0x0A, 0x0B),
+            config_needed=False,
+            has_rom_version=True,
+            has_msft_ext=True,
+            fw_name="rtl8852au_fw.bin",
+            config_name="rtl8852au_config.bin",
+        ),
+        # 8852B
+        DriverInfo(
+            rom=RTK_ROM_LMP_8852A,
+            hci=(0xB, 0xB),
+            config_needed=False,
+            has_rom_version=True,
+            has_msft_ext=True,
+            fw_name="rtl8852bu_fw.bin",
+            config_name="rtl8852bu_config.bin",
+        ),
+        # 8852C
+        DriverInfo(
+            rom=RTK_ROM_LMP_8852A,
+            hci=(0x0C, 0x0C),
+            config_needed=False,
+            has_rom_version=True,
+            has_msft_ext=True,
+            fw_name="rtl8852cu_fw.bin",
+            config_name="rtl8852cu_config.bin",
+        ),
+    ]
+
+    POST_DROP_DELAY = 0.2
+
+    @staticmethod
+    def find_driver_info(hci_version, hci_subversion, lmp_subversion):
+        for driver_info in Driver.DRIVER_INFOS:
+            if driver_info.rom == lmp_subversion and (
+                driver_info.hci
+                == (
+                    hci_subversion,
+                    hci_version,
+                )
+                or driver_info.hci
+                == (
+                    hci_subversion,
+                    0x0,
+                )
+            ):
+                return driver_info
+
+        return None
+
+    @staticmethod
+    def find_binary_path(file_name):
+        # First check if an environment variable is set
+        if RTK_FIRMWARE_DIR_ENV in os.environ:
+            if (
+                path := pathlib.Path(os.environ[RTK_FIRMWARE_DIR_ENV]) / file_name
+            ).is_file():
+                logger.debug(f"{file_name} found in env dir")
+                return path
+
+            # When the environment variable is set, don't look elsewhere
+            return None
+
+        # Then, look where the firmware download tool writes by default
+        if (path := rtk_firmware_dir() / file_name).is_file():
+            logger.debug(f"{file_name} found in project data dir")
+            return path
+
+        # Then, look in the package's driver directory
+        if (path := pathlib.Path(__file__).parent / "rtk_fw" / file_name).is_file():
+            logger.debug(f"{file_name} found in package dir")
+            return path
+
+        # On Linux, check the system's FW directory
+        if (
+            platform.system() == "Linux"
+            and (path := pathlib.Path(RTK_LINUX_FIRMWARE_DIR) / file_name).is_file()
+        ):
+            logger.debug(f"{file_name} found in Linux system FW dir")
+            return path
+
+        # Finally look in the current directory
+        if (path := pathlib.Path.cwd() / file_name).is_file():
+            logger.debug(f"{file_name} found in CWD")
+            return path
+
+        return None
+
+    @staticmethod
+    def check(host: Host) -> bool:
+        if not host.hci_metadata:
+            logger.debug("USB metadata not found")
+            return False
+
+        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
+
+        if (vendor_id, product_id) not in RTK_USB_PRODUCTS:
+            logger.debug(
+                f"USB device ({vendor_id:04X}, {product_id:04X}) not in known list"
+            )
+            return False
+
+        return True
+
+    @staticmethod
+    async def get_loaded_firmware_version(host: Host) -> int | None:
+        response1 = await host.send_sync_command(
+            HCI_RTK_Read_ROM_Version_Command(), check_status=False
+        )
+
+        if response1.status != hci.HCI_SUCCESS:
+            return None
+
+        response2 = await host.send_sync_command(
+            hci.HCI_Read_Local_Version_Information_Command()
+        )
+        return response2.hci_subversion << 16 | response2.lmp_subversion
+
+    @classmethod
+    async def driver_info_for_host(cls, host: Host) -> DriverInfo | None:
+        try:
+            await host.send_sync_command(
+                hci.HCI_Reset_Command(),
+                response_timeout=cls.POST_RESET_DELAY,
+            )
+            host.ready = True  # Needed to let the host know the controller is ready.
+        except asyncio.exceptions.TimeoutError:
+            logger.warning("timeout waiting for hci reset, retrying")
+            await host.send_sync_command(hci.HCI_Reset_Command())
+            host.ready = True
+
+        command = hci.HCI_Read_Local_Version_Information_Command()
+        response = await host.send_sync_command(command, check_status=False)
+        if response.status != hci.HCI_SUCCESS:
+            logger.error("failed to probe local version information")
+            return None
+
+        local_version = response
+
+        logger.debug(
+            f"looking for a driver: 0x{local_version.lmp_subversion:04X} "
+            f"(0x{local_version.hci_version:02X}, "
+            f"0x{local_version.hci_subversion:04X})"
+        )
+
+        driver_info = cls.find_driver_info(
+            local_version.hci_version,
+            local_version.hci_subversion,
+            local_version.lmp_subversion,
+        )
+        if driver_info is None:
+            # TODO: it seems that the Linux driver will send command (0x3f, 0x66)
+            # in this case and then re-read the local version, then re-match.
+            logger.debug("firmware already loaded or no known driver for this device")
+
+        return driver_info
+
+    @classmethod
+    async def for_host(cls, host: Host, force: bool = False):
+        # Check that a driver is needed for this host
+        if not force and not cls.check(host):
+            return None
+
+        # Get the driver info
+        driver_info = await cls.driver_info_for_host(host)
+        if driver_info is None:
+            return None
+
+        # Load the firmware
+        firmware_path = cls.find_binary_path(driver_info.fw_name)
+        if not firmware_path:
+            logger.warning(f"Firmware file {driver_info.fw_name} not found")
+            logger.warning("See https://google.github.io/bumble/drivers/realtek.html")
+            return None
+        with open(firmware_path, "rb") as firmware_file:
+            firmware = firmware_file.read()
+
+        # Load the config
+        config = None
+        if driver_info.config_name:
+            config_path = cls.find_binary_path(driver_info.config_name)
+            if config_path:
+                with open(config_path, "rb") as config_file:
+                    config = config_file.read()
+        if driver_info.config_needed and not config:
+            logger.warning("Config needed, but no config file available")
+            return None
+
+        return cls(host, driver_info, firmware, config)
+
+    def __init__(self, host, driver_info, firmware, config):
+        self.host = weakref.proxy(host)
+        self.driver_info = driver_info
+        self.firmware = firmware
+        self.config = config
+
+    @staticmethod
+    async def drop_firmware(host):
+        host.send_hci_packet(HCI_RTK_Drop_Firmware_Command())
+
+        # Wait for the command to be effective (no response is sent)
+        await asyncio.sleep(Driver.POST_DROP_DELAY)
+
+    async def download_for_rtl8723a(self):
+        # Check that the firmware image does not include an epatch signature.
+        if RTK_EPATCH_SIGNATURE in self.firmware:
+            logger.warning(
+                "epatch signature found in firmware, it is probably the wrong firmware"
+            )
+            return
+
+        # TODO: load the firmware
+
+    async def download_for_rtl8723b(self):
+        if self.driver_info.has_rom_version:
+            response1 = await self.host.send_sync_command(
+                HCI_RTK_Read_ROM_Version_Command(), check_status=False
+            )
+            if response1.status != hci.HCI_SUCCESS:
+                logger.warning("can't get ROM version")
+                return None
+            rom_version = response1.version
+            logger.debug(f"ROM version before download: {rom_version:04X}")
+        else:
+            rom_version = 0
+
+        firmware = Firmware(self.firmware)
+        logger.debug(f"firmware: project_id=0x{firmware.project_id:04X}")
+        logger.debug(f"firmware: version=0x{firmware.version:04X}")
+        for patch in firmware.patches:
+            if patch[0] == rom_version + 1:
+                logger.debug(f"using patch {patch[0]}")
+                break
+        else:
+            logger.warning("no valid patch found for rom version {rom_version}")
+            return None
+
+        # Append the config if there is one.
+        if self.config:
+            payload = patch[1] + self.config
+        else:
+            payload = patch[1]
+
+        # Download the payload, one fragment at a time.
+        fragment_count = math.ceil(len(payload) / RTK_FRAGMENT_LENGTH)
+        for fragment_index in range(fragment_count):
+            # NOTE: the Linux driver somehow adds 1 to the index after it wraps around.
+            # That's odd, but we"ll do the same here.
+            download_index = fragment_index & 0x7F
+            if download_index >= 0x80:
+                download_index += 1
+            if fragment_index == fragment_count - 1:
+                download_index |= 0x80  # End marker.
+            fragment_offset = fragment_index * RTK_FRAGMENT_LENGTH
+            fragment = payload[fragment_offset : fragment_offset + RTK_FRAGMENT_LENGTH]
+            logger.debug(f"downloading fragment {fragment_index}")
+            await self.host.send_sync_command(
+                HCI_RTK_Download_Command(index=download_index, payload=fragment)
+            )
+
+        logger.debug("download complete!")
+
+        # Read the version again
+        response2 = await self.host.send_sync_command(
+            HCI_RTK_Read_ROM_Version_Command(), check_status=False
+        )
+        if response2.status != hci.HCI_SUCCESS:
+            logger.warning("can't get ROM version")
+        else:
+            rom_version = response2.version
+            logger.debug(f"ROM version after download: {rom_version:02X}")
+
+        return firmware.version
+
+    async def download_firmware(self):
+        if self.driver_info.rom == RTK_ROM_LMP_8723A:
+            return await self.download_for_rtl8723a()
+
+        if self.driver_info.rom in (
+            RTK_ROM_LMP_8723B,
+            RTK_ROM_LMP_8821A,
+            RTK_ROM_LMP_8761A,
+            RTK_ROM_LMP_8822B,
+            RTK_ROM_LMP_8852A,
+        ):
+            return await self.download_for_rtl8723b()
+
+        raise RtkFirmwareError("ROM not supported")
+
+    async def init_controller(self):
+        await self.download_firmware()
+        await self.host.send_sync_command(hci.HCI_Reset_Command())
+        logger.info(f"loaded FW image {self.driver_info.fw_name}")
+
+
+def rtk_firmware_dir() -> pathlib.Path:
+    """
+    Returns:
+        A path to a subdir of the project data dir for Realtek firmware.
+         The directory is created if it doesn't exist.
+    """
+    from bumble.drivers import project_data_dir
+
+    p = project_data_dir() / "firmware" / "realtek"
+    p.mkdir(parents=True, exist_ok=True)
+    return p

bumble/gap.py

@@ -18,12 +18,12 @@
 import logging
 import struct
 
-from .gatt import (
-    Service,
-    Characteristic,
-    GATT_GENERIC_ACCESS_SERVICE,
-    GATT_DEVICE_NAME_CHARACTERISTIC,
+from bumble.gatt import (
     GATT_APPEARANCE_CHARACTERISTIC,
+    GATT_DEVICE_NAME_CHARACTERISTIC,
+    GATT_GENERIC_ACCESS_SERVICE,
+    Characteristic,
+    Service,
 )
 
 # -----------------------------------------------------------------------------
@@ -36,6 +36,7 @@ logger = logging.getLogger(__name__)
 # Classes
 # -----------------------------------------------------------------------------
 
+
 # -----------------------------------------------------------------------------
 class GenericAccessService(Service):
     def __init__(self, device_name, appearance=(0, 0)):

bumble/gatt.py

@@ -23,17 +23,22 @@
 # Imports
 # -----------------------------------------------------------------------------
 from __future__ import annotations
-import asyncio
+
 import enum
 import functools
 import logging
 import struct
-from typing import Optional, Sequence, List
+from collections.abc import Iterable, Sequence
+from typing import ClassVar, TypeVar
 
-from .colors import color
-from .core import UUID, get_dict_key_by_value
-from .att import Attribute
+from bumble.att import Attribute, AttributeValue, AttributeValueV2
+from bumble.colors import color
+from bumble.core import UUID, BaseBumbleError
 
+# -----------------------------------------------------------------------------
+# Typing
+# -----------------------------------------------------------------------------
+_T = TypeVar('_T')
 
 # -----------------------------------------------------------------------------
 # Logging
@@ -93,20 +98,35 @@ GATT_RECONNECTION_CONFIGURATION_SERVICE     = UUID.from_16_bits(0x1829, 'Reconne
 GATT_INSULIN_DELIVERY_SERVICE               = UUID.from_16_bits(0x183A, 'Insulin Delivery')
 GATT_BINARY_SENSOR_SERVICE                  = UUID.from_16_bits(0x183B, 'Binary Sensor')
 GATT_EMERGENCY_CONFIGURATION_SERVICE        = UUID.from_16_bits(0x183C, 'Emergency Configuration')
+GATT_AUTHORIZATION_CONTROL_SERVICE          = UUID.from_16_bits(0x183D, 'Authorization Control')
 GATT_PHYSICAL_ACTIVITY_MONITOR_SERVICE      = UUID.from_16_bits(0x183E, 'Physical Activity Monitor')
+GATT_ELAPSED_TIME_SERVICE                   = UUID.from_16_bits(0x183F, 'Elapsed Time')
+GATT_GENERIC_HEALTH_SENSOR_SERVICE          = UUID.from_16_bits(0x1840, 'Generic Health Sensor')
 GATT_AUDIO_INPUT_CONTROL_SERVICE            = UUID.from_16_bits(0x1843, 'Audio Input Control')
 GATT_VOLUME_CONTROL_SERVICE                 = UUID.from_16_bits(0x1844, 'Volume Control')
 GATT_VOLUME_OFFSET_CONTROL_SERVICE          = UUID.from_16_bits(0x1845, 'Volume Offset Control')
-GATT_COORDINATED_SET_IDENTIFICATION_SERVICE = UUID.from_16_bits(0x1846, 'Coordinated Set Identification Service')
+GATT_COORDINATED_SET_IDENTIFICATION_SERVICE = UUID.from_16_bits(0x1846, 'Coordinated Set Identification')
 GATT_DEVICE_TIME_SERVICE                    = UUID.from_16_bits(0x1847, 'Device Time')
-GATT_MEDIA_CONTROL_SERVICE                  = UUID.from_16_bits(0x1848, 'Media Control Service')
-GATT_GENERIC_MEDIA_CONTROL_SERVICE          = UUID.from_16_bits(0x1849, 'Generic Media Control Service')
+GATT_MEDIA_CONTROL_SERVICE                  = UUID.from_16_bits(0x1848, 'Media Control')
+GATT_GENERIC_MEDIA_CONTROL_SERVICE          = UUID.from_16_bits(0x1849, 'Generic Media Control')
 GATT_CONSTANT_TONE_EXTENSION_SERVICE        = UUID.from_16_bits(0x184A, 'Constant Tone Extension')
-GATT_TELEPHONE_BEARER_SERVICE               = UUID.from_16_bits(0x184B, 'Telephone Bearer Service')
-GATT_GENERIC_TELEPHONE_BEARER_SERVICE       = UUID.from_16_bits(0x184C, 'Generic Telephone Bearer Service')
+GATT_TELEPHONE_BEARER_SERVICE               = UUID.from_16_bits(0x184B, 'Telephone Bearer')
+GATT_GENERIC_TELEPHONE_BEARER_SERVICE       = UUID.from_16_bits(0x184C, 'Generic Telephone Bearer')
 GATT_MICROPHONE_CONTROL_SERVICE             = UUID.from_16_bits(0x184D, 'Microphone Control')
+GATT_AUDIO_STREAM_CONTROL_SERVICE           = UUID.from_16_bits(0x184E, 'Audio Stream Control')
+GATT_BROADCAST_AUDIO_SCAN_SERVICE           = UUID.from_16_bits(0x184F, 'Broadcast Audio Scan')
+GATT_PUBLISHED_AUDIO_CAPABILITIES_SERVICE   = UUID.from_16_bits(0x1850, 'Published Audio Capabilities')
+GATT_BASIC_AUDIO_ANNOUNCEMENT_SERVICE       = UUID.from_16_bits(0x1851, 'Basic Audio Announcement')
+GATT_BROADCAST_AUDIO_ANNOUNCEMENT_SERVICE   = UUID.from_16_bits(0x1852, 'Broadcast Audio Announcement')
+GATT_COMMON_AUDIO_SERVICE                   = UUID.from_16_bits(0x1853, 'Common Audio')
+GATT_HEARING_ACCESS_SERVICE                 = UUID.from_16_bits(0x1854, 'Hearing Access')
+GATT_TELEPHONY_AND_MEDIA_AUDIO_SERVICE      = UUID.from_16_bits(0x1855, 'Telephony and Media Audio')
+GATT_PUBLIC_BROADCAST_ANNOUNCEMENT_SERVICE  = UUID.from_16_bits(0x1856, 'Public Broadcast Announcement')
+GATT_ELECTRONIC_SHELF_LABEL_SERVICE         = UUID.from_16_bits(0X1857, 'Electronic Shelf Label')
+GATT_GAMING_AUDIO_SERVICE                   = UUID.from_16_bits(0x1858, 'Gaming Audio')
+GATT_MESH_PROXY_SOLICITATION_SERVICE        = UUID.from_16_bits(0x1859, 'Mesh Audio Solicitation')
 
-# Types
+# Attribute Types
 GATT_PRIMARY_SERVICE_ATTRIBUTE_TYPE   = UUID.from_16_bits(0x2800, 'Primary Service')
 GATT_SECONDARY_SERVICE_ATTRIBUTE_TYPE = UUID.from_16_bits(0x2801, 'Secondary Service')
 GATT_INCLUDE_ATTRIBUTE_TYPE           = UUID.from_16_bits(0x2802, 'Include')
@@ -129,6 +149,8 @@ GATT_ENVIRONMENTAL_SENSING_MEASUREMENT_DESCRIPTOR    = UUID.from_16_bits(0x290C,
 GATT_ENVIRONMENTAL_SENSING_TRIGGER_DESCRIPTOR        = UUID.from_16_bits(0x290D, 'Environmental Sensing Trigger Setting')
 GATT_TIME_TRIGGER_DESCRIPTOR                         = UUID.from_16_bits(0x290E, 'Time Trigger Setting')
 GATT_COMPLETE_BR_EDR_TRANSPORT_BLOCK_DATA_DESCRIPTOR = UUID.from_16_bits(0x290F, 'Complete BR-EDR Transport Block Data')
+GATT_OBSERVATION_SCHEDULE_DESCRIPTOR                 = UUID.from_16_bits(0x290F, 'Observation Schedule')
+GATT_VALID_RANGE_AND_ACCURACY_DESCRIPTOR             = UUID.from_16_bits(0x290F, 'Valid Range And Accuracy')
 
 # Device Information Service
 GATT_SYSTEM_ID_CHARACTERISTIC                          = UUID.from_16_bits(0x2A23, 'System ID')
@@ -156,6 +178,107 @@ GATT_HEART_RATE_CONTROL_POINT_CHARACTERISTIC = UUID.from_16_bits(0x2A39, 'Heart
 # Battery Service
 GATT_BATTERY_LEVEL_CHARACTERISTIC = UUID.from_16_bits(0x2A19, 'Battery Level')
 
+# Telephony And Media Audio Service (TMAS)
+GATT_TMAP_ROLE_CHARACTERISTIC = UUID.from_16_bits(0x2B51, 'TMAP Role')
+
+# Audio Input Control Service (AICS)
+GATT_AUDIO_INPUT_STATE_CHARACTERISTIC         = UUID.from_16_bits(0x2B77, 'Audio Input State')
+GATT_GAIN_SETTINGS_ATTRIBUTE_CHARACTERISTIC   = UUID.from_16_bits(0x2B78, 'Gain Settings Attribute')
+GATT_AUDIO_INPUT_TYPE_CHARACTERISTIC          = UUID.from_16_bits(0x2B79, 'Audio Input Type')
+GATT_AUDIO_INPUT_STATUS_CHARACTERISTIC        = UUID.from_16_bits(0x2B7A, 'Audio Input Status')
+GATT_AUDIO_INPUT_CONTROL_POINT_CHARACTERISTIC = UUID.from_16_bits(0x2B7B, 'Audio Input Control Point')
+GATT_AUDIO_INPUT_DESCRIPTION_CHARACTERISTIC   = UUID.from_16_bits(0x2B7C, 'Audio Input Description')
+
+# Volume Control Service (VCS)
+GATT_VOLUME_STATE_CHARACTERISTIC                = UUID.from_16_bits(0x2B7D, 'Volume State')
+GATT_VOLUME_CONTROL_POINT_CHARACTERISTIC        = UUID.from_16_bits(0x2B7E, 'Volume Control Point')
+GATT_VOLUME_FLAGS_CHARACTERISTIC                = UUID.from_16_bits(0x2B7F, 'Volume Flags')
+
+# Volume Offset Control Service (VOCS)
+GATT_VOLUME_OFFSET_STATE_CHARACTERISTIC         = UUID.from_16_bits(0x2B80, 'Volume Offset State')
+GATT_AUDIO_LOCATION_CHARACTERISTIC              = UUID.from_16_bits(0x2B81, 'Audio Location')
+GATT_VOLUME_OFFSET_CONTROL_POINT_CHARACTERISTIC = UUID.from_16_bits(0x2B82, 'Volume Offset Control Point')
+GATT_AUDIO_OUTPUT_DESCRIPTION_CHARACTERISTIC    = UUID.from_16_bits(0x2B83, 'Audio Output Description')
+
+# Coordinated Set Identification Service (CSIS)
+GATT_SET_IDENTITY_RESOLVING_KEY_CHARACTERISTIC  = UUID.from_16_bits(0x2B84, 'Set Identity Resolving Key')
+GATT_COORDINATED_SET_SIZE_CHARACTERISTIC        = UUID.from_16_bits(0x2B85, 'Coordinated Set Size')
+GATT_SET_MEMBER_LOCK_CHARACTERISTIC             = UUID.from_16_bits(0x2B86, 'Set Member Lock')
+GATT_SET_MEMBER_RANK_CHARACTERISTIC             = UUID.from_16_bits(0x2B87, 'Set Member Rank')
+
+# Media Control Service (MCS)
+GATT_MEDIA_PLAYER_NAME_CHARACTERISTIC                     = UUID.from_16_bits(0x2B93, 'Media Player Name')
+GATT_MEDIA_PLAYER_ICON_OBJECT_ID_CHARACTERISTIC           = UUID.from_16_bits(0x2B94, 'Media Player Icon Object ID')
+GATT_MEDIA_PLAYER_ICON_URL_CHARACTERISTIC                 = UUID.from_16_bits(0x2B95, 'Media Player Icon URL')
+GATT_TRACK_CHANGED_CHARACTERISTIC                         = UUID.from_16_bits(0x2B96, 'Track Changed')
+GATT_TRACK_TITLE_CHARACTERISTIC                           = UUID.from_16_bits(0x2B97, 'Track Title')
+GATT_TRACK_DURATION_CHARACTERISTIC                        = UUID.from_16_bits(0x2B98, 'Track Duration')
+GATT_TRACK_POSITION_CHARACTERISTIC                        = UUID.from_16_bits(0x2B99, 'Track Position')
+GATT_PLAYBACK_SPEED_CHARACTERISTIC                        = UUID.from_16_bits(0x2B9A, 'Playback Speed')
+GATT_SEEKING_SPEED_CHARACTERISTIC                         = UUID.from_16_bits(0x2B9B, 'Seeking Speed')
+GATT_CURRENT_TRACK_SEGMENTS_OBJECT_ID_CHARACTERISTIC      = UUID.from_16_bits(0x2B9C, 'Current Track Segments Object ID')
+GATT_CURRENT_TRACK_OBJECT_ID_CHARACTERISTIC               = UUID.from_16_bits(0x2B9D, 'Current Track Object ID')
+GATT_NEXT_TRACK_OBJECT_ID_CHARACTERISTIC                  = UUID.from_16_bits(0x2B9E, 'Next Track Object ID')
+GATT_PARENT_GROUP_OBJECT_ID_CHARACTERISTIC                = UUID.from_16_bits(0x2B9F, 'Parent Group Object ID')
+GATT_CURRENT_GROUP_OBJECT_ID_CHARACTERISTIC               = UUID.from_16_bits(0x2BA0, 'Current Group Object ID')
+GATT_PLAYING_ORDER_CHARACTERISTIC                         = UUID.from_16_bits(0x2BA1, 'Playing Order')
+GATT_PLAYING_ORDERS_SUPPORTED_CHARACTERISTIC              = UUID.from_16_bits(0x2BA2, 'Playing Orders Supported')
+GATT_MEDIA_STATE_CHARACTERISTIC                           = UUID.from_16_bits(0x2BA3, 'Media State')
+GATT_MEDIA_CONTROL_POINT_CHARACTERISTIC                   = UUID.from_16_bits(0x2BA4, 'Media Control Point')
+GATT_MEDIA_CONTROL_POINT_OPCODES_SUPPORTED_CHARACTERISTIC = UUID.from_16_bits(0x2BA5, 'Media Control Point Opcodes Supported')
+GATT_SEARCH_RESULTS_OBJECT_ID_CHARACTERISTIC              = UUID.from_16_bits(0x2BA6, 'Search Results Object ID')
+GATT_SEARCH_CONTROL_POINT_CHARACTERISTIC                  = UUID.from_16_bits(0x2BA7, 'Search Control Point')
+
+# Telephone Bearer Service (TBS)
+GATT_BEARER_PROVIDER_NAME_CHARACTERISTIC                      = UUID.from_16_bits(0x2BB3, 'Bearer Provider Name')
+GATT_BEARER_UCI_CHARACTERISTIC                                = UUID.from_16_bits(0x2BB4, 'Bearer UCI')
+GATT_BEARER_TECHNOLOGY_CHARACTERISTIC                         = UUID.from_16_bits(0x2BB5, 'Bearer Technology')
+GATT_BEARER_URI_SCHEMES_SUPPORTED_LIST_CHARACTERISTIC         = UUID.from_16_bits(0x2BB6, 'Bearer URI Schemes Supported List')
+GATT_BEARER_SIGNAL_STRENGTH_CHARACTERISTIC                    = UUID.from_16_bits(0x2BB7, 'Bearer Signal Strength')
+GATT_BEARER_SIGNAL_STRENGTH_REPORTING_INTERVAL_CHARACTERISTIC = UUID.from_16_bits(0x2BB8, 'Bearer Signal Strength Reporting Interval')
+GATT_BEARER_LIST_CURRENT_CALLS_CHARACTERISTIC                 = UUID.from_16_bits(0x2BB9, 'Bearer List Current Calls')
+GATT_CONTENT_CONTROL_ID_CHARACTERISTIC                        = UUID.from_16_bits(0x2BBA, 'Content Control ID')
+GATT_STATUS_FLAGS_CHARACTERISTIC                              = UUID.from_16_bits(0x2BBB, 'Status Flags')
+GATT_INCOMING_CALL_TARGET_BEARER_URI_CHARACTERISTIC           = UUID.from_16_bits(0x2BBC, 'Incoming Call Target Bearer URI')
+GATT_CALL_STATE_CHARACTERISTIC                                = UUID.from_16_bits(0x2BBD, 'Call State')
+GATT_CALL_CONTROL_POINT_CHARACTERISTIC                        = UUID.from_16_bits(0x2BBE, 'Call Control Point')
+GATT_CALL_CONTROL_POINT_OPTIONAL_OPCODES_CHARACTERISTIC       = UUID.from_16_bits(0x2BBF, 'Call Control Point Optional Opcodes')
+GATT_TERMINATION_REASON_CHARACTERISTIC                        = UUID.from_16_bits(0x2BC0, 'Termination Reason')
+GATT_INCOMING_CALL_CHARACTERISTIC                             = UUID.from_16_bits(0x2BC1, 'Incoming Call')
+GATT_CALL_FRIENDLY_NAME_CHARACTERISTIC                        = UUID.from_16_bits(0x2BC2, 'Call Friendly Name')
+
+# Microphone Control Service (MICS)
+GATT_MUTE_CHARACTERISTIC = UUID.from_16_bits(0x2BC3, 'Mute')
+
+# Audio Stream Control Service (ASCS)
+GATT_SINK_ASE_CHARACTERISTIC                    = UUID.from_16_bits(0x2BC4, 'Sink ASE')
+GATT_SOURCE_ASE_CHARACTERISTIC                  = UUID.from_16_bits(0x2BC5, 'Source ASE')
+GATT_ASE_CONTROL_POINT_CHARACTERISTIC           = UUID.from_16_bits(0x2BC6, 'ASE Control Point')
+
+# Broadcast Audio Scan Service (BASS)
+GATT_BROADCAST_AUDIO_SCAN_CONTROL_POINT_CHARACTERISTIC = UUID.from_16_bits(0x2BC7, 'Broadcast Audio Scan Control Point')
+GATT_BROADCAST_RECEIVE_STATE_CHARACTERISTIC            = UUID.from_16_bits(0x2BC8, 'Broadcast Receive State')
+
+# Published Audio Capabilities Service (PACS)
+GATT_SINK_PAC_CHARACTERISTIC                    = UUID.from_16_bits(0x2BC9, 'Sink PAC')
+GATT_SINK_AUDIO_LOCATION_CHARACTERISTIC         = UUID.from_16_bits(0x2BCA, 'Sink Audio Location')
+GATT_SOURCE_PAC_CHARACTERISTIC                  = UUID.from_16_bits(0x2BCB, 'Source PAC')
+GATT_SOURCE_AUDIO_LOCATION_CHARACTERISTIC       = UUID.from_16_bits(0x2BCC, 'Source Audio Location')
+GATT_AVAILABLE_AUDIO_CONTEXTS_CHARACTERISTIC    = UUID.from_16_bits(0x2BCD, 'Available Audio Contexts')
+GATT_SUPPORTED_AUDIO_CONTEXTS_CHARACTERISTIC    = UUID.from_16_bits(0x2BCE, 'Supported Audio Contexts')
+
+# Gaming Audio Service (GMAS)
+GATT_GMAP_ROLE_CHARACTERISTIC    = UUID.from_16_bits(0x2C00, 'GMAP Role')
+GATT_UGG_FEATURES_CHARACTERISTIC = UUID.from_16_bits(0x2C01, 'UGG Features')
+GATT_UGT_FEATURES_CHARACTERISTIC = UUID.from_16_bits(0x2C02, 'UGT Features')
+GATT_BGS_FEATURES_CHARACTERISTIC = UUID.from_16_bits(0x2C03, 'BGS Features')
+GATT_BGR_FEATURES_CHARACTERISTIC = UUID.from_16_bits(0x2C04, 'BGR Features')
+
+# Hearing Access Service
+GATT_HEARING_AID_FEATURES_CHARACTERISTIC             = UUID.from_16_bits(0x2BDA, 'Hearing Aid Features')
+GATT_HEARING_AID_PRESET_CONTROL_POINT_CHARACTERISTIC = UUID.from_16_bits(0x2BDB, 'Hearing Aid Preset Control Point')
+GATT_ACTIVE_PRESET_INDEX_CHARACTERISTIC              = UUID.from_16_bits(0x2BDC, 'Active Preset Index')
+
 # ASHA Service
 GATT_ASHA_SERVICE                             = UUID.from_16_bits(0xFDF0, 'Audio Streaming for Hearing Aid')
 GATT_ASHA_READ_ONLY_PROPERTIES_CHARACTERISTIC = UUID('6333651e-c481-4a3e-9169-7c902aad37bb', 'ReadOnlyProperties')
@@ -164,6 +287,22 @@ GATT_ASHA_AUDIO_STATUS_CHARACTERISTIC         = UUID('38663f1a-e711-4cac-b641-32
 GATT_ASHA_VOLUME_CHARACTERISTIC               = UUID('00e4ca9e-ab14-41e4-8823-f9e70c7e91df', 'Volume')
 GATT_ASHA_LE_PSM_OUT_CHARACTERISTIC           = UUID('2d410339-82b6-42aa-b34e-e2e01df8cc1a', 'LE_PSM_OUT')
 
+# Apple Notification Center Service
+GATT_ANCS_SERVICE                            = UUID('7905F431-B5CE-4E99-A40F-4B1E122D00D0', 'Apple Notification Center')
+GATT_ANCS_NOTIFICATION_SOURCE_CHARACTERISTIC = UUID('9FBF120D-6301-42D9-8C58-25E699A21DBD', 'Notification Source')
+GATT_ANCS_CONTROL_POINT_CHARACTERISTIC       = UUID('69D1D8F3-45E1-49A8-9821-9BBDFDAAD9D9', 'Control Point')
+GATT_ANCS_DATA_SOURCE_CHARACTERISTIC         = UUID('22EAC6E9-24D6-4BB5-BE44-B36ACE7C7BFB', 'Data Source')
+
+# Apple Media Service
+GATT_AMS_SERVICE                         = UUID('89D3502B-0F36-433A-8EF4-C502AD55F8DC', 'Apple Media')
+GATT_AMS_REMOTE_COMMAND_CHARACTERISTIC   = UUID('9B3C81D8-57B1-4A8A-B8DF-0E56F7CA51C2', 'Remote Command')
+GATT_AMS_ENTITY_UPDATE_CHARACTERISTIC    = UUID('2F7CABCE-808D-411F-9A0C-BB92BA96C102', 'Entity Update')
+GATT_AMS_ENTITY_ATTRIBUTE_CHARACTERISTIC = UUID('C6B2F38C-23AB-46D8-A6AB-A3A870BBD5D7', 'Entity Attribute')
+
+# Misc Apple Services
+GATT_APPLE_CONTINUITY_SERVICE = UUID('D0611E78-BBB4-4591-A5F8-487910AE4366', 'Apple Continuity')
+GATT_APPLE_NEARBY_SERVICE     = UUID('9FA480E0-4967-4542-9390-D343DC5D04AE', 'Apple Nearby')
+
 # Misc
 GATT_DEVICE_NAME_CHARACTERISTIC                                = UUID.from_16_bits(0x2A00, 'Device Name')
 GATT_APPEARANCE_CHARACTERISTIC                                 = UUID.from_16_bits(0x2A01, 'Appearance')
@@ -177,6 +316,10 @@ GATT_BOOT_KEYBOARD_INPUT_REPORT_CHARACTERISTIC                 = UUID.from_16_bi
 GATT_CURRENT_TIME_CHARACTERISTIC                               = UUID.from_16_bits(0x2A2B, 'Current Time')
 GATT_BOOT_KEYBOARD_OUTPUT_REPORT_CHARACTERISTIC                = UUID.from_16_bits(0x2A32, 'Boot Keyboard Output Report')
 GATT_CENTRAL_ADDRESS_RESOLUTION__CHARACTERISTIC                = UUID.from_16_bits(0x2AA6, 'Central Address Resolution')
+GATT_CLIENT_SUPPORTED_FEATURES_CHARACTERISTIC                  = UUID.from_16_bits(0x2B29, 'Client Supported Features')
+GATT_DATABASE_HASH_CHARACTERISTIC                              = UUID.from_16_bits(0x2B2A, 'Database Hash')
+GATT_SERVER_SUPPORTED_FEATURES_CHARACTERISTIC                  = UUID.from_16_bits(0x2B3A, 'Server Supported Features')
+GATT_LE_GATT_SECURITY_LEVELS_CHARACTERISTIC                    = UUID.from_16_bits(0x2BF5, 'E GATT Security Levels')
 
 # fmt: on
 # pylint: enable=line-too-long
@@ -185,9 +328,7 @@ GATT_CENTRAL_ADDRESS_RESOLUTION__CHARACTERISTIC                = UUID.from_16_bi
 # -----------------------------------------------------------------------------
 # Utils
 # -----------------------------------------------------------------------------
-
-
-def show_services(services):
+def show_services(services: Iterable[Service]) -> None:
     for service in services:
         print(color(str(service), 'cyan'))
 
@@ -198,6 +339,11 @@ def show_services(services):
                 print(color('    ' + str(descriptor), 'green'))
 
 
+# -----------------------------------------------------------------------------
+class InvalidServiceError(BaseBumbleError):
+    """The service is not compliant with the spec/profile"""
+
+
 # -----------------------------------------------------------------------------
 class Service(Attribute):
     '''
@@ -205,33 +351,35 @@ class Service(Attribute):
     '''
 
     uuid: UUID
-    characteristics: List[Characteristic]
-    included_services: List[Service]
+    characteristics: list[Characteristic]
+    included_services: list[Service]
 
     def __init__(
         self,
-        uuid,
-        characteristics: List[Characteristic],
+        uuid: str | UUID,
+        characteristics: Iterable[Characteristic],
         primary=True,
-        included_services: List[Service] = [],
-    ):
+        included_services: Iterable[Service] = (),
+    ) -> None:
         # Convert the uuid to a UUID object if it isn't already
         if isinstance(uuid, str):
             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(),
         )
         self.uuid = uuid
-        self.included_services = included_services[:]
-        self.characteristics = characteristics[:]
+        self.included_services = list(included_services)
+        self.characteristics = list(characteristics)
         self.primary = primary
 
-    def get_advertising_data(self) -> Optional[bytes]:
+    def get_advertising_data(self) -> bytes | None:
         """
         Get Service specific advertising data
         Defined by each Service, default value is empty
@@ -239,7 +387,7 @@ class Service(Attribute):
         """
         return None
 
-    def __str__(self):
+    def __str__(self) -> str:
         return (
             f'Service(handle=0x{self.handle:04X}, '
             f'end=0x{self.end_group_handle:04X}, '
@@ -255,10 +403,15 @@ class TemplateService(Service):
     to expose their UUID as a class property
     '''
 
-    UUID: Optional[UUID] = None
+    UUID: ClassVar[UUID]
 
-    def __init__(self, characteristics, primary=True):
-        super().__init__(self.UUID, characteristics, primary)
+    def __init__(
+        self,
+        characteristics: Iterable[Characteristic],
+        primary: bool = True,
+        included_services: Iterable[Service] = (),
+    ) -> None:
+        super().__init__(self.UUID, characteristics, primary, included_services)
 
 
 # -----------------------------------------------------------------------------
@@ -269,27 +422,26 @@ class IncludedServiceDeclaration(Attribute):
 
     service: Service
 
-    def __init__(self, service):
+    def __init__(self, service: Service) -> None:
         declaration_bytes = struct.pack(
-            '<HH2s', service.handle, service.end_group_handle, service.uuid.to_bytes()
+            '<HH2s', service.handle, service.end_group_handle, bytes(service.uuid)
         )
         super().__init__(
             GATT_INCLUDE_ATTRIBUTE_TYPE, Attribute.READABLE, declaration_bytes
         )
         self.service = service
 
-    def __str__(self):
+    def __str__(self) -> str:
         return (
             f'IncludedServiceDefinition(handle=0x{self.handle:04X}, '
             f'group_starting_handle=0x{self.service.handle:04X}, '
             f'group_ending_handle=0x{self.service.end_group_handle:04X}, '
-            f'uuid={self.service.uuid}, '
-            f'{self.service.properties!s})'
+            f'uuid={self.service.uuid})'
         )
 
 
 # -----------------------------------------------------------------------------
-class Characteristic(Attribute):
+class Characteristic(Attribute[_T]):
     '''
     See Vol 3, Part G - 3.3 CHARACTERISTIC DEFINITION
     '''
@@ -297,6 +449,8 @@ class Characteristic(Attribute):
     uuid: UUID
     properties: Characteristic.Properties
 
+    EVENT_SUBSCRIPTION = "subscription"
+
     class Properties(enum.IntFlag):
         """Property flags"""
 
@@ -309,31 +463,33 @@ class Characteristic(Attribute):
         AUTHENTICATED_SIGNED_WRITES = 0x40
         EXTENDED_PROPERTIES = 0x80
 
-        @staticmethod
-        def from_string(properties_str: str) -> Characteristic.Properties:
-            property_names: List[str] = []
-            for property in Characteristic.Properties:
-                if property.name is None:
-                    raise TypeError()
-                property_names.append(property.name)
-
-            def string_to_property(property_string) -> Characteristic.Properties:
-                for property in zip(Characteristic.Properties, property_names):
-                    if property_string == property[1]:
-                        return property[0]
-                raise TypeError(f"Unable to convert {property_string} to Property")
-
+        @classmethod
+        def from_string(cls, properties_str: str) -> Characteristic.Properties:
             try:
                 return functools.reduce(
-                    lambda x, y: x | string_to_property(y),
-                    properties_str.split(","),
+                    lambda x, y: x | cls[y],
+                    properties_str.replace("|", ",").split(","),
                     Characteristic.Properties(0),
                 )
-            except TypeError:
+            except (TypeError, KeyError):
+                # The check for `p.name is not None` here is needed because for InFlag
+                # enums, the .name property can be None, when the enum value is 0,
+                # so the type hint for .name is Optional[str].
+                enum_list: list[str] = [p.name for p in cls if p.name is not None]
+                enum_list_str = ",".join(enum_list)
                 raise TypeError(
-                    f"Characteristic.Properties::from_string() error:\nExpected a string containing any of the keys, separated by commas: {','.join(property_names)}\nGot: {properties_str}"
+                    f"Characteristic.Properties::from_string() error:\nExpected a string containing any of the keys, separated by , or |: {enum_list_str}\nGot: {properties_str}"
                 )
 
+        def __str__(self) -> str:
+            # NOTE: we override this method to offer a consistent result between python
+            # versions: the value returned by IntFlag.__str__() changed in version 11.
+            return '|'.join(
+                flag.name
+                for flag in Characteristic.Properties
+                if self.value & flag.value and flag.name is not None
+            )
+
     # For backwards compatibility these are defined here
     # For new code, please use Characteristic.Properties.X
     BROADCAST = Properties.BROADCAST
@@ -347,10 +503,10 @@ class Characteristic(Attribute):
 
     def __init__(
         self,
-        uuid,
+        uuid: str | bytes | UUID,
         properties: Characteristic.Properties,
-        permissions,
-        value=b'',
+        permissions: str | Attribute.Permissions,
+        value: AttributeValue[_T] | _T | None = None,
         descriptors: Sequence[Descriptor] = (),
     ):
         super().__init__(uuid, permissions, value)
@@ -368,12 +524,12 @@ class Characteristic(Attribute):
     def has_properties(self, properties: Characteristic.Properties) -> bool:
         return self.properties & properties == properties
 
-    def __str__(self):
+    def __str__(self) -> str:
         return (
             f'Characteristic(handle=0x{self.handle:04X}, '
             f'end=0x{self.end_group_handle:04X}, '
             f'uuid={self.uuid}, '
-            f'{self.properties!s})'
+            f'{self.properties})'
         )
 
 
@@ -385,7 +541,11 @@ class CharacteristicDeclaration(Attribute):
 
     characteristic: Characteristic
 
-    def __init__(self, characteristic, value_handle):
+    def __init__(
+        self,
+        characteristic: Characteristic,
+        value_handle: int,
+    ) -> None:
         declaration_bytes = (
             struct.pack('<BH', characteristic.properties, value_handle)
             + characteristic.uuid.to_pdu_bytes()
@@ -396,214 +556,18 @@ class CharacteristicDeclaration(Attribute):
         self.value_handle = value_handle
         self.characteristic = characteristic
 
-    def __str__(self):
+    def __str__(self) -> str:
         return (
             f'CharacteristicDeclaration(handle=0x{self.handle:04X}, '
             f'value_handle=0x{self.value_handle:04X}, '
             f'uuid={self.characteristic.uuid}, '
-            f'{self.characteristic.properties!s})'
+            f'{self.characteristic.properties})'
         )
 
 
 # -----------------------------------------------------------------------------
-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 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.
-    '''
-
-    def __init__(self, characteristic):
-        self.wrapped_characteristic = characteristic
-        self.subscribers = {}  # Map from subscriber to proxy subscriber
-
-        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:
-            self.read_value = self.read_encoded_value
-            self.write_value = self.write_encoded_value
-
-        if hasattr(self.wrapped_characteristic, 'subscribe'):
-            self.subscribe = self.wrapped_subscribe
-
-        if hasattr(self.wrapped_characteristic, 'unsubscribe'):
-            self.unsubscribe = self.wrapped_unsubscribe
-
-    def __getattr__(self, name):
-        return getattr(self.wrapped_characteristic, name)
-
-    def __setattr__(self, name, value):
-        if name in (
-            'wrapped_characteristic',
-            'subscribers',
-            'read_value',
-            'write_value',
-            'subscribe',
-            'unsubscribe',
-        ):
-            super().__setattr__(name, value)
-        else:
-            setattr(self.wrapped_characteristic, name, value)
-
-    def read_encoded_value(self, connection):
-        return self.encode_value(self.wrapped_characteristic.read_value(connection))
-
-    def write_encoded_value(self, connection, value):
-        return self.wrapped_characteristic.write_value(
-            connection, self.decode_value(value)
-        )
-
-    async def read_decoded_value(self):
-        return self.decode_value(await self.wrapped_characteristic.read_value())
-
-    async def write_decoded_value(self, value, with_response=False):
-        return await self.wrapped_characteristic.write_value(
-            self.encode_value(value), with_response
-        )
-
-    def encode_value(self, value):
-        return value
-
-    def decode_value(self, value):
-        return value
-
-    def wrapped_subscribe(self, subscriber=None):
-        if subscriber is not None:
-            if subscriber in self.subscribers:
-                # We already have a proxy subscriber
-                subscriber = self.subscribers[subscriber]
-            else:
-                # Create and register a proxy that will decode the value
-                original_subscriber = subscriber
-
-                def on_change(value):
-                    original_subscriber(self.decode_value(value))
-
-                self.subscribers[subscriber] = on_change
-                subscriber = on_change
-
-        return self.wrapped_characteristic.subscribe(subscriber)
-
-    def wrapped_unsubscribe(self, subscriber=None):
-        if subscriber in self.subscribers:
-            subscriber = self.subscribers.pop(subscriber)
-
-        return self.wrapped_characteristic.unsubscribe(subscriber)
-
-    def __str__(self):
-        wrapped = str(self.wrapped_characteristic)
-        return f'{self.__class__.__name__}({wrapped})'
-
-
-# -----------------------------------------------------------------------------
-class DelegatedCharacteristicAdapter(CharacteristicAdapter):
-    '''
-    Adapter that converts bytes values using an encode and a decode function.
-    '''
-
-    def __init__(self, characteristic, encode=None, decode=None):
-        super().__init__(characteristic)
-        self.encode = encode
-        self.decode = decode
-
-    def encode_value(self, value):
-        return self.encode(value) if self.encode else value
-
-    def decode_value(self, value):
-        return self.decode(value) if self.decode else value
-
-
-# -----------------------------------------------------------------------------
-class PackedCharacteristicAdapter(CharacteristicAdapter):
-    '''
-    Adapter that packs/unpacks characteristic values according to a standard
-    Python `struct` format.
-    For formats with a single value, the adapted `read_value` and `write_value`
-    methods return/accept single values. For formats with multiple values,
-    they return/accept a tuple with the same number of elements as is required for
-    the format.
-    '''
-
-    def __init__(self, characteristic, pack_format):
-        super().__init__(characteristic)
-        self.struct = struct.Struct(pack_format)
-
-    def pack(self, *values):
-        return self.struct.pack(*values)
-
-    def unpack(self, buffer):
-        return self.struct.unpack(buffer)
-
-    def encode_value(self, value):
-        return self.pack(*value if isinstance(value, tuple) else (value,))
-
-    def decode_value(self, value):
-        unpacked = self.unpack(value)
-        return unpacked[0] if len(unpacked) == 1 else unpacked
-
-
-# -----------------------------------------------------------------------------
-class MappedCharacteristicAdapter(PackedCharacteristicAdapter):
-    '''
-    Adapter that packs/unpacks characteristic values according to a standard
-    Python `struct` format.
-    The adapted `read_value` and `write_value` methods return/accept aa dictionary which
-    is packed/unpacked according to format, with the arguments extracted from the
-    dictionary by key, in the same order as they occur in the `keys` parameter.
-    '''
-
-    def __init__(self, characteristic, pack_format, keys):
-        super().__init__(characteristic, pack_format)
-        self.keys = keys
-
-    # pylint: disable=arguments-differ
-    def pack(self, values):
-        return super().pack(*(values[key] for key in self.keys))
-
-    def unpack(self, buffer):
-        return dict(zip(self.keys, super().unpack(buffer)))
-
-
-# -----------------------------------------------------------------------------
-class UTF8CharacteristicAdapter(CharacteristicAdapter):
-    '''
-    Adapter that converts strings to/from bytes using UTF-8 encoding
-    '''
-
-    def encode_value(self, value):
-        return value.encode('utf-8')
-
-    def decode_value(self, value):
-        return value.decode('utf-8')
+class CharacteristicValue(AttributeValue[_T]):
+    """Same as AttributeValue, for backward compatibility"""
 
 
 # -----------------------------------------------------------------------------
@@ -612,14 +576,21 @@ class Descriptor(Attribute):
     See Vol 3, Part G - 3.3.3 Characteristic Descriptor Declarations
     '''
 
-    def __str__(self):
+    def __str__(self) -> str:
+        if isinstance(self.value, bytes):
+            value_str = self.value.hex()
+        elif isinstance(self.value, (AttributeValue, AttributeValueV2)):
+            value_str = '<dynamic>'
+        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
@@ -629,3 +600,23 @@ class ClientCharacteristicConfigurationBits(enum.IntFlag):
     DEFAULT = 0x0000
     NOTIFICATION = 0x0001
     INDICATION = 0x0002
+
+
+# -----------------------------------------------------------------------------
+class ClientSupportedFeatures(enum.IntFlag):
+    '''
+    See Vol 3, Part G - 7.2 - Table 7.6: Client Supported Features bit assignments.
+    '''
+
+    ROBUST_CACHING = 0x01
+    ENHANCED_ATT_BEARER = 0x02
+    MULTIPLE_HANDLE_VALUE_NOTIFICATIONS = 0x04
+
+
+# -----------------------------------------------------------------------------
+class ServerSupportedFeatures(enum.IntFlag):
+    '''
+    See Vol 3, Part G - 7.4 - Table 7.11: Server Supported Features bit assignments.
+    '''
+
+    EATT_SUPPORTED = 0x01

bumble/gatt_adapters.py

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

bumble/helpers.py

@@ -15,30 +15,38 @@
 # -----------------------------------------------------------------------------
 # Imports
 # -----------------------------------------------------------------------------
-import logging
+from __future__ import annotations
 
-from .colors import color
-from .att import ATT_CID, ATT_PDU
-from .smp import SMP_CID, SMP_Command
-from .core import name_or_number
-from .l2cap import (
-    L2CAP_PDU,
-    L2CAP_CONNECTION_REQUEST,
-    L2CAP_CONNECTION_RESPONSE,
-    L2CAP_SIGNALING_CID,
-    L2CAP_LE_SIGNALING_CID,
-    L2CAP_Control_Frame,
-    L2CAP_Connection_Response,
-)
-from .hci import (
-    HCI_EVENT_PACKET,
+import datetime
+import logging
+from collections.abc import Callable, MutableMapping
+from typing import Any, cast
+
+from bumble import avc, avctp, avdtp, avrcp, crypto, rfcomm, sdp
+from bumble.att import ATT_CID, ATT_PDU
+from bumble.colors import color
+from bumble.core import name_or_number
+from bumble.hci import (
     HCI_ACL_DATA_PACKET,
     HCI_DISCONNECTION_COMPLETE_EVENT,
+    HCI_EVENT_PACKET,
+    Address,
+    HCI_AclDataPacket,
     HCI_AclDataPacketAssembler,
+    HCI_Disconnection_Complete_Event,
+    HCI_Event,
+    HCI_Packet,
 )
-from .rfcomm import RFCOMM_Frame, RFCOMM_PSM
-from .sdp import SDP_PDU, SDP_PSM
-from .avdtp import MessageAssembler as AVDTP_MessageAssembler, AVDTP_PSM
+from bumble.l2cap import (
+    L2CAP_LE_SIGNALING_CID,
+    L2CAP_PDU,
+    L2CAP_SIGNALING_CID,
+    CommandCode,
+    L2CAP_Connection_Request,
+    L2CAP_Connection_Response,
+    L2CAP_Control_Frame,
+)
+from bumble.smp import SMP_CID, SMP_Command
 
 # -----------------------------------------------------------------------------
 # Logging
@@ -48,26 +56,36 @@ logger = logging.getLogger(__name__)
 
 # -----------------------------------------------------------------------------
 PSM_NAMES = {
-    RFCOMM_PSM: 'RFCOMM',
-    SDP_PSM: 'SDP',
-    AVDTP_PSM: 'AVDTP'
+    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:
-        def __init__(self, analyzer):
+        psms: MutableMapping[int, int]
+        peer: PacketTracer.AclStream | None
+        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  # ACL stream in the other direction
+            self.peer = None
 
         # pylint: disable=too-many-nested-blocks
-        def on_acl_pdu(self, pdu):
+        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)
@@ -80,47 +98,60 @@ class PacketTracer:
                 self.analyzer.emit(control_frame)
 
                 # Check if this signals a new channel
-                if control_frame.code == L2CAP_CONNECTION_REQUEST:
-                    self.psms[control_frame.source_cid] = control_frame.psm
-                elif control_frame.code == L2CAP_CONNECTION_RESPONSE:
+                if control_frame.code == CommandCode.L2CAP_CONNECTION_REQUEST:
+                    connection_request = cast(L2CAP_Connection_Request, control_frame)
+                    self.psms[connection_request.source_cid] = connection_request.psm
+                elif control_frame.code == CommandCode.L2CAP_CONNECTION_RESPONSE:
+                    connection_response = cast(L2CAP_Connection_Response, control_frame)
                     if (
-                        control_frame.result
-                        == L2CAP_Connection_Response.CONNECTION_SUCCESSFUL
+                        connection_response.result
+                        == L2CAP_Connection_Response.Result.CONNECTION_SUCCESSFUL
                     ):
-                        if self.peer:
-                            if psm := self.peer.psms.get(control_frame.source_cid):
-                                # Found a pending connection
-                                self.psms[control_frame.destination_cid] = psm
-
-                                # For AVDTP connections, create a packet assembler for
-                                # each direction
-                                if psm == AVDTP_PSM:
-                                    self.avdtp_assemblers[
-                                        control_frame.source_cid
-                                    ] = AVDTP_MessageAssembler(self.on_avdtp_message)
-                                    self.peer.avdtp_assemblers[
-                                        control_frame.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_PSM:
+                    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(
@@ -130,22 +161,49 @@ class PacketTracer:
                 else:
                     self.analyzer.emit(l2cap_pdu)
 
-        def on_avdtp_message(self, transaction_label, message):
+        def on_avdtp_message(
+            self, transaction_label: int, message: avdtp.Message
+        ) -> None:
             self.analyzer.emit(
                 f'{color("AVDTP", "green")} [{transaction_label}] {message}'
             )
 
-        def feed_packet(self, packet):
+        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)
 
     class Analyzer:
-        def __init__(self, label, emit_message):
+        acl_streams: MutableMapping[int, PacketTracer.AclStream]
+        peer: PacketTracer.Analyzer
+
+        def __init__(self, label: str, emit_message: Callable[..., None]) -> None:
             self.label = label
             self.emit_message = emit_message
             self.acl_streams = {}  # ACL streams, by connection handle
-            self.peer = None  # Analyzer in the other direction
+            self.packet_timestamp: datetime.datetime | None = None
 
-        def start_acl_stream(self, connection_handle):
+        def start_acl_stream(self, connection_handle: int) -> PacketTracer.AclStream:
             logger.info(
                 f'[{self.label}] +++ Creating ACL stream for connection '
                 f'0x{connection_handle:04X}'
@@ -160,7 +218,7 @@ class PacketTracer:
 
             return stream
 
-        def end_acl_stream(self, connection_handle):
+        def end_acl_stream(self, connection_handle: int) -> None:
             if connection_handle in self.acl_streams:
                 logger.info(
                     f'[{self.label}] --- Removing ACL stream for connection '
@@ -171,34 +229,52 @@ 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):
+        def on_packet(
+            self, timestamp: datetime.datetime | None, packet: HCI_Packet
+        ) -> None:
+            self.packet_timestamp = timestamp
             self.emit(packet)
 
             if packet.hci_packet_type == HCI_ACL_DATA_PACKET:
+                acl_packet = cast(HCI_AclDataPacket, packet)
                 # Look for an existing stream for this handle, create one if it is the
                 # first ACL packet for that connection handle
-                if (stream := self.acl_streams.get(packet.connection_handle)) is None:
-                    stream = self.start_acl_stream(packet.connection_handle)
-                stream.feed_packet(packet)
+                if (
+                    stream := self.acl_streams.get(acl_packet.connection_handle)
+                ) is None:
+                    stream = self.start_acl_stream(acl_packet.connection_handle)
+                stream.feed_packet(acl_packet)
             elif packet.hci_packet_type == HCI_EVENT_PACKET:
-                if packet.event_code == HCI_DISCONNECTION_COMPLETE_EVENT:
-                    self.end_acl_stream(packet.connection_handle)
+                event_packet = cast(HCI_Event, packet)
+                if event_packet.event_code == HCI_DISCONNECTION_COMPLETE_EVENT:
+                    self.end_acl_stream(
+                        cast(HCI_Disconnection_Complete_Event, packet).connection_handle
+                    )
 
-        def emit(self, message):
-            self.emit_message(f'[{self.label}] {message}')
+        def emit(self, message: Any) -> None:
+            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, direction=0):
+    def trace(
+        self,
+        packet: HCI_Packet,
+        direction: int = 0,
+        timestamp: datetime.datetime | None = 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,
-        host_to_controller_label=color('HOST->CONTROLLER', 'blue'),
-        controller_to_host_label=color('CONTROLLER->HOST', 'cyan'),
-        emit_message=logger.info,
-    ):
+        host_to_controller_label: str = color('HOST->CONTROLLER', 'blue'),
+        controller_to_host_label: str = color('CONTROLLER->HOST', 'cyan'),
+        emit_message: Callable[..., None] = logger.info,
+    ) -> None:
         self.host_to_controller_analyzer = PacketTracer.Analyzer(
             host_to_controller_label, emit_message
         )
@@ -207,3 +283,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

@@ -0,0 +1,570 @@
+# Copyright 2021-2022 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# -----------------------------------------------------------------------------
+# Imports
+# -----------------------------------------------------------------------------
+from __future__ import annotations
+
+import enum
+import logging
+import struct
+from abc import ABC, abstractmethod
+from collections.abc import Callable
+from dataclasses import dataclass
+
+from typing_extensions import override
+
+from bumble import device, l2cap, utils
+from bumble.core import InvalidStateError, ProtocolError
+from bumble.hci import Address
+
+# -----------------------------------------------------------------------------
+# Logging
+# -----------------------------------------------------------------------------
+logger = logging.getLogger(__name__)
+
+
+# -----------------------------------------------------------------------------
+# Constants
+# -----------------------------------------------------------------------------
+# fmt: on
+HID_CONTROL_PSM = 0x0011
+HID_INTERRUPT_PSM = 0x0013
+
+
+class Message:
+    message_type: MessageType
+
+    # Report types
+    class ReportType(enum.IntEnum):
+        OTHER_REPORT = 0x00
+        INPUT_REPORT = 0x01
+        OUTPUT_REPORT = 0x02
+        FEATURE_REPORT = 0x03
+
+    # Handshake parameters
+    class Handshake(enum.IntEnum):
+        SUCCESSFUL = 0x00
+        NOT_READY = 0x01
+        ERR_INVALID_REPORT_ID = 0x02
+        ERR_UNSUPPORTED_REQUEST = 0x03
+        ERR_INVALID_PARAMETER = 0x04
+        ERR_UNKNOWN = 0x0E
+        ERR_FATAL = 0x0F
+
+    # Message Type
+    class MessageType(enum.IntEnum):
+        HANDSHAKE = 0x00
+        CONTROL = 0x01
+        GET_REPORT = 0x04
+        SET_REPORT = 0x05
+        GET_PROTOCOL = 0x06
+        SET_PROTOCOL = 0x07
+        DATA = 0x0A
+
+    # Protocol modes
+    class ProtocolMode(enum.IntEnum):
+        BOOT_PROTOCOL = 0x00
+        REPORT_PROTOCOL = 0x01
+
+    # Control Operations
+    class ControlCommand(enum.IntEnum):
+        SUSPEND = 0x03
+        EXIT_SUSPEND = 0x04
+        VIRTUAL_CABLE_UNPLUG = 0x05
+
+    # Class Method to derive header
+    @classmethod
+    def header(cls, lower_bits: int = 0x00) -> bytes:
+        return bytes([(cls.message_type << 4) | lower_bits])
+
+
+# HIDP messages
+@dataclass
+class GetReportMessage(Message):
+    report_type: int
+    report_id: int
+    buffer_size: int
+    message_type = Message.MessageType.GET_REPORT
+
+    def __bytes__(self) -> bytes:
+        packet_bytes = bytearray()
+        packet_bytes.append(self.report_id)
+        if self.buffer_size == 0:
+            return self.header(self.report_type) + packet_bytes
+        else:
+            return (
+                self.header(0x08 | self.report_type)
+                + packet_bytes
+                + struct.pack("<H", self.buffer_size)
+            )
+
+
+@dataclass
+class SetReportMessage(Message):
+    report_type: int
+    data: bytes
+    message_type = Message.MessageType.SET_REPORT
+
+    def __bytes__(self) -> bytes:
+        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
+
+    def __bytes__(self) -> bytes:
+        return self.header()
+
+
+@dataclass
+class SetProtocolMessage(Message):
+    protocol_mode: int
+    message_type = Message.MessageType.SET_PROTOCOL
+
+    def __bytes__(self) -> bytes:
+        return self.header(self.protocol_mode)
+
+
+@dataclass
+class Suspend(Message):
+    message_type = Message.MessageType.CONTROL
+
+    def __bytes__(self) -> bytes:
+        return self.header(Message.ControlCommand.SUSPEND)
+
+
+@dataclass
+class ExitSuspend(Message):
+    message_type = Message.MessageType.CONTROL
+
+    def __bytes__(self) -> bytes:
+        return self.header(Message.ControlCommand.EXIT_SUSPEND)
+
+
+@dataclass
+class VirtualCableUnplug(Message):
+    message_type = Message.MessageType.CONTROL
+
+    def __bytes__(self) -> bytes:
+        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(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 HID(ABC, utils.EventEmitter):
+    l2cap_ctrl_channel: l2cap.ClassicChannel | None = None
+    l2cap_intr_channel: l2cap.ClassicChannel | None = None
+    connection: device.Connection | None = None
+
+    EVENT_INTERRUPT_DATA = "interrupt_data"
+    EVENT_CONTROL_DATA = "control_data"
+    EVENT_SUSPEND = "suspend"
+    EVENT_EXIT_SUSPEND = "exit_suspend"
+    EVENT_VIRTUAL_CABLE_UNPLUG = "virtual_cable_unplug"
+    EVENT_HANDSHAKE = "handshake"
+
+    class Role(enum.IntEnum):
+        HOST = 0x00
+        DEVICE = 0x01
+
+    def __init__(self, device: device.Device, role: Role) -> None:
+        super().__init__()
+        self.remote_device_bd_address: Address | None = None
+        self.device = device
+        self.role = role
+
+        # Register ourselves with the L2CAP channel manager
+        device.create_l2cap_server(
+            l2cap.ClassicChannelSpec(HID_CONTROL_PSM), self.on_l2cap_connection
+        )
+        device.create_l2cap_server(
+            l2cap.ClassicChannelSpec(HID_INTERRUPT_PSM), self.on_l2cap_connection
+        )
+
+        device.on(device.EVENT_CONNECTION, self.on_device_connection)
+
+    async def connect_control_channel(self) -> None:
+        if not self.connection:
+            raise InvalidStateError("Connection is not established!")
+        # Create a new L2CAP connection - control channel
+        try:
+            channel = await self.connection.create_l2cap_channel(
+                l2cap.ClassicChannelSpec(HID_CONTROL_PSM)
+            )
+            channel.sink = self.on_ctrl_pdu
+            self.l2cap_ctrl_channel = channel
+        except ProtocolError:
+            logging.exception('L2CAP connection failed.')
+            raise
+
+    async def connect_interrupt_channel(self) -> None:
+        if not self.connection:
+            raise InvalidStateError("Connection is not established!")
+        # Create a new L2CAP connection - interrupt channel
+        try:
+            channel = await self.connection.create_l2cap_channel(
+                l2cap.ClassicChannelSpec(HID_INTERRUPT_PSM)
+            )
+            channel.sink = self.on_intr_pdu
+            self.l2cap_intr_channel = channel
+        except ProtocolError:
+            logging.exception('L2CAP connection failed.')
+            raise
+
+    async def disconnect_interrupt_channel(self) -> None:
+        if self.l2cap_intr_channel is None:
+            raise InvalidStateError('invalid state')
+        channel = self.l2cap_intr_channel
+        self.l2cap_intr_channel = None
+        await channel.disconnect()
+
+    async def disconnect_control_channel(self) -> None:
+        if self.l2cap_ctrl_channel is None:
+            raise InvalidStateError('invalid state')
+        channel = self.l2cap_ctrl_channel
+        self.l2cap_ctrl_channel = None
+        await channel.disconnect()
+
+    def on_device_connection(self, connection: device.Connection) -> None:
+        self.connection = connection
+        self.remote_device_bd_address = connection.peer_address
+        connection.on(connection.EVENT_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(
+            l2cap_channel.EVENT_OPEN, lambda: self.on_l2cap_channel_open(l2cap_channel)
+        )
+        l2cap_channel.on(
+            l2cap_channel.EVENT_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:
+            self.l2cap_ctrl_channel = l2cap_channel
+            self.l2cap_ctrl_channel.sink = self.on_ctrl_pdu
+        else:
+            self.l2cap_intr_channel = l2cap_channel
+            self.l2cap_intr_channel.sink = self.on_intr_pdu
+        logger.debug(f'$$$ L2CAP channel open: {l2cap_channel}')
+
+    def on_l2cap_channel_close(self, l2cap_channel: l2cap.ClassicChannel) -> None:
+        if l2cap_channel.psm == HID_CONTROL_PSM:
+            self.l2cap_ctrl_channel = None
+        else:
+            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(self.EVENT_INTERRUPT_DATA, pdu)
+
+    def send_pdu_on_ctrl(self, msg: bytes) -> None:
+        assert self.l2cap_ctrl_channel
+        self.l2cap_ctrl_channel.write(msg)
+
+    def send_pdu_on_intr(self, msg: bytes) -> None:
+        assert self.l2cap_intr_channel
+        self.l2cap_intr_channel.write(msg)
+
+    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)
+        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 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(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
+
+    @dataclass
+    class GetSetStatus:
+        data: bytes = b''
+        status: int = 0
+
+    get_report_cb: Callable[[int, int, int], GetSetStatus] | None = None
+    set_report_cb: Callable[[int, int, int, bytes], GetSetStatus] | None = None
+    get_protocol_cb: Callable[[], GetSetStatus] | None = None
+    set_protocol_cb: Callable[[int], GetSetStatus] | None = None
+
+    def __init__(self, device: device.Device) -> None:
+        super().__init__(device, HID.Role.DEVICE)
+
+    @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(self.EVENT_CONTROL_DATA, pdu)
+        elif message_type == Message.MessageType.CONTROL:
+            if param == Message.ControlCommand.SUSPEND:
+                logger.debug('<<< HID SUSPEND')
+                self.emit(self.EVENT_SUSPEND)
+            elif param == Message.ControlCommand.EXIT_SUSPEND:
+                logger.debug('<<< HID EXIT SUSPEND')
+                self.emit(self.EVENT_EXIT_SUSPEND)
+            elif param == Message.ControlCommand.VIRTUAL_CABLE_UNPLUG:
+                logger.debug('<<< HID VIRTUAL CABLE UNPLUG')
+                self.emit(self.EVENT_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)
+        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], Device.GetSetStatus]
+    ) -> 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)
+        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], Device.GetSetStatus]
+    ) -> 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()
+        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[[], Device.GetSetStatus]) -> 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)
+        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], Device.GetSetStatus]
+    ) -> 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(self.EVENT_HANDSHAKE, Message.Handshake(param))
+        elif message_type == Message.MessageType.DATA:
+            logger.debug('<<< HID CONTROL DATA')
+            self.emit(self.EVENT_CONTROL_DATA, pdu)
+        elif message_type == Message.MessageType.CONTROL:
+            if param == Message.ControlCommand.VIRTUAL_CABLE_UNPLUG:
+                logger.debug('<<< HID VIRTUAL CABLE UNPLUG')
+                self.emit(self.EVENT_VIRTUAL_CABLE_UNPLUG)
+            else:
+                logger.debug('<<< HID CONTROL OPERATION UNSUPPORTED')
+        else:
+            logger.debug('<<< HID MESSAGE TYPE UNSUPPORTED')

bumble/keys.py

@@ -21,17 +21,21 @@
 # Imports
 # -----------------------------------------------------------------------------
 from __future__ import annotations
+
 import asyncio
+import dataclasses
+import json
 import logging
 import os
-import json
-from typing import TYPE_CHECKING, Dict, List, Optional, Tuple
+from typing import TYPE_CHECKING, Any
 
-from .colors import color
-from .hci import Address
+from typing_extensions import Self
+
+from bumble import hci
+from bumble.colors import color
 
 if TYPE_CHECKING:
-    from .device import Device
+    from bumble.device import Device
 
 
 # -----------------------------------------------------------------------------
@@ -41,16 +45,17 @@ logger = logging.getLogger(__name__)
 
 
 # -----------------------------------------------------------------------------
+@dataclasses.dataclass
 class PairingKeys:
+    @dataclasses.dataclass
     class Key:
-        def __init__(self, value, authenticated=False, ediv=None, rand=None):
-            self.value = value
-            self.authenticated = authenticated
-            self.ediv = ediv
-            self.rand = rand
+        value: bytes
+        authenticated: bool = False
+        ediv: int | None = None
+        rand: bytes | None = None
 
         @classmethod
-        def from_dict(cls, key_dict):
+        def from_dict(cls, key_dict: dict[str, Any]) -> PairingKeys.Key:
             value = bytes.fromhex(key_dict['value'])
             authenticated = key_dict.get('authenticated', False)
             ediv = key_dict.get('ediv')
@@ -60,7 +65,7 @@ class PairingKeys:
 
             return cls(value, authenticated, ediv, rand)
 
-        def to_dict(self):
+        def to_dict(self) -> dict[str, Any]:
             key_dict = {'value': self.value.hex(), 'authenticated': self.authenticated}
             if self.ediv is not None:
                 key_dict['ediv'] = self.ediv
@@ -69,39 +74,42 @@ class PairingKeys:
 
             return key_dict
 
-    def __init__(self):
-        self.address_type = None
-        self.ltk = None
-        self.ltk_central = None
-        self.ltk_peripheral = None
-        self.irk = None
-        self.csrk = None
-        self.link_key = None  # Classic
+    address_type: hci.AddressType | None = None
+    ltk: Key | None = None
+    ltk_central: Key | None = None
+    ltk_peripheral: Key | None = None
+    irk: Key | None = None
+    csrk: Key | None = None
+    link_key: Key | None = None  # Classic
+    link_key_type: int | None = None  # Classic
 
-    @staticmethod
-    def key_from_dict(keys_dict, key_name):
+    @classmethod
+    def key_from_dict(cls, keys_dict: dict[str, Any], key_name: str) -> Key | None:
         key_dict = keys_dict.get(key_name)
         if key_dict is None:
             return None
 
         return PairingKeys.Key.from_dict(key_dict)
 
-    @staticmethod
-    def from_dict(keys_dict):
-        keys = PairingKeys()
+    @classmethod
+    def from_dict(cls, keys_dict: dict[str, Any]) -> PairingKeys:
+        return PairingKeys(
+            address_type=(
+                hci.AddressType(t)
+                if (t := keys_dict.get('address_type')) is not None
+                else None
+            ),
+            ltk=PairingKeys.key_from_dict(keys_dict, 'ltk'),
+            ltk_central=PairingKeys.key_from_dict(keys_dict, 'ltk_central'),
+            ltk_peripheral=PairingKeys.key_from_dict(keys_dict, 'ltk_peripheral'),
+            irk=PairingKeys.key_from_dict(keys_dict, 'irk'),
+            csrk=PairingKeys.key_from_dict(keys_dict, 'csrk'),
+            link_key=PairingKeys.key_from_dict(keys_dict, 'link_key'),
+            link_key_type=keys_dict.get('link_key_type'),
+        )
 
-        keys.address_type = keys_dict.get('address_type')
-        keys.ltk = PairingKeys.key_from_dict(keys_dict, 'ltk')
-        keys.ltk_central = PairingKeys.key_from_dict(keys_dict, 'ltk_central')
-        keys.ltk_peripheral = PairingKeys.key_from_dict(keys_dict, 'ltk_peripheral')
-        keys.irk = PairingKeys.key_from_dict(keys_dict, 'irk')
-        keys.csrk = PairingKeys.key_from_dict(keys_dict, 'csrk')
-        keys.link_key = PairingKeys.key_from_dict(keys_dict, 'link_key')
-
-        return keys
-
-    def to_dict(self):
-        keys = {}
+    def to_dict(self) -> dict[str, Any]:
+        keys: dict[str, Any] = {}
 
         if self.address_type is not None:
             keys['address_type'] = self.address_type
@@ -124,14 +132,17 @@ class PairingKeys:
         if self.link_key is not None:
             keys['link_key'] = self.link_key.to_dict()
 
+        if self.link_key_type is not None:
+            keys['link_key_type'] = self.link_key_type
+
         return keys
 
-    def print(self, prefix=''):
+    def print(self, prefix: str = '') -> None:
         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}')
@@ -145,39 +156,47 @@ class KeyStore:
     async def update(self, name: str, keys: PairingKeys) -> None:
         pass
 
-    async def get(self, _name: str) -> Optional[PairingKeys]:
+    async def get(self, _name: str) -> PairingKeys | None:
         return None
 
-    async def get_all(self) -> List[Tuple[str, PairingKeys]]:
+    async def get_all(self) -> list[tuple[str, PairingKeys]]:
         return []
 
     async def delete_all(self) -> None:
         all_keys = await self.get_all()
         await asyncio.gather(*(self.delete(name) for (name, _) in all_keys))
 
-    async def get_resolving_keys(self):
+    async def get_resolving_keys(self) -> list[tuple[bytes, hci.Address]]:
         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
-                else:
-                    address_type = keys.address_type
-                resolving_keys.append((keys.irk.value, Address(name, address_type)))
+                resolving_keys.append(
+                    (
+                        keys.irk.value,
+                        hci.Address(
+                            name,
+                            (
+                                keys.address_type
+                                if keys.address_type is not None
+                                else hci.Address.RANDOM_DEVICE_ADDRESS
+                            ),
+                        ),
+                    )
+                )
 
         return resolving_keys
 
-    async def print(self, prefix=''):
+    async def print(self, prefix: str = '') -> None:
         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'
 
-    @staticmethod
-    def create_for_device(device: Device) -> KeyStore:
+    @classmethod
+    def create_for_device(cls, device: Device) -> KeyStore:
         if device.config.keystore is None:
             return MemoryKeyStore()
 
@@ -253,8 +272,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: str | None = None
+    ) -> Self:
         if not filename:
             # Extract the filename from the config if there is one
             if device.config.keystore is not None:
@@ -263,20 +284,20 @@ class JsonKeyStore(KeyStore):
                     filename = params[0]
 
         # Use a namespace based on the device address
-        if device.public_address not in (Address.ANY, Address.ANY_RANDOM):
+        if device.public_address not in (hci.Address.ANY, hci.Address.ANY_RANDOM):
             namespace = str(device.public_address)
-        elif device.random_address != Address.ANY_RANDOM:
+        elif device.random_address != hci.Address.ANY_RANDOM:
             namespace = str(device.random_address)
         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
         # will be created upon saving.
         try:
-            with open(self.filename, 'r', encoding='utf-8') as json_file:
+            with open(self.filename, encoding='utf-8') as json_file:
                 db = json.load(json_file)
         except FileNotFoundError:
             db = {}
@@ -327,7 +348,7 @@ class JsonKeyStore(KeyStore):
         key_map.clear()
         await self.save(db)
 
-    async def get(self, name: str) -> Optional[PairingKeys]:
+    async def get(self, name: str) -> PairingKeys | None:
         _, key_map = await self.load()
         if name not in key_map:
             return None
@@ -337,7 +358,7 @@ class JsonKeyStore(KeyStore):
 
 # -----------------------------------------------------------------------------
 class MemoryKeyStore(KeyStore):
-    all_keys: Dict[str, PairingKeys]
+    all_keys: dict[str, PairingKeys]
 
     def __init__(self) -> None:
         self.all_keys = {}
@@ -349,8 +370,8 @@ class MemoryKeyStore(KeyStore):
     async def update(self, name: str, keys: PairingKeys) -> None:
         self.all_keys[name] = keys
 
-    async def get(self, name: str) -> Optional[PairingKeys]:
+    async def get(self, name: str) -> PairingKeys | None:
         return self.all_keys.get(name)
 
-    async def get_all(self) -> List[Tuple[str, PairingKeys]]:
+    async def get_all(self) -> list[tuple[str, PairingKeys]]:
         return list(self.all_keys.items())

bumble/link.py

@@ -11,24 +11,20 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
+from __future__ import annotations
+
+import asyncio
 
 # -----------------------------------------------------------------------------
 # Imports
 # -----------------------------------------------------------------------------
 import logging
-import asyncio
-from functools import partial
+from typing import TYPE_CHECKING
 
-from bumble.core import BT_PERIPHERAL_ROLE, BT_BR_EDR_TRANSPORT, BT_LE_TRANSPORT
-from bumble.colors import color
-from bumble.hci import (
-    Address,
-    HCI_SUCCESS,
-    HCI_CONNECTION_ACCEPT_TIMEOUT_ERROR,
-    HCI_CONNECTION_TIMEOUT_ERROR,
-    HCI_PAGE_TIMEOUT_ERROR,
-    HCI_Connection_Complete_Event,
-)
+from bumble import core, hci, ll, lmp
+
+if TYPE_CHECKING:
+    from bumble import controller
 
 # -----------------------------------------------------------------------------
 # Logging
@@ -36,18 +32,6 @@ from bumble.hci import (
 logger = logging.getLogger(__name__)
 
 
-# -----------------------------------------------------------------------------
-# Utils
-# -----------------------------------------------------------------------------
-def parse_parameters(params_str):
-    result = {}
-    for param_str in params_str.split(','):
-        if '=' in param_str:
-            key, value = param_str.split('=')
-            result[key] = value
-    return result
-
-
 # -----------------------------------------------------------------------------
 # TODO: add more support for various LL exchanges
 # (see Vol 6, Part B - 2.4 DATA CHANNEL PDU)
@@ -57,37 +41,38 @@ 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
         self.pending_classic_connection = None
 
     ############################################################
     # Common utils
     ############################################################
 
-    def add_controller(self, controller):
+    def add_controller(self, controller: controller.Controller):
         logger.debug(f'new controller: {controller}')
         self.controllers.add(controller)
 
-    def remove_controller(self, controller):
+    def remove_controller(self, controller: controller.Controller):
         self.controllers.remove(controller)
 
-    def find_controller(self, address):
+    def find_le_controller(self, address: hci.Address) -> controller.Controller | None:
         for controller in self.controllers:
-            if controller.random_address == address:
-                return controller
+            for connection in controller.le_connections.values():
+                if connection.self_address == address:
+                    return controller
         return None
 
-    def find_classic_controller(self, address):
+    def find_classic_controller(
+        self, address: hci.Address
+    ) -> controller.Controller | None:
         for controller in self.controllers:
             if controller.public_address == address:
                 return controller
         return None
 
-    def get_pending_connection(self):
-        return self.pending_connection
-
     ############################################################
     # LE handlers
     ############################################################
@@ -95,436 +80,70 @@ class LocalLink:
     def on_address_changed(self, controller):
         pass
 
-    def send_advertising_data(self, sender_address, data):
-        # Send the advertising data to all controllers, except the sender
-        for controller in self.controllers:
-            if controller.random_address != sender_address:
-                controller.on_link_advertising_data(sender_address, data)
-
-    def send_acl_data(self, sender_controller, destination_address, transport, data):
+    def send_acl_data(
+        self,
+        sender_controller: controller.Controller,
+        destination_address: hci.Address,
+        transport: core.PhysicalTransport,
+        data: bytes,
+    ):
         # Send the data to the first controller with a matching address
-        if transport == BT_LE_TRANSPORT:
-            destination_controller = self.find_controller(destination_address)
+        if transport == core.PhysicalTransport.LE:
+            destination_controller = self.find_le_controller(destination_address)
             source_address = sender_controller.random_address
-        elif transport == BT_BR_EDR_TRANSPORT:
+        elif transport == core.PhysicalTransport.BR_EDR:
             destination_controller = self.find_classic_controller(destination_address)
             source_address = sender_controller.public_address
+        else:
+            raise ValueError("unsupported transport type")
 
         if destination_controller is not None:
-            destination_controller.on_link_acl_data(source_address, transport, data)
-
-    def on_connection_complete(self):
-        # Check that we expect this call
-        if not self.pending_connection:
-            logger.warning('on_connection_complete with no pending connection')
-            return
-
-        central_address, le_create_connection_command = self.pending_connection
-        self.pending_connection = None
-
-        # Find the controller that initiated the connection
-        if not (central_controller := self.find_controller(central_address)):
-            logger.warning('!!! Initiating controller not found')
-            return
-
-        # Connect to the first controller with a matching address
-        if peripheral_controller := self.find_controller(
-            le_create_connection_command.peer_address
-        ):
-            central_controller.on_link_peripheral_connection_complete(
-                le_create_connection_command, HCI_SUCCESS
-            )
-            peripheral_controller.on_link_central_connected(central_address)
-            return
-
-        # No peripheral found
-        central_controller.on_link_peripheral_connection_complete(
-            le_create_connection_command, HCI_CONNECTION_ACCEPT_TIMEOUT_ERROR
-        )
-
-    def connect(self, central_address, le_create_connection_command):
-        logger.debug(
-            f'$$$ CONNECTION {central_address} -> '
-            f'{le_create_connection_command.peer_address}'
-        )
-        self.pending_connection = (central_address, le_create_connection_command)
-        asyncio.get_running_loop().call_soon(self.on_connection_complete)
-
-    def on_disconnection_complete(
-        self, central_address, peripheral_address, disconnect_command
-    ):
-        # Find the controller that initiated the disconnection
-        if not (central_controller := self.find_controller(central_address)):
-            logger.warning('!!! Initiating controller not found')
-            return
-
-        # Disconnect from the first controller with a matching address
-        if peripheral_controller := self.find_controller(peripheral_address):
-            peripheral_controller.on_link_central_disconnected(
-                central_address, disconnect_command.reason
+            asyncio.get_running_loop().call_soon(
+                lambda: destination_controller.on_link_acl_data(
+                    source_address, transport, data
+                )
             )
 
-        central_controller.on_link_peripheral_disconnection_complete(
-            disconnect_command, HCI_SUCCESS
-        )
-
-    def disconnect(self, central_address, peripheral_address, disconnect_command):
-        logger.debug(
-            f'$$$ DISCONNECTION {central_address} -> '
-            f'{peripheral_address}: reason = {disconnect_command.reason}'
-        )
-        args = [central_address, peripheral_address, disconnect_command]
-        asyncio.get_running_loop().call_soon(self.on_disconnection_complete, *args)
-
-    # pylint: disable=too-many-arguments
-    def on_connection_encrypted(
-        self, central_address, peripheral_address, rand, ediv, ltk
+    def send_advertising_pdu(
+        self,
+        sender_controller: controller.Controller,
+        packet: ll.AdvertisingPdu,
     ):
-        logger.debug(f'*** ENCRYPTION {central_address} -> {peripheral_address}')
+        loop = asyncio.get_running_loop()
+        for c in self.controllers:
+            if c != sender_controller:
+                loop.call_soon(c.on_ll_advertising_pdu, packet)
 
-        if central_controller := self.find_controller(central_address):
-            central_controller.on_link_encrypted(peripheral_address, rand, ediv, ltk)
-
-        if peripheral_controller := self.find_controller(peripheral_address):
-            peripheral_controller.on_link_encrypted(central_address, rand, ediv, ltk)
+    def send_ll_control_pdu(
+        self,
+        sender_address: hci.Address,
+        receiver_address: hci.Address,
+        packet: ll.ControlPdu,
+    ):
+        if not (receiver_controller := self.find_le_controller(receiver_address)):
+            raise core.InvalidArgumentError(
+                f"Unable to find controller for address {receiver_address}"
+            )
+        asyncio.get_running_loop().call_soon(
+            lambda: receiver_controller.on_ll_control_pdu(sender_address, packet)
+        )
 
     ############################################################
     # Classic handlers
     ############################################################
 
-    def classic_connect(self, initiator_controller, responder_address):
-        logger.debug(
-            f'[Classic] {initiator_controller.public_address} connects to {responder_address}'
-        )
-        responder_controller = self.find_classic_controller(responder_address)
-        if responder_controller is None:
-            initiator_controller.on_classic_connection_complete(
-                responder_address, HCI_PAGE_TIMEOUT_ERROR
-            )
-            return
-        self.pending_classic_connection = (initiator_controller, responder_controller)
-
-        responder_controller.on_classic_connection_request(
-            initiator_controller.public_address,
-            HCI_Connection_Complete_Event.ACL_LINK_TYPE,
-        )
-
-    def classic_accept_connection(
-        self, responder_controller, initiator_address, responder_role
+    def send_lmp_packet(
+        self,
+        sender_controller: controller.Controller,
+        receiver_address: hci.Address,
+        packet: lmp.Packet,
     ):
-        logger.debug(
-            f'[Classic] {responder_controller.public_address} accepts to connect {initiator_address}'
-        )
-        initiator_controller = self.find_classic_controller(initiator_address)
-        if initiator_controller is None:
-            responder_controller.on_classic_connection_complete(
-                responder_controller.public_address, HCI_PAGE_TIMEOUT_ERROR
+        if not (receiver_controller := self.find_classic_controller(receiver_address)):
+            raise core.InvalidArgumentError(
+                f"Unable to find controller for address {receiver_address}"
             )
-            return
-
-        async def task():
-            if responder_role != BT_PERIPHERAL_ROLE:
-                initiator_controller.on_classic_role_change(
-                    responder_controller.public_address, int(not (responder_role))
-                )
-            initiator_controller.on_classic_connection_complete(
-                responder_controller.public_address, HCI_SUCCESS
-            )
-
-        asyncio.create_task(task())
-        responder_controller.on_classic_role_change(
-            initiator_controller.public_address, responder_role
-        )
-        responder_controller.on_classic_connection_complete(
-            initiator_controller.public_address, HCI_SUCCESS
-        )
-        self.pending_classic_connection = None
-
-    def classic_disconnect(self, initiator_controller, responder_address, reason):
-        logger.debug(
-            f'[Classic] {initiator_controller.public_address} disconnects {responder_address}'
-        )
-        responder_controller = self.find_classic_controller(responder_address)
-
-        async def task():
-            initiator_controller.on_classic_disconnected(responder_address, reason)
-
-        asyncio.create_task(task())
-        responder_controller.on_classic_disconnected(
-            initiator_controller.public_address, reason
-        )
-
-    def classic_switch_role(
-        self, initiator_controller, responder_address, initiator_new_role
-    ):
-        responder_controller = self.find_classic_controller(responder_address)
-        if responder_controller is None:
-            return
-
-        async def task():
-            initiator_controller.on_classic_role_change(
-                responder_address, initiator_new_role
-            )
-
-        asyncio.create_task(task())
-        responder_controller.on_classic_role_change(
-            initiator_controller.public_address, int(not (initiator_new_role))
-        )
-
-
-# -----------------------------------------------------------------------------
-class RemoteLink:
-    '''
-    A Link implementation that communicates with other virtual controllers via a
-    WebSocket relay
-    '''
-
-    def __init__(self, uri):
-        self.controller = None
-        self.uri = uri
-        self.execution_queue = asyncio.Queue()
-        self.websocket = asyncio.get_running_loop().create_future()
-        self.rpc_result = None
-        self.pending_connection = None
-        self.central_connections = set()  # List of addresses that we have connected to
-        self.peripheral_connections = (
-            set()
-        )  # List of addresses that have connected to us
-
-        # Connect and run asynchronously
-        asyncio.create_task(self.run_connection())
-        asyncio.create_task(self.run_executor_loop())
-
-    def add_controller(self, controller):
-        if self.controller:
-            raise ValueError('controller already set')
-        self.controller = controller
-
-    def remove_controller(self, controller):
-        if self.controller != controller:
-            raise ValueError('controller mismatch')
-        self.controller = None
-
-    def get_pending_connection(self):
-        return self.pending_connection
-
-    def get_pending_classic_connection(self):
-        return self.pending_classic_connection
-
-    async def wait_until_connected(self):
-        await self.websocket
-
-    def execute(self, async_function):
-        self.execution_queue.put_nowait(async_function())
-
-    async def run_executor_loop(self):
-        logger.debug('executor loop starting')
-        while True:
-            item = await self.execution_queue.get()
-            try:
-                await item
-            except Exception as error:
-                logger.warning(
-                    f'{color("!!! Exception in async handler:", "red")} {error}'
-                )
-
-    async def run_connection(self):
-        import websockets  # lazy import
-
-        # Connect to the relay
-        logger.debug(f'connecting to {self.uri}')
-        # pylint: disable-next=no-member
-        websocket = await websockets.connect(self.uri)
-        self.websocket.set_result(websocket)
-        logger.debug(f'connected to {self.uri}')
-
-        while True:
-            message = await websocket.recv()
-            logger.debug(f'received message: {message}')
-            keyword, *payload = message.split(':', 1)
-
-            handler_name = f'on_{keyword}_received'
-            handler = getattr(self, handler_name, None)
-            if handler:
-                await handler(payload[0] if payload else None)
-
-    def close(self):
-        if self.websocket.done():
-            logger.debug('closing websocket')
-            websocket = self.websocket.result()
-            asyncio.create_task(websocket.close())
-
-    async def on_result_received(self, result):
-        if self.rpc_result:
-            self.rpc_result.set_result(result)
-
-    async def on_left_received(self, address):
-        if address in self.central_connections:
-            self.controller.on_link_peripheral_disconnected(Address(address))
-            self.central_connections.remove(address)
-
-        if address in self.peripheral_connections:
-            self.controller.on_link_central_disconnected(
-                address, HCI_CONNECTION_TIMEOUT_ERROR
-            )
-            self.peripheral_connections.remove(address)
-
-    async def on_unreachable_received(self, target):
-        await self.on_left_received(target)
-
-    async def on_message_received(self, message):
-        sender, *payload = message.split('/', 1)
-        if payload:
-            keyword, *payload = payload[0].split(':', 1)
-            handler_name = f'on_{keyword}_message_received'
-            handler = getattr(self, handler_name, None)
-            if handler:
-                await handler(sender, payload[0] if payload else None)
-
-    async def on_advertisement_message_received(self, sender, advertisement):
-        try:
-            self.controller.on_link_advertising_data(
-                Address(sender), bytes.fromhex(advertisement)
-            )
-        except Exception:
-            logger.exception('exception')
-
-    async def on_acl_message_received(self, sender, acl_data):
-        try:
-            self.controller.on_link_acl_data(Address(sender), bytes.fromhex(acl_data))
-        except Exception:
-            logger.exception('exception')
-
-    async def on_connect_message_received(self, sender, _):
-        # Remember the connection
-        self.peripheral_connections.add(sender)
-
-        # Notify the controller
-        logger.debug(f'connection from central {sender}')
-        self.controller.on_link_central_connected(Address(sender))
-
-        # Accept the connection by responding to it
-        await self.send_targeted_message(sender, 'connected')
-
-    async def on_connected_message_received(self, sender, _):
-        if not self.pending_connection:
-            logger.warning('received a connection ack, but no connection is pending')
-            return
-
-        # Remember the connection
-        self.central_connections.add(sender)
-
-        # Notify the controller
-        logger.debug(f'connected to peripheral {self.pending_connection.peer_address}')
-        self.controller.on_link_peripheral_connection_complete(
-            self.pending_connection, HCI_SUCCESS
-        )
-
-    async def on_disconnect_message_received(self, sender, message):
-        # Notify the controller
-        params = parse_parameters(message)
-        reason = int(params.get('reason', str(HCI_CONNECTION_TIMEOUT_ERROR)))
-        self.controller.on_link_central_disconnected(Address(sender), reason)
-
-        # Forget the connection
-        if sender in self.peripheral_connections:
-            self.peripheral_connections.remove(sender)
-
-    async def on_encrypted_message_received(self, sender, _):
-        # TODO parse params to get real args
-        self.controller.on_link_encrypted(Address(sender), bytes(8), 0, bytes(16))
-
-    async def send_rpc_command(self, command):
-        # Ensure we have a connection
-        websocket = await self.websocket
-
-        # Create a future value to hold the eventual result
-        assert self.rpc_result is None
-        self.rpc_result = asyncio.get_running_loop().create_future()
-
-        # Send the command
-        await websocket.send(command)
-
-        # Wait for the result
-        rpc_result = await self.rpc_result
-        self.rpc_result = None
-        logger.debug(f'rpc_result: {rpc_result}')
-
-        # TODO: parse the result
-
-    async def send_targeted_message(self, target, message):
-        # Ensure we have a connection
-        websocket = await self.websocket
-
-        # Send the message
-        await websocket.send(f'@{target} {message}')
-
-    async def notify_address_changed(self):
-        await self.send_rpc_command(f'/set-address {self.controller.random_address}')
-
-    def on_address_changed(self, controller):
-        logger.info(f'address changed for {controller}: {controller.random_address}')
-
-        # Notify the relay of the change
-        self.execute(self.notify_address_changed)
-
-    async def send_advertising_data_to_relay(self, data):
-        await self.send_targeted_message('*', f'advertisement:{data.hex()}')
-
-    def send_advertising_data(self, _, data):
-        self.execute(partial(self.send_advertising_data_to_relay, data))
-
-    async def send_acl_data_to_relay(self, peer_address, data):
-        await self.send_targeted_message(peer_address, f'acl:{data.hex()}')
-
-    def send_acl_data(self, _, peer_address, _transport, data):
-        # TODO: handle different transport
-        self.execute(partial(self.send_acl_data_to_relay, peer_address, data))
-
-    async def send_connection_request_to_relay(self, peer_address):
-        await self.send_targeted_message(peer_address, 'connect')
-
-    def connect(self, _, le_create_connection_command):
-        if self.pending_connection:
-            logger.warning('connection already pending')
-            return
-        self.pending_connection = le_create_connection_command
-        self.execute(
-            partial(
-                self.send_connection_request_to_relay,
-                str(le_create_connection_command.peer_address),
-            )
-        )
-
-    def on_disconnection_complete(self, disconnect_command):
-        self.controller.on_link_peripheral_disconnection_complete(
-            disconnect_command, HCI_SUCCESS
-        )
-
-    def disconnect(self, central_address, peripheral_address, disconnect_command):
-        logger.debug(
-            f'disconnect {central_address} -> '
-            f'{peripheral_address}: reason = {disconnect_command.reason}'
-        )
-        self.execute(
-            partial(
-                self.send_targeted_message,
-                peripheral_address,
-                f'disconnect:reason={disconnect_command.reason}',
-            )
-        )
         asyncio.get_running_loop().call_soon(
-            self.on_disconnection_complete, disconnect_command
-        )
-
-    def on_connection_encrypted(self, _, peripheral_address, rand, ediv, ltk):
-        asyncio.get_running_loop().call_soon(
-            self.controller.on_link_encrypted, peripheral_address, rand, ediv, ltk
-        )
-        self.execute(
-            partial(
-                self.send_targeted_message,
-                peripheral_address,
-                f'encrypted:ltk={ltk.hex()}',
+            lambda: receiver_controller.on_lmp_packet(
+                sender_controller.public_address, packet
             )
         )

bumble/ll.py

@@ -0,0 +1,200 @@
+# Copyright 2021-2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# -----------------------------------------------------------------------------
+# Imports
+# -----------------------------------------------------------------------------
+from __future__ import annotations
+
+import dataclasses
+from typing import ClassVar
+
+from bumble import hci
+
+
+# -----------------------------------------------------------------------------
+# Advertising PDU
+# -----------------------------------------------------------------------------
+class AdvertisingPdu:
+    """Base Advertising Physical Channel PDU class.
+
+    See Core Spec 6.0, Volume 6, Part B, 2.3. Advertising physical channel PDU.
+
+    Currently these messages don't really follow the LL spec, because LL protocol is
+    context-aware and we don't have real physical transport.
+    """
+
+
+@dataclasses.dataclass
+class ConnectInd(AdvertisingPdu):
+    initiator_address: hci.Address
+    advertiser_address: hci.Address
+    interval: int
+    latency: int
+    timeout: int
+
+
+@dataclasses.dataclass
+class AdvInd(AdvertisingPdu):
+    advertiser_address: hci.Address
+    data: bytes
+
+
+@dataclasses.dataclass
+class AdvDirectInd(AdvertisingPdu):
+    advertiser_address: hci.Address
+    target_address: hci.Address
+
+
+@dataclasses.dataclass
+class AdvNonConnInd(AdvertisingPdu):
+    advertiser_address: hci.Address
+    data: bytes
+
+
+@dataclasses.dataclass
+class AdvExtInd(AdvertisingPdu):
+    advertiser_address: hci.Address
+    data: bytes
+
+    target_address: hci.Address | None = None
+    adi: int | None = None
+    tx_power: int | None = None
+
+
+# -----------------------------------------------------------------------------
+# LL Control PDU
+# -----------------------------------------------------------------------------
+class ControlPdu:
+    """Base LL Control PDU Class.
+
+    See Core Spec 6.0, Volume 6, Part B, 2.4.2. LL Control PDU.
+
+    Currently these messages don't really follow the LL spec, because LL protocol is
+    context-aware and we don't have real physical transport.
+    """
+
+    class Opcode(hci.SpecableEnum):
+        LL_CONNECTION_UPDATE_IND = 0x00
+        LL_CHANNEL_MAP_IND = 0x01
+        LL_TERMINATE_IND = 0x02
+        LL_ENC_REQ = 0x03
+        LL_ENC_RSP = 0x04
+        LL_START_ENC_REQ = 0x05
+        LL_START_ENC_RSP = 0x06
+        LL_UNKNOWN_RSP = 0x07
+        LL_FEATURE_REQ = 0x08
+        LL_FEATURE_RSP = 0x09
+        LL_PAUSE_ENC_REQ = 0x0A
+        LL_PAUSE_ENC_RSP = 0x0B
+        LL_VERSION_IND = 0x0C
+        LL_REJECT_IND = 0x0D
+        LL_PERIPHERAL_FEATURE_REQ = 0x0E
+        LL_CONNECTION_PARAM_REQ = 0x0F
+        LL_CONNECTION_PARAM_RSP = 0x10
+        LL_REJECT_EXT_IND = 0x11
+        LL_PING_REQ = 0x12
+        LL_PING_RSP = 0x13
+        LL_LENGTH_REQ = 0x14
+        LL_LENGTH_RSP = 0x15
+        LL_PHY_REQ = 0x16
+        LL_PHY_RSP = 0x17
+        LL_PHY_UPDATE_IND = 0x18
+        LL_MIN_USED_CHANNELS_IND = 0x19
+        LL_CTE_REQ = 0x1A
+        LL_CTE_RSP = 0x1B
+        LL_PERIODIC_SYNC_IND = 0x1C
+        LL_CLOCK_ACCURACY_REQ = 0x1D
+        LL_CLOCK_ACCURACY_RSP = 0x1E
+        LL_CIS_REQ = 0x1F
+        LL_CIS_RSP = 0x20
+        LL_CIS_IND = 0x21
+        LL_CIS_TERMINATE_IND = 0x22
+        LL_POWER_CONTROL_REQ = 0x23
+        LL_POWER_CONTROL_RSP = 0x24
+        LL_POWER_CHANGE_IND = 0x25
+        LL_SUBRATE_REQ = 0x26
+        LL_SUBRATE_IND = 0x27
+        LL_CHANNEL_REPORTING_IND = 0x28
+        LL_CHANNEL_STATUS_IND = 0x29
+        LL_PERIODIC_SYNC_WR_IND = 0x2A
+        LL_FEATURE_EXT_REQ = 0x2B
+        LL_FEATURE_EXT_RSP = 0x2C
+        LL_CS_SEC_RSP = 0x2D
+        LL_CS_CAPABILITIES_REQ = 0x2E
+        LL_CS_CAPABILITIES_RSP = 0x2F
+        LL_CS_CONFIG_REQ = 0x30
+        LL_CS_CONFIG_RSP = 0x31
+        LL_CS_REQ = 0x32
+        LL_CS_RSP = 0x33
+        LL_CS_IND = 0x34
+        LL_CS_TERMINATE_REQ = 0x35
+        LL_CS_FAE_REQ = 0x36
+        LL_CS_FAE_RSP = 0x37
+        LL_CS_CHANNEL_MAP_IND = 0x38
+        LL_CS_SEC_REQ = 0x39
+        LL_CS_TERMINATE_RSP = 0x3A
+        LL_FRAME_SPACE_REQ = 0x3B
+        LL_FRAME_SPACE_RSP = 0x3C
+
+    opcode: ClassVar[Opcode]
+
+
+@dataclasses.dataclass
+class TerminateInd(ControlPdu):
+    opcode = ControlPdu.Opcode.LL_TERMINATE_IND
+
+    error_code: int
+
+
+@dataclasses.dataclass
+class EncReq(ControlPdu):
+    opcode = ControlPdu.Opcode.LL_ENC_REQ
+
+    rand: bytes
+    ediv: int
+    ltk: bytes
+
+
+@dataclasses.dataclass
+class CisReq(ControlPdu):
+    opcode = ControlPdu.Opcode.LL_CIS_REQ
+
+    cig_id: int
+    cis_id: int
+
+
+@dataclasses.dataclass
+class CisRsp(ControlPdu):
+    opcode = ControlPdu.Opcode.LL_CIS_REQ
+
+    cig_id: int
+    cis_id: int
+
+
+@dataclasses.dataclass
+class CisInd(ControlPdu):
+    opcode = ControlPdu.Opcode.LL_CIS_REQ
+
+    cig_id: int
+    cis_id: int
+
+
+@dataclasses.dataclass
+class CisTerminateInd(ControlPdu):
+    opcode = ControlPdu.Opcode.LL_CIS_TERMINATE_IND
+
+    cig_id: int
+    cis_id: int
+    error_code: int

bumble/lmp.py

@@ -0,0 +1,324 @@
+# Copyright 2021-2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# -----------------------------------------------------------------------------
+# Imports
+# -----------------------------------------------------------------------------
+from __future__ import annotations
+
+import struct
+from dataclasses import dataclass, field
+from typing import TypeVar
+
+from bumble import hci, utils
+
+
+class Opcode(utils.OpenIntEnum):
+    '''
+    See Bluetooth spec @ Vol 2, Part C - 5.1 PDU summary.
+
+    Follow the alphabetical order defined there.
+    '''
+
+    # fmt: off
+    LMP_ACCEPTED                    = 3
+    LMP_ACCEPTED_EXT                = 127 << 8 + 1
+    LMP_AU_RAND                     = 11
+    LMP_AUTO_RATE                   = 35
+    LMP_CHANNEL_CLASSIFICATION      = 127 << 8 + 17
+    LMP_CHANNEL_CLASSIFICATION_REQ  = 127 << 8 + 16
+    LMP_CLK_ADJ                     = 127 << 8 + 5
+    LMP_CLK_ADJ_ACK                 = 127 << 8 + 6
+    LMP_CLK_ADJ_REQ                 = 127 << 8 + 7
+    LMP_CLKOFFSET_REQ               = 5
+    LMP_CLKOFFSET_RES               = 6
+    LMP_COMB_KEY                    = 9
+    LMP_DECR_POWER_REQ              = 32
+    LMP_DETACH                      = 7
+    LMP_DHKEY_CHECK                 = 65
+    LMP_ENCAPSULATED_HEADER         = 61
+    LMP_ENCAPSULATED_PAYLOAD        = 62
+    LMP_ENCRYPTION_KEY_SIZE_MASK_REQ= 58
+    LMP_ENCRYPTION_KEY_SIZE_MASK_RES= 59
+    LMP_ENCRYPTION_KEY_SIZE_REQ     = 16
+    LMP_ENCRYPTION_MODE_REQ         = 15
+    LMP_ESCO_LINK_REQ               = 127 << 8 + 12
+    LMP_FEATURES_REQ                = 39
+    LMP_FEATURES_REQ_EXT            = 127 << 8 + 3
+    LMP_FEATURES_RES                = 40
+    LMP_FEATURES_RES_EXT            = 127 << 8 + 4
+    LMP_HOLD                        = 20
+    LMP_HOLD_REQ                    = 21
+    LMP_HOST_CONNECTION_REQ         = 51
+    LMP_IN_RAND                     = 8
+    LMP_INCR_POWER_REQ              = 31
+    LMP_IO_CAPABILITY_REQ           = 127 << 8 + 25
+    LMP_IO_CAPABILITY_RES           = 127 << 8 + 26
+    LMP_KEYPRESS_NOTIFICATION       = 127 << 8 + 30
+    LMP_MAX_POWER                   = 33
+    LMP_MAX_SLOT                    = 45
+    LMP_MAX_SLOT_REQ                = 46
+    LMP_MIN_POWER                   = 34
+    LMP_NAME_REQ                    = 1
+    LMP_NAME_RES                    = 2
+    LMP_NOT_ACCEPTED                = 4
+    LMP_NOT_ACCEPTED_EXT            = 127 << 8 + 2
+    LMP_NUMERIC_COMPARISON_FAILED   = 127 << 8 + 27
+    LMP_OOB_FAILED                  = 127 << 8 + 29
+    LMP_PACKET_TYPE_TABLE_REQ       = 127 << 8 + 11
+    LMP_PAGE_MODE_REQ               = 53
+    LMP_PAGE_SCAN_MODE_REQ          = 54
+    LMP_PASSKEY_FAILED              = 127 << 8 + 28
+    LMP_PAUSE_ENCRYPTION_AES_REQ    = 66
+    LMP_PAUSE_ENCRYPTION_REQ        = 127 << 8 + 23
+    LMP_PING_REQ                    = 127 << 8 + 33
+    LMP_PING_RES                    = 127 << 8 + 34
+    LMP_POWER_CONTROL_REQ           = 127 << 8 + 31
+    LMP_POWER_CONTROL_RES           = 127 << 8 + 32
+    LMP_PREFERRED_RATE              = 36
+    LMP_QUALITY_OF_SERVICE          = 41
+    LMP_QUALITY_OF_SERVICE_REQ      = 42
+    LMP_REMOVE_ESCO_LINK_REQ        = 127 << 8 + 13
+    LMP_REMOVE_SCO_LINK_REQ         = 44
+    LMP_RESUME_ENCRYPTION_REQ       = 127 << 8 + 24
+    LMP_SAM_DEFINE_MAP              = 127 << 8 + 36
+    LMP_SAM_SET_TYPE0               = 127 << 8 + 35
+    LMP_SAM_SWITCH                  = 127 << 8 + 37
+    LMP_SCO_LINK_REQ                = 43
+    LMP_SET_AFH                     = 60
+    LMP_SETUP_COMPLETE              = 49
+    LMP_SIMPLE_PAIRING_CONFIRM      = 63
+    LMP_SIMPLE_PAIRING_NUMBER       = 64
+    LMP_SLOT_OFFSET                 = 52
+    LMP_SNIFF_REQ                   = 23
+    LMP_SNIFF_SUBRATING_REQ         = 127 << 8 + 21
+    LMP_SNIFF_SUBRATING_RES         = 127 << 8 + 22
+    LMP_SRES                        = 12
+    LMP_START_ENCRYPTION_REQ        = 17
+    LMP_STOP_ENCRYPTION_REQ         = 18
+    LMP_SUPERVISION_TIMEOUT         = 55
+    LMP_SWITCH_REQ                  = 19
+    LMP_TEMP_KEY                    = 14
+    LMP_TEMP_RAND                   = 13
+    LMP_TEST_ACTIVATE               = 56
+    LMP_TEST_CONTROL                = 57
+    LMP_TIMING_ACCURACY_REQ         = 47
+    LMP_TIMING_ACCURACY_RES         = 48
+    LMP_UNIT_KEY                    = 10
+    LMP_UNSNIFF_REQ                 = 24
+    LMP_USE_SEMI_PERMANENT_KEY      = 50
+    LMP_VERSION_REQ                 = 37
+    LMP_VERSION_RES                 = 38
+    # fmt: on
+
+    @classmethod
+    def parse_from(cls, data: bytes, offset: int = 0) -> tuple[int, Opcode]:
+        opcode = data[offset]
+        if opcode in (124, 127):
+            opcode = struct.unpack('>H', data)[0]
+            return offset + 2, Opcode(opcode)
+        return offset + 1, Opcode(opcode)
+
+    def __bytes__(self) -> bytes:
+        if self.value >> 8:
+            return struct.pack('>H', self.value)
+        return bytes([self.value])
+
+    @classmethod
+    def type_metadata(cls):
+        return hci.metadata(
+            {
+                'serializer': bytes,
+                'parser': lambda data, offset: (Opcode.parse_from(data, offset)),
+            }
+        )
+
+
+class Packet:
+    '''
+    See Bluetooth spec @ Vol 2, Part C - 5.1 PDU summary
+    '''
+
+    subclasses: dict[int, type[Packet]] = {}
+    opcode: Opcode
+    fields: hci.Fields = ()
+    _payload: bytes = b''
+
+    _Packet = TypeVar("_Packet", bound="Packet")
+
+    @classmethod
+    def subclass(cls, subclass: type[_Packet]) -> type[_Packet]:
+        # Register a factory for this class
+        cls.subclasses[subclass.opcode] = subclass
+        subclass.fields = hci.HCI_Object.fields_from_dataclass(subclass)
+
+        return subclass
+
+    @classmethod
+    def from_bytes(cls, data: bytes) -> Packet:
+        offset, opcode = Opcode.parse_from(data)
+        if not (subclass := cls.subclasses.get(opcode)):
+            instance = Packet()
+            instance.opcode = opcode
+        else:
+            instance = subclass(
+                **hci.HCI_Object.dict_from_bytes(data, offset, subclass.fields)
+            )
+        instance.payload = data[offset:]
+        return instance
+
+    @property
+    def payload(self) -> bytes:
+        if self._payload is None:
+            self._payload = hci.HCI_Object.dict_to_bytes(self.__dict__, self.fields)
+        return self._payload
+
+    @payload.setter
+    def payload(self, value: bytes) -> None:
+        self._payload = value
+
+    def __bytes__(self) -> bytes:
+        return bytes(self.opcode) + self.payload
+
+
+@Packet.subclass
+@dataclass
+class LmpAccepted(Packet):
+    opcode = Opcode.LMP_ACCEPTED
+
+    response_opcode: Opcode = field(metadata=Opcode.type_metadata())
+
+
+@Packet.subclass
+@dataclass
+class LmpNotAccepted(Packet):
+    opcode = Opcode.LMP_NOT_ACCEPTED
+
+    response_opcode: Opcode = field(metadata=Opcode.type_metadata())
+    error_code: int = field(metadata=hci.metadata(1))
+
+
+@Packet.subclass
+@dataclass
+class LmpAcceptedExt(Packet):
+    opcode = Opcode.LMP_ACCEPTED_EXT
+
+    response_opcode: Opcode = field(metadata=Opcode.type_metadata())
+
+
+@Packet.subclass
+@dataclass
+class LmpNotAcceptedExt(Packet):
+    opcode = Opcode.LMP_NOT_ACCEPTED_EXT
+
+    response_opcode: Opcode = field(metadata=Opcode.type_metadata())
+    error_code: int = field(metadata=hci.metadata(1))
+
+
+@Packet.subclass
+@dataclass
+class LmpAuRand(Packet):
+    opcode = Opcode.LMP_AU_RAND
+
+    random_number: bytes = field(metadata=hci.metadata(16))
+
+
+@Packet.subclass
+@dataclass
+class LmpDetach(Packet):
+    opcode = Opcode.LMP_DETACH
+
+    error_code: int = field(metadata=hci.metadata(1))
+
+
+@Packet.subclass
+@dataclass
+class LmpEscoLinkReq(Packet):
+    opcode = Opcode.LMP_ESCO_LINK_REQ
+
+    esco_handle: int = field(metadata=hci.metadata(1))
+    esco_lt_addr: int = field(metadata=hci.metadata(1))
+    timing_control_flags: int = field(metadata=hci.metadata(1))
+    d_esco: int = field(metadata=hci.metadata(1))
+    t_esco: int = field(metadata=hci.metadata(1))
+    w_esco: int = field(metadata=hci.metadata(1))
+    esco_packet_type_c_to_p: int = field(metadata=hci.metadata(1))
+    esco_packet_type_p_to_c: int = field(metadata=hci.metadata(1))
+    packet_length_c_to_p: int = field(metadata=hci.metadata(2))
+    packet_length_p_to_c: int = field(metadata=hci.metadata(2))
+    air_mode: int = field(metadata=hci.metadata(1))
+    negotiation_state: int = field(metadata=hci.metadata(1))
+
+
+@Packet.subclass
+@dataclass
+class LmpHostConnectionReq(Packet):
+    opcode = Opcode.LMP_HOST_CONNECTION_REQ
+
+
+@Packet.subclass
+@dataclass
+class LmpRemoveEscoLinkReq(Packet):
+    opcode = Opcode.LMP_REMOVE_ESCO_LINK_REQ
+
+    esco_handle: int = field(metadata=hci.metadata(1))
+    error_code: int = field(metadata=hci.metadata(1))
+
+
+@Packet.subclass
+@dataclass
+class LmpRemoveScoLinkReq(Packet):
+    opcode = Opcode.LMP_REMOVE_SCO_LINK_REQ
+
+    sco_handle: int = field(metadata=hci.metadata(1))
+    error_code: int = field(metadata=hci.metadata(1))
+
+
+@Packet.subclass
+@dataclass
+class LmpScoLinkReq(Packet):
+    opcode = Opcode.LMP_SCO_LINK_REQ
+
+    sco_handle: int = field(metadata=hci.metadata(1))
+    timing_control_flags: int = field(metadata=hci.metadata(1))
+    d_sco: int = field(metadata=hci.metadata(1))
+    t_sco: int = field(metadata=hci.metadata(1))
+    sco_packet: int = field(metadata=hci.metadata(1))
+    air_mode: int = field(metadata=hci.metadata(1))
+
+
+@Packet.subclass
+@dataclass
+class LmpSwitchReq(Packet):
+    opcode = Opcode.LMP_SWITCH_REQ
+
+    switch_instant: int = field(metadata=hci.metadata(4), default=0)
+
+
+@Packet.subclass
+@dataclass
+class LmpNameReq(Packet):
+    opcode = Opcode.LMP_NAME_REQ
+
+    name_offset: int = field(metadata=hci.metadata(2))
+
+
+@Packet.subclass
+@dataclass
+class LmpNameRes(Packet):
+    opcode = Opcode.LMP_NAME_RES
+
+    name_offset: int = field(metadata=hci.metadata(2))
+    name_length: int = field(metadata=hci.metadata(3))
+    name_fregment: bytes = field(metadata=hci.metadata('*'))

bumble/logging.py

@@ -0,0 +1,65 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# -----------------------------------------------------------------------------
+# Imports
+# -----------------------------------------------------------------------------
+import functools
+import logging
+import os
+
+from bumble import colors
+
+
+# -----------------------------------------------------------------------------
+class ColorFormatter(logging.Formatter):
+    _colorizers = {
+        logging.DEBUG: functools.partial(colors.color, fg="white"),
+        logging.INFO: functools.partial(colors.color, fg="green"),
+        logging.WARNING: functools.partial(colors.color, fg="yellow"),
+        logging.ERROR: functools.partial(colors.color, fg="red"),
+        logging.CRITICAL: functools.partial(colors.color, fg="black", bg="red"),
+    }
+
+    _formatters = {
+        level: logging.Formatter(
+            fmt=colorizer("{asctime}.{msecs:03.0f} {levelname:.1} {name}: ")
+            + "{message}",
+            datefmt="%H:%M:%S",
+            style="{",
+        )
+        for level, colorizer in _colorizers.items()
+    }
+
+    def format(self, record: logging.LogRecord) -> str:
+        return self._formatters[record.levelno].format(record)
+
+
+def setup_basic_logging(default_level: str = "INFO") -> None:
+    """
+    Set up basic logging with logging.basicConfig, configured with a simple formatter
+    that prints out the date and log level in color.
+    If the BUMBLE_LOGLEVEL environment variable is set to the name of a log level, it
+    is used. Otherwise the default_level argument is used.
+
+    Args:
+      default_level: default logging level
+
+    """
+    handler = logging.StreamHandler()
+    handler.setFormatter(ColorFormatter())
+    logging.basicConfig(
+        level=os.environ.get("BUMBLE_LOGLEVEL", default_level).upper(),
+        handlers=[handler],
+    )

bumble/pairing.py

@@ -1,4 +1,4 @@
-# Copyright 2021-2023 Google LLC
+# Copyright 2021-2025 Google LLC
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -15,28 +15,79 @@
 # -----------------------------------------------------------------------------
 # Imports
 # -----------------------------------------------------------------------------
-import enum
-from typing import Optional, Tuple
+from __future__ import annotations
 
-from .hci import (
-    HCI_NO_INPUT_NO_OUTPUT_IO_CAPABILITY,
-    HCI_DISPLAY_ONLY_IO_CAPABILITY,
-    HCI_DISPLAY_YES_NO_IO_CAPABILITY,
-    HCI_KEYBOARD_ONLY_IO_CAPABILITY,
-)
-from .smp import (
-    SMP_NO_INPUT_NO_OUTPUT_IO_CAPABILITY,
-    SMP_KEYBOARD_ONLY_IO_CAPABILITY,
+import enum
+import secrets
+from dataclasses import dataclass
+
+from bumble import hci
+from bumble.core import AdvertisingData, LeRole
+from bumble.smp import (
     SMP_DISPLAY_ONLY_IO_CAPABILITY,
     SMP_DISPLAY_YES_NO_IO_CAPABILITY,
-    SMP_KEYBOARD_DISPLAY_IO_CAPABILITY,
     SMP_ENC_KEY_DISTRIBUTION_FLAG,
     SMP_ID_KEY_DISTRIBUTION_FLAG,
-    SMP_SIGN_KEY_DISTRIBUTION_FLAG,
+    SMP_KEYBOARD_DISPLAY_IO_CAPABILITY,
+    SMP_KEYBOARD_ONLY_IO_CAPABILITY,
     SMP_LINK_KEY_DISTRIBUTION_FLAG,
+    SMP_NO_INPUT_NO_OUTPUT_IO_CAPABILITY,
+    SMP_SIGN_KEY_DISTRIBUTION_FLAG,
+    OobContext,
+    OobLegacyContext,
+    OobSharedData,
 )
 
 
+# -----------------------------------------------------------------------------
+@dataclass
+class OobData:
+    """OOB data that can be sent from one device to another."""
+
+    address: hci.Address | None = None
+    role: LeRole | None = None
+    shared_data: OobSharedData | None = None
+    legacy_context: OobLegacyContext | None = None
+
+    @classmethod
+    def from_ad(cls, ad: AdvertisingData) -> OobData:
+        instance = cls()
+        shared_data_c: bytes | None = None
+        shared_data_r: bytes | None = None
+        for ad_type, ad_data in ad.ad_structures:
+            if ad_type == AdvertisingData.LE_BLUETOOTH_DEVICE_ADDRESS:
+                instance.address = hci.Address(ad_data)
+            elif ad_type == AdvertisingData.LE_ROLE:
+                instance.role = LeRole(ad_data[0])
+            elif ad_type == AdvertisingData.LE_SECURE_CONNECTIONS_CONFIRMATION_VALUE:
+                shared_data_c = ad_data
+            elif ad_type == AdvertisingData.LE_SECURE_CONNECTIONS_RANDOM_VALUE:
+                shared_data_r = ad_data
+            elif ad_type == AdvertisingData.SECURITY_MANAGER_TK_VALUE:
+                instance.legacy_context = OobLegacyContext(tk=ad_data)
+        if shared_data_c and shared_data_r:
+            instance.shared_data = OobSharedData(c=shared_data_c, r=shared_data_r)
+
+        return instance
+
+    def to_ad(self) -> AdvertisingData:
+        ad_structures: list[tuple[int, bytes]] = []
+        if self.address is not None:
+            ad_structures.append(
+                (AdvertisingData.Type.LE_BLUETOOTH_DEVICE_ADDRESS, bytes(self.address))
+            )
+        if self.role is not None:
+            ad_structures.append((AdvertisingData.Type.LE_ROLE, bytes([self.role])))
+        if self.shared_data is not None:
+            ad_structures.extend(self.shared_data.to_ad().ad_structures)
+        if self.legacy_context is not None:
+            ad_structures.append(
+                (AdvertisingData.Type.SECURITY_MANAGER_TK_VALUE, self.legacy_context.tk)
+            )
+
+        return AdvertisingData(ad_structures)
+
+
 # -----------------------------------------------------------------------------
 class PairingDelegate:
     """Abstract base class for Pairing Delegates."""
@@ -73,26 +124,29 @@ class PairingDelegate:
     # Default mapping from abstract to Classic I/O capabilities.
     # Subclasses may override this if they prefer a different mapping.
     CLASSIC_IO_CAPABILITIES_MAP = {
-        NO_OUTPUT_NO_INPUT: HCI_NO_INPUT_NO_OUTPUT_IO_CAPABILITY,
-        KEYBOARD_INPUT_ONLY: HCI_KEYBOARD_ONLY_IO_CAPABILITY,
-        DISPLAY_OUTPUT_ONLY: HCI_DISPLAY_ONLY_IO_CAPABILITY,
-        DISPLAY_OUTPUT_AND_YES_NO_INPUT: HCI_DISPLAY_YES_NO_IO_CAPABILITY,
-        DISPLAY_OUTPUT_AND_KEYBOARD_INPUT: HCI_DISPLAY_YES_NO_IO_CAPABILITY,
+        NO_OUTPUT_NO_INPUT: hci.IoCapability.NO_INPUT_NO_OUTPUT,
+        KEYBOARD_INPUT_ONLY: hci.IoCapability.KEYBOARD_ONLY,
+        DISPLAY_OUTPUT_ONLY: hci.IoCapability.DISPLAY_ONLY,
+        DISPLAY_OUTPUT_AND_YES_NO_INPUT: hci.IoCapability.DISPLAY_YES_NO,
+        DISPLAY_OUTPUT_AND_KEYBOARD_INPUT: hci.IoCapability.DISPLAY_YES_NO,
     }
 
     io_capability: IoCapability
     local_initiator_key_distribution: KeyDistribution
     local_responder_key_distribution: KeyDistribution
+    maximum_encryption_key_size: int
 
     def __init__(
         self,
         io_capability: IoCapability = NO_OUTPUT_NO_INPUT,
         local_initiator_key_distribution: KeyDistribution = DEFAULT_KEY_DISTRIBUTION,
         local_responder_key_distribution: KeyDistribution = DEFAULT_KEY_DISTRIBUTION,
+        maximum_encryption_key_size: int = 16,
     ) -> None:
         self.io_capability = io_capability
         self.local_initiator_key_distribution = local_initiator_key_distribution
         self.local_responder_key_distribution = local_responder_key_distribution
+        self.maximum_encryption_key_size = maximum_encryption_key_size
 
     @property
     def classic_io_capability(self) -> int:
@@ -100,7 +154,7 @@ class PairingDelegate:
 
         # pylint: disable=line-too-long
         return self.CLASSIC_IO_CAPABILITIES_MAP.get(
-            self.io_capability, HCI_NO_INPUT_NO_OUTPUT_IO_CAPABILITY
+            self.io_capability, hci.IoCapability.NO_INPUT_NO_OUTPUT
         )
 
     @property
@@ -126,14 +180,14 @@ class PairingDelegate:
         """Compare two numbers."""
         return True
 
-    async def get_number(self) -> Optional[int]:
+    async def get_number(self) -> int | None:
         """
         Return an optional number as an answer to a passkey request.
         Returning `None` will result in a negative reply.
         """
         return 0
 
-    async def get_string(self, max_length: int) -> Optional[str]:
+    async def get_string(self, max_length: int) -> str | None:
         """
         Return a string whose utf-8 encoding is up to max_length bytes.
         """
@@ -146,7 +200,7 @@ class PairingDelegate:
     # [LE only]
     async def key_distribution_response(
         self, peer_initiator_key_distribution: int, peer_responder_key_distribution: int
-    ) -> Tuple[int, int]:
+    ) -> tuple[int, int]:
         """
         Return the key distribution response in an SMP protocol context.
 
@@ -163,26 +217,52 @@ class PairingDelegate:
             ),
         )
 
+    async def generate_passkey(self) -> int:
+        """
+        Return a passkey value between 0 and 999999 (inclusive).
+        """
+
+        # By default, generate a random passkey.
+        return secrets.randbelow(1000000)
+
 
 # -----------------------------------------------------------------------------
 class PairingConfig:
     """Configuration for the Pairing protocol."""
 
+    class AddressType(enum.IntEnum):
+        PUBLIC = hci.Address.PUBLIC_DEVICE_ADDRESS
+        RANDOM = hci.Address.RANDOM_DEVICE_ADDRESS
+
+    @dataclass
+    class OobConfig:
+        """Config for OOB pairing."""
+
+        our_context: OobContext | None
+        peer_data: OobSharedData | None
+        legacy_context: OobLegacyContext | None
+
     def __init__(
         self,
         sc: bool = True,
         mitm: bool = True,
         bonding: bool = True,
-        delegate: Optional[PairingDelegate] = None,
+        delegate: PairingDelegate | None = None,
+        identity_address_type: AddressType | None = None,
+        oob: OobConfig | None = None,
     ) -> None:
         self.sc = sc
         self.mitm = mitm
         self.bonding = bonding
         self.delegate = delegate or PairingDelegate()
+        self.identity_address_type = identity_address_type
+        self.oob = oob
 
     def __str__(self) -> str:
         return (
             f'PairingConfig(sc={self.sc}, '
             f'mitm={self.mitm}, bonding={self.bonding}, '
-            f'delegate[{self.delegate.io_capability}])'
+            f'identity_address_type={self.identity_address_type}, '
+            f'delegate[{self.delegate.io_capability}]), '
+            f'oob[{self.oob}])'
         )

bumble/pandora/__init__.py

@@ -19,19 +19,22 @@ This module implement the Pandora Bluetooth test APIs for the Bumble stack.
 
 __version__ = "0.0.1"
 
+from collections.abc import Callable
+
 import grpc
 import grpc.aio
-
-from .config import Config
-from .device import PandoraDevice
-from .host import HostService
-from .security import SecurityService, SecurityStorageService
 from pandora.host_grpc_aio import add_HostServicer_to_server
+from pandora.l2cap_grpc_aio import add_L2CAPServicer_to_server
 from pandora.security_grpc_aio import (
     add_SecurityServicer_to_server,
     add_SecurityStorageServicer_to_server,
 )
-from typing import Callable, List, Optional
+
+from bumble.pandora.config import Config
+from bumble.pandora.device import PandoraDevice
+from bumble.pandora.host import HostService
+from bumble.pandora.l2cap import L2CAPService
+from bumble.pandora.security import SecurityService, SecurityStorageService
 
 # public symbols
 __all__ = [
@@ -43,11 +46,11 @@ __all__ = [
 
 
 # Add servicers hooks.
-_SERVICERS_HOOKS: List[Callable[[PandoraDevice, Config, grpc.aio.Server], None]] = []
+_SERVICERS_HOOKS: list[Callable[[PandoraDevice, Config, grpc.aio.Server], None]] = []
 
 
 def register_servicer_hook(
-    hook: Callable[[PandoraDevice, Config, grpc.aio.Server], None]
+    hook: Callable[[PandoraDevice, Config, grpc.aio.Server], None],
 ) -> None:
     _SERVICERS_HOOKS.append(hook)
 
@@ -55,7 +58,7 @@ def register_servicer_hook(
 async def serve(
     bumble: PandoraDevice,
     config: Config = Config(),
-    grpc_server: Optional[grpc.aio.Server] = None,
+    grpc_server: grpc.aio.Server | None = None,
     port: int = 0,
 ) -> None:
     # initialize a gRPC server if not provided.
@@ -77,6 +80,7 @@ async def serve(
             add_SecurityStorageServicer_to_server(
                 SecurityStorageService(bumble.device, config), server
             )
+            add_L2CAPServicer_to_server(L2CAPService(bumble.device, config), server)
 
             # call hooks if any.
             for hook in _SERVICERS_HOOKS:

bumble/pandora/config.py

@@ -12,14 +12,18 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from bumble.pairing import PairingDelegate
+from __future__ import annotations
+
 from dataclasses import dataclass
-from typing import Any, Dict
+from typing import Any
+
+from bumble.pairing import PairingConfig, PairingDelegate
 
 
 @dataclass
 class Config:
     io_capability: PairingDelegate.IoCapability = PairingDelegate.NO_OUTPUT_NO_INPUT
+    identity_address_type: PairingConfig.AddressType = PairingConfig.AddressType.RANDOM
     pairing_sc_enable: bool = True
     pairing_mitm_enable: bool = True
     pairing_bonding_enable: bool = True
@@ -30,11 +34,17 @@ class Config:
         PairingDelegate.DEFAULT_KEY_DISTRIBUTION
     )
 
-    def load_from_dict(self, config: Dict[str, Any]) -> None:
+    def load_from_dict(self, config: dict[str, Any]) -> None:
         io_capability_name: str = config.get(
             'io_capability', 'no_output_no_input'
         ).upper()
         self.io_capability = getattr(PairingDelegate, io_capability_name)
+        identity_address_type_name: str = config.get(
+            'identity_address_type', 'random'
+        ).upper()
+        self.identity_address_type = getattr(
+            PairingConfig.AddressType, identity_address_type_name
+        )
         self.pairing_sc_enable = config.get('pairing_sc_enable', True)
         self.pairing_mitm_enable = config.get('pairing_mitm_enable', True)
         self.pairing_bonding_enable = config.get('pairing_bonding_enable', True)

bumble/pandora/device.py

@@ -14,6 +14,10 @@
 
 """Generic & dependency free Bumble (reference) device."""
 
+from __future__ import annotations
+
+from typing import Any
+
 from bumble import transport
 from bumble.core import (
     BT_GENERIC_AUDIO_SERVICE,
@@ -31,7 +35,9 @@ from bumble.sdp import (
     DataElement,
     ServiceAttribute,
 )
-from typing import Any, Dict, List, Optional
+
+# Default rootcanal HCI TCP address
+ROOTCANAL_HCI_ADDRESS = "localhost:6402"
 
 
 class PandoraDevice:
@@ -44,16 +50,18 @@ class PandoraDevice:
 
     # Bumble device instance & configuration.
     device: Device
-    config: Dict[str, Any]
+    config: dict[str, Any]
 
     # HCI transport name & instance.
     _hci_name: str
-    _hci: Optional[transport.Transport]  # type: ignore[name-defined]
+    _hci: transport.Transport | None  # type: ignore[name-defined]
 
-    def __init__(self, config: Dict[str, Any]) -> None:
+    def __init__(self, config: dict[str, Any]) -> None:
         self.config = config
         self.device = _make_device(config)
-        self._hci_name = config.get('transport', '')
+        self._hci_name = config.get(
+            'transport', f"tcp-client:{config.get('tcp', ROOTCANAL_HCI_ADDRESS)}"
+        )
         self._hci = None
 
     @property
@@ -66,7 +74,9 @@ class PandoraDevice:
 
         # open HCI transport & set device host.
         self._hci = await transport.open_transport(self._hci_name)
-        self.device.host = Host(controller_source=self._hci.source, controller_sink=self._hci.sink)  # type: ignore[no-untyped-call]
+        self.device.host = Host(
+            controller_source=self._hci.source, controller_sink=self._hci.sink
+        )  # type: ignore[no-untyped-call]
 
         # power-on.
         await self.device.power_on()
@@ -88,14 +98,14 @@ class PandoraDevice:
         await self.close()
         await self.open()
 
-    def info(self) -> Optional[Dict[str, str]]:
+    def info(self) -> dict[str, str] | None:
         return {
             'public_bd_address': str(self.device.public_address),
             'random_address': str(self.device.random_address),
         }
 
 
-def _make_device(config: Dict[str, Any]) -> Device:
+def _make_device(config: dict[str, Any]) -> Device:
     """Initialize an idle Bumble device instance."""
 
     # initialize bumble device.
@@ -110,7 +120,7 @@ def _make_device(config: Dict[str, Any]) -> Device:
 
 
 # TODO(b/267540823): remove when Pandora A2dp is supported
-def _make_sdp_records(rfcomm_channel: int) -> Dict[int, List[ServiceAttribute]]:
+def _make_sdp_records(rfcomm_channel: int) -> dict[int, list[ServiceAttribute]]:
     return {
         0x00010001: [
             ServiceAttribute(

bumble/pandora/host.py

@@ -12,41 +12,25 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+from __future__ import annotations
+
 import asyncio
-import bumble.device
-import grpc
-import grpc.aio
 import logging
 import struct
+from collections.abc import AsyncGenerator
+from typing import cast
 
-from . import utils
-from .config import Config
-from bumble.core import (
-    BT_BR_EDR_TRANSPORT,
-    BT_LE_TRANSPORT,
-    BT_PERIPHERAL_ROLE,
-    UUID,
-    AdvertisingData,
-    ConnectionError,
+import grpc
+import grpc.aio
+from google.protobuf import (
+    any_pb2,  # pytype: disable=pyi-error
+    empty_pb2,  # pytype: disable=pyi-error
 )
-from bumble.device import (
-    DEVICE_DEFAULT_SCAN_INTERVAL,
-    DEVICE_DEFAULT_SCAN_WINDOW,
-    Advertisement,
-    AdvertisingType,
-    Device,
-)
-from bumble.gatt import Service
-from bumble.hci import (
-    HCI_CONNECTION_ALREADY_EXISTS_ERROR,
-    HCI_PAGE_TIMEOUT_ERROR,
-    HCI_REMOTE_USER_TERMINATED_CONNECTION_ERROR,
-    Address,
-)
-from google.protobuf import any_pb2  # pytype: disable=pyi-error
-from google.protobuf import empty_pb2  # pytype: disable=pyi-error
+from pandora import host_pb2
 from pandora.host_grpc_aio import HostServicer
 from pandora.host_pb2 import (
+    DISCOVERABLE_GENERAL,
+    DISCOVERABLE_LIMITED,
     NOT_CONNECTABLE,
     NOT_DISCOVERABLE,
     PRIMARY_1M,
@@ -76,9 +60,39 @@ from pandora.host_pb2 import (
     WaitConnectionResponse,
     WaitDisconnectionRequest,
 )
-from typing import AsyncGenerator, Dict, List, Optional, Set, Tuple, cast
 
-PRIMARY_PHY_MAP: Dict[int, PrimaryPhy] = {
+import bumble.device
+import bumble.utils
+from bumble.core import (
+    UUID,
+    AdvertisingData,
+    Appearance,
+    ConnectionError,
+    PhysicalTransport,
+)
+from bumble.device import (
+    DEVICE_DEFAULT_SCAN_INTERVAL,
+    DEVICE_DEFAULT_SCAN_WINDOW,
+    Advertisement,
+    AdvertisingEventProperties,
+    AdvertisingParameters,
+    AdvertisingType,
+    Device,
+)
+from bumble.gatt import Service
+from bumble.hci import (
+    HCI_CONNECTION_ALREADY_EXISTS_ERROR,
+    HCI_PAGE_TIMEOUT_ERROR,
+    HCI_REMOTE_USER_TERMINATED_CONNECTION_ERROR,
+    Address,
+    OwnAddressType,
+    Phy,
+    Role,
+)
+from bumble.pandora import utils
+from bumble.pandora.config import Config
+
+PRIMARY_PHY_MAP: dict[int, PrimaryPhy] = {
     # Default value reported by Bumble for legacy Advertising reports.
     # FIXME(uael): `None` might be a better value, but Bumble need to change accordingly.
     0: PRIMARY_1M,
@@ -86,16 +100,35 @@ PRIMARY_PHY_MAP: Dict[int, PrimaryPhy] = {
     3: PRIMARY_CODED,
 }
 
-SECONDARY_PHY_MAP: Dict[int, SecondaryPhy] = {
+SECONDARY_PHY_MAP: dict[int, SecondaryPhy] = {
     0: SECONDARY_NONE,
     1: SECONDARY_1M,
     2: SECONDARY_2M,
     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, OwnAddressType] = {
+    host_pb2.PUBLIC: OwnAddressType.PUBLIC,
+    host_pb2.RANDOM: OwnAddressType.RANDOM,
+    host_pb2.RESOLVABLE_OR_PUBLIC: OwnAddressType.RESOLVABLE_OR_PUBLIC,
+    host_pb2.RESOLVABLE_OR_RANDOM: OwnAddressType.RESOLVABLE_OR_RANDOM,
+}
+
 
 class HostService(HostServicer):
-    waited_connections: Set[int]
+    waited_connections: set[int]
 
     def __init__(
         self, grpc_server: grpc.aio.Server, device: Device, config: Config
@@ -112,7 +145,7 @@ class HostService(HostServicer):
     async def FactoryReset(
         self, request: empty_pb2.Empty, context: grpc.ServicerContext
     ) -> empty_pb2.Empty:
-        self.log.info('FactoryReset')
+        self.log.debug('FactoryReset')
 
         # delete all bonds
         if self.device.keystore is not None:
@@ -126,7 +159,7 @@ class HostService(HostServicer):
     async def Reset(
         self, request: empty_pb2.Empty, context: grpc.ServicerContext
     ) -> empty_pb2.Empty:
-        self.log.info('Reset')
+        self.log.debug('Reset')
 
         # clear service.
         self.waited_connections.clear()
@@ -139,7 +172,7 @@ class HostService(HostServicer):
     async def ReadLocalAddress(
         self, request: empty_pb2.Empty, context: grpc.ServicerContext
     ) -> ReadLocalAddressResponse:
-        self.log.info('ReadLocalAddress')
+        self.log.debug('ReadLocalAddress')
         return ReadLocalAddressResponse(
             address=bytes(reversed(bytes(self.device.public_address)))
         )
@@ -152,11 +185,11 @@ class HostService(HostServicer):
         address = Address(
             bytes(reversed(request.address)), address_type=Address.PUBLIC_DEVICE_ADDRESS
         )
-        self.log.info(f"Connect to {address}")
+        self.log.debug(f"Connect to {address}")
 
         try:
             connection = await self.device.connect(
-                address, transport=BT_BR_EDR_TRANSPORT
+                address, transport=PhysicalTransport.BR_EDR
             )
         except ConnectionError as e:
             if e.error_code == HCI_PAGE_TIMEOUT_ERROR:
@@ -167,7 +200,7 @@ class HostService(HostServicer):
                 return ConnectResponse(connection_already_exists=empty_pb2.Empty())
             raise e
 
-        self.log.info(f"Connect to {address} done (handle={connection.handle})")
+        self.log.debug(f"Connect to {address} done (handle={connection.handle})")
 
         cookie = any_pb2.Any(value=connection.handle.to_bytes(4, 'big'))
         return ConnectResponse(connection=Connection(cookie=cookie))
@@ -186,10 +219,10 @@ class HostService(HostServicer):
         if address in (Address.NIL, Address.ANY):
             raise ValueError('Invalid address')
 
-        self.log.info(f"WaitConnection from {address}...")
+        self.log.debug(f"WaitConnection from {address}...")
 
         connection = self.device.find_connection_by_bd_addr(
-            address, transport=BT_BR_EDR_TRANSPORT
+            address, transport=PhysicalTransport.BR_EDR
         )
         if connection and id(connection) in self.waited_connections:
             # this connection was already returned: wait for a new one.
@@ -201,7 +234,7 @@ class HostService(HostServicer):
         # save connection has waited and respond.
         self.waited_connections.add(id(connection))
 
-        self.log.info(
+        self.log.debug(
             f"WaitConnection from {address} done (handle={connection.handle})"
         )
 
@@ -216,13 +249,13 @@ class HostService(HostServicer):
         if address in (Address.NIL, Address.ANY):
             raise ValueError('Invalid address')
 
-        self.log.info(f"ConnectLE to {address}...")
+        self.log.debug(f"ConnectLE to {address}...")
 
         try:
             connection = await self.device.connect(
                 address,
-                transport=BT_LE_TRANSPORT,
-                own_address_type=request.own_address_type,
+                transport=PhysicalTransport.LE,
+                own_address_type=OwnAddressType(request.own_address_type),
             )
         except ConnectionError as e:
             if e.error_code == HCI_PAGE_TIMEOUT_ERROR:
@@ -233,7 +266,7 @@ class HostService(HostServicer):
                 return ConnectLEResponse(connection_already_exists=empty_pb2.Empty())
             raise e
 
-        self.log.info(f"ConnectLE to {address} done (handle={connection.handle})")
+        self.log.debug(f"ConnectLE to {address} done (handle={connection.handle})")
 
         cookie = any_pb2.Any(value=connection.handle.to_bytes(4, 'big'))
         return ConnectLEResponse(connection=Connection(cookie=cookie))
@@ -243,12 +276,12 @@ class HostService(HostServicer):
         self, request: DisconnectRequest, context: grpc.ServicerContext
     ) -> empty_pb2.Empty:
         connection_handle = int.from_bytes(request.connection.cookie.value, 'big')
-        self.log.info(f"Disconnect: {connection_handle}")
+        self.log.debug(f"Disconnect: {connection_handle}")
 
-        self.log.info("Disconnecting...")
+        self.log.debug("Disconnecting...")
         if connection := self.device.lookup_connection(connection_handle):
             await connection.disconnect(HCI_REMOTE_USER_TERMINATED_CONNECTION_ERROR)
-        self.log.info("Disconnected")
+        self.log.debug("Disconnected")
 
         return empty_pb2.Empty()
 
@@ -257,22 +290,24 @@ class HostService(HostServicer):
         self, request: WaitDisconnectionRequest, context: grpc.ServicerContext
     ) -> empty_pb2.Empty:
         connection_handle = int.from_bytes(request.connection.cookie.value, 'big')
-        self.log.info(f"WaitDisconnection: {connection_handle}")
+        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)
 
-            connection.on('disconnection', on_disconnection)
+            connection.on(connection.EVENT_DISCONNECTION, on_disconnection)
             try:
                 await disconnection_future
-                self.log.info("Disconnected")
+                self.log.debug("Disconnected")
             finally:
-                connection.remove_listener('disconnection', on_disconnection)  # type: ignore
+                connection.remove_listener(
+                    connection.EVENT_DISCONNECTION, on_disconnection
+                )  # type: ignore
 
         return empty_pb2.Empty()
 
@@ -280,14 +315,115 @@ 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,
+        )
+
+        connections: asyncio.Queue[bumble.device.Connection] = asyncio.Queue()
+
+        if request.connectable:
+
+            def on_connection(connection: bumble.device.Connection) -> None:
+                if (
+                    connection.transport == PhysicalTransport.LE
+                    and connection.role == Role.PERIPHERAL
+                ):
+                    connections.put_nowait(connection)
+
+            self.device.on(self.device.EVENT_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 connections.get()
+
+                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:
@@ -355,48 +491,42 @@ 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
+
+        connections: asyncio.Queue[bumble.device.Connection] = asyncio.Queue()
 
         if request.connectable:
 
             def on_connection(connection: bumble.device.Connection) -> None:
                 if (
-                    connection.transport == BT_LE_TRANSPORT
-                    and connection.role == BT_PERIPHERAL_ROLE
+                    connection.transport == PhysicalTransport.LE
+                    and connection.role == Role.PERIPHERAL
                 ):
-                    pending_connection.set_result(connection)
+                    connections.put_nowait(connection)
 
-            self.device.on('connection', on_connection)
+            self.device.on(self.device.EVENT_CONNECTION, on_connection)
 
         try:
             while True:
                 if not self.device.is_advertising:
-                    self.log.info('Advertise')
+                    self.log.debug('Advertise')
                     await self.device.start_advertising(
                         target=target,
                         advertising_type=advertising_type,
-                        own_address_type=request.own_address_type,
+                        own_address_type=OwnAddressType(request.own_address_type),
                     )
 
                 if not request.connectable:
                     await asyncio.sleep(1)
                     continue
 
-                pending_connection: asyncio.Future[
-                    bumble.device.Connection
-                ] = asyncio.get_running_loop().create_future()
+                self.log.debug('Wait for LE connection...')
+                connection = await connections.get()
 
-                self.log.info('Wait for LE connection...')
-                connection = await pending_connection
-
-                self.log.info(
+                self.log.debug(
                     f"Advertise: Connected to {connection.peer_address} (handle={connection.handle})"
                 )
 
@@ -407,12 +537,14 @@ class HostService(HostServicer):
                 await asyncio.sleep(1)
         finally:
             if request.connectable:
-                self.device.remove_listener('connection', on_connection)  # type: ignore
+                self.device.remove_listener(self.device.EVENT_CONNECTION, on_connection)  # type: ignore
 
             try:
-                self.log.info('Stop advertising')
-                await self.device.abort_on('flush', self.device.stop_advertising())
-            except:
+                self.log.debug('Stop advertising')
+                await bumble.utils.cancel_on_event(
+                    self.device, 'flush', self.device.stop_advertising()
+                )
+            except Exception:
                 pass
 
     @utils.rpc
@@ -420,23 +552,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')
 
-        self.log.info('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)
+        handler = self.device.on(self.device.EVENT_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,
+            own_address_type=OwnAddressType(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
+            ),
+            scanning_phys=scanning_phys,
         )
 
         try:
@@ -468,27 +608,29 @@ class HostService(HostServicer):
                 yield sr
 
         finally:
-            self.device.remove_listener('advertisement', handler)  # type: ignore
+            self.device.remove_listener(self.device.EVENT_ADVERTISEMENT, handler)  # type: ignore
             try:
-                self.log.info('Stop scanning')
-                await self.device.abort_on('flush', self.device.stop_scanning())
-            except:
+                self.log.debug('Stop scanning')
+                await bumble.utils.cancel_on_event(
+                    self.device, 'flush', self.device.stop_scanning()
+                )
+            except Exception:
                 pass
 
     @utils.rpc
     async def Inquiry(
         self, request: empty_pb2.Empty, context: grpc.ServicerContext
     ) -> AsyncGenerator[InquiryResponse, None]:
-        self.log.info('Inquiry')
+        self.log.debug('Inquiry')
 
         inquiry_queue: asyncio.Queue[
-            Optional[Tuple[Address, int, AdvertisingData, int]]
+            tuple[Address, int, AdvertisingData, int] | None
         ] = asyncio.Queue()
         complete_handler = self.device.on(
-            'inquiry_complete', lambda: inquiry_queue.put_nowait(None)
+            self.device.EVENT_INQUIRY_COMPLETE, lambda: inquiry_queue.put_nowait(None)
         )
         result_handler = self.device.on(  # type: ignore
-            'inquiry_result',
+            self.device.EVENT_INQUIRY_RESULT,
             lambda address, class_of_device, eir_data, rssi: inquiry_queue.put_nowait(  # type: ignore
                 (address, class_of_device, eir_data, rssi)  # type: ignore
             ),
@@ -507,19 +649,25 @@ class HostService(HostServicer):
                 )
 
         finally:
-            self.device.remove_listener('inquiry_complete', complete_handler)  # type: ignore
-            self.device.remove_listener('inquiry_result', result_handler)  # type: ignore
+            self.device.remove_listener(
+                self.device.EVENT_INQUIRY_COMPLETE, complete_handler
+            )  # type: ignore
+            self.device.remove_listener(
+                self.device.EVENT_INQUIRY_RESULT, result_handler
+            )  # type: ignore
             try:
-                self.log.info('Stop inquiry')
-                await self.device.abort_on('flush', self.device.stop_discovery())
-            except:
+                self.log.debug('Stop inquiry')
+                await bumble.utils.cancel_on_event(
+                    self.device, 'flush', self.device.stop_discovery()
+                )
+            except Exception:
                 pass
 
     @utils.rpc
     async def SetDiscoverabilityMode(
         self, request: SetDiscoverabilityModeRequest, context: grpc.ServicerContext
     ) -> empty_pb2.Empty:
-        self.log.info("SetDiscoverabilityMode")
+        self.log.debug("SetDiscoverabilityMode")
         await self.device.set_discoverable(request.mode != NOT_DISCOVERABLE)
         return empty_pb2.Empty()
 
@@ -527,15 +675,15 @@ class HostService(HostServicer):
     async def SetConnectabilityMode(
         self, request: SetConnectabilityModeRequest, context: grpc.ServicerContext
     ) -> empty_pb2.Empty:
-        self.log.info("SetConnectabilityMode")
+        self.log.debug("SetConnectabilityMode")
         await self.device.set_connectable(request.mode != NOT_CONNECTABLE)
         return empty_pb2.Empty()
 
     def unpack_data_types(self, dt: DataTypes) -> AdvertisingData:
-        ad_structures: List[Tuple[int, bytes]] = []
+        ad_structures: list[tuple[int, bytes]] = []
 
-        uuids: List[str]
-        datas: Dict[str, bytes]
+        uuids: list[str]
+        datas: dict[str, bytes]
 
         def uuid128_from_str(uuid: str) -> bytes:
             """Decode a 128-bit uuid encoded as XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
@@ -649,9 +797,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
+                                ),
                             ),
                         ]
                     ),
@@ -733,54 +883,64 @@ 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:
         dt = DataTypes()
-        uuids: List[UUID]
+        uuids: list[UUID]
         s: str
         i: int
-        ij: Tuple[int, int]
-        uuid_data: Tuple[UUID, bytes]
+        ij: tuple[int, int]
+        uuid_data: tuple[UUID, bytes]
         data: bytes
 
         if uuids := cast(
-            List[UUID],
+            list[UUID],
             ad.get(AdvertisingData.INCOMPLETE_LIST_OF_16_BIT_SERVICE_CLASS_UUIDS),
         ):
             dt.incomplete_service_class_uuids16.extend(
                 list(map(lambda x: x.to_hex_str('-'), uuids))
             )
         if uuids := cast(
-            List[UUID],
+            list[UUID],
             ad.get(AdvertisingData.COMPLETE_LIST_OF_16_BIT_SERVICE_CLASS_UUIDS),
         ):
             dt.complete_service_class_uuids16.extend(
                 list(map(lambda x: x.to_hex_str('-'), uuids))
             )
         if uuids := cast(
-            List[UUID],
+            list[UUID],
             ad.get(AdvertisingData.INCOMPLETE_LIST_OF_32_BIT_SERVICE_CLASS_UUIDS),
         ):
             dt.incomplete_service_class_uuids32.extend(
                 list(map(lambda x: x.to_hex_str('-'), uuids))
             )
         if uuids := cast(
-            List[UUID],
+            list[UUID],
             ad.get(AdvertisingData.COMPLETE_LIST_OF_32_BIT_SERVICE_CLASS_UUIDS),
         ):
             dt.complete_service_class_uuids32.extend(
                 list(map(lambda x: x.to_hex_str('-'), uuids))
             )
         if uuids := cast(
-            List[UUID],
+            list[UUID],
             ad.get(AdvertisingData.INCOMPLETE_LIST_OF_128_BIT_SERVICE_CLASS_UUIDS),
         ):
             dt.incomplete_service_class_uuids128.extend(
                 list(map(lambda x: x.to_hex_str('-'), uuids))
             )
         if uuids := cast(
-            List[UUID],
+            list[UUID],
             ad.get(AdvertisingData.COMPLETE_LIST_OF_128_BIT_SERVICE_CLASS_UUIDS),
         ):
             dt.complete_service_class_uuids128.extend(
@@ -795,42 +955,42 @@ class HostService(HostServicer):
         if i := cast(int, ad.get(AdvertisingData.CLASS_OF_DEVICE)):
             dt.class_of_device = i
         if ij := cast(
-            Tuple[int, int],
+            tuple[int, int],
             ad.get(AdvertisingData.PERIPHERAL_CONNECTION_INTERVAL_RANGE),
         ):
             dt.peripheral_connection_interval_min = ij[0]
             dt.peripheral_connection_interval_max = ij[1]
         if uuids := cast(
-            List[UUID],
+            list[UUID],
             ad.get(AdvertisingData.LIST_OF_16_BIT_SERVICE_SOLICITATION_UUIDS),
         ):
             dt.service_solicitation_uuids16.extend(
                 list(map(lambda x: x.to_hex_str('-'), uuids))
             )
         if uuids := cast(
-            List[UUID],
+            list[UUID],
             ad.get(AdvertisingData.LIST_OF_32_BIT_SERVICE_SOLICITATION_UUIDS),
         ):
             dt.service_solicitation_uuids32.extend(
                 list(map(lambda x: x.to_hex_str('-'), uuids))
             )
         if uuids := cast(
-            List[UUID],
+            list[UUID],
             ad.get(AdvertisingData.LIST_OF_128_BIT_SERVICE_SOLICITATION_UUIDS),
         ):
             dt.service_solicitation_uuids128.extend(
                 list(map(lambda x: x.to_hex_str('-'), uuids))
             )
         if uuid_data := cast(
-            Tuple[UUID, bytes], ad.get(AdvertisingData.SERVICE_DATA_16_BIT_UUID)
+            tuple[UUID, bytes], ad.get(AdvertisingData.SERVICE_DATA_16_BIT_UUID)
         ):
             dt.service_data_uuid16[uuid_data[0].to_hex_str('-')] = uuid_data[1]
         if uuid_data := cast(
-            Tuple[UUID, bytes], ad.get(AdvertisingData.SERVICE_DATA_32_BIT_UUID)
+            tuple[UUID, bytes], ad.get(AdvertisingData.SERVICE_DATA_32_BIT_UUID)
         ):
             dt.service_data_uuid32[uuid_data[0].to_hex_str('-')] = uuid_data[1]
         if uuid_data := cast(
-            Tuple[UUID, bytes], ad.get(AdvertisingData.SERVICE_DATA_128_BIT_UUID)
+            tuple[UUID, bytes], ad.get(AdvertisingData.SERVICE_DATA_128_BIT_UUID)
         ):
             dt.service_data_uuid128[uuid_data[0].to_hex_str('-')] = uuid_data[1]
         if data := cast(bytes, ad.get(AdvertisingData.PUBLIC_TARGET_ADDRESS, raw=True)):
@@ -841,8 +1001,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/l2cap.py

@@ -0,0 +1,310 @@
+# 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.
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+from asyncio import Future
+from asyncio import Queue as AsyncQueue
+from collections.abc import AsyncGenerator
+from dataclasses import dataclass
+
+import grpc
+from google.protobuf import any_pb2, empty_pb2  # pytype: disable=pyi-error
+from pandora.l2cap_grpc_aio import L2CAPServicer  # pytype: disable=pyi-error
+from pandora.l2cap_pb2 import (
+    COMMAND_NOT_UNDERSTOOD,
+    INVALID_CID_IN_REQUEST,
+    ConnectRequest,
+    ConnectResponse,
+    CreditBasedChannelRequest,
+    DisconnectRequest,
+    DisconnectResponse,
+    ReceiveRequest,
+    ReceiveResponse,
+    SendRequest,
+    SendResponse,
+    WaitConnectionRequest,
+    WaitConnectionResponse,
+    WaitDisconnectionRequest,
+    WaitDisconnectionResponse,
+)
+from pandora.l2cap_pb2 import Channel as PandoraChannel  # pytype: disable=pyi-error
+
+from bumble.core import InvalidArgumentError, OutOfResourcesError
+from bumble.device import Device
+from bumble.l2cap import (
+    ClassicChannel,
+    ClassicChannelServer,
+    ClassicChannelSpec,
+    LeCreditBasedChannel,
+    LeCreditBasedChannelServer,
+    LeCreditBasedChannelSpec,
+)
+from bumble.pandora import utils
+from bumble.pandora.config import Config
+
+L2capChannel = ClassicChannel | LeCreditBasedChannel
+
+
+@dataclass
+class ChannelContext:
+    close_future: Future
+    sdu_queue: AsyncQueue
+
+
+class L2CAPService(L2CAPServicer):
+    def __init__(self, device: Device, config: Config) -> None:
+        self.log = utils.BumbleServerLoggerAdapter(
+            logging.getLogger(), {'service_name': 'L2CAP', 'device': device}
+        )
+        self.device = device
+        self.config = config
+        self.channels: dict[bytes, ChannelContext] = {}
+
+    def register_event(self, l2cap_channel: L2capChannel) -> ChannelContext:
+        close_future = asyncio.get_running_loop().create_future()
+        sdu_queue: AsyncQueue = AsyncQueue()
+
+        def on_channel_sdu(sdu):
+            sdu_queue.put_nowait(sdu)
+
+        def on_close():
+            close_future.set_result(None)
+
+        l2cap_channel.sink = on_channel_sdu
+        l2cap_channel.on(l2cap_channel.EVENT_CLOSE, on_close)
+
+        return ChannelContext(close_future, sdu_queue)
+
+    @utils.rpc
+    async def WaitConnection(
+        self, request: WaitConnectionRequest, context: grpc.ServicerContext
+    ) -> WaitConnectionResponse:
+        self.log.debug('WaitConnection')
+        if not request.connection:
+            raise ValueError('A valid connection field must be set')
+
+        # find connection on device based on connection cookie value
+        connection_handle = int.from_bytes(request.connection.cookie.value, 'big')
+        connection = self.device.lookup_connection(connection_handle)
+
+        if not connection:
+            raise ValueError('The connection specified is invalid.')
+
+        oneof = request.WhichOneof('type')
+        self.log.debug(f'WaitConnection channel request type: {oneof}.')
+        channel_type = getattr(request, oneof)
+        spec: ClassicChannelSpec | LeCreditBasedChannelSpec | None = None
+        l2cap_server: ClassicChannelServer | LeCreditBasedChannelServer | None = None
+        if isinstance(channel_type, CreditBasedChannelRequest):
+            spec = LeCreditBasedChannelSpec(
+                psm=channel_type.spsm,
+                max_credits=channel_type.initial_credit,
+                mtu=channel_type.mtu,
+                mps=channel_type.mps,
+            )
+            if channel_type.spsm in self.device.l2cap_channel_manager.le_coc_servers:
+                l2cap_server = self.device.l2cap_channel_manager.le_coc_servers[
+                    channel_type.spsm
+                ]
+        else:
+            spec = ClassicChannelSpec(
+                psm=channel_type.psm,
+                mtu=channel_type.mtu,
+            )
+            if channel_type.psm in self.device.l2cap_channel_manager.servers:
+                l2cap_server = self.device.l2cap_channel_manager.servers[
+                    channel_type.psm
+                ]
+
+        self.log.info(f'Listening for L2CAP connection on PSM {spec.psm}')
+        channel_future: Future[PandoraChannel] = (
+            asyncio.get_running_loop().create_future()
+        )
+
+        def on_l2cap_channel(l2cap_channel: L2capChannel):
+            try:
+                channel_context = self.register_event(l2cap_channel)
+                pandora_channel: PandoraChannel = self.craft_pandora_channel(
+                    connection_handle, l2cap_channel
+                )
+                self.channels[pandora_channel.cookie.value] = channel_context
+                channel_future.set_result(pandora_channel)
+            except Exception as e:
+                self.log.error(f'Failed to set channel future: {e}')
+
+        if l2cap_server is None:
+            l2cap_server = self.device.create_l2cap_server(
+                spec=spec, handler=on_l2cap_channel
+            )
+        else:
+            l2cap_server.on(l2cap_server.EVENT_CONNECTION, on_l2cap_channel)
+
+        try:
+            self.log.debug('Waiting for a channel connection.')
+            pandora_channel: PandoraChannel = await channel_future
+
+            return WaitConnectionResponse(channel=pandora_channel)
+        except Exception as e:
+            self.log.warning(f'Exception: {e}')
+
+        return WaitConnectionResponse(error=COMMAND_NOT_UNDERSTOOD)
+
+    @utils.rpc
+    async def WaitDisconnection(
+        self, request: WaitDisconnectionRequest, context: grpc.ServicerContext
+    ) -> WaitDisconnectionResponse:
+        try:
+            self.log.debug('WaitDisconnection')
+
+            await self.lookup_context(request.channel).close_future
+            self.log.debug("return WaitDisconnectionResponse")
+            return WaitDisconnectionResponse(success=empty_pb2.Empty())
+        except KeyError as e:
+            self.log.warning(f'WaitDisconnection: Unable to find the channel: {e}')
+            return WaitDisconnectionResponse(error=INVALID_CID_IN_REQUEST)
+        except Exception as e:
+            self.log.exception(f'WaitDisonnection failed: {e}')
+            return WaitDisconnectionResponse(error=COMMAND_NOT_UNDERSTOOD)
+
+    @utils.rpc
+    async def Receive(
+        self, request: ReceiveRequest, context: grpc.ServicerContext
+    ) -> AsyncGenerator[ReceiveResponse, None]:
+        self.log.debug('Receive')
+        oneof = request.WhichOneof('source')
+        self.log.debug(f'Source: {oneof}.')
+        pandora_channel = getattr(request, oneof)
+
+        sdu_queue = self.lookup_context(pandora_channel).sdu_queue
+
+        while sdu := await sdu_queue.get():
+            self.log.debug(f'Receive: Received {len(sdu)} bytes -> {sdu.decode()}')
+            response = ReceiveResponse(data=sdu)
+            yield response
+
+    @utils.rpc
+    async def Connect(
+        self, request: ConnectRequest, context: grpc.ServicerContext
+    ) -> ConnectResponse:
+        self.log.debug('Connect')
+
+        if not request.connection:
+            raise ValueError('A valid connection field must be set')
+
+        # find connection on device based on connection cookie value
+        connection_handle = int.from_bytes(request.connection.cookie.value, 'big')
+        connection = self.device.lookup_connection(connection_handle)
+
+        if not connection:
+            raise ValueError('The connection specified is invalid.')
+
+        oneof = request.WhichOneof('type')
+        self.log.debug(f'Channel request type: {oneof}.')
+        channel_type = getattr(request, oneof)
+        spec: ClassicChannelSpec | LeCreditBasedChannelSpec | None = None
+        if isinstance(channel_type, CreditBasedChannelRequest):
+            spec = LeCreditBasedChannelSpec(
+                psm=channel_type.spsm,
+                max_credits=channel_type.initial_credit,
+                mtu=channel_type.mtu,
+                mps=channel_type.mps,
+            )
+        else:
+            spec = ClassicChannelSpec(
+                psm=channel_type.psm,
+                mtu=channel_type.mtu,
+            )
+
+        try:
+            self.log.info(f'Opening L2CAP channel on PSM = {spec.psm}')
+            l2cap_channel = await connection.create_l2cap_channel(spec=spec)
+            channel_context = self.register_event(l2cap_channel)
+            pandora_channel = self.craft_pandora_channel(
+                connection_handle, l2cap_channel
+            )
+            self.channels[pandora_channel.cookie.value] = channel_context
+
+            return ConnectResponse(channel=pandora_channel)
+
+        except OutOfResourcesError as e:
+            self.log.error(e)
+            return ConnectResponse(error=INVALID_CID_IN_REQUEST)
+        except InvalidArgumentError as e:
+            self.log.error(e)
+            return ConnectResponse(error=COMMAND_NOT_UNDERSTOOD)
+
+    @utils.rpc
+    async def Disconnect(
+        self, request: DisconnectRequest, context: grpc.ServicerContext
+    ) -> DisconnectResponse:
+        try:
+            self.log.debug('Disconnect')
+            l2cap_channel = self.lookup_channel(request.channel)
+            if not l2cap_channel:
+                self.log.warning('Disconnect: Unable to find the channel')
+                return DisconnectResponse(error=INVALID_CID_IN_REQUEST)
+
+            await l2cap_channel.disconnect()
+            return DisconnectResponse(success=empty_pb2.Empty())
+        except Exception as e:
+            self.log.exception(f'Disonnect failed: {e}')
+            return DisconnectResponse(error=COMMAND_NOT_UNDERSTOOD)
+
+    @utils.rpc
+    async def Send(
+        self, request: SendRequest, context: grpc.ServicerContext
+    ) -> SendResponse:
+        self.log.debug('Send')
+        try:
+            oneof = request.WhichOneof('sink')
+            self.log.debug(f'Sink: {oneof}.')
+            pandora_channel = getattr(request, oneof)
+
+            l2cap_channel = self.lookup_channel(pandora_channel)
+            if not l2cap_channel:
+                return SendResponse(error=COMMAND_NOT_UNDERSTOOD)
+            if isinstance(l2cap_channel, ClassicChannel):
+                l2cap_channel.write(request.data)
+            else:
+                l2cap_channel.write(request.data)
+            return SendResponse(success=empty_pb2.Empty())
+        except Exception as e:
+            self.log.exception(f'Disonnect failed: {e}')
+            return SendResponse(error=COMMAND_NOT_UNDERSTOOD)
+
+    def craft_pandora_channel(
+        self,
+        connection_handle: int,
+        l2cap_channel: L2capChannel,
+    ) -> PandoraChannel:
+        parameters = {
+            "connection_handle": connection_handle,
+            "source_cid": l2cap_channel.source_cid,
+        }
+        cookie = any_pb2.Any()
+        cookie.value = json.dumps(parameters).encode()
+        return PandoraChannel(cookie=cookie)
+
+    def lookup_channel(self, pandora_channel: PandoraChannel) -> L2capChannel:
+        (connection_handle, source_cid) = json.loads(
+            pandora_channel.cookie.value
+        ).values()
+
+        return self.device.l2cap_channel_manager.channels[connection_handle][source_cid]
+
+    def lookup_context(self, pandora_channel: PandoraChannel) -> ChannelContext:
+        return self.channels[pandora_channel.cookie.value]

bumble/pandora/security.py

@@ -12,26 +12,20 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-import asyncio
-import grpc
-import logging
+from __future__ import annotations
 
-from . import utils
-from .config import Config
-from bumble import hci
-from bumble.core import (
-    BT_BR_EDR_TRANSPORT,
-    BT_LE_TRANSPORT,
-    BT_PERIPHERAL_ROLE,
-    ProtocolError,
+import asyncio
+import contextlib
+import logging
+from collections.abc import AsyncGenerator, AsyncIterator, Awaitable, Callable
+from typing import Any
+
+import grpc
+from google.protobuf import (
+    any_pb2,  # pytype: disable=pyi-error
+    empty_pb2,  # pytype: disable=pyi-error
+    wrappers_pb2,  # pytype: disable=pyi-error
 )
-from bumble.device import Connection as BumbleConnection, Device
-from bumble.hci import HCI_Error
-from bumble.pairing import PairingConfig, PairingDelegate as BasePairingDelegate
-from contextlib import suppress
-from google.protobuf import any_pb2  # pytype: disable=pyi-error
-from google.protobuf import empty_pb2  # pytype: disable=pyi-error
-from google.protobuf import wrappers_pb2  # pytype: disable=pyi-error
 from pandora.host_pb2 import Connection
 from pandora.security_grpc_aio import SecurityServicer, SecurityStorageServicer
 from pandora.security_pb2 import (
@@ -55,14 +49,24 @@ from pandora.security_pb2 import (
     WaitSecurityRequest,
     WaitSecurityResponse,
 )
-from typing import Any, AsyncGenerator, AsyncIterator, Callable, Dict, Optional, Union
+
+import bumble.utils
+from bumble import hci
+from bumble.core import InvalidArgumentError, PhysicalTransport, ProtocolError
+from bumble.device import Connection as BumbleConnection
+from bumble.device import Device
+from bumble.hci import HCI_Error, Role
+from bumble.pairing import PairingConfig
+from bumble.pairing import PairingDelegate as BasePairingDelegate
+from bumble.pandora import utils
+from bumble.pandora.config import Config
 
 
 class PairingDelegate(BasePairingDelegate):
     def __init__(
         self,
         connection: BumbleConnection,
-        service: "SecurityService",
+        service: SecurityService,
         io_capability: BasePairingDelegate.IoCapability = BasePairingDelegate.NO_OUTPUT_NO_INPUT,
         local_initiator_key_distribution: BasePairingDelegate.KeyDistribution = BasePairingDelegate.DEFAULT_KEY_DISTRIBUTION,
         local_responder_key_distribution: BasePairingDelegate.KeyDistribution = BasePairingDelegate.DEFAULT_KEY_DISTRIBUTION,
@@ -93,13 +97,13 @@ class PairingDelegate(BasePairingDelegate):
         else:
             # In BR/EDR, connection may not be complete,
             # use address instead
-            assert self.connection.transport == BT_BR_EDR_TRANSPORT
+            assert self.connection.transport == PhysicalTransport.BR_EDR
             ev.address = bytes(reversed(bytes(self.connection.peer_address)))
 
         return ev
 
     async def confirm(self, auto: bool = False) -> bool:
-        self.log.info(
+        self.log.debug(
             f"Pairing event: `just_works` (io_capability: {self.io_capability})"
         )
 
@@ -108,13 +112,13 @@ 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
 
     async def compare_numbers(self, number: int, digits: int = 6) -> bool:
-        self.log.info(
+        self.log.debug(
             f"Pairing event: `numeric_comparison` (io_capability: {self.io_capability})"
         )
 
@@ -123,13 +127,13 @@ 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
 
-    async def get_number(self) -> Optional[int]:
-        self.log.info(
+    async def get_number(self) -> int | None:
+        self.log.debug(
             f"Pairing event: `passkey_entry_request` (io_capability: {self.io_capability})"
         )
 
@@ -138,15 +142,15 @@ 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
         assert answer.answer_variant() == 'passkey'
         return answer.passkey
 
-    async def get_string(self, max_length: int) -> Optional[str]:
-        self.log.info(
+    async def get_string(self, max_length: int) -> str | None:
+        self.log.debug(
             f"Pairing event: `pin_code_request` (io_capability: {self.io_capability})"
         )
 
@@ -155,7 +159,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
@@ -172,12 +176,12 @@ class PairingDelegate(BasePairingDelegate):
 
     async def display_number(self, number: int, digits: int = 6) -> None:
         if (
-            self.connection.transport == BT_BR_EDR_TRANSPORT
+            self.connection.transport == PhysicalTransport.BR_EDR
             and self.io_capability == BasePairingDelegate.DISPLAY_OUTPUT_ONLY
         ):
             return
 
-        self.log.info(
+        self.log.debug(
             f"Pairing event: `passkey_entry_notification` (io_capability: {self.io_capability})"
         )
 
@@ -188,42 +192,13 @@ class PairingDelegate(BasePairingDelegate):
         self.service.event_queue.put_nowait(event)
 
 
-BR_LEVEL_REACHED: Dict[SecurityLevel, Callable[[BumbleConnection], bool]] = {
-    LEVEL0: lambda connection: True,
-    LEVEL1: lambda connection: connection.encryption == 0 or connection.authenticated,
-    LEVEL2: lambda connection: connection.encryption != 0 and connection.authenticated,
-    LEVEL3: lambda connection: connection.encryption != 0
-    and connection.authenticated
-    and connection.link_key_type
-    in (
-        hci.HCI_AUTHENTICATED_COMBINATION_KEY_GENERATED_FROM_P_192_TYPE,
-        hci.HCI_AUTHENTICATED_COMBINATION_KEY_GENERATED_FROM_P_256_TYPE,
-    ),
-    LEVEL4: lambda connection: connection.encryption
-    == hci.HCI_Encryption_Change_Event.AES_CCM
-    and connection.authenticated
-    and connection.link_key_type
-    == hci.HCI_AUTHENTICATED_COMBINATION_KEY_GENERATED_FROM_P_256_TYPE,
-}
-
-LE_LEVEL_REACHED: Dict[LESecurityLevel, Callable[[BumbleConnection], bool]] = {
-    LE_LEVEL1: lambda connection: True,
-    LE_LEVEL2: lambda connection: connection.encryption != 0,
-    LE_LEVEL3: lambda connection: connection.encryption != 0
-    and connection.authenticated,
-    LE_LEVEL4: lambda connection: connection.encryption != 0
-    and connection.authenticated
-    and connection.sc,
-}
-
-
 class SecurityService(SecurityServicer):
     def __init__(self, device: Device, config: Config) -> None:
         self.log = utils.BumbleServerLoggerAdapter(
             logging.getLogger(), {'service_name': 'Security', 'device': device}
         )
-        self.event_queue: Optional[asyncio.Queue[PairingEvent]] = None
-        self.event_answer: Optional[AsyncIterator[PairingEventAnswer]] = None
+        self.event_queue: asyncio.Queue[PairingEvent] | None = None
+        self.event_answer: AsyncIterator[PairingEventAnswer] | None = None
         self.device = device
         self.config = config
 
@@ -232,6 +207,11 @@ class SecurityService(SecurityServicer):
                 sc=config.pairing_sc_enable,
                 mitm=config.pairing_mitm_enable,
                 bonding=config.pairing_bonding_enable,
+                identity_address_type=(
+                    PairingConfig.AddressType.PUBLIC
+                    if connection.self_address.is_public
+                    else config.identity_address_type
+                ),
                 delegate=PairingDelegate(
                     connection,
                     self,
@@ -243,11 +223,64 @@ class SecurityService(SecurityServicer):
 
         self.device.pairing_config_factory = pairing_config_factory
 
+    async def _classic_level_reached(
+        self, level: SecurityLevel, connection: BumbleConnection
+    ) -> bool:
+        if level == LEVEL0:
+            return True
+        if level == LEVEL1:
+            return connection.encryption == 0 or connection.authenticated
+        if level == LEVEL2:
+            return connection.encryption != 0 and connection.authenticated
+
+        link_key_type: int | None = None
+        if (keystore := connection.device.keystore) and (
+            keys := await keystore.get(str(connection.peer_address))
+        ):
+            link_key_type = keys.link_key_type
+        self.log.debug("link_key_type: %d", link_key_type)
+
+        if level == LEVEL3:
+            return (
+                connection.encryption != 0
+                and connection.authenticated
+                and link_key_type
+                in (
+                    hci.LinkKeyType.AUTHENTICATED_COMBINATION_KEY_GENERATED_FROM_P_192,
+                    hci.LinkKeyType.AUTHENTICATED_COMBINATION_KEY_GENERATED_FROM_P_256,
+                )
+            )
+        if level == LEVEL4:
+            return (
+                connection.encryption == hci.HCI_Encryption_Change_Event.Enabled.AES_CCM
+                and connection.authenticated
+                and link_key_type
+                == hci.LinkKeyType.AUTHENTICATED_COMBINATION_KEY_GENERATED_FROM_P_256
+            )
+        raise InvalidArgumentError(f"Unexpected level {level}")
+
+    def _le_level_reached(
+        self, level: LESecurityLevel, connection: BumbleConnection
+    ) -> bool:
+        if level == LE_LEVEL1:
+            return True
+        if level == LE_LEVEL2:
+            return connection.encryption != 0
+        if level == LE_LEVEL3:
+            return connection.encryption != 0 and connection.authenticated
+        if level == LE_LEVEL4:
+            return (
+                connection.encryption != 0
+                and connection.authenticated
+                and connection.sc
+            )
+        raise InvalidArgumentError(f"Unexpected level {level}")
+
     @utils.rpc
     async def OnPairing(
         self, request: AsyncIterator[PairingEventAnswer], context: grpc.ServicerContext
     ) -> AsyncGenerator[PairingEvent, None]:
-        self.log.info('OnPairing')
+        self.log.debug('OnPairing')
 
         if self.event_queue is not None:
             raise RuntimeError('already streaming pairing events')
@@ -273,43 +306,55 @@ class SecurityService(SecurityServicer):
         self, request: SecureRequest, context: grpc.ServicerContext
     ) -> SecureResponse:
         connection_handle = int.from_bytes(request.connection.cookie.value, 'big')
-        self.log.info(f"Secure: {connection_handle}")
+        self.log.debug(f"Secure: {connection_handle}")
 
         connection = self.device.lookup_connection(connection_handle)
         assert connection
 
         oneof = request.WhichOneof('level')
         level = getattr(request, oneof)
-        assert {BT_BR_EDR_TRANSPORT: 'classic', BT_LE_TRANSPORT: 'le'}[
+        assert {PhysicalTransport.BR_EDR: 'classic', PhysicalTransport.LE: 'le'}[
             connection.transport
         ] == oneof
 
         # security level already reached
-        if self.reached_security_level(connection, level):
+        if await self.reached_security_level(connection, level):
             return SecureResponse(success=empty_pb2.Empty())
 
         # trigger pairing if needed
         if self.need_pairing(connection, level):
             try:
-                self.log.info('Pair...')
+                self.log.debug('Pair...')
 
-                if (
-                    connection.transport == BT_LE_TRANSPORT
-                    and connection.role == BT_PERIPHERAL_ROLE
-                ):
-                    wait_for_security: asyncio.Future[
-                        bool
-                    ] = asyncio.get_running_loop().create_future()
-                    connection.on("pairing", lambda *_: wait_for_security.set_result(True))  # type: ignore
-                    connection.on("pairing_failure", wait_for_security.set_exception)
+                security_result = asyncio.get_running_loop().create_future()
 
-                    connection.request_pairing()
+                with contextlib.closing(bumble.utils.EventWatcher()) as watcher:
 
-                    await wait_for_security
-                else:
-                    await connection.pair()
+                    @watcher.on(connection, connection.EVENT_PAIRING)
+                    def on_pairing(*_: Any) -> None:
+                        security_result.set_result('success')
 
-                self.log.info('Paired')
+                    @watcher.on(connection, connection.EVENT_PAIRING_FAILURE)
+                    def on_pairing_failure(*_: Any) -> None:
+                        security_result.set_result('pairing_failure')
+
+                    @watcher.on(connection, connection.EVENT_DISCONNECTION)
+                    def on_disconnection(*_: Any) -> None:
+                        security_result.set_result('connection_died')
+
+                    if (
+                        connection.transport == PhysicalTransport.LE
+                        and connection.role == Role.PERIPHERAL
+                    ):
+                        connection.request_pairing()
+                    else:
+                        await connection.pair()
+
+                    result = await security_result
+
+                self.log.debug(f'Pairing session complete, status={result}')
+                if result != 'success':
+                    return SecureResponse(**{result: empty_pb2.Empty()})
             except asyncio.CancelledError:
                 self.log.warning("Connection died during encryption")
                 return SecureResponse(connection_died=empty_pb2.Empty())
@@ -320,9 +365,9 @@ class SecurityService(SecurityServicer):
         # trigger authentication if needed
         if self.need_authentication(connection, level):
             try:
-                self.log.info('Authenticate...')
+                self.log.debug('Authenticate...')
                 await connection.authenticate()
-                self.log.info('Authenticated')
+                self.log.debug('Authenticated')
             except asyncio.CancelledError:
                 self.log.warning("Connection died during authentication")
                 return SecureResponse(connection_died=empty_pb2.Empty())
@@ -333,9 +378,9 @@ class SecurityService(SecurityServicer):
         # trigger encryption if needed
         if self.need_encryption(connection, level):
             try:
-                self.log.info('Encrypt...')
+                self.log.debug('Encrypt...')
                 await connection.encrypt()
-                self.log.info('Encrypted')
+                self.log.debug('Encrypted')
             except asyncio.CancelledError:
                 self.log.warning("Connection died during encryption")
                 return SecureResponse(connection_died=empty_pb2.Empty())
@@ -344,7 +389,7 @@ class SecurityService(SecurityServicer):
                 return SecureResponse(encryption_failure=empty_pb2.Empty())
 
         # security level has been reached ?
-        if self.reached_security_level(connection, level):
+        if await self.reached_security_level(connection, level):
             return SecureResponse(success=empty_pb2.Empty())
         return SecureResponse(not_reached=empty_pb2.Empty())
 
@@ -353,30 +398,28 @@ class SecurityService(SecurityServicer):
         self, request: WaitSecurityRequest, context: grpc.ServicerContext
     ) -> WaitSecurityResponse:
         connection_handle = int.from_bytes(request.connection.cookie.value, 'big')
-        self.log.info(f"WaitSecurity: {connection_handle}")
+        self.log.debug(f"WaitSecurity: {connection_handle}")
 
         connection = self.device.lookup_connection(connection_handle)
         assert connection
 
         assert request.level
         level = request.level
-        assert {BT_BR_EDR_TRANSPORT: 'classic', BT_LE_TRANSPORT: 'le'}[
+        assert {PhysicalTransport.BR_EDR: 'classic', PhysicalTransport.LE: 'le'}[
             connection.transport
         ] == request.level_variant()
 
-        wait_for_security: asyncio.Future[
-            str
-        ] = asyncio.get_running_loop().create_future()
-        authenticate_task: Optional[asyncio.Future[None]] = None
+        wait_for_security: asyncio.Future[str] = (
+            asyncio.get_running_loop().create_future()
+        )
+        authenticate_task: asyncio.Future[None] | None = None
+        pair_task: asyncio.Future[None] | None = None
 
         async def authenticate() -> None:
-            assert connection
             if (encryption := connection.encryption) != 0:
                 self.log.debug('Disable encryption...')
-                try:
+                with contextlib.suppress(Exception):
                     await connection.encrypt(enable=False)
-                except:
-                    pass
                 self.log.debug('Disable encryption: done')
 
             self.log.debug('Authenticate...')
@@ -390,31 +433,33 @@ class SecurityService(SecurityServicer):
 
         def set_failure(name: str) -> Callable[..., None]:
             def wrapper(*args: Any) -> None:
-                self.log.info(f'Wait for security: error `{name}`: {args}')
+                self.log.debug(f'Wait for security: error `{name}`: {args}')
                 wait_for_security.set_result(name)
 
             return wrapper
 
-        def try_set_success(*_: Any) -> None:
-            assert connection
-            if self.reached_security_level(connection, level):
-                self.log.info('Wait for security: done')
+        async def try_set_success(*_: Any) -> None:
+            if await self.reached_security_level(connection, level):
+                self.log.debug('Wait for security: done')
                 wait_for_security.set_result('success')
 
-        def on_encryption_change(*_: Any) -> None:
-            assert connection
-            if self.reached_security_level(connection, level):
-                self.log.info('Wait for security: done')
+        async def on_encryption_change(*_: Any) -> None:
+            if await self.reached_security_level(connection, level):
+                self.log.debug('Wait for security: done')
                 wait_for_security.set_result('success')
             elif (
-                connection.transport == BT_BR_EDR_TRANSPORT
+                connection.transport == PhysicalTransport.BR_EDR
                 and self.need_authentication(connection, level)
             ):
                 nonlocal authenticate_task
                 if authenticate_task is None:
                     authenticate_task = asyncio.create_task(authenticate())
 
-        listeners: Dict[str, Callable[..., None]] = {
+        def pair(*_: Any) -> None:
+            if self.need_pairing(connection, level):
+                bumble.utils.AsyncRunner.spawn(connection.pair())
+
+        listeners: dict[str, Callable[..., None | Awaitable[None]]] = {
             'disconnection': set_failure('connection_died'),
             'pairing_failure': set_failure('pairing_failure'),
             'connection_authentication_failure': set_failure('authentication_failure'),
@@ -422,37 +467,42 @@ class SecurityService(SecurityServicer):
             'pairing': try_set_success,
             'connection_authentication': try_set_success,
             'connection_encryption_change': on_encryption_change,
+            'classic_pairing': try_set_success,
+            'classic_pairing_failure': set_failure('pairing_failure'),
+            'security_request': pair,
         }
 
-        # register event handlers
-        for event, listener in listeners.items():
-            connection.on(event, listener)
+        with contextlib.closing(bumble.utils.EventWatcher()) as watcher:
+            # register event handlers
+            for event, listener in listeners.items():
+                watcher.on(connection, event, listener)
 
-        # security level already reached
-        if self.reached_security_level(connection, level):
-            return WaitSecurityResponse(success=empty_pb2.Empty())
+            # security level already reached
+            if await self.reached_security_level(connection, level):
+                return WaitSecurityResponse(success=empty_pb2.Empty())
 
-        self.log.info('Wait for security...')
-        kwargs = {}
-        kwargs[await wait_for_security] = empty_pb2.Empty()
-
-        # remove event handlers
-        for event, listener in listeners.items():
-            connection.remove_listener(event, listener)  # type: ignore
+            self.log.debug('Wait for security...')
+            kwargs = {}
+            kwargs[await wait_for_security] = empty_pb2.Empty()
 
         # wait for `authenticate` to finish if any
         if authenticate_task is not None:
-            self.log.info('Wait for authentication...')
-            try:
+            self.log.debug('Wait for authentication...')
+            with contextlib.suppress(Exception):
                 await authenticate_task  # type: ignore
-            except:
-                pass
-            self.log.info('Authenticated')
+            self.log.debug('Authenticated')
+
+        # wait for `pair` to finish if any
+        if pair_task is not None:
+            self.log.debug('Wait for authentication...')
+            with contextlib.suppress(Exception):
+                await pair_task  # type: ignore
+            self.log.debug('paired')
 
         return WaitSecurityResponse(**kwargs)
 
-    def reached_security_level(
-        self, connection: BumbleConnection, level: Union[SecurityLevel, LESecurityLevel]
+    async def reached_security_level(
+        self, connection: BumbleConnection, level: SecurityLevel | LESecurityLevel
     ) -> bool:
         self.log.debug(
             str(
@@ -461,23 +511,22 @@ class SecurityService(SecurityServicer):
                     'encryption': connection.encryption,
                     'authenticated': connection.authenticated,
                     'sc': connection.sc,
-                    'link_key_type': connection.link_key_type,
                 }
             )
         )
 
         if isinstance(level, LESecurityLevel):
-            return LE_LEVEL_REACHED[level](connection)
+            return self._le_level_reached(level, connection)
 
-        return BR_LEVEL_REACHED[level](connection)
+        return await self._classic_level_reached(level, connection)
 
     def need_pairing(self, connection: BumbleConnection, level: int) -> bool:
-        if connection.transport == BT_LE_TRANSPORT:
+        if connection.transport == PhysicalTransport.LE:
             return level >= LE_LEVEL3 and not connection.authenticated
         return False
 
     def need_authentication(self, connection: BumbleConnection, level: int) -> bool:
-        if connection.transport == BT_LE_TRANSPORT:
+        if connection.transport == PhysicalTransport.LE:
             return False
         if level == LEVEL2 and connection.encryption != 0:
             return not connection.authenticated
@@ -485,7 +534,7 @@ class SecurityService(SecurityServicer):
 
     def need_encryption(self, connection: BumbleConnection, level: int) -> bool:
         # TODO(abel): need to support MITM
-        if connection.transport == BT_LE_TRANSPORT:
+        if connection.transport == PhysicalTransport.LE:
             return level == LE_LEVEL2 and not connection.encryption
         return level >= LEVEL2 and not connection.encryption
 
@@ -503,7 +552,7 @@ class SecurityStorageService(SecurityStorageServicer):
         self, request: IsBondedRequest, context: grpc.ServicerContext
     ) -> wrappers_pb2.BoolValue:
         address = utils.address_from_request(request, request.WhichOneof("address"))
-        self.log.info(f"IsBonded: {address}")
+        self.log.debug(f"IsBonded: {address}")
 
         if self.device.keystore is not None:
             is_bonded = await self.device.keystore.get(str(address)) is not None
@@ -517,10 +566,10 @@ class SecurityStorageService(SecurityStorageServicer):
         self, request: DeleteBondRequest, context: grpc.ServicerContext
     ) -> empty_pb2.Empty:
         address = utils.address_from_request(request, request.WhichOneof("address"))
-        self.log.info(f"DeleteBond: {address}")
+        self.log.debug(f"DeleteBond: {address}")
 
         if self.device.keystore is not None:
-            with suppress(KeyError):
+            with contextlib.suppress(KeyError):
                 await self.device.keystore.delete(str(address))
 
         return empty_pb2.Empty()

bumble/pandora/utils.py

@@ -12,18 +12,22 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+from __future__ import annotations
+
 import contextlib
 import functools
-import grpc
 import inspect
 import logging
+from collections.abc import Generator, MutableMapping
+from typing import Any
+
+import grpc
+from google.protobuf.message import Message  # pytype: disable=pyi-error
 
 from bumble.device import Device
-from bumble.hci import Address
-from google.protobuf.message import Message  # pytype: disable=pyi-error
-from typing import Any, Dict, Generator, MutableMapping, Optional, Tuple
+from bumble.hci import Address, AddressType
 
-ADDRESS_TYPES: Dict[str, int] = {
+ADDRESS_TYPES: dict[str, AddressType] = {
     "public": Address.PUBLIC_DEVICE_ADDRESS,
     "random": Address.RANDOM_DEVICE_ADDRESS,
     "public_identity": Address.PUBLIC_IDENTITY_ADDRESS,
@@ -31,7 +35,7 @@ ADDRESS_TYPES: Dict[str, int] = {
 }
 
 
-def address_from_request(request: Message, field: Optional[str]) -> Address:
+def address_from_request(request: Message, field: str | None) -> Address:
     if field is None:
         return Address.ANY
     return Address(bytes(reversed(getattr(request, field))), ADDRESS_TYPES[field])
@@ -42,7 +46,7 @@ class BumbleServerLoggerAdapter(logging.LoggerAdapter):  # type: ignore
 
     def process(
         self, msg: str, kwargs: MutableMapping[str, Any]
-    ) -> Tuple[str, MutableMapping[str, Any]]:
+    ) -> tuple[str, MutableMapping[str, Any]]:
         assert self.extra
         service_name = self.extra['service_name']
         assert isinstance(service_name, str)
@@ -92,8 +96,7 @@ def rpc(func: Any) -> Any:
     @functools.wraps(func)
     def gen_wrapper(self: Any, request: Any, context: grpc.ServicerContext) -> Any:
         with exception_to_rpc_error(context):
-            for v in func(self, request, context):
-                yield v
+            yield from func(self, request, context)
 
     @functools.wraps(func)
     def wrapper(self: Any, request: Any, context: grpc.ServicerContext) -> Any:

bumble/profiles/aics.py

@@ -0,0 +1,491 @@
+# Copyright 2024 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""LE Audio - Audio Input Control Service"""
+
+# -----------------------------------------------------------------------------
+# Imports
+# -----------------------------------------------------------------------------
+from __future__ import annotations
+
+import logging
+import struct
+from dataclasses import dataclass
+
+from bumble import utils
+from bumble.att import ATT_Error
+from bumble.device import Connection
+from bumble.gatt import (
+    GATT_AUDIO_INPUT_CONTROL_POINT_CHARACTERISTIC,
+    GATT_AUDIO_INPUT_CONTROL_SERVICE,
+    GATT_AUDIO_INPUT_DESCRIPTION_CHARACTERISTIC,
+    GATT_AUDIO_INPUT_STATE_CHARACTERISTIC,
+    GATT_AUDIO_INPUT_STATUS_CHARACTERISTIC,
+    GATT_AUDIO_INPUT_TYPE_CHARACTERISTIC,
+    GATT_GAIN_SETTINGS_ATTRIBUTE_CHARACTERISTIC,
+    Attribute,
+    Characteristic,
+    CharacteristicValue,
+    TemplateService,
+)
+from bumble.gatt_adapters import (
+    CharacteristicProxy,
+    PackedCharacteristicProxyAdapter,
+    SerializableCharacteristicAdapter,
+    SerializableCharacteristicProxyAdapter,
+    UTF8CharacteristicAdapter,
+    UTF8CharacteristicProxyAdapter,
+)
+from bumble.gatt_client import ProfileServiceProxy, ServiceProxy
+
+# -----------------------------------------------------------------------------
+# Logging
+# -----------------------------------------------------------------------------
+logger = logging.getLogger(__name__)
+
+
+# -----------------------------------------------------------------------------
+# Constants
+# -----------------------------------------------------------------------------
+CHANGE_COUNTER_MAX_VALUE = 0xFF
+GAIN_SETTINGS_MIN_VALUE = 0
+GAIN_SETTINGS_MAX_VALUE = 255
+
+
+class ErrorCode(utils.OpenIntEnum):
+    '''
+    Cf. 1.6 Application error codes
+    '''
+
+    INVALID_CHANGE_COUNTER = 0x80
+    OPCODE_NOT_SUPPORTED = 0x81
+    MUTE_DISABLED = 0x82
+    VALUE_OUT_OF_RANGE = 0x83
+    GAIN_MODE_CHANGE_NOT_ALLOWED = 0x84
+
+
+class Mute(utils.OpenIntEnum):
+    '''
+    Cf. 2.2.1.2 Mute Field
+    '''
+
+    NOT_MUTED = 0x00
+    MUTED = 0x01
+    DISABLED = 0x02
+
+
+class GainMode(utils.OpenIntEnum):
+    '''
+    Cf. 2.2.1.3 Gain Mode
+    '''
+
+    MANUAL_ONLY = 0x00
+    AUTOMATIC_ONLY = 0x01
+    MANUAL = 0x02
+    AUTOMATIC = 0x03
+
+
+class AudioInputStatus(utils.OpenIntEnum):
+    '''
+    Cf. 3.4 Audio Input Status
+    '''
+
+    INACTIVE = 0x00
+    ACTIVE = 0x01
+
+
+class AudioInputControlPointOpCode(utils.OpenIntEnum):
+    '''
+    Cf. 3.5.1 Audio Input Control Point procedure requirements
+    '''
+
+    SET_GAIN_SETTING = 0x01
+    UNMUTE = 0x02
+    MUTE = 0x03
+    SET_MANUAL_GAIN_MODE = 0x04
+    SET_AUTOMATIC_GAIN_MODE = 0x05
+
+
+# -----------------------------------------------------------------------------
+@dataclass
+class AudioInputState:
+    '''
+    Cf. 2.2.1 Audio Input State
+    '''
+
+    gain_settings: int = 0
+    mute: Mute = Mute.NOT_MUTED
+    gain_mode: GainMode = GainMode.MANUAL
+    change_counter: int = 0
+    attribute: Attribute | None = None
+
+    def __bytes__(self) -> bytes:
+        return bytes(
+            [self.gain_settings, self.mute, self.gain_mode, self.change_counter]
+        )
+
+    @classmethod
+    def from_bytes(cls, data: bytes):
+        gain_settings, mute, gain_mode, change_counter = struct.unpack("BBBB", data)
+        return cls(gain_settings, mute, gain_mode, change_counter)
+
+    def update_gain_settings_unit(self, gain_settings_unit: int) -> None:
+        self.gain_settings_unit = gain_settings_unit
+
+    def increment_gain_settings(self, gain_settings_unit: int) -> None:
+        self.gain_settings += gain_settings_unit
+        self.increment_change_counter()
+
+    def decrement_gain_settings(self) -> None:
+        self.gain_settings -= self.gain_settings_unit
+        self.increment_change_counter()
+
+    def increment_change_counter(self):
+        self.change_counter = (self.change_counter + 1) % (CHANGE_COUNTER_MAX_VALUE + 1)
+
+    async def notify_subscribers_via_connection(self, connection: Connection) -> None:
+        assert self.attribute is not None
+        await connection.device.notify_subscribers(attribute=self.attribute)
+
+
+@dataclass
+class GainSettingsProperties:
+    '''
+    Cf. 3.2 Gain Settings Properties
+    '''
+
+    gain_settings_unit: int = 1
+    gain_settings_minimum: int = GAIN_SETTINGS_MIN_VALUE
+    gain_settings_maximum: int = GAIN_SETTINGS_MAX_VALUE
+
+    @classmethod
+    def from_bytes(cls, data: bytes):
+        (gain_settings_unit, gain_settings_minimum, gain_settings_maximum) = (
+            struct.unpack('BBB', data)
+        )
+        return GainSettingsProperties(
+            gain_settings_unit, gain_settings_minimum, gain_settings_maximum
+        )
+
+    def __bytes__(self) -> bytes:
+        return bytes(
+            [
+                self.gain_settings_unit,
+                self.gain_settings_minimum,
+                self.gain_settings_maximum,
+            ]
+        )
+
+
+@dataclass
+class AudioInputControlPoint:
+    '''
+    Cf. 3.5.2 Audio Input Control Point
+    '''
+
+    audio_input_state: AudioInputState
+    gain_settings_properties: GainSettingsProperties
+
+    async def on_write(self, connection: Connection, value: bytes) -> None:
+        opcode = AudioInputControlPointOpCode(value[0])
+
+        if opcode == AudioInputControlPointOpCode.SET_GAIN_SETTING:
+            gain_settings_operand = value[2]
+            await self._set_gain_settings(connection, gain_settings_operand)
+        elif opcode == AudioInputControlPointOpCode.UNMUTE:
+            await self._unmute(connection)
+        elif opcode == AudioInputControlPointOpCode.MUTE:
+            change_counter_operand = value[1]
+            await self._mute(connection, change_counter_operand)
+        elif opcode == AudioInputControlPointOpCode.SET_MANUAL_GAIN_MODE:
+            await self._set_manual_gain_mode(connection)
+        elif opcode == AudioInputControlPointOpCode.SET_AUTOMATIC_GAIN_MODE:
+            await self._set_automatic_gain_mode(connection)
+        else:
+            logger.error(f"OpCode value is incorrect: {opcode}")
+            raise ATT_Error(ErrorCode.OPCODE_NOT_SUPPORTED)
+
+    async def _set_gain_settings(
+        self, connection: Connection, gain_settings_operand: int
+    ) -> None:
+        '''Cf. 3.5.2.1 Set Gain Settings Procedure'''
+
+        gain_mode = self.audio_input_state.gain_mode
+
+        logger.error(f"set_gain_setting: gain_mode: {gain_mode}")
+        if not (gain_mode == GainMode.MANUAL or gain_mode == GainMode.MANUAL_ONLY):
+            logger.warning(
+                "GainMode should be either MANUAL or MANUAL_ONLY Cf Spec Audio Input Control Service 3.5.2.1"
+            )
+            return
+
+        if (
+            gain_settings_operand < self.gain_settings_properties.gain_settings_minimum
+            or gain_settings_operand
+            > self.gain_settings_properties.gain_settings_maximum
+        ):
+            logger.error("gain_settings value out of range")
+            raise ATT_Error(ErrorCode.VALUE_OUT_OF_RANGE)
+
+        if self.audio_input_state.gain_settings != gain_settings_operand:
+            self.audio_input_state.gain_settings = gain_settings_operand
+            await self.audio_input_state.notify_subscribers_via_connection(connection)
+
+    async def _unmute(self, connection: Connection):
+        '''Cf. 3.5.2.2 Unmute procedure'''
+
+        logger.error(f'unmute: {self.audio_input_state.mute}')
+        mute = self.audio_input_state.mute
+        if mute == Mute.DISABLED:
+            logger.error("unmute: Cannot change Mute value, Mute state is DISABLED")
+            raise ATT_Error(ErrorCode.MUTE_DISABLED)
+
+        if mute == Mute.NOT_MUTED:
+            return
+
+        self.audio_input_state.mute = Mute.NOT_MUTED
+        self.audio_input_state.increment_change_counter()
+        await self.audio_input_state.notify_subscribers_via_connection(connection)
+
+    async def _mute(self, connection: Connection, change_counter_operand: int) -> None:
+        '''Cf. 3.5.5.2 Mute procedure'''
+
+        change_counter = self.audio_input_state.change_counter
+        mute = self.audio_input_state.mute
+        if mute == Mute.DISABLED:
+            logger.error("mute: Cannot change Mute value, Mute state is DISABLED")
+            raise ATT_Error(ErrorCode.MUTE_DISABLED)
+
+        if change_counter != change_counter_operand:
+            raise ATT_Error(ErrorCode.INVALID_CHANGE_COUNTER)
+
+        if mute == Mute.MUTED:
+            return
+
+        self.audio_input_state.mute = Mute.MUTED
+        self.audio_input_state.increment_change_counter()
+        await self.audio_input_state.notify_subscribers_via_connection(connection)
+
+    async def _set_manual_gain_mode(self, connection: Connection) -> None:
+        '''Cf. 3.5.2.4 Set Manual Gain Mode procedure'''
+
+        gain_mode = self.audio_input_state.gain_mode
+        if gain_mode in (GainMode.AUTOMATIC_ONLY, GainMode.MANUAL_ONLY):
+            logger.error(f"Cannot change gain_mode, bad state: {gain_mode}")
+            raise ATT_Error(ErrorCode.GAIN_MODE_CHANGE_NOT_ALLOWED)
+
+        if gain_mode == GainMode.MANUAL:
+            return
+
+        self.audio_input_state.gain_mode = GainMode.MANUAL
+        self.audio_input_state.increment_change_counter()
+        await self.audio_input_state.notify_subscribers_via_connection(connection)
+
+    async def _set_automatic_gain_mode(self, connection: Connection) -> None:
+        '''Cf. 3.5.2.5 Set Automatic Gain Mode'''
+
+        gain_mode = self.audio_input_state.gain_mode
+        if gain_mode in (GainMode.AUTOMATIC_ONLY, GainMode.MANUAL_ONLY):
+            logger.error(f"Cannot change gain_mode, bad state: {gain_mode}")
+            raise ATT_Error(ErrorCode.GAIN_MODE_CHANGE_NOT_ALLOWED)
+
+        if gain_mode == GainMode.AUTOMATIC:
+            return
+
+        self.audio_input_state.gain_mode = GainMode.AUTOMATIC
+        self.audio_input_state.increment_change_counter()
+        await self.audio_input_state.notify_subscribers_via_connection(connection)
+
+
+@dataclass
+class AudioInputDescription:
+    '''
+    Cf. 3.6 Audio Input Description
+    '''
+
+    audio_input_description: str = "Bluetooth"
+    attribute: Attribute | None = None
+
+    def on_read(self, _connection: Connection) -> str:
+        return self.audio_input_description
+
+    async def on_write(self, connection: Connection, value: str) -> None:
+        assert self.attribute
+
+        self.audio_input_description = value
+        await connection.device.notify_subscribers(attribute=self.attribute)
+
+
+class AICSService(TemplateService):
+    UUID = GATT_AUDIO_INPUT_CONTROL_SERVICE
+
+    audio_input_state_characteristic: Characteristic[AudioInputState]
+    audio_input_type_characteristic: Characteristic[bytes]
+    audio_input_status_characteristic: Characteristic[bytes]
+    audio_input_control_point_characteristic: Characteristic[bytes]
+    gain_settings_properties_characteristic: Characteristic[GainSettingsProperties]
+
+    def __init__(
+        self,
+        audio_input_state: AudioInputState | None = None,
+        gain_settings_properties: GainSettingsProperties | None = None,
+        audio_input_type: str = "local",
+        audio_input_status: AudioInputStatus | None = None,
+        audio_input_description: AudioInputDescription | None = None,
+    ):
+        self.audio_input_state = (
+            AudioInputState() if audio_input_state is None else audio_input_state
+        )
+        self.gain_settings_properties = (
+            GainSettingsProperties()
+            if gain_settings_properties is None
+            else gain_settings_properties
+        )
+        self.audio_input_status = (
+            AudioInputStatus.ACTIVE
+            if audio_input_status is None
+            else audio_input_status
+        )
+        self.audio_input_description = (
+            AudioInputDescription()
+            if audio_input_description is None
+            else audio_input_description
+        )
+
+        self.audio_input_control_point: AudioInputControlPoint = AudioInputControlPoint(
+            self.audio_input_state, self.gain_settings_properties
+        )
+
+        self.audio_input_state_characteristic = SerializableCharacteristicAdapter(
+            Characteristic(
+                uuid=GATT_AUDIO_INPUT_STATE_CHARACTERISTIC,
+                properties=Characteristic.Properties.READ
+                | Characteristic.Properties.NOTIFY,
+                permissions=Characteristic.Permissions.READ_REQUIRES_ENCRYPTION,
+                value=self.audio_input_state,
+            ),
+            AudioInputState,
+        )
+        self.audio_input_state.attribute = self.audio_input_state_characteristic
+
+        self.gain_settings_properties_characteristic = (
+            SerializableCharacteristicAdapter(
+                Characteristic(
+                    uuid=GATT_GAIN_SETTINGS_ATTRIBUTE_CHARACTERISTIC,
+                    properties=Characteristic.Properties.READ,
+                    permissions=Characteristic.Permissions.READ_REQUIRES_ENCRYPTION,
+                    value=self.gain_settings_properties,
+                ),
+                GainSettingsProperties,
+            )
+        )
+
+        self.audio_input_type_characteristic = Characteristic(
+            uuid=GATT_AUDIO_INPUT_TYPE_CHARACTERISTIC,
+            properties=Characteristic.Properties.READ,
+            permissions=Characteristic.Permissions.READ_REQUIRES_ENCRYPTION,
+            value=bytes(audio_input_type, 'utf-8'),
+        )
+
+        self.audio_input_status_characteristic = Characteristic(
+            uuid=GATT_AUDIO_INPUT_STATUS_CHARACTERISTIC,
+            properties=Characteristic.Properties.READ,
+            permissions=Characteristic.Permissions.READ_REQUIRES_ENCRYPTION,
+            value=bytes([self.audio_input_status]),
+        )
+
+        self.audio_input_control_point_characteristic = Characteristic(
+            uuid=GATT_AUDIO_INPUT_CONTROL_POINT_CHARACTERISTIC,
+            properties=Characteristic.Properties.WRITE,
+            permissions=Characteristic.Permissions.WRITE_REQUIRES_ENCRYPTION,
+            value=CharacteristicValue(write=self.audio_input_control_point.on_write),
+        )
+
+        self.audio_input_description_characteristic = UTF8CharacteristicAdapter(
+            Characteristic(
+                uuid=GATT_AUDIO_INPUT_DESCRIPTION_CHARACTERISTIC,
+                properties=Characteristic.Properties.READ
+                | Characteristic.Properties.NOTIFY
+                | Characteristic.Properties.WRITE_WITHOUT_RESPONSE,
+                permissions=Characteristic.Permissions.READ_REQUIRES_ENCRYPTION
+                | Characteristic.Permissions.WRITE_REQUIRES_ENCRYPTION,
+                value=CharacteristicValue(
+                    write=self.audio_input_description.on_write,
+                    read=self.audio_input_description.on_read,
+                ),
+            )
+        )
+        self.audio_input_description.attribute = (
+            self.audio_input_control_point_characteristic
+        )
+
+        super().__init__(
+            characteristics=[
+                self.audio_input_state_characteristic,  # type: ignore
+                self.gain_settings_properties_characteristic,  # type: ignore
+                self.audio_input_type_characteristic,  # type: ignore
+                self.audio_input_status_characteristic,  # type: ignore
+                self.audio_input_control_point_characteristic,  # type: ignore
+                self.audio_input_description_characteristic,  # type: ignore
+            ],
+            primary=False,
+        )
+
+
+# -----------------------------------------------------------------------------
+# Client
+# -----------------------------------------------------------------------------
+class AICSServiceProxy(ProfileServiceProxy):
+    SERVICE_CLASS = AICSService
+
+    audio_input_state: CharacteristicProxy[AudioInputState]
+    gain_settings_properties: CharacteristicProxy[GainSettingsProperties]
+    audio_input_status: CharacteristicProxy[int]
+    audio_input_control_point: CharacteristicProxy[bytes]
+
+    def __init__(self, service_proxy: ServiceProxy) -> None:
+        self.service_proxy = service_proxy
+
+        self.audio_input_state = SerializableCharacteristicProxyAdapter(
+            service_proxy.get_required_characteristic_by_uuid(
+                GATT_AUDIO_INPUT_STATE_CHARACTERISTIC
+            ),
+            AudioInputState,
+        )
+
+        self.gain_settings_properties = SerializableCharacteristicProxyAdapter(
+            service_proxy.get_required_characteristic_by_uuid(
+                GATT_GAIN_SETTINGS_ATTRIBUTE_CHARACTERISTIC
+            ),
+            GainSettingsProperties,
+        )
+
+        self.audio_input_status = PackedCharacteristicProxyAdapter(
+            service_proxy.get_required_characteristic_by_uuid(
+                GATT_AUDIO_INPUT_STATUS_CHARACTERISTIC
+            ),
+            'B',
+        )
+
+        self.audio_input_control_point = (
+            service_proxy.get_required_characteristic_by_uuid(
+                GATT_AUDIO_INPUT_CONTROL_POINT_CHARACTERISTIC
+            )
+        )
+
+        self.audio_input_description = UTF8CharacteristicProxyAdapter(
+            service_proxy.get_required_characteristic_by_uuid(
+                GATT_AUDIO_INPUT_DESCRIPTION_CHARACTERISTIC
+            )
+        )

bumble/profiles/ams.py

@@ -0,0 +1,401 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+Apple Media Service (AMS).
+"""
+
+# -----------------------------------------------------------------------------
+# Imports
+# -----------------------------------------------------------------------------
+from __future__ import annotations
+
+import asyncio
+import dataclasses
+import enum
+import logging
+from collections.abc import Iterable
+
+from bumble import utils
+from bumble.device import Peer
+from bumble.gatt import (
+    GATT_AMS_ENTITY_ATTRIBUTE_CHARACTERISTIC,
+    GATT_AMS_ENTITY_UPDATE_CHARACTERISTIC,
+    GATT_AMS_REMOTE_COMMAND_CHARACTERISTIC,
+    GATT_AMS_SERVICE,
+    Characteristic,
+    TemplateService,
+)
+from bumble.gatt_client import CharacteristicProxy, ProfileServiceProxy, ServiceProxy
+
+# -----------------------------------------------------------------------------
+# Logging
+# -----------------------------------------------------------------------------
+logger = logging.getLogger(__name__)
+
+
+# -----------------------------------------------------------------------------
+# Protocol
+# -----------------------------------------------------------------------------
+class RemoteCommandId(utils.OpenIntEnum):
+    PLAY = 0
+    PAUSE = 1
+    TOGGLE_PLAY_PAUSE = 2
+    NEXT_TRACK = 3
+    PREVIOUS_TRACK = 4
+    VOLUME_UP = 5
+    VOLUME_DOWN = 6
+    ADVANCE_REPEAT_MODE = 7
+    ADVANCE_SHUFFLE_MODE = 8
+    SKIP_FORWARD = 9
+    SKIP_BACKWARD = 10
+    LIKE_TRACK = 11
+    DISLIKE_TRACK = 12
+    BOOKMARK_TRACK = 13
+
+
+class EntityId(utils.OpenIntEnum):
+    PLAYER = 0
+    QUEUE = 1
+    TRACK = 2
+
+
+class ActionId(utils.OpenIntEnum):
+    POSITIVE = 0
+    NEGATIVE = 1
+
+
+class EntityUpdateFlags(enum.IntFlag):
+    TRUNCATED = 1
+
+
+class PlayerAttributeId(utils.OpenIntEnum):
+    NAME = 0
+    PLAYBACK_INFO = 1
+    VOLUME = 2
+
+
+class QueueAttributeId(utils.OpenIntEnum):
+    INDEX = 0
+    COUNT = 1
+    SHUFFLE_MODE = 2
+    REPEAT_MODE = 3
+
+
+class ShuffleMode(utils.OpenIntEnum):
+    OFF = 0
+    ONE = 1
+    ALL = 2
+
+
+class RepeatMode(utils.OpenIntEnum):
+    OFF = 0
+    ONE = 1
+    ALL = 2
+
+
+class TrackAttributeId(utils.OpenIntEnum):
+    ARTIST = 0
+    ALBUM = 1
+    TITLE = 2
+    DURATION = 3
+
+
+class PlaybackState(utils.OpenIntEnum):
+    PAUSED = 0
+    PLAYING = 1
+    REWINDING = 2
+    FAST_FORWARDING = 3
+
+
+@dataclasses.dataclass
+class PlaybackInfo:
+    playback_state: PlaybackState = PlaybackState.PAUSED
+    playback_rate: float = 1.0
+    elapsed_time: float = 0.0
+
+
+# -----------------------------------------------------------------------------
+# GATT Server-side
+# -----------------------------------------------------------------------------
+class Ams(TemplateService):
+    UUID = GATT_AMS_SERVICE
+
+    remote_command_characteristic: Characteristic
+    entity_update_characteristic: Characteristic
+    entity_attribute_characteristic: Characteristic
+
+    def __init__(self) -> None:
+        # TODO not the final implementation
+        self.remote_command_characteristic = Characteristic(
+            GATT_AMS_REMOTE_COMMAND_CHARACTERISTIC,
+            Characteristic.Properties.NOTIFY
+            | Characteristic.Properties.WRITE_WITHOUT_RESPONSE,
+            Characteristic.Permissions.WRITEABLE,
+        )
+
+        # TODO not the final implementation
+        self.entity_update_characteristic = Characteristic(
+            GATT_AMS_ENTITY_UPDATE_CHARACTERISTIC,
+            Characteristic.Properties.NOTIFY | Characteristic.Properties.WRITE,
+            Characteristic.Permissions.WRITEABLE,
+        )
+
+        # TODO not the final implementation
+        self.entity_attribute_characteristic = Characteristic(
+            GATT_AMS_ENTITY_ATTRIBUTE_CHARACTERISTIC,
+            Characteristic.Properties.READ
+            | Characteristic.Properties.WRITE_WITHOUT_RESPONSE,
+            Characteristic.Permissions.WRITEABLE | Characteristic.Permissions.READABLE,
+        )
+
+        super().__init__(
+            [
+                self.remote_command_characteristic,
+                self.entity_update_characteristic,
+                self.entity_attribute_characteristic,
+            ]
+        )
+
+
+# -----------------------------------------------------------------------------
+# GATT Client-side
+# -----------------------------------------------------------------------------
+class AmsProxy(ProfileServiceProxy):
+    SERVICE_CLASS = Ams
+
+    # NOTE: these don't use adapters, because the format for write and notifications
+    # are different.
+    remote_command: CharacteristicProxy[bytes]
+    entity_update: CharacteristicProxy[bytes]
+    entity_attribute: CharacteristicProxy[bytes]
+
+    def __init__(self, service_proxy: ServiceProxy):
+        self.remote_command = service_proxy.get_required_characteristic_by_uuid(
+            GATT_AMS_REMOTE_COMMAND_CHARACTERISTIC
+        )
+
+        self.entity_update = service_proxy.get_required_characteristic_by_uuid(
+            GATT_AMS_ENTITY_UPDATE_CHARACTERISTIC
+        )
+
+        self.entity_attribute = service_proxy.get_required_characteristic_by_uuid(
+            GATT_AMS_ENTITY_ATTRIBUTE_CHARACTERISTIC
+        )
+
+
+class AmsClient(utils.EventEmitter):
+    EVENT_SUPPORTED_COMMANDS = "supported_commands"
+    EVENT_PLAYER_NAME = "player_name"
+    EVENT_PLAYER_PLAYBACK_INFO = "player_playback_info"
+    EVENT_PLAYER_VOLUME = "player_volume"
+    EVENT_QUEUE_COUNT = "queue_count"
+    EVENT_QUEUE_INDEX = "queue_index"
+    EVENT_QUEUE_SHUFFLE_MODE = "queue_shuffle_mode"
+    EVENT_QUEUE_REPEAT_MODE = "queue_repeat_mode"
+    EVENT_TRACK_ARTIST = "track_artist"
+    EVENT_TRACK_ALBUM = "track_album"
+    EVENT_TRACK_TITLE = "track_title"
+    EVENT_TRACK_DURATION = "track_duration"
+
+    supported_commands: set[RemoteCommandId]
+    player_name: str = ""
+    player_playback_info: PlaybackInfo = PlaybackInfo(PlaybackState.PAUSED, 0.0, 0.0)
+    player_volume: float = 1.0
+    queue_count: int = 0
+    queue_index: int = 0
+    queue_shuffle_mode: ShuffleMode = ShuffleMode.OFF
+    queue_repeat_mode: RepeatMode = RepeatMode.OFF
+    track_artist: str = ""
+    track_album: str = ""
+    track_title: str = ""
+    track_duration: float = 0.0
+
+    def __init__(self, ams_proxy: AmsProxy) -> None:
+        super().__init__()
+        self._ams_proxy = ams_proxy
+        self._started = False
+        self._read_attribute_semaphore = asyncio.Semaphore()
+        self.supported_commands = set()
+
+    @classmethod
+    async def for_peer(cls, peer: Peer) -> AmsClient | None:
+        ams_proxy = await peer.discover_service_and_create_proxy(AmsProxy)
+        if ams_proxy is None:
+            return None
+        return cls(ams_proxy)
+
+    async def start(self) -> None:
+        logger.debug("subscribing to remote command characteristic")
+        await self._ams_proxy.remote_command.subscribe(
+            self._on_remote_command_notification
+        )
+
+        logger.debug("subscribing to entity update characteristic")
+        await self._ams_proxy.entity_update.subscribe(
+            lambda data: utils.AsyncRunner.spawn(
+                self._on_entity_update_notification(data)
+            )
+        )
+
+        self._started = True
+
+    async def stop(self) -> None:
+        await self._ams_proxy.remote_command.unsubscribe(
+            self._on_remote_command_notification
+        )
+        await self._ams_proxy.entity_update.unsubscribe(
+            self._on_entity_update_notification
+        )
+        self._started = False
+
+    async def observe(
+        self,
+        entity: EntityId,
+        attributes: Iterable[PlayerAttributeId | QueueAttributeId | TrackAttributeId],
+    ) -> None:
+        await self._ams_proxy.entity_update.write_value(
+            bytes([entity] + list(attributes)), with_response=True
+        )
+
+    async def command(self, command: RemoteCommandId) -> None:
+        await self._ams_proxy.remote_command.write_value(
+            bytes([command]), with_response=True
+        )
+
+    async def play(self) -> None:
+        await self.command(RemoteCommandId.PLAY)
+
+    async def pause(self) -> None:
+        await self.command(RemoteCommandId.PAUSE)
+
+    async def toggle_play_pause(self) -> None:
+        await self.command(RemoteCommandId.TOGGLE_PLAY_PAUSE)
+
+    async def next_track(self) -> None:
+        await self.command(RemoteCommandId.NEXT_TRACK)
+
+    async def previous_track(self) -> None:
+        await self.command(RemoteCommandId.PREVIOUS_TRACK)
+
+    async def volume_up(self) -> None:
+        await self.command(RemoteCommandId.VOLUME_UP)
+
+    async def volume_down(self) -> None:
+        await self.command(RemoteCommandId.VOLUME_DOWN)
+
+    async def advance_repeat_mode(self) -> None:
+        await self.command(RemoteCommandId.ADVANCE_REPEAT_MODE)
+
+    async def advance_shuffle_mode(self) -> None:
+        await self.command(RemoteCommandId.ADVANCE_SHUFFLE_MODE)
+
+    async def skip_forward(self) -> None:
+        await self.command(RemoteCommandId.SKIP_FORWARD)
+
+    async def skip_backward(self) -> None:
+        await self.command(RemoteCommandId.SKIP_BACKWARD)
+
+    async def like_track(self) -> None:
+        await self.command(RemoteCommandId.LIKE_TRACK)
+
+    async def dislike_track(self) -> None:
+        await self.command(RemoteCommandId.DISLIKE_TRACK)
+
+    async def bookmark_track(self) -> None:
+        await self.command(RemoteCommandId.BOOKMARK_TRACK)
+
+    def _on_remote_command_notification(self, data: bytes) -> None:
+        supported_commands = [RemoteCommandId(command) for command in data]
+        logger.debug(
+            f"supported commands: {[command.name for command in supported_commands]}"
+        )
+        for command in supported_commands:
+            self.supported_commands.add(command)
+
+        self.emit(self.EVENT_SUPPORTED_COMMANDS)
+
+    async def _on_entity_update_notification(self, data: bytes) -> None:
+        entity = EntityId(data[0])
+        flags = EntityUpdateFlags(data[2])
+        value = data[3:]
+
+        if flags & EntityUpdateFlags.TRUNCATED:
+            logger.debug("truncated attribute, fetching full value")
+
+            # Write the entity and attribute we're interested in
+            # (protected by a semaphore, so that we only read one attribute at a time)
+            async with self._read_attribute_semaphore:
+                await self._ams_proxy.entity_attribute.write_value(
+                    data[:2], with_response=True
+                )
+                value = await self._ams_proxy.entity_attribute.read_value()
+
+        if entity == EntityId.PLAYER:
+            player_attribute = PlayerAttributeId(data[1])
+            if player_attribute == PlayerAttributeId.NAME:
+                self.player_name = value.decode()
+                self.emit(self.EVENT_PLAYER_NAME)
+            elif player_attribute == PlayerAttributeId.PLAYBACK_INFO:
+                playback_state_str, playback_rate_str, elapsed_time_str = (
+                    value.decode().split(",")
+                )
+                self.player_playback_info = PlaybackInfo(
+                    PlaybackState(int(playback_state_str)),
+                    float(playback_rate_str),
+                    float(elapsed_time_str),
+                )
+                self.emit(self.EVENT_PLAYER_PLAYBACK_INFO)
+            elif player_attribute == PlayerAttributeId.VOLUME:
+                self.player_volume = float(value.decode())
+                self.emit(self.EVENT_PLAYER_VOLUME)
+            else:
+                logger.warning(f"received unknown player attribute {player_attribute}")
+
+        elif entity == EntityId.QUEUE:
+            queue_attribute = QueueAttributeId(data[1])
+            if queue_attribute == QueueAttributeId.COUNT:
+                self.queue_count = int(value)
+                self.emit(self.EVENT_QUEUE_COUNT)
+            elif queue_attribute == QueueAttributeId.INDEX:
+                self.queue_index = int(value)
+                self.emit(self.EVENT_QUEUE_INDEX)
+            elif queue_attribute == QueueAttributeId.REPEAT_MODE:
+                self.queue_repeat_mode = RepeatMode(int(value))
+                self.emit(self.EVENT_QUEUE_REPEAT_MODE)
+            elif queue_attribute == QueueAttributeId.SHUFFLE_MODE:
+                self.queue_shuffle_mode = ShuffleMode(int(value))
+                self.emit(self.EVENT_QUEUE_SHUFFLE_MODE)
+            else:
+                logger.warning(f"received unknown queue attribute {queue_attribute}")
+
+        elif entity == EntityId.TRACK:
+            track_attribute = TrackAttributeId(data[1])
+            if track_attribute == TrackAttributeId.ARTIST:
+                self.track_artist = value.decode()
+                self.emit(self.EVENT_TRACK_ARTIST)
+            elif track_attribute == TrackAttributeId.ALBUM:
+                self.track_album = value.decode()
+                self.emit(self.EVENT_TRACK_ALBUM)
+            elif track_attribute == TrackAttributeId.TITLE:
+                self.track_title = value.decode()
+                self.emit(self.EVENT_TRACK_TITLE)
+            elif track_attribute == TrackAttributeId.DURATION:
+                self.track_duration = float(value.decode())
+                self.emit(self.EVENT_TRACK_DURATION)
+            else:
+                logger.warning(f"received unknown track attribute {track_attribute}")
+
+        else:
+            logger.warning(f"received unknown attribute ID {data[1]}")

bumble/profiles/ancs.py

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

bumble/profiles/ascs.py

@@ -0,0 +1,747 @@
+# 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
+
+"""LE Audio - Audio Stream Control Service"""
+
+# -----------------------------------------------------------------------------
+# Imports
+# -----------------------------------------------------------------------------
+from __future__ import annotations
+
+import enum
+import functools
+import logging
+import struct
+from collections.abc import Sequence
+from dataclasses import dataclass, field
+from typing import Any, TypeVar
+
+from bumble import colors, device, gatt, gatt_client, hci, utils
+from bumble.profiles import le_audio
+from bumble.profiles.bap import CodecSpecificConfiguration
+
+# -----------------------------------------------------------------------------
+# Logging
+# -----------------------------------------------------------------------------
+logger = logging.getLogger(__name__)
+
+
+# -----------------------------------------------------------------------------
+# ASE Operations
+# -----------------------------------------------------------------------------
+
+
+class ASE_Operation:
+    '''
+    See Audio Stream Control Service - 5 ASE Control operations.
+    '''
+
+    classes: dict[int, type[ASE_Operation]] = {}
+    op_code: Opcode
+    name: str
+    fields: Sequence[Any] | None = None
+    ase_id: Sequence[int]
+
+    class Opcode(enum.IntEnum):
+        # fmt: off
+        CONFIG_CODEC         = 0x01
+        CONFIG_QOS           = 0x02
+        ENABLE               = 0x03
+        RECEIVER_START_READY = 0x04
+        DISABLE              = 0x05
+        RECEIVER_STOP_READY  = 0x06
+        UPDATE_METADATA      = 0x07
+        RELEASE              = 0x08
+
+    @classmethod
+    def from_bytes(cls, pdu: bytes) -> ASE_Operation:
+        op_code = pdu[0]
+
+        clazz = ASE_Operation.classes[op_code]
+        return clazz(
+            **hci.HCI_Object.dict_from_bytes(pdu, offset=1, fields=clazz.fields)
+        )
+
+    _OP = TypeVar("_OP", bound="ASE_Operation")
+
+    @classmethod
+    def subclass(cls, clazz: type[_OP]) -> type[_OP]:
+        clazz.name = f"ASE_{clazz.op_code.name.upper()}"
+        clazz.fields = hci.HCI_Object.fields_from_dataclass(clazz)
+        # Register a factory for this class
+        ASE_Operation.classes[clazz.op_code] = clazz
+        return clazz
+
+    @functools.cached_property
+    def pdu(self) -> bytes:
+        return bytes([self.op_code]) + hci.HCI_Object.dict_to_bytes(
+            self.__dict__, self.fields
+        )
+
+    def __bytes__(self) -> bytes:
+        return self.pdu
+
+    def __str__(self) -> str:
+        result = f'{colors.color(self.name, "yellow")} '
+        if fields := getattr(self, 'fields', None):
+            result += ':\n' + hci.HCI_Object.format_fields(self.__dict__, fields, '  ')
+        else:
+            if len(self.pdu) > 1:
+                result += f': {self.pdu.hex()}'
+        return result
+
+
+@ASE_Operation.subclass
+@dataclass
+class ASE_Config_Codec(ASE_Operation):
+    '''
+    See Audio Stream Control Service 5.1 - Config Codec Operation
+    '''
+
+    op_code = ASE_Operation.Opcode.CONFIG_CODEC
+
+    ase_id: Sequence[int] = field(metadata=hci.metadata(1, list_begin=True))
+    target_latency: Sequence[int] = field(metadata=hci.metadata(1))
+    target_phy: Sequence[int] = field(metadata=hci.metadata(1))
+    codec_id: Sequence[hci.CodingFormat] = field(
+        metadata=hci.metadata(hci.CodingFormat.parse_from_bytes)
+    )
+    codec_specific_configuration: Sequence[bytes] = field(
+        metadata=hci.metadata('v', list_end=True)
+    )
+
+
+@ASE_Operation.subclass
+@dataclass
+class ASE_Config_QOS(ASE_Operation):
+    '''
+    See Audio Stream Control Service 5.2 - Config Qos Operation
+    '''
+
+    op_code = ASE_Operation.Opcode.CONFIG_QOS
+
+    ase_id: Sequence[int] = field(metadata=hci.metadata(1, list_begin=True))
+    cig_id: Sequence[int] = field(metadata=hci.metadata(1))
+    cis_id: Sequence[int] = field(metadata=hci.metadata(1))
+    sdu_interval: Sequence[int] = field(metadata=hci.metadata(3))
+    framing: Sequence[int] = field(metadata=hci.metadata(1))
+    phy: Sequence[int] = field(metadata=hci.metadata(1))
+    max_sdu: Sequence[int] = field(metadata=hci.metadata(2))
+    retransmission_number: Sequence[int] = field(metadata=hci.metadata(1))
+    max_transport_latency: Sequence[int] = field(metadata=hci.metadata(2))
+    presentation_delay: Sequence[int] = field(metadata=hci.metadata(3, list_end=True))
+
+
+@ASE_Operation.subclass
+@dataclass
+class ASE_Enable(ASE_Operation):
+    '''
+    See Audio Stream Control Service 5.3 - Enable Operation
+    '''
+
+    op_code = ASE_Operation.Opcode.ENABLE
+
+    ase_id: Sequence[int] = field(metadata=hci.metadata(1, list_begin=True))
+    metadata: Sequence[bytes] = field(metadata=hci.metadata('v', list_end=True))
+
+
+@ASE_Operation.subclass
+@dataclass
+class ASE_Receiver_Start_Ready(ASE_Operation):
+    '''
+    See Audio Stream Control Service 5.4 - Receiver Start Ready Operation
+    '''
+
+    op_code = ASE_Operation.Opcode.RECEIVER_START_READY
+
+    ase_id: Sequence[int] = field(
+        metadata=hci.metadata(1, list_begin=True, list_end=True)
+    )
+
+
+@ASE_Operation.subclass
+@dataclass
+class ASE_Disable(ASE_Operation):
+    '''
+    See Audio Stream Control Service 5.5 - Disable Operation
+    '''
+
+    op_code = ASE_Operation.Opcode.DISABLE
+
+    ase_id: Sequence[int] = field(
+        metadata=hci.metadata(1, list_begin=True, list_end=True)
+    )
+
+
+@ASE_Operation.subclass
+@dataclass
+class ASE_Receiver_Stop_Ready(ASE_Operation):
+    '''
+    See Audio Stream Control Service 5.6 - Receiver Stop Ready Operation
+    '''
+
+    op_code = ASE_Operation.Opcode.RECEIVER_STOP_READY
+
+    ase_id: Sequence[int] = field(
+        metadata=hci.metadata(1, list_begin=True, list_end=True)
+    )
+
+
+@ASE_Operation.subclass
+@dataclass
+class ASE_Update_Metadata(ASE_Operation):
+    '''
+    See Audio Stream Control Service 5.7 - Update Metadata Operation
+    '''
+
+    op_code = ASE_Operation.Opcode.UPDATE_METADATA
+
+    ase_id: Sequence[int] = field(metadata=hci.metadata(1, list_begin=True))
+    metadata: Sequence[bytes] = field(metadata=hci.metadata('v', list_end=True))
+
+
+@ASE_Operation.subclass
+@dataclass
+class ASE_Release(ASE_Operation):
+    '''
+    See Audio Stream Control Service 5.8 - Release Operation
+    '''
+
+    op_code = ASE_Operation.Opcode.RELEASE
+
+    ase_id: Sequence[int] = field(
+        metadata=hci.metadata(1, list_begin=True, list_end=True)
+    )
+
+
+class AseResponseCode(enum.IntEnum):
+    # fmt: off
+    SUCCESS                                     = 0x00
+    UNSUPPORTED_OPCODE                          = 0x01
+    INVALID_LENGTH                              = 0x02
+    INVALID_ASE_ID                              = 0x03
+    INVALID_ASE_STATE_MACHINE_TRANSITION        = 0x04
+    INVALID_ASE_DIRECTION                       = 0x05
+    UNSUPPORTED_AUDIO_CAPABILITIES              = 0x06
+    UNSUPPORTED_CONFIGURATION_PARAMETER_VALUE   = 0x07
+    REJECTED_CONFIGURATION_PARAMETER_VALUE      = 0x08
+    INVALID_CONFIGURATION_PARAMETER_VALUE       = 0x09
+    UNSUPPORTED_METADATA                        = 0x0A
+    REJECTED_METADATA                           = 0x0B
+    INVALID_METADATA                            = 0x0C
+    INSUFFICIENT_RESOURCES                      = 0x0D
+    UNSPECIFIED_ERROR                           = 0x0E
+
+
+class AseReasonCode(enum.IntEnum):
+    # fmt: off
+    NONE                            = 0x00
+    CODEC_ID                        = 0x01
+    CODEC_SPECIFIC_CONFIGURATION    = 0x02
+    SDU_INTERVAL                    = 0x03
+    FRAMING                         = 0x04
+    PHY                             = 0x05
+    MAXIMUM_SDU_SIZE                = 0x06
+    RETRANSMISSION_NUMBER           = 0x07
+    MAX_TRANSPORT_LATENCY           = 0x08
+    PRESENTATION_DELAY              = 0x09
+    INVALID_ASE_CIS_MAPPING         = 0x0A
+
+
+# -----------------------------------------------------------------------------
+class AudioRole(enum.IntEnum):
+    SINK = device.CisLink.Direction.CONTROLLER_TO_HOST
+    SOURCE = device.CisLink.Direction.HOST_TO_CONTROLLER
+
+
+# -----------------------------------------------------------------------------
+class AseStateMachine(gatt.Characteristic):
+    class State(enum.IntEnum):
+        # fmt: off
+        IDLE             = 0x00
+        CODEC_CONFIGURED = 0x01
+        QOS_CONFIGURED   = 0x02
+        ENABLING         = 0x03
+        STREAMING        = 0x04
+        DISABLING        = 0x05
+        RELEASING        = 0x06
+
+    EVENT_STATE_CHANGE = "state_change"
+
+    cis_link: device.CisLink | None = None
+
+    # Additional parameters in CODEC_CONFIGURED State
+    preferred_framing = 0  # Unframed PDU supported
+    preferred_phy = 0
+    preferred_retransmission_number = 13
+    preferred_max_transport_latency = 100
+    supported_presentation_delay_min = 0
+    supported_presentation_delay_max = 0
+    preferred_presentation_delay_min = 0
+    preferred_presentation_delay_max = 0
+    codec_id = hci.CodingFormat(hci.CodecID.LC3)
+    codec_specific_configuration: CodecSpecificConfiguration | bytes = b''
+
+    # Additional parameters in QOS_CONFIGURED State
+    cig_id = 0
+    cis_id = 0
+    sdu_interval = 0
+    framing = 0
+    phy = 0
+    max_sdu = 0
+    retransmission_number = 0
+    max_transport_latency = 0
+    presentation_delay = 0
+
+    # Additional parameters in ENABLING, STREAMING, DISABLING State
+    metadata: le_audio.Metadata
+
+    def __init__(
+        self,
+        role: AudioRole,
+        ase_id: int,
+        service: AudioStreamControlService,
+    ) -> None:
+        self.service = service
+        self.ase_id = ase_id
+        self._state = AseStateMachine.State.IDLE
+        self.role = role
+        self.metadata = le_audio.Metadata()
+
+        uuid = (
+            gatt.GATT_SINK_ASE_CHARACTERISTIC
+            if role == AudioRole.SINK
+            else gatt.GATT_SOURCE_ASE_CHARACTERISTIC
+        )
+        super().__init__(
+            uuid=uuid,
+            properties=gatt.Characteristic.Properties.READ
+            | gatt.Characteristic.Properties.NOTIFY,
+            permissions=gatt.Characteristic.Permissions.READABLE,
+            value=gatt.CharacteristicValue(read=self.on_read),
+        )
+
+        self.service.device.on(
+            self.service.device.EVENT_CIS_REQUEST, self.on_cis_request
+        )
+        self.service.device.on(
+            self.service.device.EVENT_CIS_ESTABLISHMENT, self.on_cis_establishment
+        )
+
+    def on_cis_request(self, cis_link: device.CisLink) -> None:
+        if (
+            cis_link.cig_id == self.cig_id
+            and cis_link.cis_id == self.cis_id
+            and self.state == self.State.ENABLING
+        ):
+            utils.cancel_on_event(
+                cis_link.acl_connection,
+                'flush',
+                self.service.device.accept_cis_request(cis_link),
+            )
+
+    def on_cis_establishment(self, cis_link: device.CisLink) -> None:
+        if (
+            cis_link.cig_id == self.cig_id
+            and cis_link.cis_id == self.cis_id
+            and self.state == self.State.ENABLING
+        ):
+            cis_link.on(cis_link.EVENT_DISCONNECTION, self.on_cis_disconnection)
+
+            async def post_cis_established():
+                await cis_link.setup_data_path(direction=self.role)
+                if self.role == AudioRole.SINK:
+                    self.state = self.State.STREAMING
+                await self.service.device.notify_subscribers(self, self.value)
+
+            utils.cancel_on_event(
+                cis_link.acl_connection, 'flush', post_cis_established()
+            )
+            self.cis_link = cis_link
+
+    def on_cis_disconnection(self, _reason) -> None:
+        self.cis_link = None
+
+    def on_config_codec(
+        self,
+        target_latency: int,
+        target_phy: int,
+        codec_id: hci.CodingFormat,
+        codec_specific_configuration: bytes,
+    ) -> tuple[AseResponseCode, AseReasonCode]:
+        if self.state not in (
+            self.State.IDLE,
+            self.State.CODEC_CONFIGURED,
+            self.State.QOS_CONFIGURED,
+        ):
+            return (
+                AseResponseCode.INVALID_ASE_STATE_MACHINE_TRANSITION,
+                AseReasonCode.NONE,
+            )
+
+        self.max_transport_latency = target_latency
+        self.phy = target_phy
+        self.codec_id = codec_id
+        if codec_id.codec_id == hci.CodecID.VENDOR_SPECIFIC:
+            self.codec_specific_configuration = codec_specific_configuration
+        else:
+            self.codec_specific_configuration = CodecSpecificConfiguration.from_bytes(
+                codec_specific_configuration
+            )
+
+        self.state = self.State.CODEC_CONFIGURED
+
+        return (AseResponseCode.SUCCESS, AseReasonCode.NONE)
+
+    def on_config_qos(
+        self,
+        cig_id: int,
+        cis_id: int,
+        sdu_interval: int,
+        framing: int,
+        phy: int,
+        max_sdu: int,
+        retransmission_number: int,
+        max_transport_latency: int,
+        presentation_delay: int,
+    ) -> tuple[AseResponseCode, AseReasonCode]:
+        if self.state not in (
+            AseStateMachine.State.CODEC_CONFIGURED,
+            AseStateMachine.State.QOS_CONFIGURED,
+        ):
+            return (
+                AseResponseCode.INVALID_ASE_STATE_MACHINE_TRANSITION,
+                AseReasonCode.NONE,
+            )
+
+        self.cig_id = cig_id
+        self.cis_id = cis_id
+        self.sdu_interval = sdu_interval
+        self.framing = framing
+        self.phy = phy
+        self.max_sdu = max_sdu
+        self.retransmission_number = retransmission_number
+        self.max_transport_latency = max_transport_latency
+        self.presentation_delay = presentation_delay
+
+        self.state = self.State.QOS_CONFIGURED
+
+        return (AseResponseCode.SUCCESS, AseReasonCode.NONE)
+
+    def on_enable(self, metadata: bytes) -> tuple[AseResponseCode, AseReasonCode]:
+        if self.state != AseStateMachine.State.QOS_CONFIGURED:
+            return (
+                AseResponseCode.INVALID_ASE_STATE_MACHINE_TRANSITION,
+                AseReasonCode.NONE,
+            )
+
+        self.metadata = le_audio.Metadata.from_bytes(metadata)
+        self.state = self.State.ENABLING
+        # CIS could be established before enable.
+        if cis_link := next(
+            (
+                cis_link
+                for cis_link in self.service.device.cis_links.values()
+                if cis_link.cig_id == self.cig_id and cis_link.cis_id == self.cis_id
+            ),
+            None,
+        ):
+            self.on_cis_establishment(cis_link)
+
+        return (AseResponseCode.SUCCESS, AseReasonCode.NONE)
+
+    def on_receiver_start_ready(self) -> tuple[AseResponseCode, AseReasonCode]:
+        if self.state != AseStateMachine.State.ENABLING:
+            return (
+                AseResponseCode.INVALID_ASE_STATE_MACHINE_TRANSITION,
+                AseReasonCode.NONE,
+            )
+        self.state = self.State.STREAMING
+        return (AseResponseCode.SUCCESS, AseReasonCode.NONE)
+
+    def on_disable(self) -> tuple[AseResponseCode, AseReasonCode]:
+        if self.state not in (
+            AseStateMachine.State.ENABLING,
+            AseStateMachine.State.STREAMING,
+        ):
+            return (
+                AseResponseCode.INVALID_ASE_STATE_MACHINE_TRANSITION,
+                AseReasonCode.NONE,
+            )
+        if self.role == AudioRole.SINK:
+            self.state = self.State.QOS_CONFIGURED
+        else:
+            self.state = self.State.DISABLING
+        return (AseResponseCode.SUCCESS, AseReasonCode.NONE)
+
+    def on_receiver_stop_ready(self) -> tuple[AseResponseCode, AseReasonCode]:
+        if (
+            self.role != AudioRole.SOURCE
+            or self.state != AseStateMachine.State.DISABLING
+        ):
+            return (
+                AseResponseCode.INVALID_ASE_STATE_MACHINE_TRANSITION,
+                AseReasonCode.NONE,
+            )
+        self.state = self.State.QOS_CONFIGURED
+        return (AseResponseCode.SUCCESS, AseReasonCode.NONE)
+
+    def on_update_metadata(
+        self, metadata: bytes
+    ) -> tuple[AseResponseCode, AseReasonCode]:
+        if self.state not in (
+            AseStateMachine.State.ENABLING,
+            AseStateMachine.State.STREAMING,
+        ):
+            return (
+                AseResponseCode.INVALID_ASE_STATE_MACHINE_TRANSITION,
+                AseReasonCode.NONE,
+            )
+        self.metadata = le_audio.Metadata.from_bytes(metadata)
+        return (AseResponseCode.SUCCESS, AseReasonCode.NONE)
+
+    def on_release(self) -> tuple[AseResponseCode, AseReasonCode]:
+        if self.state == AseStateMachine.State.IDLE:
+            return (
+                AseResponseCode.INVALID_ASE_STATE_MACHINE_TRANSITION,
+                AseReasonCode.NONE,
+            )
+        self.state = self.State.RELEASING
+
+        async def remove_cis_async():
+            if self.cis_link:
+                await self.cis_link.remove_data_path([self.role])
+            self.state = self.State.IDLE
+            await self.service.device.notify_subscribers(self, self.value)
+
+        utils.cancel_on_event(self.service.device, 'flush', remove_cis_async())
+        return (AseResponseCode.SUCCESS, AseReasonCode.NONE)
+
+    @property
+    def state(self) -> State:
+        return self._state
+
+    @state.setter
+    def state(self, new_state: State) -> None:
+        logger.debug(f'{self} state change -> {colors.color(new_state.name, "cyan")}')
+        self._state = new_state
+        self.emit(self.EVENT_STATE_CHANGE)
+
+    @property
+    def value(self):
+        '''Returns ASE_ID, ASE_STATE, and ASE Additional Parameters.'''
+
+        if self.state == self.State.CODEC_CONFIGURED:
+            codec_specific_configuration_bytes = bytes(
+                self.codec_specific_configuration
+            )
+            additional_parameters = (
+                struct.pack(
+                    '<BBBH',
+                    self.preferred_framing,
+                    self.preferred_phy,
+                    self.preferred_retransmission_number,
+                    self.preferred_max_transport_latency,
+                )
+                + self.supported_presentation_delay_min.to_bytes(3, 'little')
+                + self.supported_presentation_delay_max.to_bytes(3, 'little')
+                + self.preferred_presentation_delay_min.to_bytes(3, 'little')
+                + self.preferred_presentation_delay_max.to_bytes(3, 'little')
+                + bytes(self.codec_id)
+                + bytes([len(codec_specific_configuration_bytes)])
+                + codec_specific_configuration_bytes
+            )
+        elif self.state == self.State.QOS_CONFIGURED:
+            additional_parameters = (
+                bytes([self.cig_id, self.cis_id])
+                + self.sdu_interval.to_bytes(3, 'little')
+                + struct.pack(
+                    '<BBHBH',
+                    self.framing,
+                    self.phy,
+                    self.max_sdu,
+                    self.retransmission_number,
+                    self.max_transport_latency,
+                )
+                + self.presentation_delay.to_bytes(3, 'little')
+            )
+        elif self.state in (
+            self.State.ENABLING,
+            self.State.STREAMING,
+            self.State.DISABLING,
+        ):
+            metadata_bytes = bytes(self.metadata)
+            additional_parameters = (
+                bytes([self.cig_id, self.cis_id, len(metadata_bytes)]) + metadata_bytes
+            )
+        else:
+            additional_parameters = b''
+
+        return bytes([self.ase_id, self.state]) + additional_parameters
+
+    @value.setter
+    def value(self, _new_value):
+        # Readonly. Do nothing in the setter.
+        pass
+
+    def on_read(self, _: device.Connection) -> bytes:
+        return self.value
+
+    def __str__(self) -> str:
+        return (
+            f'AseStateMachine(id={self.ase_id}, role={self.role.name} '
+            f'state={self._state.name})'
+        )
+
+
+# -----------------------------------------------------------------------------
+class AudioStreamControlService(gatt.TemplateService):
+    UUID = gatt.GATT_AUDIO_STREAM_CONTROL_SERVICE
+
+    ase_state_machines: dict[int, AseStateMachine]
+    ase_control_point: gatt.Characteristic[bytes]
+    _active_client: device.Connection | None = None
+
+    def __init__(
+        self,
+        device: device.Device,
+        source_ase_id: Sequence[int] = (),
+        sink_ase_id: Sequence[int] = (),
+    ) -> None:
+        self.device = device
+        self.ase_state_machines = {
+            **{
+                id: AseStateMachine(role=AudioRole.SINK, ase_id=id, service=self)
+                for id in sink_ase_id
+            },
+            **{
+                id: AseStateMachine(role=AudioRole.SOURCE, ase_id=id, service=self)
+                for id in source_ase_id
+            },
+        }  # ASE state machines, by ASE ID
+
+        self.ase_control_point = gatt.Characteristic(
+            uuid=gatt.GATT_ASE_CONTROL_POINT_CHARACTERISTIC,
+            properties=gatt.Characteristic.Properties.WRITE
+            | gatt.Characteristic.Properties.WRITE_WITHOUT_RESPONSE
+            | gatt.Characteristic.Properties.NOTIFY,
+            permissions=gatt.Characteristic.Permissions.WRITEABLE,
+            value=gatt.CharacteristicValue(write=self.on_write_ase_control_point),
+        )
+
+        super().__init__([self.ase_control_point, *self.ase_state_machines.values()])
+
+    def on_operation(self, opcode: ASE_Operation.Opcode, ase_id: int, args):
+        if ase := self.ase_state_machines.get(ase_id):
+            handler = getattr(ase, 'on_' + opcode.name.lower())
+            return (ase_id, *handler(*args))
+        else:
+            return (ase_id, AseResponseCode.INVALID_ASE_ID, AseReasonCode.NONE)
+
+    def _on_client_disconnected(self, _reason: int) -> None:
+        for ase in self.ase_state_machines.values():
+            ase.state = AseStateMachine.State.IDLE
+        self._active_client = None
+
+    def on_write_ase_control_point(
+        self, connection: device.Connection, data: bytes
+    ) -> None:
+        if not self._active_client and connection:
+            self._active_client = connection
+            connection.once('disconnection', self._on_client_disconnected)
+
+        operation = ASE_Operation.from_bytes(data)
+        responses = []
+        logger.debug(f'*** ASCS Write {operation} ***')
+
+        if isinstance(operation, ASE_Config_Codec):
+            for ase_id, *args in zip(
+                operation.ase_id,
+                operation.target_latency,
+                operation.target_phy,
+                operation.codec_id,
+                operation.codec_specific_configuration,
+            ):
+                responses.append(self.on_operation(operation.op_code, ase_id, args))
+        elif isinstance(operation, ASE_Config_QOS):
+            for ase_id, *args in zip(
+                operation.ase_id,
+                operation.cig_id,
+                operation.cis_id,
+                operation.sdu_interval,
+                operation.framing,
+                operation.phy,
+                operation.max_sdu,
+                operation.retransmission_number,
+                operation.max_transport_latency,
+                operation.presentation_delay,
+            ):
+                responses.append(self.on_operation(operation.op_code, ase_id, args))
+        elif isinstance(operation, (ASE_Enable, ASE_Update_Metadata)):
+            for ase_id, *args in zip(
+                operation.ase_id,
+                operation.metadata,
+            ):
+                responses.append(self.on_operation(operation.op_code, ase_id, args))
+        elif isinstance(
+            operation,
+            (
+                ASE_Receiver_Start_Ready,
+                ASE_Disable,
+                ASE_Receiver_Stop_Ready,
+                ASE_Release,
+            ),
+        ):
+            for ase_id in operation.ase_id:
+                responses.append(self.on_operation(operation.op_code, ase_id, []))
+
+        control_point_notification = bytes(
+            [operation.op_code, len(responses)]
+        ) + b''.join(map(bytes, responses))
+        utils.cancel_on_event(
+            self.device,
+            'flush',
+            self.device.notify_subscribers(
+                self.ase_control_point, control_point_notification
+            ),
+        )
+
+        for ase_id, *_ in responses:
+            if ase := self.ase_state_machines.get(ase_id):
+                utils.cancel_on_event(
+                    self.device,
+                    'flush',
+                    self.device.notify_subscribers(ase, ase.value),
+                )
+
+
+# -----------------------------------------------------------------------------
+class AudioStreamControlServiceProxy(gatt_client.ProfileServiceProxy):
+    SERVICE_CLASS = AudioStreamControlService
+
+    sink_ase: list[gatt_client.CharacteristicProxy[bytes]]
+    source_ase: list[gatt_client.CharacteristicProxy[bytes]]
+    ase_control_point: gatt_client.CharacteristicProxy[bytes]
+
+    def __init__(self, service_proxy: gatt_client.ServiceProxy):
+        self.service_proxy = service_proxy
+
+        self.sink_ase = service_proxy.get_characteristics_by_uuid(
+            gatt.GATT_SINK_ASE_CHARACTERISTIC
+        )
+        self.source_ase = service_proxy.get_characteristics_by_uuid(
+            gatt.GATT_SOURCE_ASE_CHARACTERISTIC
+        )
+        self.ase_control_point = service_proxy.get_characteristics_by_uuid(
+            gatt.GATT_ASE_CONTROL_POINT_CHARACTERISTIC
+        )[0]

bumble/profiles/asha.py

@@ -0,0 +1,299 @@
+# Copyright 2021-2022 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+# -----------------------------------------------------------------------------
+# Imports
+# -----------------------------------------------------------------------------
+import enum
+import logging
+import struct
+from collections.abc import Callable
+from typing import Any
+
+from bumble import data_types, gatt, gatt_client, l2cap, utils
+from bumble.core import AdvertisingData
+from bumble.device import Connection, Device
+
+# -----------------------------------------------------------------------------
+# Logging
+# -----------------------------------------------------------------------------
+_logger = logging.getLogger(__name__)
+
+
+# -----------------------------------------------------------------------------
+# Constants
+# -----------------------------------------------------------------------------
+class DeviceCapabilities(enum.IntFlag):
+    IS_RIGHT = 0x01
+    IS_DUAL = 0x02
+    CSIS_SUPPORTED = 0x04
+
+
+class FeatureMap(enum.IntFlag):
+    LE_COC_AUDIO_OUTPUT_STREAMING_SUPPORTED = 0x01
+
+
+class AudioType(utils.OpenIntEnum):
+    UNKNOWN = 0x00
+    RINGTONE = 0x01
+    PHONE_CALL = 0x02
+    MEDIA = 0x03
+
+
+class OpCode(utils.OpenIntEnum):
+    START = 1
+    STOP = 2
+    STATUS = 3
+
+
+class Codec(utils.OpenIntEnum):
+    G_722_16KHZ = 1
+
+
+class SupportedCodecs(enum.IntFlag):
+    G_722_16KHZ = 1 << Codec.G_722_16KHZ
+
+
+class PeripheralStatus(utils.OpenIntEnum):
+    """Status update on the other peripheral."""
+
+    OTHER_PERIPHERAL_DISCONNECTED = 1
+    OTHER_PERIPHERAL_CONNECTED = 2
+    CONNECTION_PARAMETER_UPDATED = 3
+
+
+class AudioStatus(utils.OpenIntEnum):
+    """Status report field for the audio control point."""
+
+    OK = 0
+    UNKNOWN_COMMAND = -1
+    ILLEGAL_PARAMETERS = -2
+
+
+# -----------------------------------------------------------------------------
+class AshaService(gatt.TemplateService):
+    UUID = gatt.GATT_ASHA_SERVICE
+
+    EVENT_STARTED = "started"
+    EVENT_STOPPED = "stopped"
+    EVENT_DISCONNECTED = "disconnected"
+    EVENT_VOLUME_CHANGED = "volume_changed"
+
+    audio_sink: Callable[[bytes], Any] | None
+    active_codec: Codec | None = None
+    audio_type: AudioType | None = None
+    volume: int | None = None
+    other_state: int | None = None
+    connection: Connection | None = None
+
+    def __init__(
+        self,
+        capability: int,
+        hisyncid: list[int] | bytes,
+        device: Device,
+        psm: int = 0,
+        audio_sink: Callable[[bytes], Any] | None = None,
+        feature_map: int = FeatureMap.LE_COC_AUDIO_OUTPUT_STREAMING_SUPPORTED,
+        protocol_version: int = 0x01,
+        render_delay_milliseconds: int = 0,
+        supported_codecs: int = SupportedCodecs.G_722_16KHZ,
+    ) -> None:
+        if len(hisyncid) != 8:
+            _logger.warning('HiSyncId should have a length of 8, got %d', len(hisyncid))
+
+        self.hisyncid = bytes(hisyncid)
+        self.capability = capability
+        self.device = device
+        self.audio_out_data = b''
+        self.psm = psm  # a non-zero psm is mainly for testing purpose
+        self.audio_sink = audio_sink
+        self.protocol_version = protocol_version
+
+        self.read_only_properties_characteristic = gatt.Characteristic(
+            gatt.GATT_ASHA_READ_ONLY_PROPERTIES_CHARACTERISTIC,
+            gatt.Characteristic.Properties.READ,
+            gatt.Characteristic.READABLE,
+            struct.pack(
+                "<BB8sBH2sH",
+                protocol_version,
+                capability,
+                self.hisyncid,
+                feature_map,
+                render_delay_milliseconds,
+                b'\x00\x00',
+                supported_codecs,
+            ),
+        )
+
+        self.audio_control_point_characteristic: gatt.Characteristic[bytes] = (
+            gatt.Characteristic(
+                gatt.GATT_ASHA_AUDIO_CONTROL_POINT_CHARACTERISTIC,
+                gatt.Characteristic.Properties.WRITE
+                | gatt.Characteristic.Properties.WRITE_WITHOUT_RESPONSE,
+                gatt.Characteristic.WRITEABLE,
+                gatt.CharacteristicValue(write=self._on_audio_control_point_write),
+            )
+        )
+        self.audio_status_characteristic = gatt.Characteristic(
+            gatt.GATT_ASHA_AUDIO_STATUS_CHARACTERISTIC,
+            gatt.Characteristic.Properties.READ | gatt.Characteristic.Properties.NOTIFY,
+            gatt.Characteristic.READABLE,
+            bytes([AudioStatus.OK]),
+        )
+        self.volume_characteristic: gatt.Characteristic[bytes] = gatt.Characteristic(
+            gatt.GATT_ASHA_VOLUME_CHARACTERISTIC,
+            gatt.Characteristic.Properties.WRITE_WITHOUT_RESPONSE,
+            gatt.Characteristic.WRITEABLE,
+            gatt.CharacteristicValue(write=self._on_volume_write),
+        )
+
+        # let the server find a free PSM
+        self.psm = device.create_l2cap_server(
+            spec=l2cap.LeCreditBasedChannelSpec(psm=self.psm, max_credits=8),
+            handler=self._on_connection,
+        ).psm
+        self.le_psm_out_characteristic = gatt.Characteristic(
+            gatt.GATT_ASHA_LE_PSM_OUT_CHARACTERISTIC,
+            gatt.Characteristic.Properties.READ,
+            gatt.Characteristic.READABLE,
+            struct.pack('<H', self.psm),
+        )
+
+        characteristics = (
+            self.read_only_properties_characteristic,
+            self.audio_control_point_characteristic,
+            self.audio_status_characteristic,
+            self.volume_characteristic,
+            self.le_psm_out_characteristic,
+        )
+
+        super().__init__(characteristics)
+
+    def get_advertising_data(self) -> bytes:
+        # Advertisement only uses 4 least significant bytes of the HiSyncId.
+        return bytes(
+            AdvertisingData(
+                [
+                    data_types.ServiceData16BitUUID(
+                        gatt.GATT_ASHA_SERVICE,
+                        bytes([self.protocol_version, self.capability])
+                        + self.hisyncid[:4],
+                    )
+                ]
+            )
+        )
+
+    # Handler for audio control commands
+    async def _on_audio_control_point_write(
+        self, connection: Connection, value: bytes
+    ) -> None:
+        _logger.debug(f'--- AUDIO CONTROL POINT Write:{value.hex()}')
+        opcode = value[0]
+        if opcode == OpCode.START:
+            # Start
+            self.active_codec = Codec(value[1])
+            self.audio_type = AudioType(value[2])
+            self.volume = value[3]
+            self.other_state = value[4]
+            _logger.debug(
+                f'### START: codec={self.active_codec.name}, '
+                f'audio_type={self.audio_type.name}, '
+                f'volume={self.volume}, '
+                f'other_state={self.other_state}'
+            )
+            self.emit(self.EVENT_STARTED)
+        elif opcode == OpCode.STOP:
+            _logger.debug('### STOP')
+            self.active_codec = None
+            self.audio_type = None
+            self.volume = None
+            self.other_state = None
+            self.emit(self.EVENT_STOPPED)
+        elif opcode == OpCode.STATUS:
+            _logger.debug('### STATUS: %s', PeripheralStatus(value[1]).name)
+
+        if self.connection is None and connection:
+            self.connection = connection
+
+            def on_disconnection(_reason) -> None:
+                self.connection = None
+                self.active_codec = None
+                self.audio_type = None
+                self.volume = None
+                self.other_state = None
+                self.emit(self.EVENT_DISCONNECTED)
+
+            connection.once('disconnection', on_disconnection)
+
+        # OPCODE_STATUS does not need audio status point update
+        if opcode != OpCode.STATUS:
+            await self.device.notify_subscribers(
+                self.audio_status_characteristic, force=True
+            )
+
+    # Handler for volume control
+    def _on_volume_write(self, connection: Connection, value: bytes) -> None:
+        _logger.debug(f'--- VOLUME Write:{value[0]}')
+        self.volume = value[0]
+        self.emit(self.EVENT_VOLUME_CHANGED)
+
+    # Register an L2CAP CoC server
+    def _on_connection(self, channel: l2cap.LeCreditBasedChannel) -> None:
+        def on_data(data: bytes) -> None:
+            if self.audio_sink:  # pylint: disable=not-callable
+                self.audio_sink(data)
+
+        channel.sink = on_data
+
+
+# -----------------------------------------------------------------------------
+class AshaServiceProxy(gatt_client.ProfileServiceProxy):
+    SERVICE_CLASS = AshaService
+    read_only_properties_characteristic: gatt_client.CharacteristicProxy[bytes]
+    audio_control_point_characteristic: gatt_client.CharacteristicProxy[bytes]
+    audio_status_point_characteristic: gatt_client.CharacteristicProxy[bytes]
+    volume_characteristic: gatt_client.CharacteristicProxy[bytes]
+    psm_characteristic: gatt_client.CharacteristicProxy[bytes]
+
+    def __init__(self, service_proxy: gatt_client.ServiceProxy) -> None:
+        self.service_proxy = service_proxy
+
+        for uuid, attribute_name in (
+            (
+                gatt.GATT_ASHA_READ_ONLY_PROPERTIES_CHARACTERISTIC,
+                'read_only_properties_characteristic',
+            ),
+            (
+                gatt.GATT_ASHA_AUDIO_CONTROL_POINT_CHARACTERISTIC,
+                'audio_control_point_characteristic',
+            ),
+            (
+                gatt.GATT_ASHA_AUDIO_STATUS_CHARACTERISTIC,
+                'audio_status_point_characteristic',
+            ),
+            (
+                gatt.GATT_ASHA_VOLUME_CHARACTERISTIC,
+                'volume_characteristic',
+            ),
+            (
+                gatt.GATT_ASHA_LE_PSM_OUT_CHARACTERISTIC,
+                'psm_characteristic',
+            ),
+        ):
+            setattr(
+                self,
+                attribute_name,
+                self.service_proxy.get_required_characteristic_by_uuid(uuid),
+            )

bumble/profiles/asha_service.py

@@ -1,188 +0,0 @@
-# Copyright 2021-2022 Google LLC
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#      https://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-
-
-# -----------------------------------------------------------------------------
-# Imports
-# -----------------------------------------------------------------------------
-import struct
-import logging
-from typing import List
-from ..core import AdvertisingData
-from ..device import Device, Connection
-from ..gatt import (
-    GATT_ASHA_SERVICE,
-    GATT_ASHA_READ_ONLY_PROPERTIES_CHARACTERISTIC,
-    GATT_ASHA_AUDIO_CONTROL_POINT_CHARACTERISTIC,
-    GATT_ASHA_AUDIO_STATUS_CHARACTERISTIC,
-    GATT_ASHA_VOLUME_CHARACTERISTIC,
-    GATT_ASHA_LE_PSM_OUT_CHARACTERISTIC,
-    TemplateService,
-    Characteristic,
-    CharacteristicValue,
-)
-from ..utils import AsyncRunner
-
-# -----------------------------------------------------------------------------
-# Logging
-# -----------------------------------------------------------------------------
-logger = logging.getLogger(__name__)
-
-
-# -----------------------------------------------------------------------------
-class AshaService(TemplateService):
-    UUID = GATT_ASHA_SERVICE
-    OPCODE_START = 1
-    OPCODE_STOP = 2
-    OPCODE_STATUS = 3
-    PROTOCOL_VERSION = 0x01
-    RESERVED_FOR_FUTURE_USE = [00, 00]
-    FEATURE_MAP = [0x01]  # [LE CoC audio output streaming supported]
-    SUPPORTED_CODEC_ID = [0x02, 0x01]  # Codec IDs [G.722 at 16 kHz]
-    RENDER_DELAY = [00, 00]
-
-    def __init__(self, capability: int, hisyncid: List[int], device: Device, psm=0):
-        self.hisyncid = hisyncid
-        self.capability = capability  # Device Capabilities [Left, Monaural]
-        self.device = device
-        self.audio_out_data = b''
-        self.psm = psm  # a non-zero psm is mainly for testing purpose
-
-        # Handler for volume control
-        def on_volume_write(connection, value):
-            logger.info(f'--- VOLUME Write:{value[0]}')
-            self.emit('volume', connection, value[0])
-
-        # Handler for audio control commands
-        def on_audio_control_point_write(connection: Connection, value):
-            logger.info(f'--- AUDIO CONTROL POINT Write:{value.hex()}')
-            opcode = value[0]
-            if opcode == AshaService.OPCODE_START:
-                # Start
-                audio_type = ('Unknown', 'Ringtone', 'Phone Call', 'Media')[value[2]]
-                logger.info(
-                    f'### START: codec={value[1]}, '
-                    f'audio_type={audio_type}, '
-                    f'volume={value[3]}, '
-                    f'otherstate={value[4]}'
-                )
-                self.emit(
-                    'start',
-                    connection,
-                    {
-                        'codec': value[1],
-                        'audiotype': value[2],
-                        'volume': value[3],
-                        'otherstate': value[4],
-                    },
-                )
-            elif opcode == AshaService.OPCODE_STOP:
-                logger.info('### STOP')
-                self.emit('stop', connection)
-            elif opcode == AshaService.OPCODE_STATUS:
-                logger.info(f'### STATUS: connected={value[1]}')
-
-            # OPCODE_STATUS does not need audio status point update
-            if opcode != AshaService.OPCODE_STATUS:
-                AsyncRunner.spawn(
-                    device.notify_subscribers(
-                        self.audio_status_characteristic, force=True
-                    )
-                )
-
-        self.read_only_properties_characteristic = Characteristic(
-            GATT_ASHA_READ_ONLY_PROPERTIES_CHARACTERISTIC,
-            Characteristic.Properties.READ,
-            Characteristic.READABLE,
-            bytes(
-                [
-                    AshaService.PROTOCOL_VERSION,  # Version
-                    self.capability,
-                ]
-            )
-            + bytes(self.hisyncid)
-            + bytes(AshaService.FEATURE_MAP)
-            + bytes(AshaService.RENDER_DELAY)
-            + bytes(AshaService.RESERVED_FOR_FUTURE_USE)
-            + bytes(AshaService.SUPPORTED_CODEC_ID),
-        )
-
-        self.audio_control_point_characteristic = Characteristic(
-            GATT_ASHA_AUDIO_CONTROL_POINT_CHARACTERISTIC,
-            Characteristic.Properties.WRITE
-            | Characteristic.Properties.WRITE_WITHOUT_RESPONSE,
-            Characteristic.WRITEABLE,
-            CharacteristicValue(write=on_audio_control_point_write),
-        )
-        self.audio_status_characteristic = Characteristic(
-            GATT_ASHA_AUDIO_STATUS_CHARACTERISTIC,
-            Characteristic.Properties.READ | Characteristic.Properties.NOTIFY,
-            Characteristic.READABLE,
-            bytes([0]),
-        )
-        self.volume_characteristic = Characteristic(
-            GATT_ASHA_VOLUME_CHARACTERISTIC,
-            Characteristic.Properties.WRITE_WITHOUT_RESPONSE,
-            Characteristic.WRITEABLE,
-            CharacteristicValue(write=on_volume_write),
-        )
-
-        # Register an L2CAP CoC server
-        def on_coc(channel):
-            def on_data(data):
-                logging.debug(f'<<< data received:{data}')
-
-                self.emit('data', channel.connection, data)
-                self.audio_out_data += data
-
-            channel.sink = on_data
-
-        # let the server find a free PSM
-        self.psm = self.device.register_l2cap_channel_server(self.psm, on_coc, 8)
-        self.le_psm_out_characteristic = Characteristic(
-            GATT_ASHA_LE_PSM_OUT_CHARACTERISTIC,
-            Characteristic.Properties.READ,
-            Characteristic.READABLE,
-            struct.pack('<H', self.psm),
-        )
-
-        characteristics = [
-            self.read_only_properties_characteristic,
-            self.audio_control_point_characteristic,
-            self.audio_status_characteristic,
-            self.volume_characteristic,
-            self.le_psm_out_characteristic,
-        ]
-
-        super().__init__(characteristics)
-
-    def get_advertising_data(self):
-        # Advertisement only uses 4 least significant bytes of the HiSyncId.
-        return bytes(
-            AdvertisingData(
-                [
-                    (
-                        AdvertisingData.SERVICE_DATA_16_BIT_UUID,
-                        bytes(GATT_ASHA_SERVICE)
-                        + bytes(
-                            [
-                                AshaService.PROTOCOL_VERSION,
-                                self.capability,
-                            ]
-                        )
-                        + bytes(self.hisyncid[:4]),
-                    ),
-                ]
-            )
-        )

bumble/profiles/bap.py

@@ -0,0 +1,610 @@
+# 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 dataclasses
+import enum
+import functools
+import logging
+import struct
+from collections.abc import Sequence
+
+from typing_extensions import Self
+
+from bumble import core, data_types, gatt, hci, utils
+from bumble.profiles import le_audio
+
+# -----------------------------------------------------------------------------
+# Logging
+# -----------------------------------------------------------------------------
+logger = logging.getLogger(__name__)
+
+# -----------------------------------------------------------------------------
+# Constants
+# -----------------------------------------------------------------------------
+
+
+class AudioLocation(enum.IntFlag):
+    '''Bluetooth Assigned Numbers, Section 6.12.1 - Audio Location'''
+
+    # fmt: off
+    NOT_ALLOWED             = 0x00000000
+    FRONT_LEFT              = 0x00000001
+    FRONT_RIGHT             = 0x00000002
+    FRONT_CENTER            = 0x00000004
+    LOW_FREQUENCY_EFFECTS_1 = 0x00000008
+    BACK_LEFT               = 0x00000010
+    BACK_RIGHT              = 0x00000020
+    FRONT_LEFT_OF_CENTER    = 0x00000040
+    FRONT_RIGHT_OF_CENTER   = 0x00000080
+    BACK_CENTER             = 0x00000100
+    LOW_FREQUENCY_EFFECTS_2 = 0x00000200
+    SIDE_LEFT               = 0x00000400
+    SIDE_RIGHT              = 0x00000800
+    TOP_FRONT_LEFT          = 0x00001000
+    TOP_FRONT_RIGHT         = 0x00002000
+    TOP_FRONT_CENTER        = 0x00004000
+    TOP_CENTER              = 0x00008000
+    TOP_BACK_LEFT           = 0x00010000
+    TOP_BACK_RIGHT          = 0x00020000
+    TOP_SIDE_LEFT           = 0x00040000
+    TOP_SIDE_RIGHT          = 0x00080000
+    TOP_BACK_CENTER         = 0x00100000
+    BOTTOM_FRONT_CENTER     = 0x00200000
+    BOTTOM_FRONT_LEFT       = 0x00400000
+    BOTTOM_FRONT_RIGHT      = 0x00800000
+    FRONT_LEFT_WIDE         = 0x01000000
+    FRONT_RIGHT_WIDE        = 0x02000000
+    LEFT_SURROUND           = 0x04000000
+    RIGHT_SURROUND          = 0x08000000
+
+    @property
+    def channel_count(self) -> int:
+        return bin(self.value).count('1')
+
+
+class AudioInputType(enum.IntEnum):
+    '''Bluetooth Assigned Numbers, Section 6.12.2 - Audio Input Type'''
+
+    # fmt: off
+    UNSPECIFIED = 0x00
+    BLUETOOTH   = 0x01
+    MICROPHONE  = 0x02
+    ANALOG      = 0x03
+    DIGITAL     = 0x04
+    RADIO       = 0x05
+    STREAMING   = 0x06
+    AMBIENT     = 0x07
+
+
+class ContextType(enum.IntFlag):
+    '''Bluetooth Assigned Numbers, Section 6.12.3 - Context Type'''
+
+    # fmt: off
+    PROHIBITED       = 0x0000
+    UNSPECIFIED      = 0x0001
+    CONVERSATIONAL   = 0x0002
+    MEDIA            = 0x0004
+    GAME             = 0x0008
+    INSTRUCTIONAL    = 0x0010
+    VOICE_ASSISTANTS = 0x0020
+    LIVE             = 0x0040
+    SOUND_EFFECTS    = 0x0080
+    NOTIFICATIONS    = 0x0100
+    RINGTONE         = 0x0200
+    ALERTS           = 0x0400
+    EMERGENCY_ALARM  = 0x0800
+
+
+class SamplingFrequency(utils.OpenIntEnum):
+    '''Bluetooth Assigned Numbers, Section 6.12.5.1 - Sampling Frequency'''
+
+    # fmt: off
+    FREQ_8000    = 0x01
+    FREQ_11025   = 0x02
+    FREQ_16000   = 0x03
+    FREQ_22050   = 0x04
+    FREQ_24000   = 0x05
+    FREQ_32000   = 0x06
+    FREQ_44100   = 0x07
+    FREQ_48000   = 0x08
+    FREQ_88200   = 0x09
+    FREQ_96000   = 0x0A
+    FREQ_176400  = 0x0B
+    FREQ_192000  = 0x0C
+    FREQ_384000  = 0x0D
+    # fmt: on
+
+    @classmethod
+    def from_hz(cls, frequency: int) -> SamplingFrequency:
+        return {
+            8000: SamplingFrequency.FREQ_8000,
+            11025: SamplingFrequency.FREQ_11025,
+            16000: SamplingFrequency.FREQ_16000,
+            22050: SamplingFrequency.FREQ_22050,
+            24000: SamplingFrequency.FREQ_24000,
+            32000: SamplingFrequency.FREQ_32000,
+            44100: SamplingFrequency.FREQ_44100,
+            48000: SamplingFrequency.FREQ_48000,
+            88200: SamplingFrequency.FREQ_88200,
+            96000: SamplingFrequency.FREQ_96000,
+            176400: SamplingFrequency.FREQ_176400,
+            192000: SamplingFrequency.FREQ_192000,
+            384000: SamplingFrequency.FREQ_384000,
+        }[frequency]
+
+    @property
+    def hz(self) -> int:
+        return {
+            SamplingFrequency.FREQ_8000: 8000,
+            SamplingFrequency.FREQ_11025: 11025,
+            SamplingFrequency.FREQ_16000: 16000,
+            SamplingFrequency.FREQ_22050: 22050,
+            SamplingFrequency.FREQ_24000: 24000,
+            SamplingFrequency.FREQ_32000: 32000,
+            SamplingFrequency.FREQ_44100: 44100,
+            SamplingFrequency.FREQ_48000: 48000,
+            SamplingFrequency.FREQ_88200: 88200,
+            SamplingFrequency.FREQ_96000: 96000,
+            SamplingFrequency.FREQ_176400: 176400,
+            SamplingFrequency.FREQ_192000: 192000,
+            SamplingFrequency.FREQ_384000: 384000,
+        }[self]
+
+
+class SupportedSamplingFrequency(enum.IntFlag):
+    '''Bluetooth Assigned Numbers, Section 6.12.4.1 - Sample Frequency'''
+
+    # fmt: off
+    FREQ_8000    = 1 << (SamplingFrequency.FREQ_8000 - 1)
+    FREQ_11025   = 1 << (SamplingFrequency.FREQ_11025 - 1)
+    FREQ_16000   = 1 << (SamplingFrequency.FREQ_16000 - 1)
+    FREQ_22050   = 1 << (SamplingFrequency.FREQ_22050 - 1)
+    FREQ_24000   = 1 << (SamplingFrequency.FREQ_24000 - 1)
+    FREQ_32000   = 1 << (SamplingFrequency.FREQ_32000 - 1)
+    FREQ_44100   = 1 << (SamplingFrequency.FREQ_44100 - 1)
+    FREQ_48000   = 1 << (SamplingFrequency.FREQ_48000 - 1)
+    FREQ_88200   = 1 << (SamplingFrequency.FREQ_88200 - 1)
+    FREQ_96000   = 1 << (SamplingFrequency.FREQ_96000 - 1)
+    FREQ_176400  = 1 << (SamplingFrequency.FREQ_176400 - 1)
+    FREQ_192000  = 1 << (SamplingFrequency.FREQ_192000 - 1)
+    FREQ_384000  = 1 << (SamplingFrequency.FREQ_384000 - 1)
+    # fmt: on
+
+    @classmethod
+    def from_hz(cls, frequencies: Sequence[int]) -> SupportedSamplingFrequency:
+        MAPPING = {
+            8000: SupportedSamplingFrequency.FREQ_8000,
+            11025: SupportedSamplingFrequency.FREQ_11025,
+            16000: SupportedSamplingFrequency.FREQ_16000,
+            22050: SupportedSamplingFrequency.FREQ_22050,
+            24000: SupportedSamplingFrequency.FREQ_24000,
+            32000: SupportedSamplingFrequency.FREQ_32000,
+            44100: SupportedSamplingFrequency.FREQ_44100,
+            48000: SupportedSamplingFrequency.FREQ_48000,
+            88200: SupportedSamplingFrequency.FREQ_88200,
+            96000: SupportedSamplingFrequency.FREQ_96000,
+            176400: SupportedSamplingFrequency.FREQ_176400,
+            192000: SupportedSamplingFrequency.FREQ_192000,
+            384000: SupportedSamplingFrequency.FREQ_384000,
+        }
+
+        return functools.reduce(
+            lambda x, y: x | MAPPING[y],
+            frequencies,
+            cls(0),
+        )
+
+
+class FrameDuration(enum.IntEnum):
+    '''Bluetooth Assigned Numbers, Section 6.12.5.2 - Frame Duration'''
+
+    # fmt: off
+    DURATION_7500_US  = 0x00
+    DURATION_10000_US = 0x01
+
+    @property
+    def us(self) -> int:
+        return {
+            FrameDuration.DURATION_7500_US: 7500,
+            FrameDuration.DURATION_10000_US: 10000,
+        }[self]
+
+
+class SupportedFrameDuration(enum.IntFlag):
+    '''Bluetooth Assigned Numbers, Section 6.12.4.2 - Frame Duration'''
+
+    # fmt: off
+    DURATION_7500_US_SUPPORTED  = 0b0001
+    DURATION_10000_US_SUPPORTED = 0b0010
+    DURATION_7500_US_PREFERRED  = 0b0001
+    DURATION_10000_US_PREFERRED = 0b0010
+
+
+class AnnouncementType(utils.OpenIntEnum):
+    '''Basic Audio Profile, 3.5.3. Additional Audio Stream Control Service requirements'''
+
+    # fmt: off
+    GENERAL  = 0x00
+    TARGETED = 0x01
+
+
+@dataclasses.dataclass
+class UnicastServerAdvertisingData:
+    """Advertising Data for ASCS."""
+
+    announcement_type: AnnouncementType = AnnouncementType.TARGETED
+    available_audio_contexts: ContextType = ContextType.MEDIA
+    metadata: bytes = b''
+
+    def __bytes__(self) -> bytes:
+        return bytes(
+            core.AdvertisingData(
+                [
+                    data_types.ServiceData16BitUUID(
+                        gatt.GATT_AUDIO_STREAM_CONTROL_SERVICE,
+                        struct.pack(
+                            '<BIB',
+                            self.announcement_type,
+                            self.available_audio_contexts,
+                            len(self.metadata),
+                        )
+                        + self.metadata,
+                    )
+                ]
+            )
+        )
+
+
+# -----------------------------------------------------------------------------
+# Utils
+# -----------------------------------------------------------------------------
+
+
+def bits_to_channel_counts(data: int) -> list[int]:
+    pos = 0
+    counts = []
+    while data != 0:
+        # Bit 0 = count 1
+        # Bit 1 = count 2, and so on
+        pos += 1
+        if data & 1:
+            counts.append(pos)
+        data >>= 1
+    return counts
+
+
+def channel_counts_to_bits(counts: Sequence[int]) -> int:
+    return sum(set([1 << (count - 1) for count in counts]))
+
+
+# -----------------------------------------------------------------------------
+# Structures
+# -----------------------------------------------------------------------------
+
+
+@dataclasses.dataclass
+class CodecSpecificCapabilities:
+    '''See:
+    * Bluetooth Assigned Numbers, 6.12.4 - Codec Specific Capabilities LTV Structures
+    * Basic Audio Profile, 4.3.1 - Codec_Specific_Capabilities LTV requirements
+    '''
+
+    class Type(enum.IntEnum):
+        # fmt: off
+        SAMPLING_FREQUENCY   = 0x01
+        FRAME_DURATION       = 0x02
+        AUDIO_CHANNEL_COUNT  = 0x03
+        OCTETS_PER_FRAME     = 0x04
+        CODEC_FRAMES_PER_SDU = 0x05
+
+    supported_sampling_frequencies: SupportedSamplingFrequency
+    supported_frame_durations: SupportedFrameDuration
+    supported_audio_channel_count: Sequence[int]
+    min_octets_per_codec_frame: int
+    max_octets_per_codec_frame: int
+    supported_max_codec_frames_per_sdu: int
+
+    @classmethod
+    def from_bytes(cls, data: bytes) -> CodecSpecificCapabilities:
+        offset = 0
+        # Allowed default values.
+        supported_audio_channel_count = [1]
+        supported_max_codec_frames_per_sdu = 1
+        while offset < len(data):
+            length, type = struct.unpack_from('BB', data, offset)
+            offset += 2
+            value = int.from_bytes(data[offset : offset + length - 1], 'little')
+            offset += length - 1
+
+            if type == CodecSpecificCapabilities.Type.SAMPLING_FREQUENCY:
+                supported_sampling_frequencies = SupportedSamplingFrequency(value)
+            elif type == CodecSpecificCapabilities.Type.FRAME_DURATION:
+                supported_frame_durations = SupportedFrameDuration(value)
+            elif type == CodecSpecificCapabilities.Type.AUDIO_CHANNEL_COUNT:
+                supported_audio_channel_count = bits_to_channel_counts(value)
+            elif type == CodecSpecificCapabilities.Type.OCTETS_PER_FRAME:
+                min_octets_per_sample = value & 0xFFFF
+                max_octets_per_sample = value >> 16
+            elif type == CodecSpecificCapabilities.Type.CODEC_FRAMES_PER_SDU:
+                supported_max_codec_frames_per_sdu = value
+
+        # It is expected here that if some fields are missing, an error should be raised.
+        # pylint: disable=possibly-used-before-assignment,used-before-assignment
+        return CodecSpecificCapabilities(
+            supported_sampling_frequencies=supported_sampling_frequencies,
+            supported_frame_durations=supported_frame_durations,
+            supported_audio_channel_count=supported_audio_channel_count,
+            min_octets_per_codec_frame=min_octets_per_sample,
+            max_octets_per_codec_frame=max_octets_per_sample,
+            supported_max_codec_frames_per_sdu=supported_max_codec_frames_per_sdu,
+        )
+
+    def __bytes__(self) -> bytes:
+        return struct.pack(
+            '<BBHBBBBBBBBHHBBB',
+            3,
+            CodecSpecificCapabilities.Type.SAMPLING_FREQUENCY,
+            self.supported_sampling_frequencies,
+            2,
+            CodecSpecificCapabilities.Type.FRAME_DURATION,
+            self.supported_frame_durations,
+            2,
+            CodecSpecificCapabilities.Type.AUDIO_CHANNEL_COUNT,
+            channel_counts_to_bits(self.supported_audio_channel_count),
+            5,
+            CodecSpecificCapabilities.Type.OCTETS_PER_FRAME,
+            self.min_octets_per_codec_frame,
+            self.max_octets_per_codec_frame,
+            2,
+            CodecSpecificCapabilities.Type.CODEC_FRAMES_PER_SDU,
+            self.supported_max_codec_frames_per_sdu,
+        )
+
+
+@dataclasses.dataclass
+class CodecSpecificConfiguration:
+    '''See:
+    * Bluetooth Assigned Numbers, 6.12.5 - Codec Specific Configuration LTV Structures
+    * Basic Audio Profile, 4.3.2 - Codec_Specific_Capabilities LTV requirements
+    '''
+
+    class Type(utils.OpenIntEnum):
+        # fmt: off
+        SAMPLING_FREQUENCY       = 0x01
+        FRAME_DURATION           = 0x02
+        AUDIO_CHANNEL_ALLOCATION = 0x03
+        OCTETS_PER_FRAME         = 0x04
+        CODEC_FRAMES_PER_SDU     = 0x05
+
+    sampling_frequency: SamplingFrequency | None = None
+    frame_duration: FrameDuration | None = None
+    audio_channel_allocation: AudioLocation | None = None
+    octets_per_codec_frame: int | None = None
+    codec_frames_per_sdu: int | None = None
+
+    @classmethod
+    def from_bytes(cls, data: bytes) -> CodecSpecificConfiguration:
+        offset = 0
+        sampling_frequency: SamplingFrequency | None = None
+        frame_duration: FrameDuration | None = None
+        audio_channel_allocation: AudioLocation | None = None
+        octets_per_codec_frame: int | None = None
+        codec_frames_per_sdu: int | None = None
+
+        while offset < len(data):
+            length, type = struct.unpack_from('BB', data, offset)
+            offset += 2
+            value = int.from_bytes(data[offset : offset + length - 1], 'little')
+            offset += length - 1
+
+            if type == CodecSpecificConfiguration.Type.SAMPLING_FREQUENCY:
+                sampling_frequency = SamplingFrequency(value)
+            elif type == CodecSpecificConfiguration.Type.FRAME_DURATION:
+                frame_duration = FrameDuration(value)
+            elif type == CodecSpecificConfiguration.Type.AUDIO_CHANNEL_ALLOCATION:
+                audio_channel_allocation = AudioLocation(value)
+            elif type == CodecSpecificConfiguration.Type.OCTETS_PER_FRAME:
+                octets_per_codec_frame = value
+            elif type == CodecSpecificConfiguration.Type.CODEC_FRAMES_PER_SDU:
+                codec_frames_per_sdu = value
+
+        return CodecSpecificConfiguration(
+            sampling_frequency=sampling_frequency,
+            frame_duration=frame_duration,
+            audio_channel_allocation=audio_channel_allocation,
+            octets_per_codec_frame=octets_per_codec_frame,
+            codec_frames_per_sdu=codec_frames_per_sdu,
+        )
+
+    def __bytes__(self) -> bytes:
+        return b''.join(
+            [
+                struct.pack(fmt, length, tag, value)
+                for fmt, length, tag, value in [
+                    (
+                        '<BBB',
+                        2,
+                        CodecSpecificConfiguration.Type.SAMPLING_FREQUENCY,
+                        self.sampling_frequency,
+                    ),
+                    (
+                        '<BBB',
+                        2,
+                        CodecSpecificConfiguration.Type.FRAME_DURATION,
+                        self.frame_duration,
+                    ),
+                    (
+                        '<BBI',
+                        5,
+                        CodecSpecificConfiguration.Type.AUDIO_CHANNEL_ALLOCATION,
+                        self.audio_channel_allocation,
+                    ),
+                    (
+                        '<BBH',
+                        3,
+                        CodecSpecificConfiguration.Type.OCTETS_PER_FRAME,
+                        self.octets_per_codec_frame,
+                    ),
+                    (
+                        '<BBB',
+                        2,
+                        CodecSpecificConfiguration.Type.CODEC_FRAMES_PER_SDU,
+                        self.codec_frames_per_sdu,
+                    ),
+                ]
+                if value is not None
+            ]
+        )
+
+
+@dataclasses.dataclass
+class BroadcastAudioAnnouncement:
+    broadcast_id: int
+
+    @classmethod
+    def from_bytes(cls, data: bytes) -> Self:
+        return cls(int.from_bytes(data[:3], 'little'))
+
+    def __bytes__(self) -> bytes:
+        return self.broadcast_id.to_bytes(3, 'little')
+
+    def get_advertising_data(self) -> bytes:
+        return bytes(
+            core.AdvertisingData(
+                [
+                    data_types.ServiceData16BitUUID(
+                        gatt.GATT_BROADCAST_AUDIO_ANNOUNCEMENT_SERVICE, bytes(self)
+                    )
+                ]
+            )
+        )
+
+
+@dataclasses.dataclass
+class BasicAudioAnnouncement:
+    @dataclasses.dataclass
+    class BIS:
+        index: int
+        codec_specific_configuration: CodecSpecificConfiguration
+
+        def __bytes__(self) -> bytes:
+            codec_specific_configuration_bytes = bytes(
+                self.codec_specific_configuration
+            )
+            return (
+                bytes([self.index, len(codec_specific_configuration_bytes)])
+                + codec_specific_configuration_bytes
+            )
+
+    @dataclasses.dataclass
+    class Subgroup:
+        codec_id: hci.CodingFormat
+        codec_specific_configuration: CodecSpecificConfiguration
+        metadata: le_audio.Metadata
+        bis: list[BasicAudioAnnouncement.BIS]
+
+        def __bytes__(self) -> bytes:
+            metadata_bytes = bytes(self.metadata)
+            codec_specific_configuration_bytes = bytes(
+                self.codec_specific_configuration
+            )
+            return (
+                bytes([len(self.bis)])
+                + bytes(self.codec_id)
+                + bytes([len(codec_specific_configuration_bytes)])
+                + codec_specific_configuration_bytes
+                + bytes([len(metadata_bytes)])
+                + metadata_bytes
+                + b''.join(map(bytes, self.bis))
+            )
+
+    presentation_delay: int
+    subgroups: list[BasicAudioAnnouncement.Subgroup]
+
+    @classmethod
+    def from_bytes(cls, data: bytes) -> Self:
+        presentation_delay = int.from_bytes(data[:3], 'little')
+        subgroups = []
+        offset = 4
+        for _ in range(data[3]):
+            num_bis = data[offset]
+            offset += 1
+            codec_id = hci.CodingFormat.from_bytes(data[offset : offset + 5])
+            offset += 5
+            codec_specific_configuration_length = data[offset]
+            offset += 1
+            codec_specific_configuration = data[
+                offset : offset + codec_specific_configuration_length
+            ]
+            offset += codec_specific_configuration_length
+            metadata_length = data[offset]
+            offset += 1
+            metadata = le_audio.Metadata.from_bytes(
+                data[offset : offset + metadata_length]
+            )
+            offset += metadata_length
+
+            bis = []
+            for _ in range(num_bis):
+                bis_index = data[offset]
+                offset += 1
+                bis_codec_specific_configuration_length = data[offset]
+                offset += 1
+                bis_codec_specific_configuration = data[
+                    offset : offset + bis_codec_specific_configuration_length
+                ]
+                offset += bis_codec_specific_configuration_length
+                bis.append(
+                    cls.BIS(
+                        bis_index,
+                        CodecSpecificConfiguration.from_bytes(
+                            bis_codec_specific_configuration
+                        ),
+                    )
+                )
+
+            subgroups.append(
+                cls.Subgroup(
+                    codec_id,
+                    CodecSpecificConfiguration.from_bytes(codec_specific_configuration),
+                    metadata,
+                    bis,
+                )
+            )
+
+        return cls(presentation_delay, subgroups)
+
+    def __bytes__(self) -> bytes:
+        return (
+            self.presentation_delay.to_bytes(3, 'little')
+            + bytes([len(self.subgroups)])
+            + b''.join(map(bytes, self.subgroups))
+        )
+
+    def get_advertising_data(self) -> bytes:
+        return bytes(
+            core.AdvertisingData(
+                [
+                    data_types.ServiceData16BitUUID(
+                        gatt.GATT_BASIC_AUDIO_ANNOUNCEMENT_SERVICE, bytes(self)
+                    )
+                ]
+            )
+        )

bumble/profiles/bass.py

@@ -0,0 +1,432 @@
+# 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
+
+"""LE Audio - Broadcast Audio Scan Service"""
+
+# -----------------------------------------------------------------------------
+# Imports
+# -----------------------------------------------------------------------------
+from __future__ import annotations
+
+import dataclasses
+import logging
+import struct
+from collections.abc import Sequence
+from typing import ClassVar
+
+from bumble import core, device, gatt, gatt_adapters, gatt_client, hci, utils
+
+# -----------------------------------------------------------------------------
+# Logging
+# -----------------------------------------------------------------------------
+logger = logging.getLogger(__name__)
+
+
+# -----------------------------------------------------------------------------
+# Constants
+# -----------------------------------------------------------------------------
+class ApplicationError(utils.OpenIntEnum):
+    OPCODE_NOT_SUPPORTED = 0x80
+    INVALID_SOURCE_ID = 0x81
+
+
+# -----------------------------------------------------------------------------
+def encode_subgroups(subgroups: Sequence[SubgroupInfo]) -> bytes:
+    return bytes([len(subgroups)]) + b"".join(
+        struct.pack("<IB", subgroup.bis_sync, len(subgroup.metadata))
+        + subgroup.metadata
+        for subgroup in subgroups
+    )
+
+
+def decode_subgroups(data: bytes) -> list[SubgroupInfo]:
+    num_subgroups = data[0]
+    offset = 1
+    subgroups = []
+    for _ in range(num_subgroups):
+        bis_sync = struct.unpack("<I", data[offset : offset + 4])[0]
+        metadata_length = data[offset + 4]
+        metadata = data[offset + 5 : offset + 5 + metadata_length]
+        offset += 5 + metadata_length
+        subgroups.append(SubgroupInfo(bis_sync, metadata))
+
+    return subgroups
+
+
+# -----------------------------------------------------------------------------
+class PeriodicAdvertisingSyncParams(utils.OpenIntEnum):
+    DO_NOT_SYNCHRONIZE_TO_PA = 0x00
+    SYNCHRONIZE_TO_PA_PAST_AVAILABLE = 0x01
+    SYNCHRONIZE_TO_PA_PAST_NOT_AVAILABLE = 0x02
+
+
+@dataclasses.dataclass
+class SubgroupInfo:
+    ANY_BIS: ClassVar[int] = 0xFFFFFFFF
+
+    bis_sync: int
+    metadata: bytes
+
+
+class ControlPointOperation:
+    class OpCode(utils.OpenIntEnum):
+        REMOTE_SCAN_STOPPED = 0x00
+        REMOTE_SCAN_STARTED = 0x01
+        ADD_SOURCE = 0x02
+        MODIFY_SOURCE = 0x03
+        SET_BROADCAST_CODE = 0x04
+        REMOVE_SOURCE = 0x05
+
+    op_code: OpCode
+    parameters: bytes
+
+    @classmethod
+    def from_bytes(cls, data: bytes) -> ControlPointOperation:
+        op_code = data[0]
+
+        if op_code == cls.OpCode.REMOTE_SCAN_STOPPED:
+            return RemoteScanStoppedOperation()
+
+        if op_code == cls.OpCode.REMOTE_SCAN_STARTED:
+            return RemoteScanStartedOperation()
+
+        if op_code == cls.OpCode.ADD_SOURCE:
+            return AddSourceOperation.from_parameters(data[1:])
+
+        if op_code == cls.OpCode.MODIFY_SOURCE:
+            return ModifySourceOperation.from_parameters(data[1:])
+
+        if op_code == cls.OpCode.SET_BROADCAST_CODE:
+            return SetBroadcastCodeOperation.from_parameters(data[1:])
+
+        if op_code == cls.OpCode.REMOVE_SOURCE:
+            return RemoveSourceOperation.from_parameters(data[1:])
+
+        raise core.InvalidArgumentError("invalid op code")
+
+    def __init__(self, op_code: OpCode, parameters: bytes = b"") -> None:
+        self.op_code = op_code
+        self.parameters = parameters
+
+    def __bytes__(self) -> bytes:
+        return bytes([self.op_code]) + self.parameters
+
+
+class RemoteScanStoppedOperation(ControlPointOperation):
+    def __init__(self) -> None:
+        super().__init__(ControlPointOperation.OpCode.REMOTE_SCAN_STOPPED)
+
+
+class RemoteScanStartedOperation(ControlPointOperation):
+    def __init__(self) -> None:
+        super().__init__(ControlPointOperation.OpCode.REMOTE_SCAN_STARTED)
+
+
+class AddSourceOperation(ControlPointOperation):
+    @classmethod
+    def from_parameters(cls, parameters: bytes) -> AddSourceOperation:
+        instance = cls.__new__(cls)
+        instance.op_code = ControlPointOperation.OpCode.ADD_SOURCE
+        instance.parameters = parameters
+        instance.advertiser_address = hci.Address.parse_address_preceded_by_type(
+            parameters, 1
+        )[1]
+        instance.advertising_sid = parameters[7]
+        instance.broadcast_id = int.from_bytes(parameters[8:11], "little")
+        instance.pa_sync = PeriodicAdvertisingSyncParams(parameters[11])
+        instance.pa_interval = struct.unpack("<H", parameters[12:14])[0]
+        instance.subgroups = decode_subgroups(parameters[14:])
+        return instance
+
+    def __init__(
+        self,
+        advertiser_address: hci.Address,
+        advertising_sid: int,
+        broadcast_id: int,
+        pa_sync: PeriodicAdvertisingSyncParams,
+        pa_interval: int,
+        subgroups: Sequence[SubgroupInfo],
+    ) -> None:
+        super().__init__(
+            ControlPointOperation.OpCode.ADD_SOURCE,
+            struct.pack(
+                "<B6sB3sBH",
+                advertiser_address.address_type,
+                bytes(advertiser_address),
+                advertising_sid,
+                broadcast_id.to_bytes(3, "little"),
+                pa_sync,
+                pa_interval,
+            )
+            + encode_subgroups(subgroups),
+        )
+        self.advertiser_address = advertiser_address
+        self.advertising_sid = advertising_sid
+        self.broadcast_id = broadcast_id
+        self.pa_sync = pa_sync
+        self.pa_interval = pa_interval
+        self.subgroups = list(subgroups)
+
+
+class ModifySourceOperation(ControlPointOperation):
+    @classmethod
+    def from_parameters(cls, parameters: bytes) -> ModifySourceOperation:
+        instance = cls.__new__(cls)
+        instance.op_code = ControlPointOperation.OpCode.MODIFY_SOURCE
+        instance.parameters = parameters
+        instance.source_id = parameters[0]
+        instance.pa_sync = PeriodicAdvertisingSyncParams(parameters[1])
+        instance.pa_interval = struct.unpack("<H", parameters[2:4])[0]
+        instance.subgroups = decode_subgroups(parameters[4:])
+        return instance
+
+    def __init__(
+        self,
+        source_id: int,
+        pa_sync: PeriodicAdvertisingSyncParams,
+        pa_interval: int,
+        subgroups: Sequence[SubgroupInfo],
+    ) -> None:
+        super().__init__(
+            ControlPointOperation.OpCode.MODIFY_SOURCE,
+            struct.pack("<BBH", source_id, pa_sync, pa_interval)
+            + encode_subgroups(subgroups),
+        )
+        self.source_id = source_id
+        self.pa_sync = pa_sync
+        self.pa_interval = pa_interval
+        self.subgroups = list(subgroups)
+
+
+class SetBroadcastCodeOperation(ControlPointOperation):
+    @classmethod
+    def from_parameters(cls, parameters: bytes) -> SetBroadcastCodeOperation:
+        instance = cls.__new__(cls)
+        instance.op_code = ControlPointOperation.OpCode.SET_BROADCAST_CODE
+        instance.parameters = parameters
+        instance.source_id = parameters[0]
+        instance.broadcast_code = parameters[1:17]
+        return instance
+
+    def __init__(
+        self,
+        source_id: int,
+        broadcast_code: bytes,
+    ) -> None:
+        super().__init__(
+            ControlPointOperation.OpCode.SET_BROADCAST_CODE,
+            bytes([source_id]) + broadcast_code,
+        )
+        self.source_id = source_id
+        self.broadcast_code = broadcast_code
+
+        if len(self.broadcast_code) != 16:
+            raise core.InvalidArgumentError("broadcast_code must be 16 bytes")
+
+
+class RemoveSourceOperation(ControlPointOperation):
+    @classmethod
+    def from_parameters(cls, parameters: bytes) -> RemoveSourceOperation:
+        instance = cls.__new__(cls)
+        instance.op_code = ControlPointOperation.OpCode.REMOVE_SOURCE
+        instance.parameters = parameters
+        instance.source_id = parameters[0]
+        return instance
+
+    def __init__(self, source_id: int) -> None:
+        super().__init__(ControlPointOperation.OpCode.REMOVE_SOURCE, bytes([source_id]))
+        self.source_id = source_id
+
+
+@dataclasses.dataclass
+class BroadcastReceiveState:
+    class PeriodicAdvertisingSyncState(utils.OpenIntEnum):
+        NOT_SYNCHRONIZED_TO_PA = 0x00
+        SYNCINFO_REQUEST = 0x01
+        SYNCHRONIZED_TO_PA = 0x02
+        FAILED_TO_SYNCHRONIZE_TO_PA = 0x03
+        NO_PAST = 0x04
+
+    class BigEncryption(utils.OpenIntEnum):
+        NOT_ENCRYPTED = 0x00
+        BROADCAST_CODE_REQUIRED = 0x01
+        DECRYPTING = 0x02
+        BAD_CODE = 0x03
+
+    source_id: int
+    source_address: hci.Address
+    source_adv_sid: int
+    broadcast_id: int
+    pa_sync_state: PeriodicAdvertisingSyncState
+    big_encryption: BigEncryption
+    bad_code: bytes
+    subgroups: list[SubgroupInfo]
+
+    @classmethod
+    def from_bytes(cls, data: bytes) -> BroadcastReceiveState:
+        source_id = data[0]
+        _, source_address = hci.Address.parse_address_preceded_by_type(data, 2)
+        source_adv_sid = data[8]
+        broadcast_id = int.from_bytes(data[9:12], "little")
+        pa_sync_state = cls.PeriodicAdvertisingSyncState(data[12])
+        big_encryption = cls.BigEncryption(data[13])
+        if big_encryption == cls.BigEncryption.BAD_CODE:
+            bad_code = data[14:30]
+            subgroups = decode_subgroups(data[30:])
+        else:
+            bad_code = b""
+            subgroups = decode_subgroups(data[14:])
+
+        return cls(
+            source_id,
+            source_address,
+            source_adv_sid,
+            broadcast_id,
+            pa_sync_state,
+            big_encryption,
+            bad_code,
+            subgroups,
+        )
+
+    def __bytes__(self) -> bytes:
+        return (
+            struct.pack(
+                "<BB6sB3sBB",
+                self.source_id,
+                self.source_address.address_type,
+                bytes(self.source_address),
+                self.source_adv_sid,
+                self.broadcast_id.to_bytes(3, "little"),
+                self.pa_sync_state,
+                self.big_encryption,
+            )
+            + self.bad_code
+            + encode_subgroups(self.subgroups)
+        )
+
+
+# -----------------------------------------------------------------------------
+class BroadcastAudioScanService(gatt.TemplateService):
+    UUID = gatt.GATT_BROADCAST_AUDIO_SCAN_SERVICE
+
+    def __init__(self):
+        self.broadcast_audio_scan_control_point_characteristic = gatt.Characteristic(
+            gatt.GATT_BROADCAST_AUDIO_SCAN_CONTROL_POINT_CHARACTERISTIC,
+            gatt.Characteristic.Properties.WRITE
+            | gatt.Characteristic.Properties.WRITE_WITHOUT_RESPONSE,
+            gatt.Characteristic.WRITEABLE,
+            gatt.CharacteristicValue(
+                write=self.on_broadcast_audio_scan_control_point_write
+            ),
+        )
+
+        self.broadcast_receive_state_characteristic = gatt.Characteristic(
+            gatt.GATT_BROADCAST_RECEIVE_STATE_CHARACTERISTIC,
+            gatt.Characteristic.Properties.READ | gatt.Characteristic.Properties.NOTIFY,
+            gatt.Characteristic.Permissions.READABLE
+            | gatt.Characteristic.Permissions.READ_REQUIRES_ENCRYPTION,
+            b"12",  # TEST
+        )
+
+        super().__init__(
+            [
+                self.broadcast_audio_scan_control_point_characteristic,
+                self.broadcast_receive_state_characteristic,
+            ]
+        )
+
+    def on_broadcast_audio_scan_control_point_write(
+        self, connection: device.Connection, value: bytes
+    ) -> None:
+        pass
+
+
+# -----------------------------------------------------------------------------
+class BroadcastAudioScanServiceProxy(gatt_client.ProfileServiceProxy):
+    SERVICE_CLASS = BroadcastAudioScanService
+
+    broadcast_audio_scan_control_point: gatt_client.CharacteristicProxy[bytes]
+    broadcast_receive_states: list[
+        gatt_client.CharacteristicProxy[BroadcastReceiveState | None]
+    ]
+
+    def __init__(self, service_proxy: gatt_client.ServiceProxy):
+        self.service_proxy = service_proxy
+
+        self.broadcast_audio_scan_control_point = (
+            service_proxy.get_required_characteristic_by_uuid(
+                gatt.GATT_BROADCAST_AUDIO_SCAN_CONTROL_POINT_CHARACTERISTIC
+            )
+        )
+
+        self.broadcast_receive_states = [
+            gatt_adapters.DelegatedCharacteristicProxyAdapter(
+                characteristic,
+                decode=lambda x: BroadcastReceiveState.from_bytes(x) if x else None,
+            )
+            for characteristic in service_proxy.get_characteristics_by_uuid(
+                gatt.GATT_BROADCAST_RECEIVE_STATE_CHARACTERISTIC
+            )
+        ]
+
+    async def send_control_point_operation(
+        self, operation: ControlPointOperation
+    ) -> None:
+        await self.broadcast_audio_scan_control_point.write_value(
+            bytes(operation), with_response=True
+        )
+
+    async def remote_scan_started(self) -> None:
+        await self.send_control_point_operation(RemoteScanStartedOperation())
+
+    async def remote_scan_stopped(self) -> None:
+        await self.send_control_point_operation(RemoteScanStoppedOperation())
+
+    async def add_source(
+        self,
+        advertiser_address: hci.Address,
+        advertising_sid: int,
+        broadcast_id: int,
+        pa_sync: PeriodicAdvertisingSyncParams,
+        pa_interval: int,
+        subgroups: Sequence[SubgroupInfo],
+    ) -> None:
+        await self.send_control_point_operation(
+            AddSourceOperation(
+                advertiser_address,
+                advertising_sid,
+                broadcast_id,
+                pa_sync,
+                pa_interval,
+                subgroups,
+            )
+        )
+
+    async def modify_source(
+        self,
+        source_id: int,
+        pa_sync: PeriodicAdvertisingSyncParams,
+        pa_interval: int,
+        subgroups: Sequence[SubgroupInfo],
+    ) -> None:
+        await self.send_control_point_operation(
+            ModifySourceOperation(
+                source_id,
+                pa_sync,
+                pa_interval,
+                subgroups,
+            )
+        )
+
+    async def remove_source(self, source_id: int) -> None:
+        await self.send_control_point_operation(RemoveSourceOperation(source_id))