fix some linter warnings

bench mobly snippets

.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"
+}

.git-blame-ignore-revs

@@ -0,0 +1,2 @@
+# Migrate code style to Black
+135df0dcc01ab765f432e19b1a5202d29bd55545

.github/workflows/code-check.yml

@@ -0,0 +1,39 @@
+# Check the code against the formatter and linter
+name: Code format and lint check
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    name: Check Code
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+      fail-fast: false
+
+    steps:
+    - name: Check out from Git
+      uses: actions/checkout@v3
+    - 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
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        python -m pip install ".[build,test,development,pandora]"
+    - name: Check
+      run: |
+        invoke project.pre-commit

.github/workflows/python-avatar.yml

@@ -0,0 +1,50 @@
+name: Python Avatar
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    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@v3
+      - name: Set Up Python 3.11
+        uses: actions/setup-python@v4
+        with:
+          python-version: 3.11
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install .[avatar,pandora]
+      - 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@v3
+        with:
+          name: mobly-logs
+          path: /tmp/logs/mobly/bumble.bumbles/

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

@@ -12,8 +12,12 @@ permissions:
 
 jobs:
   build:
-
-    runs-on: ubuntu-latest
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: ['ubuntu-latest', 'macos-latest', 'windows-latest']
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+      fail-fast: false
 
     steps:
     - name: Check out from Git
@@ -21,19 +25,58 @@ jobs:
     - 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 3.10
-      uses: actions/setup-python@v3
+        git fetch --depth=1 origin +refs/tags/*:refs/tags/*
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v4
       with:
-        python-version: "3.10"
+        python-version: ${{ matrix.python-version }}
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
         python -m pip install ".[build,test,development,documentation]"
-    - name: Test with pytest
+    - name: Test
       run: |
-        pytest
+        invoke test
     - name: Build
       run: |
         inv build
         inv build.mkdocs
+
+  build-rust:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+        rust-version: [ "1.76.0", "stable" ]
+      fail-fast: false
+    steps:
+      - name: Check out from Git
+        uses: actions/checkout@v3
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v4
+        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 # 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 --all-targets
+      # 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

.gitignore

@@ -3,9 +3,17 @@ build/
 dist/
 *.egg-info/
 *~
-bumble/__pycache__
 docs/mkdocs/site
-tests/__pycache__
 test-results.xml
-bumble/transport/__pycache__
-bumble/profiles/__pycache__
+__pycache__
+# Vim
+.*.sw*
+# generated by setuptools_scm
+bumble/_version.py
+.vscode/launch.json
+.vscode/settings.json
+/.idea
+venv/
+.venv/
+# snoop logs
+out/

.vscode/settings.json

@@ -0,0 +1,99 @@
+{
+    "cSpell.words": [
+        "Abortable",
+        "aiohttp",
+        "altsetting",
+        "ansiblue",
+        "ansicyan",
+        "ansigreen",
+        "ansimagenta",
+        "ansired",
+        "ansiyellow",
+        "appendleft",
+        "ascs",
+        "ASHA",
+        "asyncio",
+        "ATRAC",
+        "avctp",
+        "avdtp",
+        "avrcp",
+        "bitpool",
+        "bitstruct",
+        "BSCP",
+        "BTPROTO",
+        "CCCD",
+        "cccds",
+        "cmac",
+        "CONNECTIONLESS",
+        "csip",
+        "csis",
+        "csrcs",
+        "CVSD",
+        "datagram",
+        "DATALINK",
+        "delayreport",
+        "deregisters",
+        "deregistration",
+        "dhkey",
+        "diversifier",
+        "endianness",
+        "ESCO",
+        "Fitbit",
+        "GATTLINK",
+        "HANDSFREE",
+        "keydown",
+        "keyup",
+        "levelname",
+        "libc",
+        "liblc",
+        "libusb",
+        "MITM",
+        "MSBC",
+        "NDIS",
+        "netsim",
+        "NONBLOCK",
+        "NONCONN",
+        "OXIMETER",
+        "popleft",
+        "PRAND",
+        "protobuf",
+        "psms",
+        "pyee",
+        "Pyodide",
+        "pyusb",
+        "rfcomm",
+        "ROHC",
+        "rssi",
+        "SEID",
+        "seids",
+        "SERV",
+        "SIRK",
+        "ssrc",
+        "strerror",
+        "subband",
+        "subbands",
+        "subevent",
+        "Subrating",
+        "substates",
+        "tobytes",
+        "tsep",
+        "UNMUTE",
+        "unmuted",
+        "usbmodem",
+        "vhci",
+        "wasmtime",
+        "websockets",
+        "xcursor",
+        "ycursor"
+    ],
+    "[python]": {
+        "editor.rulers": [88]
+    },
+    "python.formatting.provider": "black",
+    "pylint.importStrategy": "useBundled",
+    "python.testing.pytestArgs": [
+        "."
+    ],
+    "python.testing.unittestEnabled": false,
+    "python.testing.pytestEnabled": true
+}

LICENSE

@@ -199,4 +199,23 @@
    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.
+   limitations under the License.
+
+
+---
+
+
+Files: bumble/colors.py
+Copyright (c) 2012 Giorgos Verigakis <verigak@gmail.com>
+
+Permission to use, copy, modify, and distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

README.md

@@ -15,10 +15,10 @@ Bumble is a full-featured Bluetooth stack written entirely in Python. It support
 
 ## Documentation
 
-Browse the pre-built [Online Documentation](https://google.github.io/bumble/), 
+Browse the pre-built [Online Documentation](https://google.github.io/bumble/),
 or see the documentation source under `docs/mkdocs/src`, or build the static HTML site from the markdown text with:
 ```
-mkdocs build -f docs/mkdocs/mkdocs.yml 
+mkdocs build -f docs/mkdocs/mkdocs.yml
 ```
 
 ## Usage
@@ -29,7 +29,7 @@ For a quick start to using Bumble, see the [Getting Started](docs/mkdocs/src/get
 
 ### Dependencies
 
-To install package dependencies needed to run the bumble examples execute the following commands:
+To install package dependencies needed to run the bumble examples, execute the following commands:
 
 ```
 python -m pip install --upgrade pip
@@ -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.
+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).
 
 ## License
 

apps/README.md

@@ -47,5 +47,3 @@ NOTE: this assumes you're running a Link Relay on port `10723`.
 
 ## `console.py`
 A simple text-based-ui interactive Bluetooth device with GATT client capabilities.
-
-

apps/auracast.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.
+
+# -----------------------------------------------------------------------------
+# Imports
+# -----------------------------------------------------------------------------
+from __future__ import annotations
+import asyncio
+import contextlib
+import dataclasses
+import logging
+import os
+from typing import cast, Any, AsyncGenerator, Coroutine, Dict, Optional, Tuple
+
+import click
+import pyee
+
+from bumble.colors import color
+import bumble.company_ids
+import bumble.core
+import bumble.device
+import bumble.gatt
+import bumble.hci
+import bumble.profiles.bap
+import bumble.profiles.bass
+import bumble.profiles.pbp
+import bumble.transport
+import bumble.utils
+
+
+# -----------------------------------------------------------------------------
+# Logging
+# -----------------------------------------------------------------------------
+logger = logging.getLogger(__name__)
+
+
+# -----------------------------------------------------------------------------
+# Constants
+# -----------------------------------------------------------------------------
+AURACAST_DEFAULT_DEVICE_NAME = 'Bumble Auracast'
+AURACAST_DEFAULT_DEVICE_ADDRESS = bumble.hci.Address('F0:F1:F2:F3:F4:F5')
+AURACAST_DEFAULT_SYNC_TIMEOUT = 5.0
+AURACAST_DEFAULT_ATT_MTU = 256
+
+
+# -----------------------------------------------------------------------------
+# Scan For Broadcasts
+# -----------------------------------------------------------------------------
+class BroadcastScanner(pyee.EventEmitter):
+    @dataclasses.dataclass
+    class Broadcast(pyee.EventEmitter):
+        name: str
+        sync: bumble.device.PeriodicAdvertisingSync
+        rssi: int = 0
+        public_broadcast_announcement: Optional[
+            bumble.profiles.pbp.PublicBroadcastAnnouncement
+        ] = None
+        broadcast_audio_announcement: Optional[
+            bumble.profiles.bap.BroadcastAudioAnnouncement
+        ] = None
+        basic_audio_announcement: Optional[
+            bumble.profiles.bap.BasicAudioAnnouncement
+        ] = None
+        appearance: Optional[bumble.core.Appearance] = None
+        biginfo: Optional[bumble.device.BIGInfoAdvertisement] = None
+        manufacturer_data: Optional[Tuple[str, bytes]] = None
+
+        def __post_init__(self) -> None:
+            super().__init__()
+            self.sync.on('establishment', self.on_sync_establishment)
+            self.sync.on('loss', self.on_sync_loss)
+            self.sync.on('periodic_advertisement', self.on_periodic_advertisement)
+            self.sync.on('biginfo_advertisement', self.on_biginfo_advertisement)
+
+        def update(self, advertisement: bumble.device.Advertisement) -> None:
+            self.rssi = advertisement.rssi
+            for service_data in advertisement.data.get_all(
+                bumble.core.AdvertisingData.SERVICE_DATA
+            ):
+                assert isinstance(service_data, tuple)
+                service_uuid, data = service_data
+                assert isinstance(data, bytes)
+
+                if (
+                    service_uuid
+                    == bumble.gatt.GATT_PUBLIC_BROADCAST_ANNOUNCEMENT_SERVICE
+                ):
+                    self.public_broadcast_announcement = (
+                        bumble.profiles.pbp.PublicBroadcastAnnouncement.from_bytes(data)
+                    )
+                    continue
+
+                if (
+                    service_uuid
+                    == bumble.gatt.GATT_BROADCAST_AUDIO_ANNOUNCEMENT_SERVICE
+                ):
+                    self.broadcast_audio_announcement = (
+                        bumble.profiles.bap.BroadcastAudioAnnouncement.from_bytes(data)
+                    )
+                    continue
+
+            self.appearance = advertisement.data.get(  # type: ignore[assignment]
+                bumble.core.AdvertisingData.APPEARANCE
+            )
+
+            if manufacturer_data := advertisement.data.get(
+                bumble.core.AdvertisingData.MANUFACTURER_SPECIFIC_DATA
+            ):
+                assert isinstance(manufacturer_data, tuple)
+                company_id = cast(int, manufacturer_data[0])
+                data = cast(bytes, manufacturer_data[1])
+                self.manufacturer_data = (
+                    bumble.company_ids.COMPANY_IDENTIFIERS.get(
+                        company_id, f'0x{company_id:04X}'
+                    ),
+                    data,
+                )
+
+            self.emit('update')
+
+        def print(self) -> None:
+            print(
+                color('Broadcast:', 'yellow'),
+                self.sync.advertiser_address,
+                color(self.sync.state.name, 'green'),
+            )
+            print(f'  {color("Name", "cyan")}:         {self.name}')
+            if self.appearance:
+                print(f'  {color("Appearance", "cyan")}:   {str(self.appearance)}')
+            print(f'  {color("RSSI", "cyan")}:         {self.rssi}')
+            print(f'  {color("SID", "cyan")}:          {self.sync.sid}')
+
+            if self.manufacturer_data:
+                print(
+                    f'  {color("Manufacturer Data", "cyan")}: '
+                    f'{self.manufacturer_data[0]} -> {self.manufacturer_data[1].hex()}'
+                )
+
+            if self.broadcast_audio_announcement:
+                print(
+                    f'  {color("Broadcast ID", "cyan")}: '
+                    f'{self.broadcast_audio_announcement.broadcast_id}'
+                )
+
+            if self.public_broadcast_announcement:
+                print(
+                    f'  {color("Features", "cyan")}:     '
+                    f'{self.public_broadcast_announcement.features}'
+                )
+                print(
+                    f'  {color("Metadata", "cyan")}:     '
+                    f'{self.public_broadcast_announcement.metadata}'
+                )
+
+            if self.basic_audio_announcement:
+                print(color('  Audio:', 'cyan'))
+                print(
+                    color('    Presentation Delay:', 'magenta'),
+                    self.basic_audio_announcement.presentation_delay,
+                )
+                for subgroup in self.basic_audio_announcement.subgroups:
+                    print(color('    Subgroup:', 'magenta'))
+                    print(color('      Codec ID:', 'yellow'))
+                    print(
+                        color('        Coding Format:           ', 'green'),
+                        subgroup.codec_id.coding_format.name,
+                    )
+                    print(
+                        color('        Company ID:              ', 'green'),
+                        subgroup.codec_id.company_id,
+                    )
+                    print(
+                        color('        Vendor Specific Codec ID:', 'green'),
+                        subgroup.codec_id.vendor_specific_codec_id,
+                    )
+                    print(
+                        color('      Codec Config:', 'yellow'),
+                        subgroup.codec_specific_configuration,
+                    )
+                    print(color('      Metadata:    ', 'yellow'), subgroup.metadata)
+
+                    for bis in subgroup.bis:
+                        print(color(f'      BIS [{bis.index}]:', 'yellow'))
+                        print(
+                            color('       Codec Config:', 'green'),
+                            bis.codec_specific_configuration,
+                        )
+
+            if self.biginfo:
+                print(color('  BIG:', 'cyan'))
+                print(
+                    color('    Number of BIS:', 'magenta'),
+                    self.biginfo.num_bis,
+                )
+                print(
+                    color('    PHY:          ', 'magenta'),
+                    self.biginfo.phy.name,
+                )
+                print(
+                    color('    Framed:       ', 'magenta'),
+                    self.biginfo.framed,
+                )
+                print(
+                    color('    Encrypted:    ', 'magenta'),
+                    self.biginfo.encrypted,
+                )
+
+        def on_sync_establishment(self) -> None:
+            self.emit('sync_establishment')
+
+        def on_sync_loss(self) -> None:
+            self.basic_audio_announcement = None
+            self.biginfo = None
+            self.emit('sync_loss')
+
+        def on_periodic_advertisement(
+            self, advertisement: bumble.device.PeriodicAdvertisement
+        ) -> None:
+            if advertisement.data is None:
+                return
+
+            for service_data in advertisement.data.get_all(
+                bumble.core.AdvertisingData.SERVICE_DATA
+            ):
+                assert isinstance(service_data, tuple)
+                service_uuid, data = service_data
+                assert isinstance(data, bytes)
+
+                if service_uuid == bumble.gatt.GATT_BASIC_AUDIO_ANNOUNCEMENT_SERVICE:
+                    self.basic_audio_announcement = (
+                        bumble.profiles.bap.BasicAudioAnnouncement.from_bytes(data)
+                    )
+                    break
+
+            self.emit('change')
+
+        def on_biginfo_advertisement(
+            self, advertisement: bumble.device.BIGInfoAdvertisement
+        ) -> None:
+            self.biginfo = advertisement
+            self.emit('change')
+
+    def __init__(
+        self,
+        device: bumble.device.Device,
+        filter_duplicates: bool,
+        sync_timeout: float,
+    ):
+        super().__init__()
+        self.device = device
+        self.filter_duplicates = filter_duplicates
+        self.sync_timeout = sync_timeout
+        self.broadcasts: Dict[bumble.hci.Address, BroadcastScanner.Broadcast] = {}
+        device.on('advertisement', self.on_advertisement)
+
+    async def start(self) -> None:
+        await self.device.start_scanning(
+            active=False,
+            filter_duplicates=False,
+        )
+
+    async def stop(self) -> None:
+        await self.device.stop_scanning()
+
+    def on_advertisement(self, advertisement: bumble.device.Advertisement) -> None:
+        if (
+            broadcast_name := advertisement.data.get(
+                bumble.core.AdvertisingData.BROADCAST_NAME
+            )
+        ) is None:
+            return
+        assert isinstance(broadcast_name, str)
+
+        if broadcast := self.broadcasts.get(advertisement.address):
+            broadcast.update(advertisement)
+            return
+
+        bumble.utils.AsyncRunner.spawn(
+            self.on_new_broadcast(broadcast_name, advertisement)
+        )
+
+    async def on_new_broadcast(
+        self, name: str, advertisement: bumble.device.Advertisement
+    ) -> None:
+        periodic_advertising_sync = await self.device.create_periodic_advertising_sync(
+            advertiser_address=advertisement.address,
+            sid=advertisement.sid,
+            sync_timeout=self.sync_timeout,
+            filter_duplicates=self.filter_duplicates,
+        )
+        broadcast = self.Broadcast(
+            name,
+            periodic_advertising_sync,
+        )
+        broadcast.update(advertisement)
+        self.broadcasts[advertisement.address] = broadcast
+        periodic_advertising_sync.on('loss', lambda: self.on_broadcast_loss(broadcast))
+        self.emit('new_broadcast', broadcast)
+
+    def on_broadcast_loss(self, broadcast: Broadcast) -> None:
+        del self.broadcasts[broadcast.sync.advertiser_address]
+        bumble.utils.AsyncRunner.spawn(broadcast.sync.terminate())
+        self.emit('broadcast_loss', broadcast)
+
+
+class PrintingBroadcastScanner:
+    def __init__(
+        self, device: bumble.device.Device, filter_duplicates: bool, sync_timeout: float
+    ) -> None:
+        self.scanner = BroadcastScanner(device, filter_duplicates, sync_timeout)
+        self.scanner.on('new_broadcast', self.on_new_broadcast)
+        self.scanner.on('broadcast_loss', self.on_broadcast_loss)
+        self.scanner.on('update', self.refresh)
+        self.status_message = ''
+
+    async def start(self) -> None:
+        self.status_message = color('Scanning...', 'green')
+        await self.scanner.start()
+
+    def on_new_broadcast(self, broadcast: BroadcastScanner.Broadcast) -> None:
+        self.status_message = color(
+            f'+Found {len(self.scanner.broadcasts)} broadcasts', 'green'
+        )
+        broadcast.on('change', self.refresh)
+        broadcast.on('update', self.refresh)
+        self.refresh()
+
+    def on_broadcast_loss(self, broadcast: BroadcastScanner.Broadcast) -> None:
+        self.status_message = color(
+            f'-Found {len(self.scanner.broadcasts)} broadcasts', 'green'
+        )
+        self.refresh()
+
+    def refresh(self) -> None:
+        # Clear the screen from the top
+        print('\033[H')
+        print('\033[0J')
+        print('\033[H')
+
+        # Print the status message
+        print(self.status_message)
+        print("==========================================")
+
+        # Print all broadcasts
+        for broadcast in self.scanner.broadcasts.values():
+            broadcast.print()
+            print('------------------------------------------')
+
+        # Clear the screen to the bottom
+        print('\033[0J')
+
+
+@contextlib.asynccontextmanager
+async def create_device(transport: str) -> AsyncGenerator[bumble.device.Device, Any]:
+    async with await bumble.transport.open_transport(transport) as (
+        hci_source,
+        hci_sink,
+    ):
+        device_config = bumble.device.DeviceConfiguration(
+            name=AURACAST_DEFAULT_DEVICE_NAME,
+            address=AURACAST_DEFAULT_DEVICE_ADDRESS,
+            keystore='JsonKeyStore',
+        )
+
+        device = bumble.device.Device.from_config_with_hci(
+            device_config,
+            hci_source,
+            hci_sink,
+        )
+        await device.power_on()
+
+        yield device
+
+
+async def find_broadcast_by_name(
+    device: bumble.device.Device, name: Optional[str]
+) -> BroadcastScanner.Broadcast:
+    result = asyncio.get_running_loop().create_future()
+
+    def on_broadcast_change(broadcast: BroadcastScanner.Broadcast) -> None:
+        if broadcast.basic_audio_announcement and not result.done():
+            print(color('Broadcast basic audio announcement received', 'green'))
+            result.set_result(broadcast)
+
+    def on_new_broadcast(broadcast: BroadcastScanner.Broadcast) -> None:
+        if name is None or broadcast.name == name:
+            print(color('Broadcast found:', 'green'), broadcast.name)
+            broadcast.on('change', lambda: on_broadcast_change(broadcast))
+            return
+
+        print(color(f'Skipping broadcast {broadcast.name}'))
+
+    scanner = BroadcastScanner(device, False, AURACAST_DEFAULT_SYNC_TIMEOUT)
+    scanner.on('new_broadcast', on_new_broadcast)
+    await scanner.start()
+
+    broadcast = await result
+    await scanner.stop()
+
+    return broadcast
+
+
+async def run_scan(
+    filter_duplicates: bool, sync_timeout: float, transport: str
+) -> None:
+    async with create_device(transport) as device:
+        if not device.supports_le_periodic_advertising:
+            print(color('Periodic advertising not supported', 'red'))
+            return
+
+        scanner = PrintingBroadcastScanner(device, filter_duplicates, sync_timeout)
+        await scanner.start()
+        await asyncio.get_running_loop().create_future()
+
+
+async def run_assist(
+    broadcast_name: Optional[str],
+    source_id: Optional[int],
+    command: str,
+    transport: str,
+    address: str,
+) -> None:
+    async with create_device(transport) as device:
+        if not device.supports_le_periodic_advertising:
+            print(color('Periodic advertising not supported', 'red'))
+            return
+
+        # Connect to the server
+        print(f'=== Connecting to {address}...')
+        connection = await device.connect(address)
+        peer = bumble.device.Peer(connection)
+        print(f'=== Connected to {peer}')
+
+        print("+++ Encrypting connection...")
+        await peer.connection.encrypt()
+        print("+++ Connection encrypted")
+
+        # Request a larger MTU
+        mtu = AURACAST_DEFAULT_ATT_MTU
+        print(color(f'$$$ Requesting MTU={mtu}', 'yellow'))
+        await peer.request_mtu(mtu)
+
+        # Get the BASS service
+        bass = await peer.discover_service_and_create_proxy(
+            bumble.profiles.bass.BroadcastAudioScanServiceProxy
+        )
+
+        # Check that the service was found
+        if not bass:
+            print(color('!!! Broadcast Audio Scan Service not found', 'red'))
+            return
+
+        # Subscribe to and read the broadcast receive state characteristics
+        for i, broadcast_receive_state in enumerate(bass.broadcast_receive_states):
+            try:
+                await broadcast_receive_state.subscribe(
+                    lambda value, i=i: print(
+                        f"{color(f'Broadcast Receive State Update [{i}]:', 'green')} {value}"
+                    )
+                )
+            except bumble.core.ProtocolError as error:
+                print(
+                    color(
+                        f'!!! Failed to subscribe to Broadcast Receive State characteristic:',
+                        'red',
+                    ),
+                    error,
+                )
+            value = await broadcast_receive_state.read_value()
+            print(
+                f'{color(f"Initial Broadcast Receive State [{i}]:", "green")} {value}'
+            )
+
+        if command == 'monitor-state':
+            await peer.sustain()
+            return
+
+        if command == 'add-source':
+            # Find the requested broadcast
+            await bass.remote_scan_started()
+            if broadcast_name:
+                print(color('Scanning for broadcast:', 'cyan'), broadcast_name)
+            else:
+                print(color('Scanning for any broadcast', 'cyan'))
+            broadcast = await find_broadcast_by_name(device, broadcast_name)
+
+            if broadcast.broadcast_audio_announcement is None:
+                print(color('No broadcast audio announcement found', 'red'))
+                return
+
+            if (
+                broadcast.basic_audio_announcement is None
+                or not broadcast.basic_audio_announcement.subgroups
+            ):
+                print(color('No subgroups found', 'red'))
+                return
+
+            # Add the source
+            print(color('Adding source:', 'blue'), broadcast.sync.advertiser_address)
+            await bass.add_source(
+                broadcast.sync.advertiser_address,
+                broadcast.sync.sid,
+                broadcast.broadcast_audio_announcement.broadcast_id,
+                bumble.profiles.bass.PeriodicAdvertisingSyncParams.SYNCHRONIZE_TO_PA_PAST_AVAILABLE,
+                0xFFFF,
+                [
+                    bumble.profiles.bass.SubgroupInfo(
+                        bumble.profiles.bass.SubgroupInfo.ANY_BIS,
+                        bytes(broadcast.basic_audio_announcement.subgroups[0].metadata),
+                    )
+                ],
+            )
+
+            # Initiate a PA Sync Transfer
+            await broadcast.sync.transfer(peer.connection)
+
+            # Notify the sink that we're done scanning.
+            await bass.remote_scan_stopped()
+
+            await peer.sustain()
+            return
+
+        if command == 'modify-source':
+            if source_id is None:
+                print(color('!!! modify-source requires --source-id'))
+                return
+
+            # Find the requested broadcast
+            await bass.remote_scan_started()
+            if broadcast_name:
+                print(color('Scanning for broadcast:', 'cyan'), broadcast_name)
+            else:
+                print(color('Scanning for any broadcast', 'cyan'))
+            broadcast = await find_broadcast_by_name(device, broadcast_name)
+
+            if broadcast.broadcast_audio_announcement is None:
+                print(color('No broadcast audio announcement found', 'red'))
+                return
+
+            if (
+                broadcast.basic_audio_announcement is None
+                or not broadcast.basic_audio_announcement.subgroups
+            ):
+                print(color('No subgroups found', 'red'))
+                return
+
+            # Modify the source
+            print(
+                color('Modifying source:', 'blue'),
+                source_id,
+            )
+            await bass.modify_source(
+                source_id,
+                bumble.profiles.bass.PeriodicAdvertisingSyncParams.SYNCHRONIZE_TO_PA_PAST_NOT_AVAILABLE,
+                0xFFFF,
+                [
+                    bumble.profiles.bass.SubgroupInfo(
+                        bumble.profiles.bass.SubgroupInfo.ANY_BIS,
+                        bytes(broadcast.basic_audio_announcement.subgroups[0].metadata),
+                    )
+                ],
+            )
+            await peer.sustain()
+            return
+
+        if command == 'remove-source':
+            if source_id is None:
+                print(color('!!! remove-source requires --source-id'))
+                return
+
+            # Remove the source
+            print(color('Removing source:', 'blue'), source_id)
+            await bass.remove_source(source_id)
+            await peer.sustain()
+            return
+
+        print(color(f'!!! invalid command {command}'))
+
+
+async def run_pair(transport: str, address: str) -> None:
+    async with create_device(transport) as device:
+
+        # Connect to the server
+        print(f'=== Connecting to {address}...')
+        async with device.connect_as_gatt(address) as peer:
+            print(f'=== Connected to {peer}')
+
+            print("+++ Initiating pairing...")
+            await peer.connection.pair()
+            print("+++ Paired")
+
+
+def run_async(async_command: Coroutine) -> None:
+    try:
+        asyncio.run(async_command)
+    except bumble.core.ProtocolError as error:
+        if error.error_namespace == 'att' and error.error_code in list(
+            bumble.profiles.bass.ApplicationError
+        ):
+            message = bumble.profiles.bass.ApplicationError(error.error_code).name
+        else:
+            message = str(error)
+
+        print(
+            color('!!! An error occurred while executing the command:', 'red'), message
+        )
+
+
+# -----------------------------------------------------------------------------
+# Main
+# -----------------------------------------------------------------------------
+@click.group()
+@click.pass_context
+def auracast(
+    ctx,
+):
+    ctx.ensure_object(dict)
+
+
+@auracast.command('scan')
+@click.option(
+    '--filter-duplicates', is_flag=True, default=False, help='Filter duplicates'
+)
+@click.option(
+    '--sync-timeout',
+    metavar='SYNC_TIMEOUT',
+    type=float,
+    default=AURACAST_DEFAULT_SYNC_TIMEOUT,
+    help='Sync timeout (in seconds)',
+)
+@click.argument('transport')
+@click.pass_context
+def scan(ctx, filter_duplicates, sync_timeout, transport):
+    """Scan for public broadcasts"""
+    run_async(run_scan(filter_duplicates, sync_timeout, transport))
+
+
+@auracast.command('assist')
+@click.option(
+    '--broadcast-name',
+    metavar='BROADCAST_NAME',
+    help='Broadcast Name to tune to',
+)
+@click.option(
+    '--source-id',
+    metavar='SOURCE_ID',
+    type=int,
+    help='Source ID (for remove-source command)',
+)
+@click.option(
+    '--command',
+    type=click.Choice(
+        ['monitor-state', 'add-source', 'modify-source', 'remove-source']
+    ),
+    required=True,
+)
+@click.argument('transport')
+@click.argument('address')
+@click.pass_context
+def assist(ctx, broadcast_name, source_id, command, transport, address):
+    """Scan for broadcasts on behalf of a audio server"""
+    run_async(run_assist(broadcast_name, source_id, command, transport, address))
+
+
+@auracast.command('pair')
+@click.argument('transport')
+@click.argument('address')
+@click.pass_context
+def pair(ctx, transport, address):
+    """Pair with an audio server"""
+    run_async(run_pair(transport, address))
+
+
+def main():
+    logging.basicConfig(level=os.environ.get('BUMBLE_LOGLEVEL', 'INFO').upper())
+    auracast()
+
+
+# -----------------------------------------------------------------------------
+if __name__ == "__main__":
+    main()  # pylint: disable=no-value-for-parameter

apps/ble_rpa_tool.py

@@ -0,0 +1,63 @@
+# Copyright 2023 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import click
+from bumble.colors import color
+from bumble.hci import Address
+from bumble.helpers import generate_irk, verify_rpa_with_irk
+
+
+@click.group()
+def cli():
+    '''
+    This is a tool for generating IRK, RPA,
+    and verifying IRK/RPA pairs
+    '''
+
+
+@click.command()
+def gen_irk() -> None:
+    print(generate_irk().hex())
+
+
+@click.command()
+@click.argument("irk", type=str)
+def gen_rpa(irk: str) -> None:
+    irk_bytes = bytes.fromhex(irk)
+    rpa = Address.generate_private_address(irk_bytes)
+    print(rpa.to_string(with_type_qualifier=False))
+
+
+@click.command()
+@click.argument("irk", type=str)
+@click.argument("rpa", type=str)
+def verify_rpa(irk: str, rpa: str) -> None:
+    address = Address(rpa)
+    irk_bytes = bytes.fromhex(irk)
+    if verify_rpa_with_irk(address, irk_bytes):
+        print(color("Verified", "green"))
+    else:
+        print(color("Not Verified", "red"))
+
+
+def main():
+    cli.add_command(gen_irk)
+    cli.add_command(gen_rpa)
+    cli.add_command(verify_rpa)
+    cli()
+
+
+# -----------------------------------------------------------------------------
+if __name__ == '__main__':
+    main()

apps/controller_info.py

@@ -18,52 +18,215 @@
 import asyncio
 import os
 import logging
-import click
-from colors import color
-from bumble.company_ids import COMPANY_IDENTIFIERS
+import time
 
+import click
+
+from bumble.company_ids import COMPANY_IDENTIFIERS
+from bumble.colors import color
 from bumble.core import name_or_number
 from bumble.hci import (
     map_null_terminated_utf8_string,
-    HCI_LE_SUPPORTED_FEATURES_NAMES,
+    CodecID,
+    LeFeature,
     HCI_SUCCESS,
     HCI_VERSION_NAMES,
     LMP_VERSION_NAMES,
     HCI_Command,
-    HCI_Read_BD_ADDR_Command,
+    HCI_Command_Complete_Event,
+    HCI_Command_Status_Event,
+    HCI_READ_BUFFER_SIZE_COMMAND,
+    HCI_Read_Buffer_Size_Command,
     HCI_READ_BD_ADDR_COMMAND,
+    HCI_Read_BD_ADDR_Command,
+    HCI_READ_LOCAL_NAME_COMMAND,
     HCI_Read_Local_Name_Command,
-    HCI_READ_LOCAL_NAME_COMMAND
+    HCI_LE_READ_BUFFER_SIZE_COMMAND,
+    HCI_LE_Read_Buffer_Size_Command,
+    HCI_LE_READ_MAXIMUM_DATA_LENGTH_COMMAND,
+    HCI_LE_Read_Maximum_Data_Length_Command,
+    HCI_LE_READ_NUMBER_OF_SUPPORTED_ADVERTISING_SETS_COMMAND,
+    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_SUGGESTED_DEFAULT_DATA_LENGTH_COMMAND,
+    HCI_LE_Read_Suggested_Default_Data_Length_Command,
+    HCI_Read_Local_Supported_Codecs_Command,
+    HCI_Read_Local_Supported_Codecs_V2_Command,
+    HCI_Read_Local_Version_Information_Command,
 )
 from bumble.host import Host
 from bumble.transport import open_transport_or_link
 
 
 # -----------------------------------------------------------------------------
-async def get_classic_info(host):
+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: Host) -> None:
     if host.supports_command(HCI_READ_BD_ADDR_COMMAND):
         response = await host.send_command(HCI_Read_BD_ADDR_Command())
-        if response.return_parameters.status == HCI_SUCCESS:
+        if command_succeeded(response):
             print()
-            print(color('Classic Address:', 'yellow'), response.return_parameters.bd_addr)
+            print(
+                color('Classic Address:', 'yellow'),
+                response.return_parameters.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 response.return_parameters.status == HCI_SUCCESS:
+        if command_succeeded(response):
             print()
-            print(color('Local Name:', 'yellow'), map_null_terminated_utf8_string(response.return_parameters.local_name))
+            print(
+                color('Local Name:', 'yellow'),
+                map_null_terminated_utf8_string(response.return_parameters.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',
+            )
+
+    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',
+            )
+
+    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):
+            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}'
+                ),
+                '\n',
+            )
+
+    if host.supports_command(HCI_LE_READ_SUGGESTED_DEFAULT_DATA_LENGTH_COMMAND):
+        response = await host.send_command(
+            HCI_LE_Read_Suggested_Default_Data_Length_Command()
+        )
+        if command_succeeded(response):
+            print(
+                color('Suggested Default Data Length:', 'yellow'),
+                f'{response.return_parameters.suggested_max_tx_octets}/'
+                f'{response.return_parameters.suggested_max_tx_time}',
+                '\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_acl_flow_control_info(host: Host) -> None:
+    print()
+
+    if host.supports_command(HCI_READ_BUFFER_SIZE_COMMAND):
+        response = await host.send_command(
+            HCI_Read_Buffer_Size_Command(), check_result=True
+        )
+        print(
+            color('ACL Flow Control:', 'yellow'),
+            f'{response.return_parameters.hc_total_num_acl_data_packets} '
+            f'packets of size {response.return_parameters.hc_acl_data_packet_length}',
+        )
+
+    if host.supports_command(HCI_LE_READ_BUFFER_SIZE_COMMAND):
+        response = await host.send_command(
+            HCI_LE_Read_Buffer_Size_Command(), check_result=True
+        )
+        print(
+            color('LE ACL Flow Control:', 'yellow'),
+            f'{response.return_parameters.hc_total_num_le_acl_data_packets} '
+            f'packets of size {response.return_parameters.hc_le_acl_data_packet_length}',
+        )
+
+
+# -----------------------------------------------------------------------------
+async def get_codecs_info(host: Host) -> None:
+    print()
+
+    if host.supports_command(HCI_Read_Local_Supported_Codecs_V2_Command.op_code):
+        response = await host.send_command(
+            HCI_Read_Local_Supported_Codecs_V2_Command(), check_result=True
+        )
+        print(color('Codecs:', 'yellow'))
+
+        for codec_id, transport in zip(
+            response.return_parameters.standard_codec_ids,
+            response.return_parameters.standard_codec_transports,
+        ):
+            transport_name = HCI_Read_Local_Supported_Codecs_V2_Command.Transport(
+                transport
+            ).name
+            codec_name = CodecID(codec_id).name
+            print(f'  {codec_name} - {transport_name}')
+
+        for codec_id, transport in zip(
+            response.return_parameters.vendor_specific_codec_ids,
+            response.return_parameters.vendor_specific_codec_transports,
+        ):
+            transport_name = HCI_Read_Local_Supported_Codecs_V2_Command.Transport(
+                transport
+            ).name
+            company = name_or_number(COMPANY_IDENTIFIERS, codec_id >> 16)
+            print(f'  {company} / {codec_id & 0xFFFF} - {transport_name}')
+
+        if not response.return_parameters.standard_codec_ids:
+            print('  No standard codecs')
+        if not response.return_parameters.vendor_specific_codec_ids:
+            print('  No Vendor-specific codecs')
+
+    if host.supports_command(HCI_Read_Local_Supported_Codecs_Command.op_code):
+        response = await host.send_command(
+            HCI_Read_Local_Supported_Codecs_Command(), check_result=True
+        )
+        print(color('Codecs (BR/EDR):', 'yellow'))
+        for codec_id in response.return_parameters.standard_codec_ids:
+            codec_name = CodecID(codec_id).name
+            print(f'  {codec_name}')
+
+        for codec_id in response.return_parameters.vendor_specific_codec_ids:
+            company = name_or_number(COMPANY_IDENTIFIERS, codec_id >> 16)
+            print(f'  {company} / {codec_id & 0xFFFF}')
+
+        if not response.return_parameters.standard_codec_ids:
+            print('  No standard codecs')
+        if not response.return_parameters.vendor_specific_codec_ids:
+            print('  No Vendor-specific codecs')
+
+
+# -----------------------------------------------------------------------------
+async def async_main(latency_probes, transport):
     print('<<< connecting to HCI...')
     async with await open_transport_or_link(transport) as (hci_source, hci_sink):
         print('<<< connected')
@@ -71,12 +234,38 @@ async def async_main(transport):
         host = Host(hci_source, hci_sink)
         await host.reset()
 
+        # Measure the latency if requested
+        latencies = []
+        if latency_probes:
+            for _ in range(latency_probes):
+                start = time.time()
+                await host.send_command(HCI_Read_Local_Version_Information_Command())
+                latencies.append(1000 * (time.time() - start))
+            print(
+                color('HCI Command Latency:', 'yellow'),
+                (
+                    f'min={min(latencies):.2f}, '
+                    f'max={max(latencies):.2f}, '
+                    f'average={sum(latencies)/len(latencies):.2f}'
+                ),
+                '\n',
+            )
+
         # Print version
         print(color('Version:', 'yellow'))
-        print(color('  Manufacturer:  ', 'green'), name_or_number(COMPANY_IDENTIFIERS, host.local_version.company_identifier))
-        print(color('  HCI Version:   ', 'green'), name_or_number(HCI_VERSION_NAMES, host.local_version.hci_version))
+        print(
+            color('  Manufacturer:  ', 'green'),
+            name_or_number(COMPANY_IDENTIFIERS, host.local_version.company_identifier),
+        )
+        print(
+            color('  HCI Version:   ', 'green'),
+            name_or_number(HCI_VERSION_NAMES, host.local_version.hci_version),
+        )
         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))
+        print(
+            color('  LMP Version:   ', 'green'),
+            name_or_number(LMP_VERSION_NAMES, host.local_version.lmp_version),
+        )
         print(color('  LMP Subversion:', 'green'), host.local_version.lmp_subversion)
 
         # Get the Classic info
@@ -85,19 +274,31 @@ async def async_main(transport):
         # Get the LE info
         await get_le_info(host)
 
+        # Print the ACL flow control info
+        await get_acl_flow_control_info(host)
+
+        # 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.argument('transport')
-def main(transport):
-    logging.basicConfig(level = os.environ.get('BUMBLE_LOGLEVEL', 'WARNING').upper())
-    asyncio.run(async_main(transport))
+def main(latency_probes, transport):
+    logging.basicConfig(level=os.environ.get('BUMBLE_LOGLEVEL', 'WARNING').upper())
+    asyncio.run(async_main(latency_probes, transport))
 
 
 # -----------------------------------------------------------------------------

apps/controller_loopback.py

@@ -0,0 +1,205 @@
+# Copyright 2024 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# -----------------------------------------------------------------------------
+# Imports
+# -----------------------------------------------------------------------------
+import asyncio
+import logging
+import os
+import time
+from typing import Optional
+from bumble.colors import color
+from bumble.hci import (
+    HCI_READ_LOOPBACK_MODE_COMMAND,
+    HCI_Read_Loopback_Mode_Command,
+    HCI_WRITE_LOOPBACK_MODE_COMMAND,
+    HCI_Write_Loopback_Mode_Command,
+    LoopbackMode,
+)
+from bumble.host import Host
+from bumble.transport import open_transport_or_link
+import click
+
+
+class Loopback:
+    """Send and receive ACL data packets in local loopback mode"""
+
+    def __init__(self, packet_size: int, packet_count: int, transport: str):
+        self.transport = transport
+        self.packet_size = packet_size
+        self.packet_count = packet_count
+        self.connection_handle: Optional[int] = None
+        self.connection_event = asyncio.Event()
+        self.done = asyncio.Event()
+        self.expected_cid = 0
+        self.bytes_received = 0
+        self.start_timestamp = 0.0
+        self.last_timestamp = 0.0
+
+    def on_connection(self, connection_handle: int, *args):
+        """Retrieve connection handle from new connection event"""
+        if not self.connection_event.is_set():
+            # save first connection handle for ACL
+            # subsequent connections are SCO
+            self.connection_handle = connection_handle
+            self.connection_event.set()
+
+    def on_l2cap_pdu(self, connection_handle: int, cid: int, pdu: bytes):
+        """Calculate packet receive speed"""
+        now = time.time()
+        print(f'<<< Received packet {cid}: {len(pdu)} bytes')
+        assert connection_handle == self.connection_handle
+        assert cid == self.expected_cid
+        self.expected_cid += 1
+        if cid == 0:
+            self.start_timestamp = now
+        else:
+            elapsed_since_start = now - self.start_timestamp
+            elapsed_since_last = now - self.last_timestamp
+            self.bytes_received += len(pdu)
+            instant_rx_speed = len(pdu) / elapsed_since_last
+            average_rx_speed = self.bytes_received / elapsed_since_start
+            print(
+                color(
+                    f'@@@ RX speed: instant={instant_rx_speed:.4f},'
+                    f' average={average_rx_speed:.4f}',
+                    'cyan',
+                )
+            )
+
+        self.last_timestamp = now
+
+        if self.expected_cid == self.packet_count:
+            print(color('@@@ Received last packet', 'green'))
+            self.done.set()
+
+    async def run(self):
+        """Run a loopback throughput test"""
+        print(color('>>> Connecting to HCI...', 'green'))
+        async with await open_transport_or_link(self.transport) as (
+            hci_source,
+            hci_sink,
+        ):
+            print(color('>>> Connected', 'green'))
+
+            host = Host(hci_source, hci_sink)
+            await host.reset()
+
+            # make sure data can fit in one l2cap pdu
+            l2cap_header_size = 4
+
+            max_packet_size = (
+                host.acl_packet_queue
+                if host.acl_packet_queue
+                else host.le_acl_packet_queue
+            ).max_packet_size - l2cap_header_size
+            if self.packet_size > max_packet_size:
+                print(
+                    color(
+                        f'!!! Packet size ({self.packet_size}) larger than max supported'
+                        f' size ({max_packet_size})',
+                        'red',
+                    )
+                )
+                return
+
+            if not host.supports_command(
+                HCI_WRITE_LOOPBACK_MODE_COMMAND
+            ) or not host.supports_command(HCI_READ_LOOPBACK_MODE_COMMAND):
+                print(color('!!! Loopback mode not supported', 'red'))
+                return
+
+            # set event callbacks
+            host.on('connection', self.on_connection)
+            host.on('l2cap_pdu', self.on_l2cap_pdu)
+
+            loopback_mode = LoopbackMode.LOCAL
+
+            print(color('### Setting loopback mode', 'blue'))
+            await host.send_command(
+                HCI_Write_Loopback_Mode_Command(loopback_mode=LoopbackMode.LOCAL),
+                check_result=True,
+            )
+
+            print(color('### Checking loopback mode', 'blue'))
+            response = await host.send_command(
+                HCI_Read_Loopback_Mode_Command(), check_result=True
+            )
+            if response.return_parameters.loopback_mode != loopback_mode:
+                print(color('!!! Loopback mode mismatch', 'red'))
+                return
+
+            await self.connection_event.wait()
+            print(color('### Connected', 'cyan'))
+
+            print(color('=== Start sending', 'magenta'))
+            start_time = time.time()
+            bytes_sent = 0
+            for cid in range(0, self.packet_count):
+                # using the cid as an incremental index
+                host.send_l2cap_pdu(
+                    self.connection_handle, cid, bytes(self.packet_size)
+                )
+                print(
+                    color(
+                        f'>>> Sending packet {cid}: {self.packet_size} bytes', 'yellow'
+                    )
+                )
+                bytes_sent += self.packet_size  # don't count L2CAP or HCI header sizes
+                await asyncio.sleep(0)  # yield to allow packet receive
+
+            await self.done.wait()
+            print(color('=== Done!', 'magenta'))
+
+            elapsed = time.time() - start_time
+            average_tx_speed = bytes_sent / elapsed
+            print(
+                color(
+                    f'@@@ TX speed: average={average_tx_speed:.4f} ({bytes_sent} bytes'
+                    f' in {elapsed:.2f} seconds)',
+                    'green',
+                )
+            )
+
+
+# -----------------------------------------------------------------------------
+@click.command()
+@click.option(
+    '--packet-size',
+    '-s',
+    metavar='SIZE',
+    type=click.IntRange(8, 4096),
+    default=500,
+    help='Packet size',
+)
+@click.option(
+    '--packet-count',
+    '-c',
+    metavar='COUNT',
+    type=click.IntRange(1, 65535),
+    default=10,
+    help='Packet count',
+)
+@click.argument('transport')
+def main(packet_size, packet_count, transport):
+    logging.basicConfig(level=os.environ.get('BUMBLE_LOGLEVEL', 'WARNING').upper())
+
+    loopback = Loopback(packet_size, packet_count, transport)
+    asyncio.run(loopback.run())
+
+
+# -----------------------------------------------------------------------------
+if __name__ == '__main__':
+    main()

apps/controllers.py

@@ -28,11 +28,14 @@ from bumble.transport import open_transport_or_link
 # -----------------------------------------------------------------------------
 async def async_main():
     if len(sys.argv) != 3:
-        print('Usage: controllers.py <hci-transport-1> <hci-transport-2> [<hci-transport-3> ...]')
+        print(
+            'Usage: controllers.py <hci-transport-1> <hci-transport-2> '
+            '[<hci-transport-3> ...]'
+        )
         print('example: python controllers.py pty:ble1 pty:ble2')
         return
 
-    # Create a loccal link to attach the controllers to
+    # Create a local link to attach the controllers to
     link = LocalLink()
 
     # Create a transport and controller for all requested names
@@ -41,7 +44,12 @@ async def async_main():
     for index, transport_name in enumerate(sys.argv[1:]):
         transport = await open_transport_or_link(transport_name)
         transports.append(transport)
-        controller = Controller(f'C{index}', host_source = transport.source, host_sink = transport.sink, link = link)
+        controller = Controller(
+            f'C{index}',
+            host_source=transport.source,
+            host_sink=transport.sink,
+            link=link,
+        )
         controllers.append(controller)
 
     # Wait until the user interrupts
@@ -54,7 +62,7 @@ async def async_main():
 
 # -----------------------------------------------------------------------------
 def main():
-    logging.basicConfig(level = os.environ.get('BUMBLE_LOGLEVEL', 'INFO').upper())
+    logging.basicConfig(level=os.environ.get('BUMBLE_LOGLEVEL', 'INFO').upper())
     asyncio.run(async_main())
 
 

apps/device_info.py

@@ -0,0 +1,230 @@
+# 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
+import os
+import logging
+from typing import Callable, Iterable, Optional
+
+import click
+
+from bumble.core import ProtocolError
+from bumble.colors import color
+from bumble.device import Device, Peer
+from bumble.gatt import Service
+from bumble.profiles.device_information_service import DeviceInformationServiceProxy
+from bumble.profiles.battery_service import BatteryServiceProxy
+from bumble.profiles.gap import GenericAccessServiceProxy
+from bumble.profiles.tmap import TelephonyAndMediaAudioServiceProxy
+from bumble.transport import open_transport_or_link
+
+
+# -----------------------------------------------------------------------------
+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:
+        print(
+            color('  Role:', 'green'),
+            await tmas.role.read_value(),
+        )
+
+    print()
+
+
+# -----------------------------------------------------------------------------
+async def show_device_info(peer, done: Optional[asyncio.Future]) -> 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 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_or_link(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.
+    """
+    logging.basicConfig(level=os.environ.get('BUMBLE_LOGLEVEL', 'INFO').upper())
+    asyncio.run(async_main(device_config, encrypt, transport, address_or_name))
+
+
+# -----------------------------------------------------------------------------
+if __name__ == '__main__':
+    main()

apps/gatt_dump.py

@@ -19,9 +19,9 @@ import asyncio
 import os
 import logging
 import click
-from colors import color
 
-from bumble.core import ProtocolError, TimeoutError
+import bumble.core
+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
@@ -49,9 +49,9 @@ async def dump_gatt_db(peer, done):
         try:
             value = await attribute.read_value()
             print(color(f'{value.hex()}', 'green'))
-        except ProtocolError as error:
+        except bumble.core.ProtocolError as error:
             print(color(error, 'red'))
-        except TimeoutError:
+        except bumble.core.TimeoutError:
             print(color('read timeout', 'red'))
 
     if done is not None:
@@ -64,24 +64,37 @@ async def async_main(device_config, encrypt, transport, address_or_name):
 
         # Create a device
         if device_config:
-            device = Device.from_config_file_with_hci(device_config, hci_source, hci_sink)
+            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)
+            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 dump_gatt_db(Peer(connection), None)
         else:
             # Wait for a connection
             done = asyncio.get_running_loop().create_future()
-            device.on('connection', lambda connection: asyncio.create_task(dump_gatt_db(Peer(connection), done)))
+            device.on(
+                'connection',
+                lambda connection: asyncio.create_task(
+                    dump_gatt_db(Peer(connection), done)
+                ),
+            )
             await device.start_advertising(auto_restart=True)
 
             print(color('### Waiting for connection...', 'blue'))
@@ -99,7 +112,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())
+    logging.basicConfig(level=os.environ.get('BUMBLE_LOGLEVEL', 'INFO').upper())
     asyncio.run(async_main(device_config, encrypt, transport, address_or_name))
 
 

apps/gg_bridge.py

@@ -17,13 +17,15 @@
 # -----------------------------------------------------------------------------
 import asyncio
 import os
+import struct
 import logging
 import click
-from colors import color
 
+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
+from bumble.gatt import Service, Characteristic, CharacteristicValue
 from bumble.utils import AsyncRunner
 from bumble.transport import open_transport_or_link
 from bumble.hci import HCI_Constant
@@ -32,24 +34,73 @@ from bumble.hci import HCI_Constant
 # -----------------------------------------------------------------------------
 # Constants
 # -----------------------------------------------------------------------------
-GG_GATTLINK_SERVICE_UUID                          = 'ABBAFF00-E56A-484C-B832-8B17CF6CBFE8'
-GG_GATTLINK_RX_CHARACTERISTIC_UUID                = 'ABBAFF01-E56A-484C-B832-8B17CF6CBFE8'
-GG_GATTLINK_TX_CHARACTERISTIC_UUID                = 'ABBAFF02-E56A-484C-B832-8B17CF6CBFE8'
-GG_GATTLINK_L2CAP_CHANNEL_PSM_CHARACTERISTIC_UUID = 'ABBAFF03-E56A-484C-B832-8B17CF6CBFE8'
+GG_GATTLINK_SERVICE_UUID = 'ABBAFF00-E56A-484C-B832-8B17CF6CBFE8'
+GG_GATTLINK_RX_CHARACTERISTIC_UUID = 'ABBAFF01-E56A-484C-B832-8B17CF6CBFE8'
+GG_GATTLINK_TX_CHARACTERISTIC_UUID = 'ABBAFF02-E56A-484C-B832-8B17CF6CBFE8'
+GG_GATTLINK_L2CAP_CHANNEL_PSM_CHARACTERISTIC_UUID = (
+    'ABBAFF03-E56A-484C-B832-8B17CF6CBFE8'
+)
 
 GG_PREFERRED_MTU = 256
 
 
 # -----------------------------------------------------------------------------
-class GattlinkHubBridge(Device.Listener):
+class GattlinkL2capEndpoint:
     def __init__(self):
-        self.peer              = None
-        self.rx_socket         = None
-        self.tx_socket         = None
+        self.l2cap_channel = None
+        self.l2cap_packet = b''
+        self.l2cap_packet_size = 0
+
+    # Called when an L2CAP SDU has been received
+    def on_coc_sdu(self, sdu):
+        print(color(f'<<< [L2CAP SDU]: {len(sdu)} bytes', 'cyan'))
+        while len(sdu):
+            if self.l2cap_packet_size == 0:
+                # Expect a new packet
+                self.l2cap_packet_size = sdu[0] + 1
+                sdu = sdu[1:]
+            else:
+                bytes_needed = self.l2cap_packet_size - len(self.l2cap_packet)
+                chunk = min(bytes_needed, len(sdu))
+                self.l2cap_packet += sdu[:chunk]
+                sdu = sdu[chunk:]
+                if len(self.l2cap_packet) == self.l2cap_packet_size:
+                    self.on_l2cap_packet(self.l2cap_packet)
+                    self.l2cap_packet = b''
+                    self.l2cap_packet_size = 0
+
+
+# -----------------------------------------------------------------------------
+class GattlinkHubBridge(GattlinkL2capEndpoint, Device.Listener):
+    def __init__(self, device, peer_address):
+        super().__init__()
+        self.device = device
+        self.peer_address = peer_address
+        self.peer = None
+        self.tx_socket = None
         self.rx_characteristic = None
         self.tx_characteristic = None
+        self.l2cap_psm_characteristic = None
+
+        device.listener = self
+
+    async def start(self):
+        # Connect to the peer
+        print(f'=== Connecting to {self.peer_address}...')
+        await self.device.connect(self.peer_address)
+
+    async def connect_l2cap(self, psm):
+        print(color(f'### Connecting with L2CAP on PSM = {psm}', 'yellow'))
+        try:
+            self.l2cap_channel = await self.peer.connection.open_l2cap_channel(psm)
+            print(color('*** Connected', 'yellow'), self.l2cap_channel)
+            self.l2cap_channel.sink = self.on_coc_sdu
+
+        except Exception as error:
+            print(color(f'!!! Connection failed: {error}', 'red'))
 
     @AsyncRunner.run_in_task()
+    # pylint: disable=invalid-overridden-method
     async def on_connection(self, connection):
         print(f'=== Connected to {connection}')
         self.peer = Peer(connection)
@@ -80,115 +131,226 @@ class GattlinkHubBridge(Device.Listener):
                 self.rx_characteristic = characteristic
             elif characteristic.uuid == GG_GATTLINK_TX_CHARACTERISTIC_UUID:
                 self.tx_characteristic = characteristic
+            elif (
+                characteristic.uuid == GG_GATTLINK_L2CAP_CHANNEL_PSM_CHARACTERISTIC_UUID
+            ):
+                self.l2cap_psm_characteristic = characteristic
         print('RX:', self.rx_characteristic)
         print('TX:', self.tx_characteristic)
+        print('PSM:', self.l2cap_psm_characteristic)
 
-        # Subscribe to TX
-        if self.tx_characteristic:
+        if self.l2cap_psm_characteristic:
+            # Subscribe to and then read the PSM value
+            await self.peer.subscribe(
+                self.l2cap_psm_characteristic, self.on_l2cap_psm_received
+            )
+            psm_bytes = await self.peer.read_value(self.l2cap_psm_characteristic)
+            psm = struct.unpack('<H', psm_bytes)[0]
+            await self.connect_l2cap(psm)
+        elif self.tx_characteristic:
+            # Subscribe to TX
             await self.peer.subscribe(self.tx_characteristic, self.on_tx_received)
             print(color('=== Subscribed to Gattlink TX', 'yellow'))
         else:
-            print(color('!!! Gattlink TX not found', 'red'))
+            print(color('!!! No Gattlink TX or PSM found', 'red'))
 
     def on_connection_failure(self, error):
         print(color(f'!!! Connection failed: {error}'))
 
     def on_disconnection(self, reason):
-        print(color(f'!!! Disconnected from {self.peer}, reason={HCI_Constant.error_name(reason)}', 'red'))
+        print(
+            color(
+                f'!!! Disconnected from {self.peer}, '
+                f'reason={HCI_Constant.error_name(reason)}',
+                'red',
+            )
+        )
         self.tx_characteristic = None
         self.rx_characteristic = None
         self.peer = None
 
+    # Called when an L2CAP packet has been received
+    def on_l2cap_packet(self, packet):
+        print(color(f'<<< [L2CAP PACKET]: {len(packet)} bytes', 'cyan'))
+        print(color('>>> [UDP]', 'magenta'))
+        self.tx_socket.sendto(packet)
+
     # Called by the GATT client when a notification is received
     def on_tx_received(self, value):
-        print(color('>>> TX:', 'magenta'), value.hex())
+        print(color(f'<<< [GATT TX]: {len(value)} bytes', 'cyan'))
         if self.tx_socket:
+            print(color('>>> [UDP]', 'magenta'))
             self.tx_socket.sendto(value)
 
     # Called by asyncio when the UDP socket is created
-    def connection_made(self, transport):
-        pass
-
-    # Called by asyncio when a UDP datagram is received
-    def datagram_received(self, data, address):
-        print(color('<<< RX:', 'magenta'), data.hex())
-
-        # TODO: use a queue instead of creating a task everytime
-        if self.peer and self.rx_characteristic:
-            asyncio.create_task(self.peer.write_value(self.rx_characteristic, data))
-
-
-# -----------------------------------------------------------------------------
-class GattlinkNodeBridge(Device.Listener):
-    def __init__(self):
-        self.peer      = None
-        self.rx_socket = None
-        self.tx_socket = None
+    def on_l2cap_psm_received(self, value):
+        psm = struct.unpack('<H', value)[0]
+        asyncio.create_task(self.connect_l2cap(psm))
 
     # Called by asyncio when the UDP socket is created
     def connection_made(self, transport):
         pass
 
     # Called by asyncio when a UDP datagram is received
-    def datagram_received(self, data, address):
-        print(color('<<< RX:', 'magenta'), data.hex())
+    def datagram_received(self, data, _address):
+        print(color(f'<<< [UDP]: {len(data)} bytes', 'green'))
 
-        # TODO: use a queue instead of creating a task everytime
-        if self.peer and self.rx_characteristic:
+        if self.l2cap_channel:
+            print(color('>>> [L2CAP]', 'yellow'))
+            self.l2cap_channel.write(bytes([len(data) - 1]) + data)
+        elif self.peer and self.rx_characteristic:
+            print(color('>>> [GATT RX]', 'yellow'))
             asyncio.create_task(self.peer.write_value(self.rx_characteristic, data))
 
 
 # -----------------------------------------------------------------------------
-async def run(hci_transport, device_address, send_host, send_port, receive_host, receive_port):
+class GattlinkNodeBridge(GattlinkL2capEndpoint, Device.Listener):
+    def __init__(self, device: Device):
+        super().__init__()
+        self.device = device
+        self.peer = None
+        self.tx_socket = None
+        self.tx_subscriber = None
+        self.rx_characteristic = None
+        self.transport = None
+
+        # Register as a listener
+        device.listener = self
+
+        # Listen for incoming L2CAP CoC connections
+        psm = 0xFB
+        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
+        self.rx_characteristic = Characteristic(
+            GG_GATTLINK_RX_CHARACTERISTIC_UUID,
+            Characteristic.WRITE_WITHOUT_RESPONSE,
+            Characteristic.WRITEABLE,
+            CharacteristicValue(write=self.on_rx_write),
+        )
+        self.tx_characteristic = Characteristic(
+            GG_GATTLINK_TX_CHARACTERISTIC_UUID,
+            Characteristic.Properties.NOTIFY,
+            Characteristic.READABLE,
+        )
+        self.tx_characteristic.on('subscription', self.on_tx_subscription)
+        self.psm_characteristic = Characteristic(
+            GG_GATTLINK_L2CAP_CHANNEL_PSM_CHARACTERISTIC_UUID,
+            Characteristic.Properties.READ | Characteristic.Properties.NOTIFY,
+            Characteristic.READABLE,
+            bytes([psm, 0]),
+        )
+        gattlink_service = Service(
+            GG_GATTLINK_SERVICE_UUID,
+            [self.rx_characteristic, self.tx_characteristic, self.psm_characteristic],
+        )
+        device.add_services([gattlink_service])
+        device.advertising_data = bytes(
+            AdvertisingData(
+                [
+                    (AdvertisingData.COMPLETE_LOCAL_NAME, bytes('Bumble GG', 'utf-8')),
+                    (
+                        AdvertisingData.INCOMPLETE_LIST_OF_128_BIT_SERVICE_CLASS_UUIDS,
+                        bytes(
+                            reversed(bytes.fromhex('ABBAFF00E56A484CB8328B17CF6CBFE8'))
+                        ),
+                    ),
+                ]
+            )
+        )
+
+    async def start(self):
+        await self.device.start_advertising()
+
+    # Called by asyncio when the UDP socket is created
+    def connection_made(self, transport):
+        self.transport = transport
+
+    # Called by asyncio when a UDP datagram is received
+    def datagram_received(self, data, _address):
+        print(color(f'<<< [UDP]: {len(data)} bytes', 'green'))
+
+        if self.l2cap_channel:
+            print(color('>>> [L2CAP]', 'yellow'))
+            self.l2cap_channel.write(bytes([len(data) - 1]) + data)
+        elif self.tx_subscriber:
+            print(color('>>> [GATT TX]', 'yellow'))
+            self.tx_characteristic.value = data
+            asyncio.create_task(self.device.notify_subscribers(self.tx_characteristic))
+
+    # Called when a write to the RX characteristic has been received
+    def on_rx_write(self, _connection, data):
+        print(color(f'<<< [GATT RX]: {len(data)} bytes', 'cyan'))
+        print(color('>>> [UDP]', 'magenta'))
+        self.tx_socket.sendto(data)
+
+    # Called when the subscription to the TX characteristic has changed
+    def on_tx_subscription(self, peer, enabled):
+        print(
+            f'### [GATT TX] subscription from {peer}: '
+            f'{"enabled" if enabled else "disabled"}'
+        )
+        if enabled:
+            self.tx_subscriber = peer
+        else:
+            self.tx_subscriber = None
+
+    # Called when an L2CAP packet is received
+    def on_l2cap_packet(self, packet):
+        print(color(f'<<< [L2CAP PACKET]: {len(packet)} bytes', 'cyan'))
+        print(color('>>> [UDP]', 'magenta'))
+        self.tx_socket.sendto(packet)
+
+    # Called when a new connection is established
+    def on_coc(self, channel):
+        print('*** CoC Connection', channel)
+        self.l2cap_channel = channel
+        channel.sink = self.on_coc_sdu
+
+
+# -----------------------------------------------------------------------------
+async def run(
+    hci_transport,
+    device_address,
+    role_or_peer_address,
+    send_host,
+    send_port,
+    receive_host,
+    receive_port,
+):
     print('<<< connecting to HCI...')
     async with await open_transport_or_link(hci_transport) as (hci_source, hci_sink):
         print('<<< connected')
 
         # Instantiate a bridge object
-        bridge = GattlinkNodeBridge()
+        device = Device.with_hci('Bumble GG', device_address, hci_source, hci_sink)
+
+        # Instantiate a bridge object
+        if role_or_peer_address == 'node':
+            bridge = GattlinkNodeBridge(device)
+        else:
+            bridge = GattlinkHubBridge(device, role_or_peer_address)
 
         # Create a UDP to RX bridge (receive from UDP, send to RX)
         loop = asyncio.get_running_loop()
         await loop.create_datagram_endpoint(
-            lambda: bridge,
-            local_addr=(receive_host, receive_port)
+            lambda: bridge, local_addr=(receive_host, receive_port)
         )
 
         # Create a UDP to TX bridge (receive from TX, send to UDP)
         bridge.tx_socket, _ = await loop.create_datagram_endpoint(
-            lambda: asyncio.DatagramProtocol(),
-            remote_addr=(send_host, send_port)
+            asyncio.DatagramProtocol,
+            remote_addr=(send_host, send_port),
         )
 
-        # Create a device to manage the host, with a custom listener
-        device = Device.with_hci('Bumble', 'F0:F1:F2:F3:F4:F5', hci_source, hci_sink)
-        device.listener = bridge
         await device.power_on()
-
-        # Connect to the peer
-        # print(f'=== Connecting to {device_address}...')
-        # await device.connect(device_address)
-
-        # TODO move to class
-        gattlink_service = Service(
-            GG_GATTLINK_SERVICE_UUID,
-            [
-                Characteristic(
-                    GG_GATTLINK_L2CAP_CHANNEL_PSM_CHARACTERISTIC_UUID,
-                    Characteristic.READ,
-                    Characteristic.READABLE,
-                    bytes([193, 0])
-                )
-            ]
-        )
-        device.add_services([gattlink_service])
-        device.advertising_data = bytes(
-            AdvertisingData([
-                (AdvertisingData.COMPLETE_LOCAL_NAME, bytes('Bumble GG', 'utf-8')),
-                (AdvertisingData.INCOMPLETE_LIST_OF_128_BIT_SERVICE_CLASS_UUIDS, bytes(reversed(bytes.fromhex('ABBAFF00E56A484CB8328B17CF6CBFE8'))))
-            ])
-        )
-        await device.start_advertising()
+        await bridge.start()
 
         # Wait until the source terminates
         await hci_source.wait_for_termination()
@@ -197,15 +359,44 @@ async def run(hci_transport, device_address, send_host, send_port, receive_host,
 @click.command()
 @click.argument('hci_transport')
 @click.argument('device_address')
-@click.option('-sh', '--send-host', type=str, default='127.0.0.1', help='UDP host to send to')
+@click.argument('role_or_peer_address')
+@click.option(
+    '-sh', '--send-host', type=str, default='127.0.0.1', help='UDP host to send to'
+)
 @click.option('-sp', '--send-port', type=int, default=9001, help='UDP port to send to')
-@click.option('-rh', '--receive-host', type=str, default='127.0.0.1', help='UDP host to receive on')
-@click.option('-rp', '--receive-port', type=int, default=9000, help='UDP port to receive on')
-def main(hci_transport, device_address, send_host, send_port, receive_host, receive_port):
-    logging.basicConfig(level = os.environ.get('BUMBLE_LOGLEVEL', 'INFO').upper())
-    asyncio.run(run(hci_transport, device_address, send_host, send_port, receive_host, receive_port))
+@click.option(
+    '-rh',
+    '--receive-host',
+    type=str,
+    default='127.0.0.1',
+    help='UDP host to receive on',
+)
+@click.option(
+    '-rp', '--receive-port', type=int, default=9000, help='UDP port to receive on'
+)
+def main(
+    hci_transport,
+    device_address,
+    role_or_peer_address,
+    send_host,
+    send_port,
+    receive_host,
+    receive_port,
+):
+    asyncio.run(
+        run(
+            hci_transport,
+            device_address,
+            role_or_peer_address,
+            send_host,
+            send_port,
+            receive_host,
+            receive_port,
+        )
+    )
 
 
 # -----------------------------------------------------------------------------
+logging.basicConfig(level=os.environ.get('BUMBLE_LOGLEVEL', 'WARNING').upper())
 if __name__ == '__main__':
     main()

apps/hci_bridge.py

@@ -34,16 +34,29 @@ logger = logging.getLogger(__name__)
 # -----------------------------------------------------------------------------
 async def async_main():
     if len(sys.argv) < 3:
-        print('Usage: hci_bridge.py <host-transport-spec> <controller-transport-spec> [command-short-circuit-list]')
-        print('example: python hci_bridge.py udp:0.0.0.0:9000,127.0.0.1:9001 serial:/dev/tty.usbmodem0006839912171,1000000 0x3f:0x0070,0x3f:0x0074,0x3f:0x0077,0x3f:0x0078')
+        print(
+            'Usage: hci_bridge.py <host-transport-spec> <controller-transport-spec> '
+            '[command-short-circuit-list]'
+        )
+        print(
+            'example: python hci_bridge.py udp:0.0.0.0:9000,127.0.0.1:9001 '
+            'serial:/dev/tty.usbmodem0006839912171,1000000 '
+            '0x3f:0x0070,0x3f:0x0074,0x3f:0x0077,0x3f:0x0078'
+        )
         return
 
     print('>>> connecting to HCI...')
-    async with await transport.open_transport_or_link(sys.argv[1]) as (hci_host_source, hci_host_sink):
+    async with await transport.open_transport_or_link(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 (hci_controller_source, hci_controller_sink):
+        async with await transport.open_transport_or_link(sys.argv[2]) as (
+            hci_controller_source,
+            hci_controller_sink,
+        ):
             print('>>> connected')
 
             command_short_circuits = []
@@ -51,36 +64,43 @@ async def async_main():
                 for op_code_str in sys.argv[3].split(','):
                     if ':' in op_code_str:
                         ogf, ocf = op_code_str.split(':')
-                        command_short_circuits.append(hci.hci_command_op_code(int(ogf, 16), int(ocf, 16)))
+                        command_short_circuits.append(
+                            hci.hci_command_op_code(int(ogf, 16), int(ocf, 16))
+                        )
                     else:
                         command_short_circuits.append(int(op_code_str, 16))
 
             def host_to_controller_filter(hci_packet):
-                if hci_packet.hci_packet_type == hci.HCI_COMMAND_PACKET and hci_packet.op_code in command_short_circuits:
+                if (
+                    hci_packet.hci_packet_type == hci.HCI_COMMAND_PACKET
+                    and hci_packet.op_code in command_short_circuits
+                ):
                     # Respond with a success response
                     logger.debug('short-circuiting packet')
                     response = hci.HCI_Command_Complete_Event(
-                        num_hci_command_packets = 1,
-                        command_opcode          = hci_packet.op_code,
-                        return_parameters       = bytes([hci.HCI_SUCCESS])
+                        num_hci_command_packets=1,
+                        command_opcode=hci_packet.op_code,
+                        return_parameters=bytes([hci.HCI_SUCCESS]),
                     )
                     # Return a packet with 'respond to sender' set to True
                     return (response.to_bytes(), True)
 
+                return None
+
             _ = HCI_Bridge(
                 hci_host_source,
                 hci_host_sink,
                 hci_controller_source,
                 hci_controller_sink,
                 host_to_controller_filter,
-                None
+                None,
             )
             await asyncio.get_running_loop().create_future()
 
 
 # -----------------------------------------------------------------------------
 def main():
-    logging.basicConfig(level = os.environ.get('BUMBLE_LOGLEVEL', 'INFO').upper())
+    logging.basicConfig(level=os.environ.get('BUMBLE_LOGLEVEL', 'INFO').upper())
     asyncio.run(async_main())
 
 

apps/l2cap_bridge.py

@@ -0,0 +1,361 @@
+# 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
+import logging
+import os
+import click
+
+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
+
+
+# -----------------------------------------------------------------------------
+class ServerBridge:
+    """
+    L2CAP CoC server bridge: waits for a peer to connect an L2CAP CoC channel
+    on a specified PSM. 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 L2CAP CoC channel is closed, the bridge disconnects the TCP socket
+    and waits for a new L2CAP CoC channel to be connected.
+    When the TCP connection is closed by the TCP server, XXXX
+    """
+
+    def __init__(self, psm, max_credits, mtu, mps, tcp_host, tcp_port):
+        self.psm = psm
+        self.max_credits = max_credits
+        self.mtu = mtu
+        self.mps = mps
+        self.tcp_host = tcp_host
+        self.tcp_port = tcp_port
+
+    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')
+        )
+
+        def on_ble_connection(connection):
+            def on_ble_disconnection(reason):
+                print(
+                    color('@@@ Bluetooth disconnection:', 'red'),
+                    HCI_Constant.error_name(reason),
+                )
+
+            print(color('@@@ Bluetooth connection:', 'green'), connection)
+            connection.on('disconnection', on_ble_disconnection)
+
+        device.on('connection', on_ble_connection)
+
+        await device.start_advertising(auto_restart=True)
+
+    # Called when a new L2CAP connection is established
+    def on_channel(self, l2cap_channel):
+        print(color('*** L2CAP channel:', 'cyan'), l2cap_channel)
+
+        class Pipe:
+            def __init__(self, bridge, l2cap_channel):
+                self.bridge = bridge
+                self.tcp_transport = None
+                self.l2cap_channel = l2cap_channel
+
+                l2cap_channel.on('close', self.on_l2cap_close)
+                l2cap_channel.sink = self.on_channel_sdu
+
+            async def connect_to_tcp(self):
+                # Connect to the TCP server
+                print(
+                    color(
+                        f'### Connecting to TCP {self.bridge.tcp_host}:'
+                        f'{self.bridge.tcp_port}...',
+                        'yellow',
+                    )
+                )
+
+                class TcpClientProtocol(asyncio.Protocol):
+                    def __init__(self, pipe):
+                        self.pipe = pipe
+
+                    def connection_lost(self, exc):
+                        print(color(f'!!! TCP connection lost: {exc}', 'red'))
+                        if self.pipe.l2cap_channel is not None:
+                            asyncio.create_task(self.pipe.l2cap_channel.disconnect())
+
+                    def data_received(self, data):
+                        print(color(f'<<< [TCP DATA]: {len(data)} bytes', 'blue'))
+                        self.pipe.l2cap_channel.write(data)
+
+                try:
+                    (
+                        self.tcp_transport,
+                        _,
+                    ) = await asyncio.get_running_loop().create_connection(
+                        lambda: TcpClientProtocol(self),
+                        host=self.bridge.tcp_host,
+                        port=self.bridge.tcp_port,
+                    )
+                    print(color('### Connected', 'green'))
+                except Exception as error:
+                    print(color(f'!!! Connection failed: {error}', 'red'))
+                    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_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'))
+                    return
+                self.tcp_transport.write(sdu)
+
+        pipe = Pipe(self, l2cap_channel)
+
+        asyncio.create_task(pipe.connect_to_tcp())
+
+
+# -----------------------------------------------------------------------------
+class ClientBridge:
+    """
+    L2CAP CoC client bridge: connects to a BLE device, then waits for an inbound
+    TCP connection on a specified port number. When a TCP client connects, an
+    L2CAP CoC channel connection to the BLE device is established, and the data
+    is bridged in both directions, with flow control.
+    When the TCP connection is closed by the client, the L2CAP CoC channel is
+    disconnected, but the connection to the BLE device remains, ready for a new
+    TCP client to connect.
+    When the L2CAP CoC channel is closed, XXXX
+    """
+
+    READ_CHUNK_SIZE = 4096
+
+    def __init__(self, psm, max_credits, mtu, mps, address, tcp_host, tcp_port):
+        self.psm = psm
+        self.max_credits = max_credits
+        self.mtu = mtu
+        self.mps = mps
+        self.address = address
+        self.tcp_host = tcp_host
+        self.tcp_port = tcp_port
+
+    async def start(self, device):
+        print(color(f'### Connecting to {self.address}...', 'yellow'))
+        connection = await device.connect(self.address)
+        print(color('### Connected', 'green'))
+
+        # Called when the BLE connection is disconnected
+        def on_ble_disconnection(reason):
+            print(
+                color('@@@ Bluetooth disconnection:', 'red'),
+                HCI_Constant.error_name(reason),
+            )
+
+        connection.on('disconnection', on_ble_disconnection)
+
+        # Called when a TCP connection is established
+        async def on_tcp_connection(reader, writer):
+            peer_name = writer.get_extra_info('peer_name')
+            print(color(f'<<< TCP connection from {peer_name}', 'magenta'))
+
+            def on_channel_sdu(sdu):
+                print(color(f'<<< [L2CAP SDU]: {len(sdu)} bytes', 'cyan'))
+                l2cap_to_tcp_pipe.write(sdu)
+
+            def on_l2cap_close():
+                print(color('*** L2CAP channel closed', 'red'))
+                l2cap_to_tcp_pipe.stop()
+                writer.close()
+
+            # Connect a new L2CAP channel
+            print(color(f'>>> Opening L2CAP channel on PSM = {self.psm}', 'yellow'))
+            try:
+                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:
+                print(color(f'!!! Connection failed: {error}', 'red'))
+                writer.close()
+                return
+
+            l2cap_channel.sink = on_channel_sdu
+            l2cap_channel.on('close', on_l2cap_close)
+
+            # Start a flow control pipe from L2CAP to TCP
+            l2cap_to_tcp_pipe = FlowControlAsyncPipe(
+                l2cap_channel.pause_reading,
+                l2cap_channel.resume_reading,
+                writer.write,
+                writer.drain,
+            )
+            l2cap_to_tcp_pipe.start()
+
+            # Pipe data from TCP to L2CAP
+            while True:
+                try:
+                    data = await reader.read(self.READ_CHUNK_SIZE)
+
+                    if len(data) == 0:
+                        print(color('!!! End of stream', 'red'))
+                        await l2cap_channel.disconnect()
+                        return
+
+                    print(color(f'<<< [TCP DATA]: {len(data)} bytes', 'blue'))
+                    l2cap_channel.write(data)
+                    await l2cap_channel.drain()
+                except Exception as error:
+                    print(f'!!! Exception: {error}')
+                    break
+
+            writer.close()
+            print(color('~~~ Bye bye', 'magenta'))
+
+        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 run(device_config, hci_transport, bridge):
+    print('<<< connecting to HCI...')
+    async with await open_transport_or_link(hci_transport) as (hci_source, hci_sink):
+        print('<<< connected')
+
+        device = Device.from_config_file_with_hci(device_config, hci_source, hci_sink)
+
+        # Let's go
+        await device.power_on()
+        await bridge.start(device)
+
+        # Wait until the transport terminates
+        await hci_source.wait_for_termination()
+
+
+# -----------------------------------------------------------------------------
+@click.group()
+@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', type=int, default=1234)
+@click.option(
+    '--l2cap-max-credits',
+    help='Maximum L2CAP Credits',
+    type=click.IntRange(1, 65535),
+    default=128,
+)
+@click.option(
+    '--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-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(
+    context,
+    device_config,
+    hci_transport,
+    psm,
+    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_max_credits
+    context.obj['mtu'] = l2cap_mtu
+    context.obj['mps'] = l2cap_mps
+
+
+# -----------------------------------------------------------------------------
+@cli.command()
+@click.pass_context
+@click.option('--tcp-host', help='TCP host', default='localhost')
+@click.option('--tcp-port', help='TCP port', default=9544)
+def server(context, tcp_host, tcp_port):
+    bridge = ServerBridge(
+        context.obj['psm'],
+        context.obj['max_credits'],
+        context.obj['mtu'],
+        context.obj['mps'],
+        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=9543)
+def client(context, bluetooth_address, tcp_host, tcp_port):
+    bridge = ClientBridge(
+        context.obj['psm'],
+        context.obj['max_credits'],
+        context.obj['mtu'],
+        context.obj['mps'],
+        bluetooth_address,
+        tcp_host,
+        tcp_port,
+    )
+    asyncio.run(run(context.obj['device_config'], context.obj['hci_transport'], bridge))
+
+
+# -----------------------------------------------------------------------------
+logging.basicConfig(level=os.environ.get('BUMBLE_LOGLEVEL', 'WARNING').upper())
+if __name__ == '__main__':
+    cli(obj={})  # pylint: disable=no-value-for-parameter

apps/lea_unicast/app.py

@@ -0,0 +1,576 @@
+# Copyright 2021-2024 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# -----------------------------------------------------------------------------
+# Imports
+# -----------------------------------------------------------------------------
+from __future__ import annotations
+import asyncio
+import datetime
+import enum
+import functools
+from importlib import resources
+import json
+import os
+import logging
+import pathlib
+from typing import Optional, List, cast
+import weakref
+import struct
+
+import ctypes
+import wasmtime
+import wasmtime.loader
+import liblc3  # type: ignore
+
+import click
+import aiohttp.web
+
+import bumble
+from bumble.core import AdvertisingData
+from bumble.colors import color
+from bumble.device import Device, DeviceConfiguration, AdvertisingParameters
+from bumble.transport import open_transport
+from bumble.profiles import ascs, bap, pacs
+from bumble.hci import Address, CodecID, CodingFormat, HCI_IsoDataPacket
+
+# -----------------------------------------------------------------------------
+# Logging
+# -----------------------------------------------------------------------------
+logger = logging.getLogger(__name__)
+
+# -----------------------------------------------------------------------------
+# Constants
+# -----------------------------------------------------------------------------
+DEFAULT_UI_PORT = 7654
+
+
+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,
+        ),
+    )
+
+
+# -----------------------------------------------------------------------------
+# WASM - liblc3
+# -----------------------------------------------------------------------------
+store = wasmtime.loader.store
+_memory = cast(wasmtime.Memory, liblc3.memory)
+STACK_POINTER = _memory.data_len(store)
+_memory.grow(store, 1)
+# Mapping wasmtime memory to linear address
+memory = (ctypes.c_ubyte * _memory.data_len(store)).from_address(
+    ctypes.addressof(_memory.data_ptr(store).contents)  # type: ignore
+)
+
+
+class Liblc3PcmFormat(enum.IntEnum):
+    S16 = 0
+    S24 = 1
+    S24_3LE = 2
+    FLOAT = 3
+
+
+MAX_DECODER_SIZE = liblc3.lc3_decoder_size(10000, 48000)
+MAX_ENCODER_SIZE = liblc3.lc3_encoder_size(10000, 48000)
+
+DECODER_STACK_POINTER = STACK_POINTER
+ENCODER_STACK_POINTER = DECODER_STACK_POINTER + MAX_DECODER_SIZE * 2
+DECODE_BUFFER_STACK_POINTER = ENCODER_STACK_POINTER + MAX_ENCODER_SIZE * 2
+ENCODE_BUFFER_STACK_POINTER = DECODE_BUFFER_STACK_POINTER + 8192
+DEFAULT_PCM_SAMPLE_RATE = 48000
+DEFAULT_PCM_FORMAT = Liblc3PcmFormat.S16
+DEFAULT_PCM_BYTES_PER_SAMPLE = 2
+
+
+encoders: List[int] = []
+decoders: List[int] = []
+
+
+def setup_encoders(
+    sample_rate_hz: int, frame_duration_us: int, num_channels: int
+) -> None:
+    logger.info(
+        f"setup_encoders {sample_rate_hz}Hz {frame_duration_us}us {num_channels}channels"
+    )
+    encoders[:num_channels] = [
+        liblc3.lc3_setup_encoder(
+            frame_duration_us,
+            sample_rate_hz,
+            DEFAULT_PCM_SAMPLE_RATE,  # Input sample rate
+            ENCODER_STACK_POINTER + MAX_ENCODER_SIZE * i,
+        )
+        for i in range(num_channels)
+    ]
+
+
+def setup_decoders(
+    sample_rate_hz: int, frame_duration_us: int, num_channels: int
+) -> None:
+    logger.info(
+        f"setup_decoders {sample_rate_hz}Hz {frame_duration_us}us {num_channels}channels"
+    )
+    decoders[:num_channels] = [
+        liblc3.lc3_setup_decoder(
+            frame_duration_us,
+            sample_rate_hz,
+            DEFAULT_PCM_SAMPLE_RATE,  # Output sample rate
+            DECODER_STACK_POINTER + MAX_DECODER_SIZE * i,
+        )
+        for i in range(num_channels)
+    ]
+
+
+def decode(
+    frame_duration_us: int,
+    num_channels: int,
+    input_bytes: bytes,
+) -> bytes:
+    if not input_bytes:
+        return b''
+
+    input_buffer_offset = DECODE_BUFFER_STACK_POINTER
+    input_buffer_size = len(input_bytes)
+    input_bytes_per_frame = input_buffer_size // num_channels
+
+    # Copy into wasm
+    memory[input_buffer_offset : input_buffer_offset + input_buffer_size] = input_bytes  # type: ignore
+
+    output_buffer_offset = input_buffer_offset + input_buffer_size
+    output_buffer_size = (
+        liblc3.lc3_frame_samples(frame_duration_us, DEFAULT_PCM_SAMPLE_RATE)
+        * DEFAULT_PCM_BYTES_PER_SAMPLE
+        * num_channels
+    )
+
+    for i in range(num_channels):
+        res = liblc3.lc3_decode(
+            decoders[i],
+            input_buffer_offset + input_bytes_per_frame * i,
+            input_bytes_per_frame,
+            DEFAULT_PCM_FORMAT,
+            output_buffer_offset + i * DEFAULT_PCM_BYTES_PER_SAMPLE,
+            num_channels,  # Stride
+        )
+
+        if res != 0:
+            logging.error(f"Parsing failed, res={res}")
+
+    # Extract decoded data from the output buffer
+    return bytes(
+        memory[output_buffer_offset : output_buffer_offset + output_buffer_size]
+    )
+
+
+def encode(
+    sdu_length: int,
+    num_channels: int,
+    stride: int,
+    input_bytes: bytes,
+) -> bytes:
+    if not input_bytes:
+        return b''
+
+    input_buffer_offset = ENCODE_BUFFER_STACK_POINTER
+    input_buffer_size = len(input_bytes)
+
+    # Copy into wasm
+    memory[input_buffer_offset : input_buffer_offset + input_buffer_size] = input_bytes  # type: ignore
+
+    output_buffer_offset = input_buffer_offset + input_buffer_size
+    output_buffer_size = sdu_length
+    output_frame_size = output_buffer_size // num_channels
+
+    for i in range(num_channels):
+        res = liblc3.lc3_encode(
+            encoders[i],
+            DEFAULT_PCM_FORMAT,
+            input_buffer_offset + DEFAULT_PCM_BYTES_PER_SAMPLE * i,
+            stride,
+            output_frame_size,
+            output_buffer_offset + output_frame_size * i,
+        )
+
+        if res != 0:
+            logging.error(f"Parsing failed, res={res}")
+
+    # Extract decoded data from the output buffer
+    return bytes(
+        memory[output_buffer_offset : output_buffer_offset + output_buffer_size]
+    )
+
+
+async def lc3_source_task(
+    filename: str,
+    sdu_length: int,
+    frame_duration_us: int,
+    device: Device,
+    cis_handle: int,
+) -> None:
+    with open(filename, 'rb') as f:
+        header = f.read(44)
+        assert header[8:12] == b'WAVE'
+
+        pcm_num_channel, pcm_sample_rate, _byte_rate, _block_align, bits_per_sample = (
+            struct.unpack("<HIIHH", header[22:36])
+        )
+        assert pcm_sample_rate == DEFAULT_PCM_SAMPLE_RATE
+        assert bits_per_sample == DEFAULT_PCM_BYTES_PER_SAMPLE * 8
+
+        frame_bytes = (
+            liblc3.lc3_frame_samples(frame_duration_us, DEFAULT_PCM_SAMPLE_RATE)
+            * DEFAULT_PCM_BYTES_PER_SAMPLE
+        )
+        packet_sequence_number = 0
+
+        while True:
+            next_round = datetime.datetime.now() + datetime.timedelta(
+                microseconds=frame_duration_us
+            )
+            pcm_data = f.read(frame_bytes)
+            sdu = encode(sdu_length, pcm_num_channel, pcm_num_channel, pcm_data)
+
+            iso_packet = HCI_IsoDataPacket(
+                connection_handle=cis_handle,
+                data_total_length=sdu_length + 4,
+                packet_sequence_number=packet_sequence_number,
+                pb_flag=0b10,
+                packet_status_flag=0,
+                iso_sdu_length=sdu_length,
+                iso_sdu_fragment=sdu,
+            )
+            device.host.send_hci_packet(iso_packet)
+            packet_sequence_number += 1
+            sleep_time = next_round - datetime.datetime.now()
+            await asyncio.sleep(sleep_time.total_seconds())
+
+
+# -----------------------------------------------------------------------------
+class UiServer:
+    speaker: weakref.ReferenceType[Speaker]
+    port: int
+
+    def __init__(self, speaker: Speaker, port: int) -> None:
+        self.speaker = weakref.ref(speaker)
+        self.port = port
+        self.channel_socket = None
+
+    async def start_http(self) -> None:
+        """Start the UI HTTP server."""
+
+        app = aiohttp.web.Application()
+        app.add_routes(
+            [
+                aiohttp.web.get('/', self.get_static),
+                aiohttp.web.get('/index.html', self.get_static),
+                aiohttp.web.get('/channel', self.get_channel),
+            ]
+        )
+
+        runner = aiohttp.web.AppRunner(app)
+        await runner.setup()
+        site = aiohttp.web.TCPSite(runner, 'localhost', self.port)
+        print('UI HTTP server at ' + color(f'http://127.0.0.1:{self.port}', 'green'))
+        await site.start()
+
+    async def get_static(self, request):
+        path = request.path
+        if path == '/':
+            path = '/index.html'
+        if path.endswith('.html'):
+            content_type = 'text/html'
+        elif path.endswith('.js'):
+            content_type = 'text/javascript'
+        elif path.endswith('.css'):
+            content_type = 'text/css'
+        elif path.endswith('.svg'):
+            content_type = 'image/svg+xml'
+        else:
+            content_type = 'text/plain'
+        text = (
+            resources.files("bumble.apps.lea_unicast")
+            .joinpath(pathlib.Path(path).relative_to('/'))
+            .read_text(encoding="utf-8")
+        )
+        return aiohttp.web.Response(text=text, content_type=content_type)
+
+    async def get_channel(self, request):
+        ws = aiohttp.web.WebSocketResponse()
+        await ws.prepare(request)
+
+        # Process messages until the socket is closed.
+        self.channel_socket = ws
+        async for message in ws:
+            if message.type == aiohttp.WSMsgType.TEXT:
+                logger.debug(f'<<< received message: {message.data}')
+                await self.on_message(message.data)
+            elif message.type == aiohttp.WSMsgType.ERROR:
+                logger.debug(
+                    f'channel connection closed with exception {ws.exception()}'
+                )
+
+        self.channel_socket = None
+        logger.debug('--- channel connection closed')
+
+        return ws
+
+    async def on_message(self, message_str: str):
+        # Parse the message as JSON
+        message = json.loads(message_str)
+
+        # Dispatch the message
+        message_type = message['type']
+        message_params = message.get('params', {})
+        handler = getattr(self, f'on_{message_type}_message')
+        if handler:
+            await handler(**message_params)
+
+    async def on_hello_message(self):
+        await self.send_message(
+            'hello',
+            bumble_version=bumble.__version__,
+            codec=self.speaker().codec,
+            streamState=self.speaker().stream_state.name,
+        )
+        if connection := self.speaker().connection:
+            await self.send_message(
+                'connection',
+                peer_address=connection.peer_address.to_string(False),
+                peer_name=connection.peer_name,
+            )
+
+    async def send_message(self, message_type: str, **kwargs) -> None:
+        if self.channel_socket is None:
+            return
+
+        message = {'type': message_type, 'params': kwargs}
+        await self.channel_socket.send_json(message)
+
+    async def send_audio(self, data: bytes) -> None:
+        if self.channel_socket is None:
+            return
+
+        try:
+            await self.channel_socket.send_bytes(data)
+        except Exception as error:
+            logger.warning(f'exception while sending audio packet: {error}')
+
+
+# -----------------------------------------------------------------------------
+class Speaker:
+
+    def __init__(
+        self,
+        device_config_path: Optional[str],
+        ui_port: int,
+        transport: str,
+        lc3_input_file_path: str,
+    ):
+        self.device_config_path = device_config_path
+        self.transport = transport
+        self.lc3_input_file_path = lc3_input_file_path
+
+        # Create an HTTP server for the UI
+        self.ui_server = UiServer(speaker=self, port=ui_port)
+
+    async def run(self) -> None:
+        await self.ui_server.start_http()
+
+        async with await open_transport(self.transport) as hci_transport:
+            # Create a device
+            if self.device_config_path:
+                device_config = DeviceConfiguration.from_file(self.device_config_path)
+            else:
+                device_config = DeviceConfiguration(
+                    name="Bumble LE Headphone",
+                    class_of_device=0x244418,
+                    keystore="JsonKeyStore",
+                    advertising_interval_min=25,
+                    advertising_interval_max=25,
+                    address=Address('F1:F2:F3:F4:F5:F6'),
+                )
+
+            device_config.le_enabled = True
+            device_config.cis_enabled = True
+            self.device = Device.from_config_with_hci(
+                device_config, hci_transport.source, hci_transport.sink
+            )
+
+            self.device.add_service(
+                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(
+                    [
+                        (
+                            AdvertisingData.COMPLETE_LOCAL_NAME,
+                            bytes(device_config.name, 'utf-8'),
+                        ),
+                        (
+                            AdvertisingData.FLAGS,
+                            bytes([AdvertisingData.LE_GENERAL_DISCOVERABLE_MODE_FLAG]),
+                        ),
+                        (
+                            AdvertisingData.INCOMPLETE_LIST_OF_16_BIT_SERVICE_CLASS_UUIDS,
+                            bytes(pacs.PublishedAudioCapabilitiesService.UUID),
+                        ),
+                    ]
+                )
+            ) + bytes(bap.UnicastServerAdvertisingData())
+
+            def on_pdu(pdu: HCI_IsoDataPacket, ase: ascs.AseStateMachine):
+                codec_config = ase.codec_specific_configuration
+                assert isinstance(codec_config, bap.CodecSpecificConfiguration)
+                pcm = decode(
+                    codec_config.frame_duration.us,
+                    codec_config.audio_channel_allocation.channel_count,
+                    pdu.iso_sdu_fragment,
+                )
+                self.device.abort_on('disconnection', self.ui_server.send_audio(pcm))
+
+            def on_ase_state_change(ase: ascs.AseStateMachine) -> None:
+                if ase.state == ascs.AseStateMachine.State.STREAMING:
+                    codec_config = ase.codec_specific_configuration
+                    assert isinstance(codec_config, bap.CodecSpecificConfiguration)
+                    assert ase.cis_link
+                    if ase.role == ascs.AudioRole.SOURCE:
+                        ase.cis_link.abort_on(
+                            'disconnection',
+                            lc3_source_task(
+                                filename=self.lc3_input_file_path,
+                                sdu_length=(
+                                    codec_config.codec_frames_per_sdu
+                                    * codec_config.octets_per_codec_frame
+                                ),
+                                frame_duration_us=codec_config.frame_duration.us,
+                                device=self.device,
+                                cis_handle=ase.cis_link.handle,
+                            ),
+                        )
+                    else:
+                        ase.cis_link.sink = functools.partial(on_pdu, ase=ase)
+                elif ase.state == ascs.AseStateMachine.State.CODEC_CONFIGURED:
+                    codec_config = ase.codec_specific_configuration
+                    assert isinstance(codec_config, bap.CodecSpecificConfiguration)
+                    if ase.role == ascs.AudioRole.SOURCE:
+                        setup_encoders(
+                            codec_config.sampling_frequency.hz,
+                            codec_config.frame_duration.us,
+                            codec_config.audio_channel_allocation.channel_count,
+                        )
+                    else:
+                        setup_decoders(
+                            codec_config.sampling_frequency.hz,
+                            codec_config.frame_duration.us,
+                            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():
+    logging.basicConfig(level=os.environ.get('BUMBLE_LOGLEVEL', 'WARNING').upper())
+    speaker()
+
+
+# -----------------------------------------------------------------------------
+if __name__ == "__main__":
+    main()  # pylint: disable=no-value-for-parameter

apps/lea_unicast/index.html

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

apps/link_relay/link_relay.py

@@ -16,7 +16,6 @@
 # Imports
 # ----------------------------------------------------------------------------
 import sys
-import websockets
 import logging
 import json
 import asyncio
@@ -24,7 +23,9 @@ import argparse
 import uuid
 import os
 from urllib.parse import urlparse
-from colors import color
+import websockets
+
+from bumble.colors import color
 
 # -----------------------------------------------------------------------------
 # Logging
@@ -65,9 +66,9 @@ class Connection:
     """
 
     def __init__(self, room, websocket):
-        self.room      = room
+        self.room = room
         self.websocket = websocket
-        self.address   = str(uuid.uuid4())
+        self.address = str(uuid.uuid4())
 
     async def send_message(self, message):
         try:
@@ -98,7 +99,11 @@ class Connection:
         self.address = address
 
     def __str__(self):
-        return f'Connection(address="{self.address}", client={self.websocket.remote_address[0]}:{self.websocket.remote_address[1]})'
+        return (
+            f'Connection(address="{self.address}", '
+            f'client={self.websocket.remote_address[0]}:'
+            f'{self.websocket.remote_address[1]})'
+        )
 
 
 # ----------------------------------------------------------------------------
@@ -110,9 +115,9 @@ class Room:
     """
 
     def __init__(self, relay, name):
-        self.relay       = relay
-        self.name        = name
-        self.observers   = []
+        self.relay = relay
+        self.name = name
+        self.observers = []
         self.connections = []
 
     async def add_connection(self, connection):
@@ -139,13 +144,15 @@ class Room:
 
             # Parse the message to decide how to handle it
             if message.startswith('@'):
-                # This is a targetted message
-                await self.on_targetted_message(connection, message)
+                # 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")}')
+                await connection.send_message(
+                    f'result:{error_to_json("error: invalid message")}'
+                )
 
     async def broadcast_message(self, sender, message):
         '''
@@ -155,7 +162,9 @@ class Room:
 
     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):
+        if handler := getattr(
+            self, f'on_{command[1:].lower().replace("-","_")}_command', None
+        ):
             try:
                 result = await handler(connection, params)
             except Exception as error:
@@ -165,7 +174,7 @@ class Room:
 
         await connection.send_message(result or 'result:{}')
 
-    async def on_targetted_message(self, connection, message):
+    async def on_targeted_message(self, connection, message):
         target, *payload = message.split(' ', 1)
         if not payload:
             return error_to_json('missing arguments')
@@ -174,7 +183,8 @@ class Room:
 
         # Determine what targets to send to
         if target == '*':
-            # Send to all connections in the room except the connection from which the message was received
+            # 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)
@@ -192,7 +202,9 @@ class Room:
         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}')
+        await self.broadcast_message(
+            connection, f'address-changed:from={current_address},to={new_address}'
+        )
 
 
 # ----------------------------------------------------------------------------
@@ -210,9 +222,10 @@ class Relay:
     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(connection):
+    async def serve_as_controller(self, connection):
         pass
 
     async def serve(self, websocket, path):
@@ -246,24 +259,24 @@ def main():
         print('ERROR: Python 3.6.1 or higher is required')
         sys.exit(1)
 
-    logging.basicConfig(level = os.environ.get('BUMBLE_LOGLEVEL', 'INFO').upper())
+    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')
+    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
+        from logging import config  # pylint: disable=import-outside-toplevel
+
         config.fileConfig(args.log_config)
     else:
-        logging.basicConfig(level = getattr(logging, args.log_level.upper()))
+        logging.basicConfig(level=getattr(logging, args.log_level.upper()))
 
     # Start a relay
     relay = Relay(args.port)

apps/pair.py

@@ -19,44 +19,85 @@ import asyncio
 import os
 import logging
 import click
-import aioconsole
-from colors import color
+from prompt_toolkit.shortcuts import PromptSession
 
+from bumble.colors import color
 from bumble.device import Device, Peer
 from bumble.transport import open_transport_or_link
-from bumble.smp import PairingDelegate, PairingConfig
+from bumble.pairing import OobData, PairingDelegate, PairingConfig
+from bumble.smp import OobContext, OobLegacyContext
 from bumble.smp import error_name as smp_error_name
 from bumble.keys import JsonKeyStore
-from bumble.core import ProtocolError
+from bumble.core import (
+    AdvertisingData,
+    ProtocolError,
+    BT_LE_TRANSPORT,
+    BT_BR_EDR_TRANSPORT,
+)
 from bumble.gatt import (
     GATT_DEVICE_NAME_CHARACTERISTIC,
     GATT_GENERIC_ACCESS_SERVICE,
     Service,
     Characteristic,
-    CharacteristicValue
+    CharacteristicValue,
 )
 from bumble.att import (
     ATT_Error,
     ATT_INSUFFICIENT_AUTHENTICATION_ERROR,
-    ATT_INSUFFICIENT_ENCRYPTION_ERROR
+    ATT_INSUFFICIENT_ENCRYPTION_ERROR,
 )
+from bumble.utils import AsyncRunner
+
+# -----------------------------------------------------------------------------
+# Constants
+# -----------------------------------------------------------------------------
+POST_PAIRING_DELAY = 1
+
+
+# -----------------------------------------------------------------------------
+class Waiter:
+    instance = None
+
+    def __init__(self, linger=False):
+        self.done = asyncio.get_running_loop().create_future()
+        self.linger = linger
+
+    def terminate(self):
+        if not self.linger:
+            self.done.set_result(None)
+
+    async def wait_until_terminated(self):
+        return await self.done
 
 
 # -----------------------------------------------------------------------------
 class Delegate(PairingDelegate):
-    def __init__(self, mode, connection, capability_string, prompt):
-        super().__init__({
-            'keyboard':         PairingDelegate.KEYBOARD_INPUT_ONLY,
-            'display':          PairingDelegate.DISPLAY_OUTPUT_ONLY,
-            'display+keyboard': PairingDelegate.DISPLAY_OUTPUT_AND_KEYBOARD_INPUT,
-            'display+yes/no':   PairingDelegate.DISPLAY_OUTPUT_AND_YES_NO_INPUT,
-            'none':             PairingDelegate.NO_OUTPUT_NO_INPUT
-        }[capability_string.lower()])
+    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,
+                'display+yes/no': PairingDelegate.DISPLAY_OUTPUT_AND_YES_NO_INPUT,
+                'none': PairingDelegate.NO_OUTPUT_NO_INPUT,
+            }[capability_string.lower()]
+        )
 
-        self.mode      = mode
-        self.peer      = Peer(connection)
+        self.mode = mode
+        self.peer = Peer(connection)
         self.peer_name = None
-        self.prompt    = prompt
+        self.do_prompt = do_prompt
+
+    def print(self, message):
+        print(color(message, 'yellow'))
+
+    async def prompt(self, message):
+        # Wait a bit to allow some of the log lines to print before we prompt
+        await asyncio.sleep(1)
+
+        session = PromptSession(message)
+        response = await session.prompt_async()
+        return response.lower().strip()
 
     async def update_peer_name(self):
         if self.peer_name is not None:
@@ -71,87 +112,103 @@ class Delegate(PairingDelegate):
             self.peer_name = '[?]'
 
     async def accept(self):
-        if self.prompt:
+        if self.do_prompt:
             await self.update_peer_name()
 
-            # Wait a bit to allow some of the log lines to print before we prompt
-            await asyncio.sleep(1)
-
             # Prompt for acceptance
-            print(color('###-----------------------------------', 'yellow'))
-            print(color(f'### Pairing request from {self.peer_name}', 'yellow'))
-            print(color('###-----------------------------------', 'yellow'))
+            self.print('###-----------------------------------')
+            self.print(f'### Pairing request from {self.peer_name}')
+            self.print('###-----------------------------------')
             while True:
-                response = await aioconsole.ainput(color('>>> Accept? ', 'yellow'))
-                response = response.lower().strip()
+                response = await self.prompt('>>> Accept? ')
+
                 if response == 'yes':
                     return True
-                elif response == 'no':
+
+                if response == 'no':
                     return False
-        else:
-            # Accept silently
-            return True
+
+        # Accept silently
+        return True
 
     async def compare_numbers(self, number, digits):
         await self.update_peer_name()
 
-        # Wait a bit to allow some of the log lines to print before we prompt
-        await asyncio.sleep(1)
-
         # Prompt for a numeric comparison
-        print(color('###-----------------------------------', 'yellow'))
-        print(color(f'### Pairing with {self.peer_name}', 'yellow'))
-        print(color('###-----------------------------------', 'yellow'))
+        self.print('###-----------------------------------')
+        self.print(f'### Pairing with {self.peer_name}')
+        self.print('###-----------------------------------')
         while True:
-            response = await aioconsole.ainput(color(f'>>> Does the other device display {number:0{digits}}? ', 'yellow'))
-            response = response.lower().strip()
+            response = await self.prompt(
+                f'>>> Does the other device display {number:0{digits}}? '
+            )
+
             if response == 'yes':
                 return True
-            elif response == 'no':
+
+            if response == 'no':
                 return False
 
     async def get_number(self):
         await self.update_peer_name()
 
-        # Wait a bit to allow some of the log lines to print before we prompt
-        await asyncio.sleep(1)
-
         # Prompt for a PIN
         while True:
             try:
-                print(color('###-----------------------------------', 'yellow'))
-                print(color(f'### Pairing with {self.peer_name}', 'yellow'))
-                print(color('###-----------------------------------', 'yellow'))
-                return int(await aioconsole.ainput(color('>>> Enter PIN: ', 'yellow')))
+                self.print('###-----------------------------------')
+                self.print(f'### Pairing with {self.peer_name}')
+                self.print('###-----------------------------------')
+                return int(await self.prompt('>>> Enter PIN: '))
             except ValueError:
                 pass
 
     async def display_number(self, number, digits):
         await self.update_peer_name()
 
-        # Wait a bit to allow some of the log lines to print before we prompt
-        await asyncio.sleep(1)
-
         # Display a PIN code
-        print(color('###-----------------------------------', 'yellow'))
-        print(color(f'### Pairing with {self.peer_name}', 'yellow'))
-        print(color(f'### PIN: {number:0{digits}}', 'yellow'))
-        print(color('###-----------------------------------', 'yellow'))
+        self.print('###-----------------------------------')
+        self.print(f'### Pairing with {self.peer_name}')
+        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':
         return await peer.request_name()
-    else:
-        # Try to get the peer name from GATT
-        services = await peer.discover_service(GATT_GENERIC_ACCESS_SERVICE)
-        if not services:
-            return None
 
-        values = await peer.read_characteristics_by_uuid(GATT_DEVICE_NAME_CHARACTERISTIC, services[0])
-        if values:
-            return values[0].decode('utf-8')
+    # Try to get the peer name from GATT
+    services = await peer.discover_service(GATT_GENERIC_ACCESS_SERVICE)
+    if not services:
+        return None
+
+    values = await peer.read_characteristics_by_uuid(
+        GATT_DEVICE_NAME_CHARACTERISTIC, services[0]
+    )
+    if values:
+        return values[0].decode('utf-8')
+
+    return None
 
 
 # -----------------------------------------------------------------------------
@@ -164,12 +221,12 @@ def read_with_error(connection):
 
     if AUTHENTICATION_ERROR_RETURNED[0]:
         return bytes([1])
-    else:
-        AUTHENTICATION_ERROR_RETURNED[0] = True
-        raise ATT_Error(ATT_INSUFFICIENT_AUTHENTICATION_ERROR)
+
+    AUTHENTICATION_ERROR_RETURNED[0] = True
+    raise ATT_Error(ATT_INSUFFICIENT_AUTHENTICATION_ERROR)
 
 
-def write_with_error(connection, value):
+def write_with_error(connection, _value):
     if not connection.is_encrypted:
         raise ATT_Error(ATT_INSUFFICIENT_ENCRYPTION_ERROR)
 
@@ -183,14 +240,16 @@ 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',         on_pairing)
-    connection.on('pairing_failure', on_pairing_failure)
+    connection.on('pairing_start', on_pairing_start)
+    connection.on('pairing', lambda keys: on_pairing(connection, keys))
+    connection.on(
+        'pairing_failure', lambda reason: on_pairing_failure(connection, reason)
+    )
 
     # Listen for encryption changes
     connection.on(
         'connection_encryption_change',
-        lambda: on_connection_encryption_change(connection)
+        lambda: on_connection_encryption_change(connection),
     )
 
     # Request pairing if needed
@@ -202,7 +261,12 @@ def on_connection(connection, request):
 # -----------------------------------------------------------------------------
 def on_connection_encryption_change(connection):
     print(color('@@@-----------------------------------', 'blue'))
-    print(color(f'@@@ Connection is {"" if connection.is_encrypted else "not"}encrypted', 'blue'))
+    print(
+        color(
+            f'@@@ Connection is {"" if connection.is_encrypted else "not"}encrypted',
+            'blue',
+        )
+    )
     print(color('@@@-----------------------------------', 'blue'))
 
 
@@ -214,18 +278,25 @@ def on_pairing_start():
 
 
 # -----------------------------------------------------------------------------
-def on_pairing(keys):
+@AsyncRunner.run_in_task()
+async def on_pairing(connection, keys):
     print(color('***-----------------------------------', 'cyan'))
-    print(color('*** Paired!', '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_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()
 
 
 # -----------------------------------------------------------------------------
@@ -234,15 +305,21 @@ async def pair(
     sc,
     mitm,
     bond,
+    ctkd,
+    identity_address,
+    linger,
     io,
+    oob,
     prompt,
     request,
     print_keys,
     keystore_file,
     device_config,
     hci_transport,
-    address_or_name
+    address_or_name,
 ):
+    Waiter.instance = Waiter(linger=linger)
+
     print('<<< connecting to HCI...')
     async with await open_transport_or_link(hci_transport) as (hci_source, hci_sink):
         print('<<< connected')
@@ -250,9 +327,38 @@ async def pair(
         # Create a device to manage the host
         device = Device.from_config_file_with_hci(device_config, hci_source, hci_sink)
 
+        # Expose a GATT characteristic that can be used to trigger pairing by
+        # responding with an authentication error when read
+        if mode == 'le':
+            device.le_enabled = True
+            device.add_service(
+                Service(
+                    '50DB505C-8AC4-4738-8448-3B1D9CC09CC5',
+                    [
+                        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
+                            ),
+                        )
+                    ],
+                )
+            )
+
+        # Select LE or Classic
+        if mode == 'classic':
+            device.classic_enabled = True
+            device.classic_smp_enabled = ctkd
+
+        # Get things going
+        await device.power_on()
+
         # Set a custom keystore if specified on the command line
         if keystore_file:
-            device.keystore = JsonKeyStore(namespace=None, filename=keystore_file)
+            device.keystore = JsonKeyStore.from_device(device, filename=keystore_file)
 
         # Print the existing keys before pairing
         if print_keys and device.keystore:
@@ -261,44 +367,58 @@ async def pair(
             await device.keystore.print(prefix=color('@@@ ', 'blue'))
             print(color('@@@-----------------------------------', 'blue'))
 
-        # Expose a GATT characteristic that can be used to trigger pairing by
-        # responding with an authentication error when read
-        if mode == 'le':
-            device.add_service(
-                Service(
-                    '50DB505C-8AC4-4738-8448-3B1D9CC09CC5',
-                    [
-                        Characteristic(
-                            '552957FB-CF1F-4A31-9535-E78847E1A714',
-                            Characteristic.READ | Characteristic.WRITE,
-                            Characteristic.READABLE | Characteristic.WRITEABLE,
-                            CharacteristicValue(read=read_with_error, write=write_with_error)
-                        )
-                    ]
-                )
+        # Create an OOB context if needed
+        if oob:
+            our_oob_context = OobContext()
+            shared_data = (
+                None
+                if oob == '-'
+                else OobData.from_ad(AdvertisingData.from_bytes(bytes.fromhex(oob)))
             )
-
-        # Select LE or Classic
-        if mode == 'classic':
-            device.classic_enabled = True
-            device.le_enabled = False
-
-        # Get things going
-        await device.power_on()
+            legacy_context = OobLegacyContext()
+            oob_contexts = PairingConfig.OobConfig(
+                our_context=our_oob_context,
+                peer_data=shared_data,
+                legacy_context=legacy_context,
+            )
+            oob_data = OobData(
+                address=device.random_address,
+                shared_data=shared_data,
+                legacy_context=legacy_context,
+            )
+            print(color('@@@-----------------------------------', 'yellow'))
+            print(color('@@@ OOB Data:', 'yellow'))
+            print(color(f'@@@   {our_oob_context.share()}', 'yellow'))
+            print(color(f'@@@   TK={legacy_context.tk.hex()}', 'yellow'))
+            print(color(f'@@@   HEX: ({bytes(oob_data.to_ad()).hex()})', 'yellow'))
+            print(color('@@@-----------------------------------', 'yellow'))
+        else:
+            oob_contexts = None
 
         # 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=BT_LE_TRANSPORT if mode == 'le' else BT_BR_EDR_TRANSPORT,
+            )
 
             if not request:
                 try:
@@ -306,34 +426,137 @@ async def pair(
                         await connection.pair()
                     else:
                         await connection.authenticate()
-                    return
                 except ProtocolError as error:
                     print(color(f'Pairing failed: {error}', 'red'))
-                    return
-        else:
-            # Advertise so that peers can find us and connect
-            await device.start_advertising(auto_restart=True)
 
-        await hci_source.wait_for_termination()
+        else:
+            if mode == 'le':
+                # Advertise so that peers can find us and connect
+                await device.start_advertising(auto_restart=True)
+            else:
+                # Become discoverable and connectable
+                await device.set_discoverable(True)
+                await device.set_connectable(True)
+
+        # Run until the user asks to exit
+        await Waiter.instance.wait_until_terminated()
+
+
+# -----------------------------------------------------------------------------
+class LogHandler(logging.Handler):
+    def __init__(self):
+        super().__init__()
+        self.setFormatter(logging.Formatter('%(levelname)s:%(name)s:%(message)s'))
+
+    def emit(self, record):
+        message = self.format(record)
+        print(message)
 
 
 # -----------------------------------------------------------------------------
 @click.command()
-@click.option('--mode', type=click.Choice(['le', 'classic']), default='le', show_default=True)
-@click.option('--sc', type=bool, default=True, help='Use the Secure Connections protocol', show_default=True)
-@click.option('--mitm', type=bool, default=True, help='Request MITM protection', show_default=True)
-@click.option('--bond', type=bool, default=True, help='Enable bonding', show_default=True)
-@click.option('--io', type=click.Choice(['keyboard', 'display', 'display+keyboard', 'display+yes/no', 'none']), default='display+keyboard', show_default=True)
+@click.option(
+    '--mode', type=click.Choice(['le', 'classic']), default='le', show_default=True
+)
+@click.option(
+    '--sc',
+    type=bool,
+    default=True,
+    help='Use the Secure Connections protocol',
+    show_default=True,
+)
+@click.option(
+    '--mitm', type=bool, default=True, help='Request MITM protection', show_default=True
+)
+@click.option(
+    '--bond', type=bool, default=True, help='Enable bonding', show_default=True
+)
+@click.option(
+    '--ctkd',
+    type=bool,
+    default=True,
+    help='Enable CTKD',
+    show_default=True,
+)
+@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(
+        ['keyboard', 'display', 'display+keyboard', 'display+yes/no', 'none']
+    ),
+    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')
+@click.option(
+    '--request', is_flag=True, help='Request that the connecting peer initiate pairing'
+)
 @click.option('--print-keys', is_flag=True, help='Print the bond keys before pairing')
-@click.option('--keystore-file', help='File in which to store the pairing keys')
+@click.option(
+    '--keystore-file',
+    metavar='<filename>',
+    help='File in which to store the pairing keys',
+)
 @click.argument('device-config')
 @click.argument('hci_transport')
 @click.argument('address-or-name', required=False)
-def main(mode, sc, mitm, bond, io, prompt, request, print_keys, keystore_file, device_config, hci_transport, address_or_name):
-    logging.basicConfig(level = os.environ.get('BUMBLE_LOGLEVEL', 'INFO').upper())
-    asyncio.run(pair(mode, sc, mitm, bond, io, prompt, request, print_keys, keystore_file, device_config, hci_transport, address_or_name))
+def main(
+    mode,
+    sc,
+    mitm,
+    bond,
+    ctkd,
+    identity_address,
+    linger,
+    io,
+    oob,
+    prompt,
+    request,
+    print_keys,
+    keystore_file,
+    device_config,
+    hci_transport,
+    address_or_name,
+):
+    # Setup logging
+    log_handler = LogHandler()
+    root_logger = logging.getLogger()
+    root_logger.addHandler(log_handler)
+    root_logger.setLevel(os.environ.get('BUMBLE_LOGLEVEL', 'INFO').upper())
+
+    # Pair
+    asyncio.run(
+        pair(
+            mode,
+            sc,
+            mitm,
+            bond,
+            ctkd,
+            identity_address,
+            linger,
+            io,
+            oob,
+            prompt,
+            request,
+            print_keys,
+            keystore_file,
+            device_config,
+            hci_transport,
+            address_or_name,
+        )
+    )
 
 
 # -----------------------------------------------------------------------------

apps/pandora_server.py

@@ -0,0 +1,51 @@
+import asyncio
+import click
+import logging
+import json
+
+from bumble.pandora import PandoraDevice, Config, serve
+from typing import Dict, Any
+
+BUMBLE_SERVER_GRPC_PORT = 7999
+ROOTCANAL_PORT_CUTTLEFISH = 7300
+
+
+@click.command()
+@click.option('--grpc-port', help='gRPC port to serve', default=BUMBLE_SERVER_GRPC_PORT)
+@click.option(
+    '--rootcanal-port', help='Rootcanal TCP port', default=ROOTCANAL_PORT_CUTTLEFISH
+)
+@click.option(
+    '--transport',
+    help='HCI transport',
+    default=f'tcp-client:127.0.0.1:<rootcanal-port>',
+)
+@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))
+
+    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, config=server_config, port=grpc_port))
+
+
+def retrieve_config(config: str) -> Dict[str, Any]:
+    if not config:
+        return {}
+
+    with open(config, 'r') as f:
+        return json.load(f)
+
+
+if __name__ == '__main__':
+    main()  # pylint: disable=no-value-for-parameter

apps/player/player.py

@@ -0,0 +1,608 @@
+# 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 asyncio.subprocess
+import os
+import logging
+from typing import Optional, Union
+
+import click
+
+from bumble.a2dp import (
+    make_audio_source_service_sdp_records,
+    A2DP_SBC_CODEC_TYPE,
+    A2DP_MPEG_2_4_AAC_CODEC_TYPE,
+    A2DP_NON_A2DP_CODEC_TYPE,
+    AacFrame,
+    AacParser,
+    AacPacketSource,
+    AacMediaCodecInformation,
+    SbcFrame,
+    SbcParser,
+    SbcPacketSource,
+    SbcMediaCodecInformation,
+    OpusPacket,
+    OpusParser,
+    OpusPacketSource,
+    OpusMediaCodecInformation,
+)
+from bumble.avrcp import Protocol as AvrcpProtocol
+from bumble.avdtp import (
+    find_avdtp_service_with_connection,
+    AVDTP_AUDIO_MEDIA_TYPE,
+    AVDTP_DELAY_REPORTING_SERVICE_CATEGORY,
+    MediaCodecCapabilities,
+    MediaPacketPump,
+    Protocol as AvdtpProtocol,
+)
+from bumble.colors import color
+from bumble.core import (
+    AdvertisingData,
+    ConnectionError as BumbleConnectionError,
+    DeviceClass,
+    BT_BR_EDR_TRANSPORT,
+)
+from bumble.device import Connection, Device, DeviceConfiguration
+from bumble.hci import Address, HCI_CONNECTION_ALREADY_EXISTS_ERROR, 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: Optional[str],
+        authenticate: bool,
+        encrypt: bool,
+    ) -> None:
+        self.transport = transport
+        self.device_config = device_config
+        self.authenticate = authenticate
+        self.encrypt = encrypt
+        self.avrcp_protocol: Optional[AvrcpProtocol] = None
+        self.done: Optional[asyncio.Event]
+
+    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=BT_BR_EDR_TRANSPORT)
+
+        # 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: Union[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("  Device Major Class: " f"{major_class_name}")
+            minor_class_name = DeviceClass.minor_device_class_name(
+                major_device_class, minor_device_class
+            )
+            print("  Device Minor Class: " f"{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=BT_BR_EDR_TRANSPORT)
+
+        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: Optional[str],
+        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: Union[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():
+    logging.basicConfig(level=os.environ.get("BUMBLE_LOGLEVEL", "WARNING").upper())
+    player_cli()
+
+
+# -----------------------------------------------------------------------------
+if __name__ == "__main__":
+    main()  # pylint: disable=no-value-for-parameter

apps/rfcomm_bridge.py

@@ -0,0 +1,520 @@
+# Copyright 2024 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# -----------------------------------------------------------------------------
+# Imports
+# -----------------------------------------------------------------------------
+import asyncio
+import logging
+import os
+import time
+from typing import Optional
+
+import click
+
+from bumble.colors import color
+from bumble.device import Device, DeviceConfiguration, Connection
+from bumble import core
+from bumble import hci
+from bumble import rfcomm
+from bumble import transport
+from bumble import utils
+
+
+# -----------------------------------------------------------------------------
+# Constants
+# -----------------------------------------------------------------------------
+DEFAULT_RFCOMM_UUID = "E6D55659-C8B4-4B85-96BB-B1143AF6D3AE"
+DEFAULT_MTU = 4096
+DEFAULT_CLIENT_TCP_PORT = 9544
+DEFAULT_SERVER_TCP_PORT = 9545
+
+TRACE_MAX_SIZE = 48
+
+
+# -----------------------------------------------------------------------------
+class Tracer:
+    """
+    Trace data buffers transmitted from one endpoint to another, with stats.
+    """
+
+    def __init__(self, channel_name: str) -> None:
+        self.channel_name = channel_name
+        self.last_ts: float = 0.0
+
+    def trace_data(self, data: bytes) -> None:
+        now = time.time()
+        elapsed_s = now - self.last_ts if self.last_ts else 0
+        elapsed_ms = int(elapsed_s * 1000)
+        instant_throughput_kbps = ((len(data) / elapsed_s) / 1000) if elapsed_s else 0.0
+
+        hex_str = data[:TRACE_MAX_SIZE].hex() + (
+            "..." if len(data) > TRACE_MAX_SIZE else ""
+        )
+        print(
+            f"[{self.channel_name}] {len(data):4} bytes "
+            f"(+{elapsed_ms:4}ms, {instant_throughput_kbps: 7.2f}kB/s) "
+            f" {hex_str}"
+        )
+
+        self.last_ts = now
+
+
+# -----------------------------------------------------------------------------
+class ServerBridge:
+    """
+    RFCOMM server bridge: waits for a peer to connect an RFCOMM channel.
+    The RFCOMM channel may be associated with a UUID published in an SDP service
+    description, or simply be on a system-assigned channel number.
+    When the connection is made, the bridge connects a TCP socket to a remote host and
+    bridges the data in both directions, with flow control.
+    When the RFCOMM channel is closed, the bridge disconnects the TCP socket
+    and waits for a new channel to be connected.
+    """
+
+    READ_CHUNK_SIZE = 4096
+
+    def __init__(
+        self, channel: int, uuid: str, trace: bool, tcp_host: str, tcp_port: int
+    ) -> None:
+        self.device: Optional[Device] = None
+        self.channel = channel
+        self.uuid = uuid
+        self.tcp_host = tcp_host
+        self.tcp_port = tcp_port
+        self.rfcomm_channel: Optional[rfcomm.DLC] = None
+        self.tcp_tracer: Optional[Tracer]
+        self.rfcomm_tracer: Optional[Tracer]
+
+        if trace:
+            self.tcp_tracer = Tracer(color("RFCOMM->TCP", "cyan"))
+            self.rfcomm_tracer = Tracer(color("TCP->RFCOMM", "magenta"))
+        else:
+            self.rfcomm_tracer = None
+            self.tcp_tracer = None
+
+    async def start(self, device: Device) -> None:
+        self.device = device
+
+        # Create and register a server
+        rfcomm_server = rfcomm.Server(self.device)
+
+        # Listen for incoming DLC connections
+        self.channel = rfcomm_server.listen(self.on_rfcomm_channel, self.channel)
+
+        # Setup the SDP to advertise this channel
+        service_record_handle = 0x00010001
+        self.device.sdp_service_records = {
+            service_record_handle: rfcomm.make_service_sdp_records(
+                service_record_handle, self.channel, core.UUID(self.uuid)
+            )
+        }
+
+        # We're ready for a connection
+        self.device.on("connection", self.on_connection)
+        await self.set_available(True)
+
+        print(
+            color(
+                (
+                    f"### Listening for RFCOMM connection on {device.public_address}, "
+                    f"channel {self.channel}"
+                ),
+                "yellow",
+            )
+        )
+
+    async def set_available(self, available: bool):
+        # Become discoverable and connectable
+        assert self.device
+        await self.device.set_connectable(available)
+        await self.device.set_discoverable(available)
+
+    def on_connection(self, connection):
+        print(color(f"@@@ Bluetooth connection: {connection}", "blue"))
+        connection.on("disconnection", self.on_disconnection)
+
+        # Don't accept new connections until we're disconnected
+        utils.AsyncRunner.spawn(self.set_available(False))
+
+    def on_disconnection(self, reason: int):
+        print(
+            color("@@@ Bluetooth disconnection:", "red"),
+            hci.HCI_Constant.error_name(reason),
+        )
+
+        # We're ready for a new connection
+        utils.AsyncRunner.spawn(self.set_available(True))
+
+    # Called when an RFCOMM channel is established
+    @utils.AsyncRunner.run_in_task()
+    async def on_rfcomm_channel(self, rfcomm_channel):
+        print(color("*** RFCOMM channel:", "cyan"), rfcomm_channel)
+
+        # Connect to the TCP server
+        print(
+            color(
+                f"### Connecting to TCP {self.tcp_host}:{self.tcp_port}",
+                "yellow",
+            )
+        )
+        try:
+            reader, writer = await asyncio.open_connection(self.tcp_host, self.tcp_port)
+        except OSError:
+            print(color("!!! Connection failed", "red"))
+            await rfcomm_channel.disconnect()
+            return
+
+        # Pipe data from RFCOMM to TCP
+        def on_rfcomm_channel_closed():
+            print(color("*** RFCOMM channel closed", "cyan"))
+            writer.close()
+
+        def write_rfcomm_data(data):
+            if self.rfcomm_tracer:
+                self.rfcomm_tracer.trace_data(data)
+
+            writer.write(data)
+
+        rfcomm_channel.sink = write_rfcomm_data
+        rfcomm_channel.on("close", on_rfcomm_channel_closed)
+
+        # Pipe data from TCP to RFCOMM
+        while True:
+            try:
+                data = await reader.read(self.READ_CHUNK_SIZE)
+
+                if len(data) == 0:
+                    print(color("### TCP end of stream", "yellow"))
+                    if rfcomm_channel.state == rfcomm.DLC.State.CONNECTED:
+                        await rfcomm_channel.disconnect()
+                    return
+
+                if self.tcp_tracer:
+                    self.tcp_tracer.trace_data(data)
+
+                rfcomm_channel.write(data)
+                await rfcomm_channel.drain()
+            except Exception as error:
+                print(f"!!! Exception: {error}")
+                break
+
+        writer.close()
+        await writer.wait_closed()
+        print(color("~~~ Bye bye", "magenta"))
+
+
+# -----------------------------------------------------------------------------
+class ClientBridge:
+    """
+    RFCOMM client bridge: connects to a BR/EDR device, then waits for an inbound
+    TCP connection on a specified port number. When a TCP client connects, an
+    RFCOMM connection to the device is established, and the data is bridged in both
+    directions, with flow control.
+    When the TCP connection is closed by the client, the RFCOMM channel is
+    disconnected, but the connection to the device remains, ready for a new TCP client
+    to connect.
+    """
+
+    READ_CHUNK_SIZE = 4096
+
+    def __init__(
+        self,
+        channel: int,
+        uuid: str,
+        trace: bool,
+        address: str,
+        tcp_host: str,
+        tcp_port: int,
+        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: Optional[Device] = None
+        self.connection: Optional[Connection] = None
+        self.rfcomm_client: Optional[rfcomm.Client]
+        self.rfcomm_mux: Optional[rfcomm.Multiplexer]
+        self.tcp_connected: bool = False
+
+        self.tcp_tracer: Optional[Tracer]
+        self.rfcomm_tracer: Optional[Tracer]
+
+        if trace:
+            self.tcp_tracer = Tracer(color("RFCOMM->TCP", "cyan"))
+            self.rfcomm_tracer = Tracer(color("TCP->RFCOMM", "magenta"))
+        else:
+            self.rfcomm_tracer = None
+            self.tcp_tracer = None
+
+    async def connect(self) -> None:
+        if self.connection:
+            return
+
+        print(color(f"@@@ Connecting to Bluetooth {self.address}", "blue"))
+        assert self.device
+        self.connection = await self.device.connect(
+            self.address, transport=core.BT_BR_EDR_TRANSPORT
+        )
+        print(color(f"@@@ Bluetooth connection: {self.connection}", "blue"))
+        self.connection.on("disconnection", self.on_disconnection)
+
+        if self.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_or_link(hci_transport) as (
+        hci_source,
+        hci_sink,
+    ):
+        print("<<< connected")
+
+        if device_config:
+            device = Device.from_config_file_with_hci(
+                device_config, hci_source, hci_sink
+            )
+        else:
+            device = Device.from_config_with_hci(
+                DeviceConfiguration(), hci_source, hci_sink
+            )
+        device.classic_enabled = True
+
+        # Let's go
+        await device.power_on()
+        try:
+            await bridge.start(device)
+
+            # Wait until the transport terminates
+            await hci_source.wait_for_termination()
+        except core.ConnectionError as error:
+            print(color(f"!!! Bluetooth connection failed: {error}", "red"))
+        except Exception as error:
+            print(f"Exception while running bridge: {error}")
+
+
+# -----------------------------------------------------------------------------
+@click.group()
+@click.pass_context
+@click.option(
+    "--device-config",
+    metavar="CONFIG_FILE",
+    help="Device configuration file",
+)
+@click.option(
+    "--hci-transport", metavar="TRANSPORT_NAME", help="HCI transport", required=True
+)
+@click.option("--trace", is_flag=True, help="Trace bridged data to stdout")
+@click.option(
+    "--channel",
+    metavar="CHANNEL_NUMER",
+    help="RFCOMM channel number",
+    type=int,
+    default=0,
+)
+@click.option(
+    "--uuid",
+    metavar="UUID",
+    help="UUID for the RFCOMM channel",
+    default=DEFAULT_RFCOMM_UUID,
+)
+def cli(
+    context,
+    device_config,
+    hci_transport,
+    trace,
+    channel,
+    uuid,
+):
+    context.ensure_object(dict)
+    context.obj["device_config"] = device_config
+    context.obj["hci_transport"] = hci_transport
+    context.obj["trace"] = trace
+    context.obj["channel"] = channel
+    context.obj["uuid"] = uuid
+
+
+# -----------------------------------------------------------------------------
+@cli.command()
+@click.pass_context
+@click.option("--tcp-host", help="TCP host", default="localhost")
+@click.option("--tcp-port", help="TCP port", default=DEFAULT_SERVER_TCP_PORT)
+def server(context, tcp_host, tcp_port):
+    bridge = ServerBridge(
+        context.obj["channel"],
+        context.obj["uuid"],
+        context.obj["trace"],
+        tcp_host,
+        tcp_port,
+    )
+    asyncio.run(run(context.obj["device_config"], context.obj["hci_transport"], bridge))
+
+
+# -----------------------------------------------------------------------------
+@cli.command()
+@click.pass_context
+@click.argument("bluetooth-address")
+@click.option("--tcp-host", help="TCP host", default="_")
+@click.option("--tcp-port", help="TCP port", default=DEFAULT_CLIENT_TCP_PORT)
+@click.option("--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))
+
+
+# -----------------------------------------------------------------------------
+logging.basicConfig(level=os.environ.get("BUMBLE_LOGLEVEL", "WARNING").upper())
+if __name__ == "__main__":
+    cli(obj={})  # pylint: disable=no-value-for-parameter

apps/scan.py

@@ -19,20 +19,20 @@ import asyncio
 import os
 import logging
 import click
-from colors import color
 
+from bumble.colors import color
 from bumble.device import Device
 from bumble.transport import open_transport_or_link
 from bumble.keys import JsonKeyStore
 from bumble.smp import AddressResolver
-from bumble.hci import HCI_LE_Advertising_Report_Event
-from bumble.core import AdvertisingData
+from bumble.device import Advertisement
+from bumble.hci import Address, HCI_Constant, HCI_LE_1M_PHY, HCI_LE_CODED_PHY
 
 
 # -----------------------------------------------------------------------------
 def make_rssi_bar(rssi):
-    DISPLAY_MIN_RSSI       = -105
-    DISPLAY_MAX_RSSI       = -30
+    DISPLAY_MIN_RSSI = -105
+    DISPLAY_MAX_RSSI = -30
     DEFAULT_RSSI_BAR_WIDTH = 30
 
     blocks = ['', '▏', '▎', '▍', '▌', '▋', '▊', '▉']
@@ -48,23 +48,33 @@ class AdvertisementPrinter:
         self.min_rssi = min_rssi
         self.resolver = resolver
 
-    def print_advertisement(self, address, address_color, ad_data, rssi):
-        if self.min_rssi is not None and rssi < self.min_rssi:
+    def print_advertisement(self, advertisement):
+        address = advertisement.address
+        address_color = 'yellow' if advertisement.is_connectable else 'red'
+
+        if self.min_rssi is not None and advertisement.rssi < self.min_rssi:
             return
 
         address_qualifier = ''
         resolution_qualifier = ''
-        if self.resolver and address.is_resolvable:
-            resolved = self.resolver.resolve(address)
+        if self.resolver and advertisement.address.is_resolvable:
+            resolved = self.resolver.resolve(advertisement.address)
             if resolved is not None:
-                resolution_qualifier = f'(resolved from {address})'
+                resolution_qualifier = f'(resolved from {advertisement.address})'
                 address = resolved
 
-        address_type_string = ('PUBLIC', 'RANDOM', 'PUBLIC_ID', 'RANDOM_ID')[address.address_type]
-        if address.is_public:
-            type_color = 'cyan'
+        address_type_string = ('PUBLIC', 'RANDOM', 'PUBLIC_ID', 'RANDOM_ID')[
+            address.address_type
+        ]
+        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:
@@ -74,18 +84,32 @@ class AdvertisementPrinter:
                 type_color = 'blue'
                 address_qualifier = '(non-resolvable)'
 
-        rssi_bar = make_rssi_bar(rssi)
         separator = '\n  '
-        print(f'>>> {color(address, address_color)} [{color(address_type_string, type_color)}]{address_qualifier}{resolution_qualifier}:{separator}RSSI:{rssi:4} {rssi_bar}{separator}{ad_data.to_string(separator)}\n')
+        rssi_bar = make_rssi_bar(advertisement.rssi)
+        if not advertisement.is_legacy:
+            phy_info = (
+                f'PHY: {HCI_Constant.le_phy_name(advertisement.primary_phy)}/'
+                f'{HCI_Constant.le_phy_name(advertisement.secondary_phy)} '
+                f'{separator}'
+            )
+        else:
+            phy_info = ''
 
-    def on_advertisement(self, address, ad_data, rssi, connectable):
-        address_color = 'yellow' if connectable else 'red'
-        self.print_advertisement(address, address_color, ad_data, rssi)
+        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'
+        )
 
-    def on_advertising_report(self, address, ad_data, rssi, event_type):
-        print(f'{color("EVENT", "green")}: {HCI_LE_Advertising_Report_Event.event_type_name(event_type)}')
-        ad_data = AdvertisingData.from_bytes(ad_data)
-        self.print_advertisement(address, 'yellow', ad_data, rssi)
+    def on_advertisement(self, advertisement):
+        self.print_advertisement(advertisement)
+
+    def on_advertising_report(self, report):
+        print(f'{color("EVENT", "green")}: {report.event_type_string()}')
+        self.print_advertisement(Advertisement.from_advertising_report(report))
 
 
 # -----------------------------------------------------------------------------
@@ -94,30 +118,49 @@ async def scan(
     passive,
     scan_interval,
     scan_window,
+    phy,
     filter_duplicates,
     raw,
+    irks,
     keystore_file,
     device_config,
-    transport
+    transport,
 ):
     print('<<< connecting to HCI...')
     async with await open_transport_or_link(transport) as (hci_source, hci_sink):
         print('<<< connected')
 
         if device_config:
-            device = Device.from_config_file_with_hci(device_config, hci_source, hci_sink)
+            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)
+            device = Device.with_hci(
+                'Bumble', 'F0:F1:F2:F3:F4:F5', hci_source, hci_sink
+            )
+
+        await device.power_on()
 
         if keystore_file:
-            keystore = JsonKeyStore(namespace=None, filename=keystore_file)
-            device.keystore = keystore
-        else:
-            resolver = None
+            device.keystore = JsonKeyStore.from_device(device, filename=keystore_file)
 
         if device.keystore:
             resolving_keys = await device.keystore.get_resolving_keys()
-            resolver = AddressResolver(resolving_keys)
+        else:
+            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:
@@ -125,12 +168,17 @@ async def scan(
         else:
             device.on('advertisement', printer.on_advertisement)
 
-        await device.power_on()
+        if phy is None:
+            scanning_phys = [HCI_LE_1M_PHY, HCI_LE_CODED_PHY]
+        else:
+            scanning_phys = [{'1m': HCI_LE_1M_PHY, 'coded': HCI_LE_CODED_PHY}[phy]]
+
         await device.start_scanning(
             active=(not passive),
             scan_interval=scan_interval,
             scan_window=scan_window,
-            filter_duplicates=filter_duplicates
+            filter_duplicates=filter_duplicates,
+            scanning_phys=scanning_phys,
         )
 
         await hci_source.wait_for_termination()
@@ -142,14 +190,69 @@ async def scan(
 @click.option('--passive', is_flag=True, default=False, help='Perform passive scanning')
 @click.option('--scan-interval', type=int, default=60, help='Scan interval')
 @click.option('--scan-window', type=int, default=60, help='Scan window')
-@click.option('--filter-duplicates', type=bool, default=True, help='Filter duplicates at the controller level')
-@click.option('--raw', is_flag=True, 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(
+    '--phy', type=click.Choice(['1m', 'coded']), help='Only scan on the specified PHY'
+)
+@click.option(
+    '--filter-duplicates',
+    type=bool,
+    default=True,
+    help='Filter duplicates at the controller level',
+)
+@click.option(
+    '--raw',
+    is_flag=True,
+    default=False,
+    help='Listen for raw advertising reports instead of processed ones',
+)
+@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, passive, scan_interval, scan_window, filter_duplicates, raw, keystore_file, device_config, transport):
-    logging.basicConfig(level = os.environ.get('BUMBLE_LOGLEVEL', 'WARNING').upper())
-    asyncio.run(scan(min_rssi, passive, scan_interval, scan_window, filter_duplicates, raw, keystore_file, device_config, transport))
+def main(
+    min_rssi,
+    passive,
+    scan_interval,
+    scan_window,
+    phy,
+    filter_duplicates,
+    raw,
+    irk,
+    keystore_file,
+    device_config,
+    transport,
+):
+    logging.basicConfig(level=os.environ.get('BUMBLE_LOGLEVEL', 'WARNING').upper())
+    asyncio.run(
+        scan(
+            min_rssi,
+            passive,
+            scan_interval,
+            scan_window,
+            phy,
+            filter_duplicates,
+            raw,
+            irk,
+            keystore_file,
+            device_config,
+            transport,
+        )
+    )
 
 
 # -----------------------------------------------------------------------------

apps/show.py

@@ -15,54 +15,90 @@
 # -----------------------------------------------------------------------------
 # Imports
 # -----------------------------------------------------------------------------
+import datetime
+import logging
+import os
 import struct
-import click
-from colors import color
 
+import click
+
+from bumble.colors import color
 from bumble import hci
 from bumble.transport.common import PacketReader
 from bumble.helpers import PacketTracer
 
 
+# -----------------------------------------------------------------------------
+# Logging
+# -----------------------------------------------------------------------------
+logger = logging.getLogger(__name__)
+
+
+# -----------------------------------------------------------------------------
+# Classes
 # -----------------------------------------------------------------------------
 class SnoopPacketReader:
     '''
-    Reader that reads HCI packets from a "snoop" file (based on RFC 1761, but not exactly the same...)
+    Reader that reads HCI packets from a "snoop" file (based on RFC 1761, but not
+    exactly the same...)
     '''
 
-    DATALINK_H1   = 1001
-    DATALINK_H4   = 1002
+    DATALINK_H1 = 1001
+    DATALINK_H4 = 1002
     DATALINK_BSCP = 1003
-    DATALINK_H5   = 1004
+    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':
-            raise ValueError('not a valid snoop file, unexpected identification pattern')
-        (self.version_number, self.data_link_type) = struct.unpack('>II', source.read(8))
-        if self.data_link_type != self.DATALINK_H4 and self.data_link_type != self.DATALINK_H1:
+        if identification_pattern != self.IDENTIFICATION_PATTERN:
+            raise ValueError(
+                'not a valid snoop file, unexpected identification pattern'
+            )
+        (self.version_number, self.data_link_type) = struct.unpack(
+            '>II', source.read(8)
+        )
+        if self.data_link_type not in (self.DATALINK_H4, self.DATALINK_H1):
             raise ValueError(f'datalink type {self.data_link_type} not supported')
 
     def next_packet(self):
         # 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)
+            _cumulative_drops,
+            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
@@ -79,42 +115,76 @@ class SnoopPacketReader:
                 else:
                     packet_type = hci.HCI_ACL_DATA_PACKET
 
-            return (packet_flags & 1, bytes([packet_type]) + self.source.read(included_length))
-        else:
-            return (packet_flags & 1, self.source.read(included_length))
+            return (
+                packet_flags & 1,
+                bytes([packet_type]) + 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}")
 
 
 # -----------------------------------------------------------------------------
 # Main
 # -----------------------------------------------------------------------------
 @click.command()
-@click.option('--format', type=click.Choice(['h4', 'snoop']), default='h4', help='Format of the input file')
+@click.option(
+    '--format',
+    type=click.Choice(['h4', 'snoop']),
+    default='h4',
+    help='Format of the input file',
+)
+@click.option(
+    '--vendors',
+    type=click.Choice(['android', 'zephyr']),
+    multiple=True,
+    help='Support vendor-specific commands (list one or more)',
+)
 @click.argument('filename')
-def show(format, filename):
+# pylint: disable=redefined-builtin
+def main(format, vendors, filename):
+    for vendor in vendors:
+        if vendor == 'android':
+            import bumble.vendor.android.hci
+        elif vendor == 'zephyr':
+            import bumble.vendor.zephyr.hci
+
     input = open(filename, 'rb')
     if format == 'h4':
         packet_reader = PacketReader(input)
 
         def read_next_packet():
-            (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'))
-            pass
 
 
 # -----------------------------------------------------------------------------
 if __name__ == '__main__':
-    show()
+    logging.basicConfig(level=os.environ.get('BUMBLE_LOGLEVEL', 'WARNING').upper())
+    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,34 @@
+<!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>
+        </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,315 @@
+(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 streamStateText;
+let connectionStateText;
+let controlsDiv;
+let audioOnButton;
+let mediaSource;
+let sourceBuffer;
+let audioElement;
+let audioContext;
+let audioAnalyzer;
+let audioFrequencyBinCount;
+let audioFrequencyData;
+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 = [];
+
+const FFT_WIDTH = 800;
+const FFT_HEIGHT = 256;
+const BANDWIDTH_WIDTH = 500;
+const BANDWIDTH_HEIGHT = 100;
+
+function hexToBytes(hex) {
+    return Uint8Array.from(hex.match(/.{1,2}/g).map((byte) => parseInt(byte, 16)));
+}
+
+function init() {
+    initUI();
+    initMediaSource();
+    initAudioElement();
+    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");
+    streamStateText = document.getElementById("streamStateText");
+    connectionStateText = document.getElementById("connectionStateText");
+    audioSupportMessageText = document.getElementById("audioSupportMessageText");
+
+    audioOnButton.onclick = () => startAudio();
+
+    setConnectionText("");
+
+    requestAnimationFrame(onAnimationFrame);
+}
+
+function initMediaSource() {
+    mediaSource = new MediaSource();
+    mediaSource.onsourceopen = onMediaSourceOpen;
+    mediaSource.onsourceclose = onMediaSourceClose;
+    mediaSource.onsourceended = onMediaSourceEnd;
+}
+
+function initAudioElement() {
+    audioElement = document.getElementById("audio");
+    audioElement.src = URL.createObjectURL(mediaSource);
+    // audioElement.controls = true;
+}
+
+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);
+}
+
+function startAnalyzer() {
+    // FFT
+    if (audioElement.captureStream !== undefined) {
+        audioContext = new AudioContext();
+        audioAnalyzer = audioContext.createAnalyser();
+        audioAnalyzer.fftSize = 128;
+        audioFrequencyBinCount = audioAnalyzer.frequencyBinCount;
+        audioFrequencyData = new Uint8Array(audioFrequencyBinCount);
+        const stream = audioElement.captureStream();
+        const source = audioContext.createMediaStreamSource(stream);
+        source.connect(audioAnalyzer);
+    }
+
+    // Bandwidth
+    bandwidthBinCount = BANDWIDTH_WIDTH / 2;
+    bandwidthBins = [];
+}
+
+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 lineHeight = (bandwidthBins[t] / 1000) * BANDWIDTH_HEIGHT;
+        bandwidthCanvasContext.fillRect(t * 2, BANDWIDTH_HEIGHT - lineHeight, 2, lineHeight);
+    }
+
+    // Display again at the next frame
+    requestAnimationFrame(onAnimationFrame);
+}
+
+function onMediaSourceOpen() {
+    console.log(this.readyState);
+    sourceBuffer = mediaSource.addSourceBuffer("audio/aac");
+}
+
+function onMediaSourceClose() {
+    console.log(this.readyState);
+}
+
+function onMediaSourceEnd() {
+    console.log(this.readyState);
+}
+
+async function startAudio() {
+    try {
+        console.log("starting audio...");
+        audioOnButton.disabled = true;
+        audioState = "starting";
+        await audioElement.play();
+        console.log("audio started");
+        audioState = "playing";
+        startAnalyzer();
+    } catch(error) {
+        console.error(`play failed: ${error}`);
+        audioState = "stopped";
+        audioOnButton.disabled = false;
+    }
+}
+
+function onAudioPacket(packet) {
+    if (audioState != "stopped") {
+        // Queue the audio packet.
+        sourceBuffer.appendBuffer(packet);
+    }
+
+    packetsReceived += 1;
+    packetsReceivedText.innerText = packetsReceived;
+    bytesReceived += packet.byteLength;
+    bytesReceivedText.innerText = bytesReceived;
+
+    bandwidthBins[bandwidthBins.length] = packet.byteLength;
+    if (bandwidthBins.length > bandwidthBinCount) {
+        bandwidthBins.shift();
+    }
+}
+
+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);
+    }
+}
+
+function onHelloMessage(params) {
+    codecText.innerText = params.codec;
+    if (params.codec != "aac") {
+        audioOnButton.disabled = true;
+        audioSupportMessageText.innerText = "Only AAC can be played, audio will be disabled";
+        audioSupportMessageText.style.display = "inline-block";
+    } else {
+        audioSupportMessageText.innerText = "";
+        audioSupportMessageText.style.display = "none";
+    }
+    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,736 @@
+# 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
+from importlib import resources
+import enum
+import json
+import os
+import logging
+import pathlib
+import subprocess
+from typing import Dict, List, Optional
+import weakref
+
+import click
+import aiohttp
+from aiohttp import web
+
+import bumble
+from bumble.colors import color
+from bumble.core import BT_BR_EDR_TRANSPORT, CommandTimeoutError
+from bumble.device import Connection, Device, DeviceConfiguration
+from bumble.hci import HCI_StatusError
+from bumble.pairing import PairingConfig
+from bumble.sdp import ServiceAttribute
+from bumble.transport import open_transport
+from bumble.avdtp import (
+    AVDTP_AUDIO_MEDIA_TYPE,
+    Listener,
+    MediaCodecCapabilities,
+    Protocol,
+)
+from bumble.a2dp import (
+    make_audio_sink_service_sdp_records,
+    A2DP_SBC_CODEC_TYPE,
+    A2DP_MPEG_2_4_AAC_CODEC_TYPE,
+    SbcMediaCodecInformation,
+    AacMediaCodecInformation,
+)
+from bumble.utils import AsyncRunner
+from bumble.codecs import AacAudioRtpPacket
+from bumble.rtp import MediaPacket
+
+
+# -----------------------------------------------------------------------------
+# 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()
+
+    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 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: Optional[asyncio.Task]
+    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: Optional[asyncio.subprocess.Process]
+    ffplay_task: Optional[asyncio.Task]
+
+    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 -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, discover, outputs, ui_port):
+        self.device_config = device_config
+        self.transport = transport
+        self.codec = codec
+        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()
+
+        raise RuntimeError('unsupported codec')
+
+    def aac_codec_capabilities(self) -> MediaCodecCapabilities:
+        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=AacMediaCodecInformation.SamplingFrequency.SF_48000
+                | AacMediaCodecInformation.SamplingFrequency.SF_44100,
+                channels=AacMediaCodecInformation.Channels.MONO
+                | AacMediaCodecInformation.Channels.STEREO,
+                vbr=1,
+                bitrate=256000,
+            ),
+        )
+
+    def sbc_codec_capabilities(self) -> MediaCodecCapabilities:
+        return MediaCodecCapabilities(
+            media_type=AVDTP_AUDIO_MEDIA_TYPE,
+            media_codec_type=A2DP_SBC_CODEC_TYPE,
+            media_codec_information=SbcMediaCodecInformation(
+                sampling_frequency=SbcMediaCodecInformation.SamplingFrequency.SF_48000
+                | SbcMediaCodecInformation.SamplingFrequency.SF_44100
+                | SbcMediaCodecInformation.SamplingFrequency.SF_32000
+                | SbcMediaCodecInformation.SamplingFrequency.SF_16000,
+                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,
+            ),
+        )
+
+    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=BT_BR_EDR_TRANSPORT)
+        print(f'=== Connected to {connection.peer_address}')
+
+        # Request authentication
+        print('*** Authenticating...')
+        await connection.authenticate()
+        print('*** Authenticated')
+
+        # Enable encryption
+        print('*** Enabling encryption...')
+        await connection.encrypt()
+        print('*** Encryption on')
+
+        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']), default='aac', show_default=True
+)
+@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, 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, discover, output, ui_port).run(
+            connect_address
+        )
+    )
+
+
+# -----------------------------------------------------------------------------
+def main():
+    logging.basicConfig(level=os.environ.get('BUMBLE_LOGLEVEL', 'WARNING').upper())
+    speaker()
+
+
+# -----------------------------------------------------------------------------
+if __name__ == "__main__":
+    main()  # pylint: disable=no-value-for-parameter

apps/unbond.py

@@ -22,40 +22,59 @@ import click
 
 from bumble.device import Device
 from bumble.keys import JsonKeyStore
+from bumble.transport import open_transport
 
 
 # -----------------------------------------------------------------------------
-async def unbond(keystore_file, device_config, address):
-    # Create a device to manage the host
-    device = Device.from_config_file(device_config)
-
-    # Get all entries in the keystore
-    if keystore_file:
-        keystore = JsonKeyStore(None, keystore_file)
-    else:
-        keystore = device.keystore
-
-    if keystore is None:
-        print('no keystore')
-        return
-
+async def unbond_with_keystore(keystore, address):
     if address is None:
-        await keystore.print()
-    else:
-        try:
-            await keystore.delete(address)
-        except KeyError:
-            print('!!! pairing not found')
+        return await keystore.print()
+
+    try:
+        await keystore.delete(address)
+    except KeyError:
+        print('!!! pairing not found')
+
+
+# -----------------------------------------------------------------------------
+async def unbond(keystore_file, device_config, hci_transport, address):
+    # With a keystore file, we can instantiate the keystore directly
+    if keystore_file:
+        return await unbond_with_keystore(JsonKeyStore(None, keystore_file), address)
+
+    # Without a keystore file, we need to obtain the keystore from the device
+    async with await open_transport(hci_transport) as (hci_source, hci_sink):
+        # Create a device to manage the host
+        device = Device.from_config_file_with_hci(device_config, hci_source, hci_sink)
+
+        # Power-on the device to ensure we have a key store
+        await device.power_on()
+
+        return await unbond_with_keystore(device.keystore, address)
 
 
 # -----------------------------------------------------------------------------
 @click.command()
-@click.option('--keystore-file', help='File in which to store the pairing keys')
-@click.argument('device-config')
+@click.option('--keystore-file', help='File in which the pairing keys are stored')
+@click.option('--hci-transport', help='HCI transport for the controller')
+@click.argument('device-config', required=False)
 @click.argument('address', required=False)
-def main(keystore_file, device_config, address):
-    logging.basicConfig(level = os.environ.get('BUMBLE_LOGLEVEL', 'INFO').upper())
-    asyncio.run(unbond(keystore_file, device_config, address))
+def main(keystore_file, hci_transport, device_config, address):
+    """
+    Remove pairing keys for a device, given its address.
+
+    If no keystore file is specified, the --hci-transport option must be used to
+    connect to a controller, so that the keystore for that controller can be
+    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())
+
+    if not keystore_file and not hci_transport:
+        print('either --keystore-file or --hci-transport must be specified.')
+        return
+
+    asyncio.run(unbond(keystore_file, device_config, hci_transport, address))
 
 
 # -----------------------------------------------------------------------------

apps/usb_probe.py

@@ -28,17 +28,19 @@
 # -----------------------------------------------------------------------------
 import os
 import logging
-import sys
+import click
 import usb1
-from colors import color
+
+from bumble.colors import color
+from bumble.transport.usb import load_libusb
 
 
 # -----------------------------------------------------------------------------
 # Constants
 # -----------------------------------------------------------------------------
-USB_DEVICE_CLASS_DEVICE                          = 0x00
-USB_DEVICE_CLASS_WIRELESS_CONTROLLER             = 0xE0
-USB_DEVICE_SUBCLASS_RF_CONTROLLER                = 0x01
+USB_DEVICE_CLASS_DEVICE = 0x00
+USB_DEVICE_CLASS_WIRELESS_CONTROLLER = 0xE0
+USB_DEVICE_SUBCLASS_RF_CONTROLLER = 0x01
 USB_DEVICE_PROTOCOL_BLUETOOTH_PRIMARY_CONTROLLER = 0x01
 
 USB_DEVICE_CLASSES = {
@@ -68,22 +70,22 @@ USB_DEVICE_CLASSES = {
                 0x01: 'Bluetooth',
                 0x02: 'UWB',
                 0x03: 'Remote NDIS',
-                0x04: 'Bluetooth AMP'
+                0x04: 'Bluetooth AMP',
             }
-        }
+        },
     ),
     0xEF: 'Miscellaneous',
     0xFE: 'Application Specific',
-    0xFF: 'Vendor Specific'
+    0xFF: 'Vendor Specific',
 }
 
-USB_ENDPOINT_IN    = 0x80
+USB_ENDPOINT_IN = 0x80
 USB_ENDPOINT_TYPES = ['CONTROL', 'ISOCHRONOUS', 'BULK', 'INTERRUPT']
 
 USB_BT_HCI_CLASS_TUPLE = (
     USB_DEVICE_CLASS_WIRELESS_CONTROLLER,
     USB_DEVICE_SUBCLASS_RF_CONTROLLER,
-    USB_DEVICE_PROTOCOL_BLUETOOTH_PRIMARY_CONTROLLER
+    USB_DEVICE_PROTOCOL_BLUETOOTH_PRIMARY_CONTROLLER,
 )
 
 
@@ -93,19 +95,26 @@ def show_device_details(device):
         print(f'  Configuration {configuration.getConfigurationValue()}')
         for interface in configuration:
             for setting in interface:
-                alternateSetting = setting.getAlternateSetting()
-                suffix = f'/{alternateSetting}' if interface.getNumSettings() > 1 else ''
+                alternate_setting = setting.getAlternateSetting()
+                suffix = (
+                    f'/{alternate_setting}' if interface.getNumSettings() > 1 else ''
+                )
                 (class_string, subclass_string) = get_class_info(
-                    setting.getClass(),
-                    setting.getSubClass(),
-                    setting.getProtocol()
+                    setting.getClass(), setting.getSubClass(), setting.getProtocol()
                 )
                 details = f'({class_string}, {subclass_string})'
                 print(f'      Interface: {setting.getNumber()}{suffix} {details}')
                 for endpoint in setting:
                     endpoint_type = USB_ENDPOINT_TYPES[endpoint.getAttributes() & 3]
-                    endpoint_direction = 'OUT' if (endpoint.getAddress() & USB_ENDPOINT_IN == 0) else 'IN'
-                    print(f'        Endpoint 0x{endpoint.getAddress():02X}: {endpoint_type} {endpoint_direction}')
+                    endpoint_direction = (
+                        'OUT'
+                        if (endpoint.getAddress() & USB_ENDPOINT_IN == 0)
+                        else 'IN'
+                    )
+                    print(
+                        f'        Endpoint 0x{endpoint.getAddress():02X}: '
+                        f'{endpoint_type} {endpoint_direction}'
+                    )
 
 
 # -----------------------------------------------------------------------------
@@ -115,7 +124,7 @@ def get_class_info(cls, subclass, protocol):
     if class_info is None:
         class_string = f'0x{cls:02X}'
     else:
-        if type(class_info) is tuple:
+        if isinstance(class_info, tuple):
             class_string = class_info[0]
             subclass_info = class_info[1].get(subclass)
             if subclass_info:
@@ -134,7 +143,11 @@ def get_class_info(cls, subclass, protocol):
 # -----------------------------------------------------------------------------
 def is_bluetooth_hci(device):
     # Check if the device class indicates a match
-    if (device.getDeviceClass(), device.getDeviceSubClass(), device.getDeviceProtocol()) == USB_BT_HCI_CLASS_TUPLE:
+    if (
+        device.getDeviceClass(),
+        device.getDeviceSubClass(),
+        device.getDeviceProtocol(),
+    ) == USB_BT_HCI_CLASS_TUPLE:
         return True
 
     # If the device class is 'Device', look for a matching interface
@@ -142,31 +155,36 @@ def is_bluetooth_hci(device):
         for configuration in device:
             for interface in configuration:
                 for setting in interface:
-                    if (setting.getClass(), setting.getSubClass(), setting.getProtocol()) == USB_BT_HCI_CLASS_TUPLE:
+                    if (
+                        setting.getClass(),
+                        setting.getSubClass(),
+                        setting.getProtocol(),
+                    ) == USB_BT_HCI_CLASS_TUPLE:
                         return True
 
     return False
 
 
 # -----------------------------------------------------------------------------
+@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())
+    logging.basicConfig(level=os.environ.get('BUMBLE_LOGLEVEL', 'WARNING').upper())
 
+    load_libusb()
     with usb1.USBContext() as context:
         bluetooth_device_count = 0
         devices = {}
 
         for device in context.getDeviceIterator(skip_on_error=True):
-            device_class    = device.getDeviceClass()
+            device_class = device.getDeviceClass()
             device_subclass = device.getDeviceSubClass()
             device_protocol = device.getDeviceProtocol()
 
             device_id = (device.getVendorID(), device.getProductID())
 
             (device_class_string, device_subclass_string) = get_class_info(
-                device_class,
-                device_subclass,
-                device_protocol
+                device_class, device_subclass, device_protocol
             )
 
             try:
@@ -195,7 +213,9 @@ def main(verbose):
 
             # Compute the different ways this can be referenced as a Bumble transport
             bumble_transport_names = []
-            basic_transport_name = f'usb:{device.getVendorID():04X}:{device.getProductID():04X}'
+            basic_transport_name = (
+                f'usb:{device.getVendorID():04X}:{device.getProductID():04X}'
+            )
 
             if device_is_bluetooth_hci:
                 bumble_transport_names.append(f'usb:{bluetooth_device_count - 1}')
@@ -203,17 +223,39 @@ def main(verbose):
             if device_id not in devices:
                 bumble_transport_names.append(basic_transport_name)
             else:
-                bumble_transport_names.append(f'{basic_transport_name}#{len(devices[device_id])}')
+                bumble_transport_names.append(
+                    f'{basic_transport_name}#{len(devices[device_id])}'
+                )
 
             if device_serial_number is not None:
-                if device_id not in devices or device_serial_number not in devices[device_id]:
-                    bumble_transport_names.append(f'{basic_transport_name}/{device_serial_number}')
+                if (
+                    device_id not in devices
+                    or device_serial_number not in devices[device_id]
+                ):
+                    bumble_transport_names.append(
+                        f'{basic_transport_name}/{device_serial_number}'
+                    )
 
             # Print the results
-            print(color(f'ID {device.getVendorID():04X}:{device.getProductID():04X}', fg=fg_color, bg=bg_color))
+            print(
+                color(
+                    f'ID {device.getVendorID():04X}:{device.getProductID():04X}',
+                    fg=fg_color,
+                    bg=bg_color,
+                )
+            )
             if bumble_transport_names:
-                print(color('  Bumble Transport Names:', 'blue'), ' or '.join(color(x, 'cyan' if device_is_bluetooth_hci else 'red') for x in bumble_transport_names))
-            print(color('  Bus/Device:            ', 'green'), f'{device.getBusNumber():03}/{device.getDeviceAddress():03}')
+                print(
+                    color('  Bumble Transport Names:', 'blue'),
+                    ' or '.join(
+                        color(x, 'cyan' if device_is_bluetooth_hci else 'red')
+                        for x in bumble_transport_names
+                    ),
+                )
+            print(
+                color('  Bus/Device:            ', 'green'),
+                f'{device.getBusNumber():03}/{device.getDeviceAddress():03}',
+            )
             print(color('  Class:                 ', 'green'), device_class_string)
             print(color('  Subclass/Protocol:     ', 'green'), device_subclass_string)
             if device_serial_number is not None:
@@ -233,9 +275,4 @@ def main(verbose):
 
 # -----------------------------------------------------------------------------
 if __name__ == '__main__':
-    if len(sys.argv) == 2 and sys.argv[1] == '--verbose':
-        verbose = True
-    else:
-        verbose = False
-
-    main(verbose)
+    main()  # pylint: disable=no-value-for-parameter

bumble/__init__.py

@@ -0,0 +1,4 @@
+try:
+    from ._version import version as __version__
+except ImportError:
+    __version__ = "unknown version"

bumble/at.py

@@ -0,0 +1,91 @@
+# 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 typing import List, Union
+
+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[Union[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: Union[bytes, list] = bytes()
+
+    for token in tokens:
+        if token == b',':
+            accumulator[-1].append(current)
+            current = bytes()
+        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/att.py

@@ -22,15 +22,40 @@
 # -----------------------------------------------------------------------------
 # Imports
 # -----------------------------------------------------------------------------
-from colors import color
+from __future__ import annotations
+
+import enum
+import functools
+import inspect
+import struct
+from typing import (
+    Any,
+    Awaitable,
+    Callable,
+    Dict,
+    List,
+    Optional,
+    Type,
+    Union,
+    TYPE_CHECKING,
+)
+
 from pyee import EventEmitter
 
-from .core import *
-from .hci import *
+from bumble import utils
+from bumble.core import UUID, name_or_number, ProtocolError
+from bumble.hci import HCI_Object, key_with_value
+from bumble.colors import color
+
+if TYPE_CHECKING:
+    from bumble.device import Connection
 
 # -----------------------------------------------------------------------------
 # Constants
 # -----------------------------------------------------------------------------
+# fmt: off
+# pylint: disable=line-too-long
+
 ATT_CID = 0x04
 
 ATT_ERROR_RESPONSE              = 0x01
@@ -122,71 +147,86 @@ ATT_RESPONSES = [
     ATT_EXECUTE_WRITE_RESPONSE
 ]
 
-ATT_INVALID_HANDLE_ERROR                   = 0x01
-ATT_READ_NOT_PERMITTED_ERROR               = 0x02
-ATT_WRITE_NOT_PERMITTED_ERROR              = 0x03
-ATT_INVALID_PDU_ERROR                      = 0x04
-ATT_INSUFFICIENT_AUTHENTICATION_ERROR      = 0x05
-ATT_REQUEST_NOT_SUPPORTED_ERROR            = 0x06
-ATT_INVALID_OFFSET_ERROR                   = 0x07
-ATT_INSUFFICIENT_AUTHORIZATION_ERROR       = 0x08
-ATT_PREPARE_QUEUE_FULL_ERROR               = 0x09
-ATT_ATTRIBUTE_NOT_FOUND_ERROR              = 0x0A
-ATT_ATTRIBUTE_NOT_LONG_ERROR               = 0x0B
-ATT_INSUFFICIENT_ENCRYPTION_KEY_SIZE_ERROR = 0x0C
-ATT_INVALID_ATTRIBUTE_LENGTH_ERROR         = 0x0D
-ATT_UNLIKELY_ERROR_ERROR                   = 0x0E
-ATT_INSUFFICIENT_ENCRYPTION_ERROR          = 0x0F
-ATT_UNSUPPORTED_GROUP_TYPE_ERROR           = 0x10
-ATT_INSUFFICIENT_RESOURCES_ERROR           = 0x11
+class ErrorCode(utils.OpenIntEnum):
+    '''
+    See
 
-ATT_ERROR_NAMES = {
-    ATT_INVALID_HANDLE_ERROR:                   'ATT_INVALID_HANDLE_ERROR',
-    ATT_READ_NOT_PERMITTED_ERROR:               'ATT_READ_NOT_PERMITTED_ERROR',
-    ATT_WRITE_NOT_PERMITTED_ERROR:              'ATT_WRITE_NOT_PERMITTED_ERROR',
-    ATT_INVALID_PDU_ERROR:                      'ATT_INVALID_PDU_ERROR',
-    ATT_INSUFFICIENT_AUTHENTICATION_ERROR:      'ATT_INSUFFICIENT_AUTHENTICATION_ERROR',
-    ATT_REQUEST_NOT_SUPPORTED_ERROR:            'ATT_REQUEST_NOT_SUPPORTED_ERROR',
-    ATT_INVALID_OFFSET_ERROR:                   'ATT_INVALID_OFFSET_ERROR',
-    ATT_INSUFFICIENT_AUTHORIZATION_ERROR:       'ATT_INSUFFICIENT_AUTHORIZATION_ERROR',
-    ATT_PREPARE_QUEUE_FULL_ERROR:               'ATT_PREPARE_QUEUE_FULL_ERROR',
-    ATT_ATTRIBUTE_NOT_FOUND_ERROR:              'ATT_ATTRIBUTE_NOT_FOUND_ERROR',
-    ATT_ATTRIBUTE_NOT_LONG_ERROR:               'ATT_ATTRIBUTE_NOT_LONG_ERROR',
-    ATT_INSUFFICIENT_ENCRYPTION_KEY_SIZE_ERROR: 'ATT_INSUFFICIENT_ENCRYPTION_KEY_SIZE_ERROR',
-    ATT_INVALID_ATTRIBUTE_LENGTH_ERROR:         'ATT_INVALID_ATTRIBUTE_LENGTH_ERROR',
-    ATT_UNLIKELY_ERROR_ERROR:                   'ATT_UNLIKELY_ERROR_ERROR',
-    ATT_INSUFFICIENT_ENCRYPTION_ERROR:          'ATT_INSUFFICIENT_ENCRYPTION_ERROR',
-    ATT_UNSUPPORTED_GROUP_TYPE_ERROR:           'ATT_UNSUPPORTED_GROUP_TYPE_ERROR',
-    ATT_INSUFFICIENT_RESOURCES_ERROR:           'ATT_INSUFFICIENT_RESOURCES_ERROR'
-}
+    * Bluetooth spec @ Vol 3, Part F - 3.4.1.1 Error Response
+    * Core Specification Supplement: Common Profile And Service Error Codes
+    '''
+    INVALID_HANDLE                   = 0x01
+    READ_NOT_PERMITTED               = 0x02
+    WRITE_NOT_PERMITTED              = 0x03
+    INVALID_PDU                      = 0x04
+    INSUFFICIENT_AUTHENTICATION      = 0x05
+    REQUEST_NOT_SUPPORTED            = 0x06
+    INVALID_OFFSET                   = 0x07
+    INSUFFICIENT_AUTHORIZATION       = 0x08
+    PREPARE_QUEUE_FULL               = 0x09
+    ATTRIBUTE_NOT_FOUND              = 0x0A
+    ATTRIBUTE_NOT_LONG               = 0x0B
+    INSUFFICIENT_ENCRYPTION_KEY_SIZE = 0x0C
+    INVALID_ATTRIBUTE_LENGTH         = 0x0D
+    UNLIKELY_ERROR                   = 0x0E
+    INSUFFICIENT_ENCRYPTION          = 0x0F
+    UNSUPPORTED_GROUP_TYPE           = 0x10
+    INSUFFICIENT_RESOURCES           = 0x11
+    DATABASE_OUT_OF_SYNC             = 0x12
+    VALUE_NOT_ALLOWED                = 0x13
+    # 0x80 – 0x9F: Application Error
+    # 0xE0 – 0xFF: Common Profile and Service Error Codes
+    WRITE_REQUEST_REJECTED           = 0xFC
+    CCCD_IMPROPERLY_CONFIGURED       = 0xFD
+    PROCEDURE_ALREADY_IN_PROGRESS    = 0xFE
+    OUT_OF_RANGE                     = 0xFF
+
+# Backward Compatible Constants
+ATT_INVALID_HANDLE_ERROR                   = ErrorCode.INVALID_HANDLE
+ATT_READ_NOT_PERMITTED_ERROR               = ErrorCode.READ_NOT_PERMITTED
+ATT_WRITE_NOT_PERMITTED_ERROR              = ErrorCode.WRITE_NOT_PERMITTED
+ATT_INVALID_PDU_ERROR                      = ErrorCode.INVALID_PDU
+ATT_INSUFFICIENT_AUTHENTICATION_ERROR      = ErrorCode.INSUFFICIENT_AUTHENTICATION
+ATT_REQUEST_NOT_SUPPORTED_ERROR            = ErrorCode.REQUEST_NOT_SUPPORTED
+ATT_INVALID_OFFSET_ERROR                   = ErrorCode.INVALID_OFFSET
+ATT_INSUFFICIENT_AUTHORIZATION_ERROR       = ErrorCode.INSUFFICIENT_AUTHORIZATION
+ATT_PREPARE_QUEUE_FULL_ERROR               = ErrorCode.PREPARE_QUEUE_FULL
+ATT_ATTRIBUTE_NOT_FOUND_ERROR              = ErrorCode.ATTRIBUTE_NOT_FOUND
+ATT_ATTRIBUTE_NOT_LONG_ERROR               = ErrorCode.ATTRIBUTE_NOT_LONG
+ATT_INSUFFICIENT_ENCRYPTION_KEY_SIZE_ERROR = ErrorCode.INSUFFICIENT_ENCRYPTION_KEY_SIZE
+ATT_INVALID_ATTRIBUTE_LENGTH_ERROR         = ErrorCode.INVALID_ATTRIBUTE_LENGTH
+ATT_UNLIKELY_ERROR_ERROR                   = ErrorCode.UNLIKELY_ERROR
+ATT_INSUFFICIENT_ENCRYPTION_ERROR          = ErrorCode.INSUFFICIENT_ENCRYPTION
+ATT_UNSUPPORTED_GROUP_TYPE_ERROR           = ErrorCode.UNSUPPORTED_GROUP_TYPE
+ATT_INSUFFICIENT_RESOURCES_ERROR           = ErrorCode.INSUFFICIENT_RESOURCES
 
 ATT_DEFAULT_MTU = 23
 
 HANDLE_FIELD_SPEC    = {'size': 2, 'mapper': lambda x: f'0x{x:04X}'}
-UUID_2_16_FIELD_SPEC = lambda x, y: UUID.parse_uuid(x, y)    # noqa: E731
+# pylint: disable-next=unnecessary-lambda-assignment,unnecessary-lambda
+UUID_2_16_FIELD_SPEC = lambda x, y: UUID.parse_uuid(x, y)
+# pylint: disable-next=unnecessary-lambda-assignment,unnecessary-lambda
 UUID_2_FIELD_SPEC    = lambda x, y: UUID.parse_uuid_2(x, y)  # noqa: E731
 
-
-# -----------------------------------------------------------------------------
-# Utils
-# -----------------------------------------------------------------------------
-def key_with_value(dictionary, target_value):
-    for key, value in dictionary.items():
-        if value == target_value:
-            return key
-    return None
+# fmt: on
+# pylint: enable=line-too-long
+# pylint: disable=invalid-name
 
 
 # -----------------------------------------------------------------------------
 # Exceptions
 # -----------------------------------------------------------------------------
-class ATT_Error(Exception):
-    def __init__(self, error_code, att_handle=0x0000):
-        self.error_code = error_code
+class ATT_Error(ProtocolError):
+    def __init__(self, error_code, att_handle=0x0000, message=''):
+        super().__init__(
+            error_code,
+            error_namespace='att',
+            error_name=ATT_PDU.error_name(error_code),
+        )
         self.att_handle = att_handle
+        self.message = message
 
     def __str__(self):
-        return f'ATT_Error({ATT_PDU.error_name(self.error_code)})'
+        return f'ATT_Error(error={self.error_name}, handle={self.att_handle:04X}): {self.message}'
 
 
 # -----------------------------------------------------------------------------
@@ -196,8 +236,10 @@ class ATT_PDU:
     '''
     See Bluetooth spec @ Vol 3, Part F - 3.3 ATTRIBUTE PDU
     '''
-    pdu_classes = {}
+
+    pdu_classes: Dict[int, Type[ATT_PDU]] = {}
     op_code = 0
+    name: str
 
     @staticmethod
     def from_bytes(pdu):
@@ -219,9 +261,9 @@ class ATT_PDU:
     def pdu_name(op_code):
         return name_or_number(ATT_PDU_NAMES, op_code, 2)
 
-    @staticmethod
-    def error_name(error_code):
-        return name_or_number(ATT_ERROR_NAMES, error_code, 2)
+    @classmethod
+    def error_name(cls, error_code: int) -> str:
+        return ErrorCode(error_code).name
 
     @staticmethod
     def subclass(fields):
@@ -274,11 +316,13 @@ class ATT_PDU:
 
 
 # -----------------------------------------------------------------------------
-@ATT_PDU.subclass([
-    ('request_opcode_in_error',   {'size': 1, 'mapper': ATT_PDU.pdu_name}),
-    ('attribute_handle_in_error', HANDLE_FIELD_SPEC),
-    ('error_code',                {'size': 1, 'mapper': ATT_PDU.error_name})
-])
+@ATT_PDU.subclass(
+    [
+        ('request_opcode_in_error', {'size': 1, 'mapper': ATT_PDU.pdu_name}),
+        ('attribute_handle_in_error', HANDLE_FIELD_SPEC),
+        ('error_code', {'size': 1, 'mapper': ATT_PDU.error_name}),
+    ]
+)
 class ATT_Error_Response(ATT_PDU):
     '''
     See Bluetooth spec @ Vol 3, Part F - 3.4.1.1 Error Response
@@ -286,9 +330,7 @@ class ATT_Error_Response(ATT_PDU):
 
 
 # -----------------------------------------------------------------------------
-@ATT_PDU.subclass([
-    ('client_rx_mtu', 2)
-])
+@ATT_PDU.subclass([('client_rx_mtu', 2)])
 class ATT_Exchange_MTU_Request(ATT_PDU):
     '''
     See Bluetooth spec @ Vol 3, Part F - 3.4.2.1 Exchange MTU Request
@@ -296,9 +338,7 @@ class ATT_Exchange_MTU_Request(ATT_PDU):
 
 
 # -----------------------------------------------------------------------------
-@ATT_PDU.subclass([
-    ('server_rx_mtu', 2)
-])
+@ATT_PDU.subclass([('server_rx_mtu', 2)])
 class ATT_Exchange_MTU_Response(ATT_PDU):
     '''
     See Bluetooth spec @ Vol 3, Part F - 3.4.2.2 Exchange MTU Response
@@ -306,10 +346,9 @@ class ATT_Exchange_MTU_Response(ATT_PDU):
 
 
 # -----------------------------------------------------------------------------
-@ATT_PDU.subclass([
-    ('starting_handle', HANDLE_FIELD_SPEC),
-    ('ending_handle',   HANDLE_FIELD_SPEC)
-])
+@ATT_PDU.subclass(
+    [('starting_handle', HANDLE_FIELD_SPEC), ('ending_handle', HANDLE_FIELD_SPEC)]
+)
 class ATT_Find_Information_Request(ATT_PDU):
     '''
     See Bluetooth spec @ Vol 3, Part F - 3.4.3.1 Find Information Request
@@ -317,10 +356,7 @@ class ATT_Find_Information_Request(ATT_PDU):
 
 
 # -----------------------------------------------------------------------------
-@ATT_PDU.subclass([
-    ('format',           1),
-    ('information_data', '*')
-])
+@ATT_PDU.subclass([('format', 1), ('information_data', '*')])
 class ATT_Find_Information_Response(ATT_PDU):
     '''
     See Bluetooth spec @ Vol 3, Part F - 3.4.3.2 Find Information Response
@@ -332,7 +368,7 @@ class ATT_Find_Information_Response(ATT_PDU):
         uuid_size = 2 if self.format == 1 else 16
         while offset + uuid_size <= len(self.information_data):
             handle = struct.unpack_from('<H', self.information_data, offset)[0]
-            uuid   = self.information_data[2 + offset:2 + offset + uuid_size]
+            uuid = self.information_data[2 + offset : 2 + offset + uuid_size]
             self.information.append((handle, uuid))
             offset += 2 + uuid_size
 
@@ -346,20 +382,33 @@ class ATT_Find_Information_Response(ATT_PDU):
 
     def __str__(self):
         result = color(self.name, 'yellow')
-        result += ':\n' + HCI_Object.format_fields(self.__dict__, [
-            ('format',       1),
-            ('information', {'mapper': lambda x: ', '.join([f'0x{handle:04X}:{uuid.hex()}' for handle, uuid in x])})
-        ], '  ')
+        result += ':\n' + HCI_Object.format_fields(
+            self.__dict__,
+            [
+                ('format', 1),
+                (
+                    'information',
+                    {
+                        'mapper': lambda x: ', '.join(
+                            [f'0x{handle:04X}:{uuid.hex()}' for handle, uuid in x]
+                        )
+                    },
+                ),
+            ],
+            '  ',
+        )
         return result
 
 
 # -----------------------------------------------------------------------------
-@ATT_PDU.subclass([
-    ('starting_handle', HANDLE_FIELD_SPEC),
-    ('ending_handle',   HANDLE_FIELD_SPEC),
-    ('attribute_type',  UUID_2_FIELD_SPEC),
-    ('attribute_value', '*')
-])
+@ATT_PDU.subclass(
+    [
+        ('starting_handle', HANDLE_FIELD_SPEC),
+        ('ending_handle', HANDLE_FIELD_SPEC),
+        ('attribute_type', UUID_2_FIELD_SPEC),
+        ('attribute_value', '*'),
+    ]
+)
 class ATT_Find_By_Type_Value_Request(ATT_PDU):
     '''
     See Bluetooth spec @ Vol 3, Part F - 3.4.3.3 Find By Type Value Request
@@ -367,9 +416,7 @@ class ATT_Find_By_Type_Value_Request(ATT_PDU):
 
 
 # -----------------------------------------------------------------------------
-@ATT_PDU.subclass([
-    ('handles_information_list', '*')
-])
+@ATT_PDU.subclass([('handles_information_list', '*')])
 class ATT_Find_By_Type_Value_Response(ATT_PDU):
     '''
     See Bluetooth spec @ Vol 3, Part F - 3.4.3.4 Find By Type Value Response
@@ -379,7 +426,9 @@ class ATT_Find_By_Type_Value_Response(ATT_PDU):
         self.handles_information = []
         offset = 0
         while offset + 4 <= len(self.handles_information_list):
-            found_attribute_handle, group_end_handle = struct.unpack_from('<HH', self.handles_information_list, offset)
+            found_attribute_handle, group_end_handle = struct.unpack_from(
+                '<HH', self.handles_information_list, offset
+            )
             self.handles_information.append((found_attribute_handle, group_end_handle))
             offset += 4
 
@@ -393,18 +442,34 @@ class ATT_Find_By_Type_Value_Response(ATT_PDU):
 
     def __str__(self):
         result = color(self.name, 'yellow')
-        result += ':\n' + HCI_Object.format_fields(self.__dict__, [
-            ('handles_information', {'mapper': lambda x: ', '.join([f'0x{handle1:04X}-0x{handle2:04X}' for handle1, handle2 in x])})
-        ], '  ')
+        result += ':\n' + HCI_Object.format_fields(
+            self.__dict__,
+            [
+                (
+                    'handles_information',
+                    {
+                        'mapper': lambda x: ', '.join(
+                            [
+                                f'0x{handle1:04X}-0x{handle2:04X}'
+                                for handle1, handle2 in x
+                            ]
+                        )
+                    },
+                )
+            ],
+            '  ',
+        )
         return result
 
 
 # -----------------------------------------------------------------------------
-@ATT_PDU.subclass([
-    ('starting_handle', HANDLE_FIELD_SPEC),
-    ('ending_handle',   HANDLE_FIELD_SPEC),
-    ('attribute_type',  UUID_2_16_FIELD_SPEC)
-])
+@ATT_PDU.subclass(
+    [
+        ('starting_handle', HANDLE_FIELD_SPEC),
+        ('ending_handle', HANDLE_FIELD_SPEC),
+        ('attribute_type', UUID_2_16_FIELD_SPEC),
+    ]
+)
 class ATT_Read_By_Type_Request(ATT_PDU):
     '''
     See Bluetooth spec @ Vol 3, Part F - 3.4.4.1 Read By Type Request
@@ -412,10 +477,7 @@ class ATT_Read_By_Type_Request(ATT_PDU):
 
 
 # -----------------------------------------------------------------------------
-@ATT_PDU.subclass([
-    ('length',              1),
-    ('attribute_data_list', '*')
-])
+@ATT_PDU.subclass([('length', 1), ('attribute_data_list', '*')])
 class ATT_Read_By_Type_Response(ATT_PDU):
     '''
     See Bluetooth spec @ Vol 3, Part F - 3.4.4.2 Read By Type Response
@@ -424,9 +486,15 @@ class ATT_Read_By_Type_Response(ATT_PDU):
     def parse_attribute_data_list(self):
         self.attributes = []
         offset = 0
-        while self.length != 0 and offset + self.length <= len(self.attribute_data_list):
-            attribute_handle, = struct.unpack_from('<H', self.attribute_data_list, offset)
-            attribute_value = self.attribute_data_list[offset + 2:offset + self.length]
+        while self.length != 0 and offset + self.length <= len(
+            self.attribute_data_list
+        ):
+            (attribute_handle,) = struct.unpack_from(
+                '<H', self.attribute_data_list, offset
+            )
+            attribute_value = self.attribute_data_list[
+                offset + 2 : offset + self.length
+            ]
             self.attributes.append((attribute_handle, attribute_value))
             offset += self.length
 
@@ -440,17 +508,26 @@ class ATT_Read_By_Type_Response(ATT_PDU):
 
     def __str__(self):
         result = color(self.name, 'yellow')
-        result += ':\n' + HCI_Object.format_fields(self.__dict__, [
-            ('length',     1),
-            ('attributes', {'mapper': lambda x: ', '.join([f'0x{handle:04X}:{value.hex()}' for handle, value in x])})
-        ], '  ')
+        result += ':\n' + HCI_Object.format_fields(
+            self.__dict__,
+            [
+                ('length', 1),
+                (
+                    'attributes',
+                    {
+                        'mapper': lambda x: ', '.join(
+                            [f'0x{handle:04X}:{value.hex()}' for handle, value in x]
+                        )
+                    },
+                ),
+            ],
+            '  ',
+        )
         return result
 
 
 # -----------------------------------------------------------------------------
-@ATT_PDU.subclass([
-    ('attribute_handle', HANDLE_FIELD_SPEC)
-])
+@ATT_PDU.subclass([('attribute_handle', HANDLE_FIELD_SPEC)])
 class ATT_Read_Request(ATT_PDU):
     '''
     See Bluetooth spec @ Vol 3, Part F - 3.4.4.3 Read Request
@@ -458,9 +535,7 @@ class ATT_Read_Request(ATT_PDU):
 
 
 # -----------------------------------------------------------------------------
-@ATT_PDU.subclass([
-    ('attribute_value', '*')
-])
+@ATT_PDU.subclass([('attribute_value', '*')])
 class ATT_Read_Response(ATT_PDU):
     '''
     See Bluetooth spec @ Vol 3, Part F - 3.4.4.4 Read Response
@@ -468,10 +543,7 @@ class ATT_Read_Response(ATT_PDU):
 
 
 # -----------------------------------------------------------------------------
-@ATT_PDU.subclass([
-    ('attribute_handle', HANDLE_FIELD_SPEC),
-    ('value_offset',     2)
-])
+@ATT_PDU.subclass([('attribute_handle', HANDLE_FIELD_SPEC), ('value_offset', 2)])
 class ATT_Read_Blob_Request(ATT_PDU):
     '''
     See Bluetooth spec @ Vol 3, Part F - 3.4.4.5 Read Blob Request
@@ -479,9 +551,7 @@ class ATT_Read_Blob_Request(ATT_PDU):
 
 
 # -----------------------------------------------------------------------------
-@ATT_PDU.subclass([
-    ('part_attribute_value', '*')
-])
+@ATT_PDU.subclass([('part_attribute_value', '*')])
 class ATT_Read_Blob_Response(ATT_PDU):
     '''
     See Bluetooth spec @ Vol 3, Part F - 3.4.4.6 Read Blob Response
@@ -489,9 +559,7 @@ class ATT_Read_Blob_Response(ATT_PDU):
 
 
 # -----------------------------------------------------------------------------
-@ATT_PDU.subclass([
-    ('set_of_handles', '*')
-])
+@ATT_PDU.subclass([('set_of_handles', '*')])
 class ATT_Read_Multiple_Request(ATT_PDU):
     '''
     See Bluetooth spec @ Vol 3, Part F - 3.4.4.7 Read Multiple Request
@@ -499,9 +567,7 @@ class ATT_Read_Multiple_Request(ATT_PDU):
 
 
 # -----------------------------------------------------------------------------
-@ATT_PDU.subclass([
-    ('set_of_values', '*')
-])
+@ATT_PDU.subclass([('set_of_values', '*')])
 class ATT_Read_Multiple_Response(ATT_PDU):
     '''
     See Bluetooth spec @ Vol 3, Part F - 3.4.4.8 Read Multiple Response
@@ -509,11 +575,13 @@ class ATT_Read_Multiple_Response(ATT_PDU):
 
 
 # -----------------------------------------------------------------------------
-@ATT_PDU.subclass([
-    ('starting_handle',      HANDLE_FIELD_SPEC),
-    ('ending_handle',        HANDLE_FIELD_SPEC),
-    ('attribute_group_type', UUID_2_16_FIELD_SPEC)
-])
+@ATT_PDU.subclass(
+    [
+        ('starting_handle', HANDLE_FIELD_SPEC),
+        ('ending_handle', HANDLE_FIELD_SPEC),
+        ('attribute_group_type', UUID_2_16_FIELD_SPEC),
+    ]
+)
 class ATT_Read_By_Group_Type_Request(ATT_PDU):
     '''
     See Bluetooth spec @ Vol 3, Part F - 3.4.4.9 Read by Group Type Request
@@ -521,10 +589,7 @@ class ATT_Read_By_Group_Type_Request(ATT_PDU):
 
 
 # -----------------------------------------------------------------------------
-@ATT_PDU.subclass([
-    ('length',              1),
-    ('attribute_data_list', '*')
-])
+@ATT_PDU.subclass([('length', 1), ('attribute_data_list', '*')])
 class ATT_Read_By_Group_Type_Response(ATT_PDU):
     '''
     See Bluetooth spec @ Vol 3, Part F - 3.4.4.10 Read by Group Type Response
@@ -533,10 +598,18 @@ class ATT_Read_By_Group_Type_Response(ATT_PDU):
     def parse_attribute_data_list(self):
         self.attributes = []
         offset = 0
-        while self.length != 0 and offset + self.length <= len(self.attribute_data_list):
-            attribute_handle, end_group_handle = struct.unpack_from('<HH', self.attribute_data_list, offset)
-            attribute_value = self.attribute_data_list[offset + 4:offset + self.length]
-            self.attributes.append((attribute_handle, end_group_handle, attribute_value))
+        while self.length != 0 and offset + self.length <= len(
+            self.attribute_data_list
+        ):
+            attribute_handle, end_group_handle = struct.unpack_from(
+                '<HH', self.attribute_data_list, offset
+            )
+            attribute_value = self.attribute_data_list[
+                offset + 4 : offset + self.length
+            ]
+            self.attributes.append(
+                (attribute_handle, end_group_handle, attribute_value)
+            )
             offset += self.length
 
     def __init__(self, *args, **kwargs):
@@ -549,18 +622,29 @@ class ATT_Read_By_Group_Type_Response(ATT_PDU):
 
     def __str__(self):
         result = color(self.name, 'yellow')
-        result += ':\n' + HCI_Object.format_fields(self.__dict__, [
-            ('length',     1),
-            ('attributes', {'mapper': lambda x: ', '.join([f'0x{handle:04X}-0x{end:04X}:{value.hex()}' for handle, end, value in x])})
-        ], '  ')
+        result += ':\n' + HCI_Object.format_fields(
+            self.__dict__,
+            [
+                ('length', 1),
+                (
+                    'attributes',
+                    {
+                        'mapper': lambda x: ', '.join(
+                            [
+                                f'0x{handle:04X}-0x{end:04X}:{value.hex()}'
+                                for handle, end, value in x
+                            ]
+                        )
+                    },
+                ),
+            ],
+            '  ',
+        )
         return result
 
 
 # -----------------------------------------------------------------------------
-@ATT_PDU.subclass([
-    ('attribute_handle', HANDLE_FIELD_SPEC),
-    ('attribute_value',  '*')
-])
+@ATT_PDU.subclass([('attribute_handle', HANDLE_FIELD_SPEC), ('attribute_value', '*')])
 class ATT_Write_Request(ATT_PDU):
     '''
     See Bluetooth spec @ Vol 3, Part F - 3.4.5.1 Write Request
@@ -576,10 +660,7 @@ class ATT_Write_Response(ATT_PDU):
 
 
 # -----------------------------------------------------------------------------
-@ATT_PDU.subclass([
-    ('attribute_handle', HANDLE_FIELD_SPEC),
-    ('attribute_value',  '*')
-])
+@ATT_PDU.subclass([('attribute_handle', HANDLE_FIELD_SPEC), ('attribute_value', '*')])
 class ATT_Write_Command(ATT_PDU):
     '''
     See Bluetooth spec @ Vol 3, Part F - 3.4.5.3 Write Command
@@ -587,11 +668,13 @@ class ATT_Write_Command(ATT_PDU):
 
 
 # -----------------------------------------------------------------------------
-@ATT_PDU.subclass([
-    ('attribute_handle', HANDLE_FIELD_SPEC),
-    ('attribute_value',  '*')
-    # ('authentication_signature', 'TODO')
-])
+@ATT_PDU.subclass(
+    [
+        ('attribute_handle', HANDLE_FIELD_SPEC),
+        ('attribute_value', '*'),
+        # ('authentication_signature', 'TODO')
+    ]
+)
 class ATT_Signed_Write_Command(ATT_PDU):
     '''
     See Bluetooth spec @ Vol 3, Part F - 3.4.5.4 Signed Write Command
@@ -599,11 +682,13 @@ class ATT_Signed_Write_Command(ATT_PDU):
 
 
 # -----------------------------------------------------------------------------
-@ATT_PDU.subclass([
-    ('attribute_handle',     HANDLE_FIELD_SPEC),
-    ('value_offset',         2),
-    ('part_attribute_value', '*')
-])
+@ATT_PDU.subclass(
+    [
+        ('attribute_handle', HANDLE_FIELD_SPEC),
+        ('value_offset', 2),
+        ('part_attribute_value', '*'),
+    ]
+)
 class ATT_Prepare_Write_Request(ATT_PDU):
     '''
     See Bluetooth spec @ Vol 3, Part F - 3.4.6.1 Prepare Write Request
@@ -611,11 +696,13 @@ class ATT_Prepare_Write_Request(ATT_PDU):
 
 
 # -----------------------------------------------------------------------------
-@ATT_PDU.subclass([
-    ('attribute_handle',     HANDLE_FIELD_SPEC),
-    ('value_offset',         2),
-    ('part_attribute_value', '*')
-])
+@ATT_PDU.subclass(
+    [
+        ('attribute_handle', HANDLE_FIELD_SPEC),
+        ('value_offset', 2),
+        ('part_attribute_value', '*'),
+    ]
+)
 class ATT_Prepare_Write_Response(ATT_PDU):
     '''
     See Bluetooth spec @ Vol 3, Part F - 3.4.6.2 Prepare Write Response
@@ -623,7 +710,7 @@ class ATT_Prepare_Write_Response(ATT_PDU):
 
 
 # -----------------------------------------------------------------------------
-@ATT_PDU.subclass([])
+@ATT_PDU.subclass([("flags", 1)])
 class ATT_Execute_Write_Request(ATT_PDU):
     '''
     See Bluetooth spec @ Vol 3, Part F - 3.4.6.3 Execute Write Request
@@ -639,10 +726,7 @@ class ATT_Execute_Write_Response(ATT_PDU):
 
 
 # -----------------------------------------------------------------------------
-@ATT_PDU.subclass([
-    ('attribute_handle', HANDLE_FIELD_SPEC),
-    ('attribute_value',  '*')
-])
+@ATT_PDU.subclass([('attribute_handle', HANDLE_FIELD_SPEC), ('attribute_value', '*')])
 class ATT_Handle_Value_Notification(ATT_PDU):
     '''
     See Bluetooth spec @ Vol 3, Part F - 3.4.7.1 Handle Value Notification
@@ -650,10 +734,7 @@ class ATT_Handle_Value_Notification(ATT_PDU):
 
 
 # -----------------------------------------------------------------------------
-@ATT_PDU.subclass([
-    ('attribute_handle', HANDLE_FIELD_SPEC),
-    ('attribute_value',  '*')
-])
+@ATT_PDU.subclass([('attribute_handle', HANDLE_FIELD_SPEC), ('attribute_value', '*')])
 class ATT_Handle_Value_Indication(ATT_PDU):
     '''
     See Bluetooth spec @ Vol 3, Part F - 3.4.7.2 Handle Value Indication
@@ -669,60 +750,199 @@ class ATT_Handle_Value_Confirmation(ATT_PDU):
 
 
 # -----------------------------------------------------------------------------
-class Attribute(EventEmitter):
-    # Permission flags
-    READABLE                      = 0x01
-    WRITEABLE                     = 0x02
-    READ_REQUIRES_ENCRYPTION      = 0x04
-    WRITE_REQUIRES_ENCRYPTION     = 0x08
-    READ_REQUIRES_AUTHENTICATION  = 0x10
-    WRITE_REQUIRES_AUTHENTICATION = 0x20
-    READ_REQUIRES_AUTHORIZATION   = 0x40
-    WRITE_REQUIRES_AUTHORIZATION  = 0x80
+class AttributeValue:
+    '''
+    Attribute value where reading and/or writing is delegated to functions
+    passed as arguments to the constructor.
+    '''
 
-    def __init__(self, attribute_type, permissions, value = b''):
+    def __init__(
+        self,
+        read: Union[
+            Callable[[Optional[Connection]], bytes],
+            Callable[[Optional[Connection]], Awaitable[bytes]],
+            None,
+        ] = None,
+        write: Union[
+            Callable[[Optional[Connection], bytes], None],
+            Callable[[Optional[Connection], bytes], Awaitable[None]],
+            None,
+        ] = None,
+    ):
+        self._read = read
+        self._write = write
+
+    def read(self, connection: Optional[Connection]) -> Union[bytes, Awaitable[bytes]]:
+        return self._read(connection) if self._read else b''
+
+    def write(
+        self, connection: Optional[Connection], value: bytes
+    ) -> Union[Awaitable[None], None]:
+        if self._write:
+            return self._write(connection, value)
+
+        return None
+
+
+# -----------------------------------------------------------------------------
+class Attribute(EventEmitter):
+    class Permissions(enum.IntFlag):
+        READABLE = 0x01
+        WRITEABLE = 0x02
+        READ_REQUIRES_ENCRYPTION = 0x04
+        WRITE_REQUIRES_ENCRYPTION = 0x08
+        READ_REQUIRES_AUTHENTICATION = 0x10
+        WRITE_REQUIRES_AUTHENTICATION = 0x20
+        READ_REQUIRES_AUTHORIZATION = 0x40
+        WRITE_REQUIRES_AUTHORIZATION = 0x80
+
+        @classmethod
+        def from_string(cls, permissions_str: str) -> Attribute.Permissions:
+            try:
+                return functools.reduce(
+                    lambda x, y: x | Attribute.Permissions[y],
+                    permissions_str.replace('|', ',').split(","),
+                    Attribute.Permissions(0),
+                )
+            except TypeError as exc:
+                # 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"Attribute::permissions error:\nExpected a string containing any of the keys, separated by commas: {enum_list_str}\nGot: {permissions_str}"
+                ) from exc
+
+    # Permission flags(legacy-use only)
+    READABLE = Permissions.READABLE
+    WRITEABLE = Permissions.WRITEABLE
+    READ_REQUIRES_ENCRYPTION = Permissions.READ_REQUIRES_ENCRYPTION
+    WRITE_REQUIRES_ENCRYPTION = Permissions.WRITE_REQUIRES_ENCRYPTION
+    READ_REQUIRES_AUTHENTICATION = Permissions.READ_REQUIRES_AUTHENTICATION
+    WRITE_REQUIRES_AUTHENTICATION = Permissions.WRITE_REQUIRES_AUTHENTICATION
+    READ_REQUIRES_AUTHORIZATION = Permissions.READ_REQUIRES_AUTHORIZATION
+    WRITE_REQUIRES_AUTHORIZATION = Permissions.WRITE_REQUIRES_AUTHORIZATION
+
+    value: Union[bytes, AttributeValue]
+
+    def __init__(
+        self,
+        attribute_type: Union[str, bytes, UUID],
+        permissions: Union[str, Attribute.Permissions],
+        value: Union[str, bytes, AttributeValue] = b'',
+    ) -> None:
         EventEmitter.__init__(self)
-        self.handle           = 0
+        self.handle = 0
         self.end_group_handle = 0
-        self.permissions      = permissions
+        if isinstance(permissions, str):
+            self.permissions = Attribute.Permissions.from_string(permissions)
+        else:
+            self.permissions = permissions
 
         # Convert the type to a UUID object if it isn't already
-        if type(attribute_type) is str:
+        if isinstance(attribute_type, str):
             self.type = UUID(attribute_type)
-        elif type(attribute_type) is bytes:
+        elif isinstance(attribute_type, bytes):
             self.type = UUID.from_bytes(attribute_type)
         else:
             self.type = attribute_type
 
         # Convert the value to a byte array
-        if type(value) is str:
+        if isinstance(value, str):
             self.value = bytes(value, 'utf-8')
         else:
             self.value = value
 
-    def read_value(self, connection):
-        if read := getattr(self.value, 'read', None):
-            try:
-                return read(connection)
-            except ATT_Error as error:
-                raise ATT_Error(error_code=error.error_code, att_handle=self.handle)
-        else:
-            return self.value
+    def encode_value(self, value: Any) -> bytes:
+        return value
 
-    def write_value(self, connection, value):
-        if write := getattr(self.value, 'write', None):
+    def decode_value(self, value_bytes: bytes) -> Any:
+        return value_bytes
+
+    async def read_value(self, connection: Optional[Connection]) -> bytes:
+        if (
+            (self.permissions & self.READ_REQUIRES_ENCRYPTION)
+            and connection is not None
+            and not connection.encryption
+        ):
+            raise ATT_Error(
+                error_code=ATT_INSUFFICIENT_ENCRYPTION_ERROR, att_handle=self.handle
+            )
+        if (
+            (self.permissions & self.READ_REQUIRES_AUTHENTICATION)
+            and connection is not None
+            and not connection.authenticated
+        ):
+            raise ATT_Error(
+                error_code=ATT_INSUFFICIENT_AUTHENTICATION_ERROR, att_handle=self.handle
+            )
+        if self.permissions & self.READ_REQUIRES_AUTHORIZATION:
+            # TODO: handle authorization better
+            raise ATT_Error(
+                error_code=ATT_INSUFFICIENT_AUTHORIZATION_ERROR, att_handle=self.handle
+            )
+
+        if hasattr(self.value, 'read'):
             try:
-                write(connection, value)
+                value = self.value.read(connection)
+                if inspect.isawaitable(value):
+                    value = await value
             except ATT_Error as error:
-                raise ATT_Error(error_code=error.error_code, att_handle=self.handle)
+                raise ATT_Error(
+                    error_code=error.error_code, att_handle=self.handle
+                ) from error
+        else:
+            value = self.value
+
+        return self.encode_value(value)
+
+    async def write_value(self, connection: Connection, value_bytes: bytes) -> None:
+        if (
+            self.permissions & self.WRITE_REQUIRES_ENCRYPTION
+        ) and not connection.encryption:
+            raise ATT_Error(
+                error_code=ATT_INSUFFICIENT_ENCRYPTION_ERROR, att_handle=self.handle
+            )
+        if (
+            self.permissions & self.WRITE_REQUIRES_AUTHENTICATION
+        ) and not connection.authenticated:
+            raise ATT_Error(
+                error_code=ATT_INSUFFICIENT_AUTHENTICATION_ERROR, att_handle=self.handle
+            )
+        if self.permissions & self.WRITE_REQUIRES_AUTHORIZATION:
+            # TODO: handle authorization better
+            raise ATT_Error(
+                error_code=ATT_INSUFFICIENT_AUTHORIZATION_ERROR, att_handle=self.handle
+            )
+
+        value = self.decode_value(value_bytes)
+
+        if hasattr(self.value, 'write'):
+            try:
+                result = self.value.write(connection, value)
+                if inspect.isawaitable(result):
+                    await result
+            except ATT_Error as error:
+                raise ATT_Error(
+                    error_code=error.error_code, att_handle=self.handle
+                ) from error
         else:
             self.value = value
 
         self.emit('write', connection, value)
 
     def __repr__(self):
-        if len(self.value) > 0:
+        if isinstance(self.value, bytes):
+            value_str = self.value.hex()
+        else:
+            value_str = str(self.value)
+        if value_str:
             value_string = f', value={self.value.hex()}'
         else:
             value_string = ''
-        return f'Attribute(handle=0x{self.handle:04X}, type={self.type}, permissions={self.permissions}{value_string})'
+        return (
+            f'Attribute(handle=0x{self.handle:04X}, '
+            f'type={self.type}, '
+            f'permissions={self.permissions}{value_string})'
+        )

bumble/avc.py

@@ -0,0 +1,524 @@
+# Copyright 2021-2023 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# -----------------------------------------------------------------------------
+# Imports
+# -----------------------------------------------------------------------------
+from __future__ import annotations
+import enum
+import struct
+from typing import Dict, Type, Union, Tuple
+
+from bumble import core
+from bumble.utils import OpenIntEnum
+
+
+# -----------------------------------------------------------------------------
+class Frame:
+    class SubunitType(enum.IntEnum):
+        # AV/C Digital Interface Command Set General Specification Version 4.1
+        # Table 7.4
+        MONITOR = 0x00
+        AUDIO = 0x01
+        PRINTER = 0x02
+        DISC = 0x03
+        TAPE_RECORDER_OR_PLAYER = 0x04
+        TUNER = 0x05
+        CA = 0x06
+        CAMERA = 0x07
+        PANEL = 0x09
+        BULLETIN_BOARD = 0x0A
+        VENDOR_UNIQUE = 0x1C
+        EXTENDED = 0x1E
+        UNIT = 0x1F
+
+    class OperationCode(OpenIntEnum):
+        # 0x00 - 0x0F: Unit and subunit commands
+        VENDOR_DEPENDENT = 0x00
+        RESERVE = 0x01
+        PLUG_INFO = 0x02
+
+        # 0x10 - 0x3F: Unit commands
+        DIGITAL_OUTPUT = 0x10
+        DIGITAL_INPUT = 0x11
+        CHANNEL_USAGE = 0x12
+        OUTPUT_PLUG_SIGNAL_FORMAT = 0x18
+        INPUT_PLUG_SIGNAL_FORMAT = 0x19
+        GENERAL_BUS_SETUP = 0x1F
+        CONNECT_AV = 0x20
+        DISCONNECT_AV = 0x21
+        CONNECTIONS = 0x22
+        CONNECT = 0x24
+        DISCONNECT = 0x25
+        UNIT_INFO = 0x30
+        SUBUNIT_INFO = 0x31
+
+        # 0x40 - 0x7F: Subunit commands
+        PASS_THROUGH = 0x7C
+        GUI_UPDATE = 0x7D
+        PUSH_GUI_DATA = 0x7E
+        USER_ACTION = 0x7F
+
+        # 0xA0 - 0xBF: Unit and subunit commands
+        VERSION = 0xB0
+        POWER = 0xB2
+
+    subunit_type: SubunitType
+    subunit_id: int
+    opcode: OperationCode
+    operands: bytes
+
+    @staticmethod
+    def subclass(subclass):
+        # Infer the opcode from the class name
+        if subclass.__name__.endswith("CommandFrame"):
+            short_name = subclass.__name__.replace("CommandFrame", "")
+            category_class = CommandFrame
+        elif subclass.__name__.endswith("ResponseFrame"):
+            short_name = subclass.__name__.replace("ResponseFrame", "")
+            category_class = ResponseFrame
+        else:
+            raise 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: Union[CommandFrame.CommandType, ResponseFrame.ResponseCode],
+    ) -> bytes:
+        # TODO: support extended subunit types and ids.
+        return (
+            bytes(
+                [
+                    ctype_or_response,
+                    self.subunit_type << 3 | self.subunit_id,
+                    self.opcode,
+                ]
+            )
+            + self.operands
+        )
+
+    def to_string(self, extra: str) -> str:
+        return (
+            f"{self.__class__.__name__}({extra}"
+            f"subunit_type={self.subunit_type.name}, "
+            f"subunit_id=0x{self.subunit_id:02X}, "
+            f"opcode={self.opcode.name}, "
+            f"operands={self.operands.hex()})"
+        )
+
+    def __init__(
+        self,
+        subunit_type: SubunitType,
+        subunit_id: int,
+        opcode: OperationCode,
+        operands: bytes,
+    ) -> None:
+        self.subunit_type = subunit_type
+        self.subunit_id = subunit_id
+        self.opcode = opcode
+        self.operands = operands
+
+
+# -----------------------------------------------------------------------------
+class CommandFrame(Frame):
+    class CommandType(OpenIntEnum):
+        # AV/C Digital Interface Command Set General Specification Version 4.1
+        # Table 7.1
+        CONTROL = 0x00
+        STATUS = 0x01
+        SPECIFIC_INQUIRY = 0x02
+        NOTIFY = 0x03
+        GENERAL_INQUIRY = 0x04
+
+    subclasses: Dict[Frame.OperationCode, Type[CommandFrame]] = {}
+    ctype: CommandType
+
+    @staticmethod
+    def parse_operands(operands: bytes) -> Tuple:
+        raise NotImplementedError
+
+    def __init__(
+        self,
+        ctype: CommandType,
+        subunit_type: Frame.SubunitType,
+        subunit_id: int,
+        opcode: Frame.OperationCode,
+        operands: bytes,
+    ) -> None:
+        super().__init__(subunit_type, subunit_id, opcode, operands)
+        self.ctype = ctype
+
+    def __bytes__(self):
+        return self.to_bytes(self.ctype)
+
+    def __str__(self):
+        return self.to_string(f"ctype={self.ctype.name}, ")
+
+
+# -----------------------------------------------------------------------------
+class ResponseFrame(Frame):
+    class ResponseCode(OpenIntEnum):
+        # AV/C Digital Interface Command Set General Specification Version 4.1
+        # Table 7.2
+        NOT_IMPLEMENTED = 0x08
+        ACCEPTED = 0x09
+        REJECTED = 0x0A
+        IN_TRANSITION = 0x0B
+        IMPLEMENTED_OR_STABLE = 0x0C
+        CHANGED = 0x0D
+        INTERIM = 0x0F
+
+    subclasses: Dict[Frame.OperationCode, Type[ResponseFrame]] = {}
+    response: ResponseCode
+
+    @staticmethod
+    def parse_operands(operands: bytes) -> Tuple:
+        raise NotImplementedError
+
+    def __init__(
+        self,
+        response: ResponseCode,
+        subunit_type: Frame.SubunitType,
+        subunit_id: int,
+        opcode: Frame.OperationCode,
+        operands: bytes,
+    ) -> None:
+        super().__init__(subunit_type, subunit_id, opcode, operands)
+        self.response = response
+
+    def __bytes__(self):
+        return self.to_bytes(self.response)
+
+    def __str__(self):
+        return self.to_string(f"response={self.response.name}, ")
+
+
+# -----------------------------------------------------------------------------
+class VendorDependentFrame:
+    company_id: int
+    vendor_dependent_data: bytes
+
+    @staticmethod
+    def parse_operands(operands: bytes) -> Tuple:
+        return (
+            struct.unpack(">I", b"\x00" + operands[:3])[0],
+            operands[3:],
+        )
+
+    def make_operands(self) -> bytes:
+        return struct.pack(">I", self.company_id)[1:] + self.vendor_dependent_data
+
+    def __init__(self, company_id: int, vendor_dependent_data: bytes):
+        self.company_id = company_id
+        self.vendor_dependent_data = vendor_dependent_data
+
+
+# -----------------------------------------------------------------------------
+@Frame.subclass
+class VendorDependentCommandFrame(VendorDependentFrame, CommandFrame):
+    def __init__(
+        self,
+        ctype: CommandFrame.CommandType,
+        subunit_type: Frame.SubunitType,
+        subunit_id: int,
+        company_id: int,
+        vendor_dependent_data: bytes,
+    ) -> None:
+        VendorDependentFrame.__init__(self, company_id, vendor_dependent_data)
+        CommandFrame.__init__(
+            self,
+            ctype,
+            subunit_type,
+            subunit_id,
+            Frame.OperationCode.VENDOR_DEPENDENT,
+            self.make_operands(),
+        )
+
+    def __str__(self):
+        return (
+            f"VendorDependentCommandFrame(ctype={self.ctype.name}, "
+            f"subunit_type={self.subunit_type.name}, "
+            f"subunit_id=0x{self.subunit_id:02X}, "
+            f"company_id=0x{self.company_id:06X}, "
+            f"vendor_dependent_data={self.vendor_dependent_data.hex()})"
+        )
+
+
+# -----------------------------------------------------------------------------
+@Frame.subclass
+class VendorDependentResponseFrame(VendorDependentFrame, ResponseFrame):
+    def __init__(
+        self,
+        response: ResponseFrame.ResponseCode,
+        subunit_type: Frame.SubunitType,
+        subunit_id: int,
+        company_id: int,
+        vendor_dependent_data: bytes,
+    ) -> None:
+        VendorDependentFrame.__init__(self, company_id, vendor_dependent_data)
+        ResponseFrame.__init__(
+            self,
+            response,
+            subunit_type,
+            subunit_id,
+            Frame.OperationCode.VENDOR_DEPENDENT,
+            self.make_operands(),
+        )
+
+    def __str__(self):
+        return (
+            f"VendorDependentResponseFrame(response={self.response.name}, "
+            f"subunit_type={self.subunit_type.name}, "
+            f"subunit_id=0x{self.subunit_id:02X}, "
+            f"company_id=0x{self.company_id:06X}, "
+            f"vendor_dependent_data={self.vendor_dependent_data.hex()})"
+        )
+
+
+# -----------------------------------------------------------------------------
+class PassThroughFrame:
+    """
+    See AV/C Panel Subunit Specification 1.1 - 9.4 PASS THROUGH control command
+    """
+
+    class StateFlag(enum.IntEnum):
+        PRESSED = 0
+        RELEASED = 1
+
+    class OperationId(OpenIntEnum):
+        SELECT = 0x00
+        UP = 0x01
+        DOWN = 0x01
+        LEFT = 0x03
+        RIGHT = 0x04
+        RIGHT_UP = 0x05
+        RIGHT_DOWN = 0x06
+        LEFT_UP = 0x07
+        LEFT_DOWN = 0x08
+        ROOT_MENU = 0x09
+        SETUP_MENU = 0x0A
+        CONTENTS_MENU = 0x0B
+        FAVORITE_MENU = 0x0C
+        EXIT = 0x0D
+        NUMBER_0 = 0x20
+        NUMBER_1 = 0x21
+        NUMBER_2 = 0x22
+        NUMBER_3 = 0x23
+        NUMBER_4 = 0x24
+        NUMBER_5 = 0x25
+        NUMBER_6 = 0x26
+        NUMBER_7 = 0x27
+        NUMBER_8 = 0x28
+        NUMBER_9 = 0x29
+        DOT = 0x2A
+        ENTER = 0x2B
+        CLEAR = 0x2C
+        CHANNEL_UP = 0x30
+        CHANNEL_DOWN = 0x31
+        PREVIOUS_CHANNEL = 0x32
+        SOUND_SELECT = 0x33
+        INPUT_SELECT = 0x34
+        DISPLAY_INFORMATION = 0x35
+        HELP = 0x36
+        PAGE_UP = 0x37
+        PAGE_DOWN = 0x38
+        POWER = 0x40
+        VOLUME_UP = 0x41
+        VOLUME_DOWN = 0x42
+        MUTE = 0x43
+        PLAY = 0x44
+        STOP = 0x45
+        PAUSE = 0x46
+        RECORD = 0x47
+        REWIND = 0x48
+        FAST_FORWARD = 0x49
+        EJECT = 0x4A
+        FORWARD = 0x4B
+        BACKWARD = 0x4C
+        ANGLE = 0x50
+        SUBPICTURE = 0x51
+        F1 = 0x71
+        F2 = 0x72
+        F3 = 0x73
+        F4 = 0x74
+        F5 = 0x75
+        VENDOR_UNIQUE = 0x7E
+
+    state_flag: StateFlag
+    operation_id: OperationId
+    operation_data: bytes
+
+    @staticmethod
+    def parse_operands(operands: bytes) -> Tuple:
+        return (
+            PassThroughFrame.StateFlag(operands[0] >> 7),
+            PassThroughFrame.OperationId(operands[0] & 0x7F),
+            operands[1 : 1 + operands[1]],
+        )
+
+    def make_operands(self):
+        return (
+            bytes([self.state_flag << 7 | self.operation_id, len(self.operation_data)])
+            + self.operation_data
+        )
+
+    def __init__(
+        self,
+        state_flag: StateFlag,
+        operation_id: OperationId,
+        operation_data: bytes,
+    ) -> None:
+        if len(operation_data) > 255:
+            raise 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,292 @@
+# Copyright 2021-2023 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# -----------------------------------------------------------------------------
+# Imports
+# -----------------------------------------------------------------------------
+from __future__ import annotations
+from enum import IntEnum
+import logging
+import struct
+from typing import Callable, cast, Dict, Optional
+
+from bumble.colors import color
+from bumble import avc
+from bumble import core
+from bumble import l2cap
+
+# -----------------------------------------------------------------------------
+# Logging
+# -----------------------------------------------------------------------------
+logger = logging.getLogger(__name__)
+
+
+# -----------------------------------------------------------------------------
+# Constants
+# -----------------------------------------------------------------------------
+AVCTP_PSM = 0x0017
+AVCTP_BROWSING_PSM = 0x001B
+
+
+# -----------------------------------------------------------------------------
+class MessageAssembler:
+    Callback = Callable[[int, bool, bool, int, bytes], None]
+
+    transaction_label: int
+    pid: int
+    c_r: int
+    ipid: int
+    payload: bytes
+    number_of_packets: int
+    packets_received: int
+
+    def __init__(self, callback: Callback) -> None:
+        self.callback = callback
+        self.reset()
+
+    def reset(self) -> None:
+        self.packets_received = 0
+        self.transaction_label = -1
+        self.pid = -1
+        self.c_r = -1
+        self.ipid = -1
+        self.payload = b''
+        self.number_of_packets = 0
+        self.packet_count = 0
+
+    def on_pdu(self, pdu: bytes) -> None:
+        self.packets_received += 1
+
+        transaction_label = pdu[0] >> 4
+        packet_type = Protocol.PacketType((pdu[0] >> 2) & 3)
+        c_r = (pdu[0] >> 1) & 1
+        ipid = pdu[0] & 1
+
+        if c_r == 0 and ipid != 0:
+            logger.warning("invalid IPID in command frame")
+            self.reset()
+            return
+
+        pid_offset = 1
+        if packet_type in (Protocol.PacketType.SINGLE, Protocol.PacketType.START):
+            if self.transaction_label >= 0:
+                # We are already in a transaction
+                logger.warning("received START or SINGLE fragment while in transaction")
+                self.reset()
+                self.packets_received = 1
+
+            if packet_type == Protocol.PacketType.START:
+                self.number_of_packets = pdu[1]
+                pid_offset = 2
+
+        pid = struct.unpack_from(">H", pdu, pid_offset)[0]
+        self.payload += pdu[pid_offset + 2 :]
+
+        if packet_type in (Protocol.PacketType.CONTINUE, Protocol.PacketType.END):
+            if transaction_label != self.transaction_label:
+                logger.warning("transaction label does not match")
+                self.reset()
+                return
+
+            if pid != self.pid:
+                logger.warning("PID does not match")
+                self.reset()
+                return
+
+            if c_r != self.c_r:
+                logger.warning("C/R does not match")
+                self.reset()
+                return
+
+            if self.packets_received > self.number_of_packets:
+                logger.warning("too many fragments in transaction")
+                self.reset()
+                return
+
+            if packet_type == Protocol.PacketType.END:
+                if self.packets_received != self.number_of_packets:
+                    logger.warning("premature END")
+                    self.reset()
+                    return
+        else:
+            self.transaction_label = transaction_label
+            self.c_r = c_r
+            self.ipid = ipid
+            self.pid = pid
+
+        if packet_type in (Protocol.PacketType.SINGLE, Protocol.PacketType.END):
+            self.on_message_complete()
+
+    def on_message_complete(self):
+        try:
+            self.callback(
+                self.transaction_label,
+                self.c_r == 0,
+                self.ipid != 0,
+                self.pid,
+                self.payload,
+            )
+        except Exception as error:
+            logger.exception(color(f"!!! exception in callback: {error}", "red"))
+
+        self.reset()
+
+
+# -----------------------------------------------------------------------------
+class Protocol:
+    CommandHandler = Callable[[int, avc.CommandFrame], None]
+    command_handlers: Dict[int, CommandHandler]  # Command handlers, by PID
+    ResponseHandler = Callable[[int, Optional[avc.ResponseFrame]], None]
+    response_handlers: Dict[int, ResponseHandler]  # Response handlers, by PID
+    next_transaction_label: int
+    message_assembler: MessageAssembler
+
+    class PacketType(IntEnum):
+        SINGLE = 0b00
+        START = 0b01
+        CONTINUE = 0b10
+        END = 0b11
+
+    def __init__(self, l2cap_channel: l2cap.ClassicChannel) -> None:
+        self.command_handlers = {}
+        self.response_handlers = {}
+        self.l2cap_channel = l2cap_channel
+        self.message_assembler = MessageAssembler(self.on_message)
+
+        # Register to receive PDUs from the channel
+        l2cap_channel.sink = self.on_pdu
+        l2cap_channel.on("open", self.on_l2cap_channel_open)
+        l2cap_channel.on("close", self.on_l2cap_channel_close)
+
+    def on_l2cap_channel_open(self):
+        logger.debug(color("<<< AVCTP channel open", "magenta"))
+
+    def on_l2cap_channel_close(self):
+        logger.debug(color("<<< AVCTP channel closed", "magenta"))
+
+    def on_pdu(self, pdu: bytes) -> None:
+        self.message_assembler.on_pdu(pdu)
+
+    def on_message(
+        self,
+        transaction_label: int,
+        is_command: bool,
+        ipid: bool,
+        pid: int,
+        payload: bytes,
+    ) -> None:
+        logger.debug(
+            f"<<< AVCTP Message: pid={pid}, "
+            f"transaction_label={transaction_label}, "
+            f"is_command={is_command}, "
+            f"ipid={ipid}, "
+            f"payload={payload.hex()}"
+        )
+
+        # Check for invalid PID responses.
+        if ipid:
+            logger.debug(f"received IPID for PID={pid}")
+
+        # Find the appropriate handler.
+        if is_command:
+            if pid not in self.command_handlers:
+                logger.warning(f"no command handler for PID {pid}")
+                self.send_ipid(transaction_label, pid)
+                return
+
+            command_frame = cast(avc.CommandFrame, avc.Frame.from_bytes(payload))
+            self.command_handlers[pid](transaction_label, command_frame)
+        else:
+            if pid not in self.response_handlers:
+                logger.warning(f"no response handler for PID {pid}")
+                return
+
+            # By convention, for an ipid, send a None payload to the response handler.
+            if ipid:
+                response_frame = None
+            else:
+                response_frame = cast(avc.ResponseFrame, avc.Frame.from_bytes(payload))
+
+            self.response_handlers[pid](transaction_label, response_frame)
+
+    def send_message(
+        self,
+        transaction_label: int,
+        is_command: bool,
+        ipid: bool,
+        pid: int,
+        payload: bytes,
+    ):
+        # TODO: fragment large messages
+        packet_type = Protocol.PacketType.SINGLE
+        pdu = (
+            struct.pack(
+                ">BH",
+                transaction_label << 4
+                | packet_type << 2
+                | (0 if is_command else 1) << 1
+                | (1 if ipid else 0),
+                pid,
+            )
+            + payload
+        )
+        self.l2cap_channel.send_pdu(pdu)
+
+    def send_command(self, transaction_label: int, pid: int, payload: bytes) -> None:
+        logger.debug(
+            ">>> AVCTP command: "
+            f"transaction_label={transaction_label}, "
+            f"pid={pid}, "
+            f"payload={payload.hex()}"
+        )
+        self.send_message(transaction_label, True, False, pid, payload)
+
+    def send_response(self, transaction_label: int, pid: int, payload: bytes):
+        logger.debug(
+            ">>> AVCTP response: "
+            f"transaction_label={transaction_label}, "
+            f"pid={pid}, "
+            f"payload={payload.hex()}"
+        )
+        self.send_message(transaction_label, False, False, pid, payload)
+
+    def send_ipid(self, transaction_label: int, pid: int) -> None:
+        logger.debug(
+            ">>> AVCTP ipid: " f"transaction_label={transaction_label}, " f"pid={pid}"
+        )
+        self.send_message(transaction_label, False, True, pid, b'')
+
+    def register_command_handler(
+        self, pid: int, handler: Protocol.CommandHandler
+    ) -> None:
+        self.command_handlers[pid] = handler
+
+    def unregister_command_handler(
+        self, pid: int, handler: Protocol.CommandHandler
+    ) -> None:
+        if pid not in self.command_handlers or self.command_handlers[pid] != handler:
+            raise 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

@@ -30,10 +30,10 @@ logger = logging.getLogger(__name__)
 class HCI_Bridge:
     class Forwarder:
         def __init__(self, hci_sink, sender_hci_sink, packet_filter, trace):
-            self.hci_sink        = hci_sink
+            self.hci_sink = hci_sink
             self.sender_hci_sink = sender_hci_sink
-            self.packet_filter   = packet_filter
-            self.trace           = trace
+            self.packet_filter = packet_filter
+            self.trace = trace
 
         def on_packet(self, packet):
             # Convert the packet bytes to an object
@@ -61,15 +61,15 @@ class HCI_Bridge:
         hci_host_sink,
         hci_controller_source,
         hci_controller_sink,
-        host_to_controller_filter = None,
-        controller_to_host_filter = None
+        host_to_controller_filter=None,
+        controller_to_host_filter=None,
     ):
         tracer = PacketTracer(emit_message=logger.info)
         host_to_controller_forwarder = HCI_Bridge.Forwarder(
             hci_controller_sink,
             hci_host_sink,
             host_to_controller_filter,
-            lambda packet: tracer.trace(packet, 0)
+            lambda packet: tracer.trace(packet, 0),
         )
         hci_host_source.set_packet_sink(host_to_controller_forwarder)
 
@@ -77,6 +77,6 @@ class HCI_Bridge:
             hci_host_sink,
             hci_controller_sink,
             controller_to_host_filter,
-            lambda packet: tracer.trace(packet, 1)
+            lambda packet: tracer.trace(packet, 1),
         )
         hci_controller_source.set_packet_sink(controller_to_host_forwarder)

bumble/codecs.py

@@ -0,0 +1,531 @@
+# 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
+            frame_length_flag = reader.read(1)
+            depends_on_core_coder = reader.read(1)
+            if depends_on_core_coder:
+                core_coder_delay = reader.read(14)
+            extension_flag = reader.read(1)
+            if not channel_configuration:
+                raise core.InvalidPacketError('program_config_element not supported')
+            if audio_object_type in (6, 20):
+                layer_nr = reader.read(3)
+            if extension_flag:
+                if audio_object_type == 22:
+                    num_of_sub_frame = reader.read(5)
+                layer_length = reader.read(11)
+                if audio_object_type in (17, 19, 20, 23):
+                    aac_section_data_resilience_flags = reader.read(1)
+                    aac_scale_factor_data_resilience_flags = reader.read(1)
+                    aac_spectral_data_resilience_flags = reader.read(1)
+                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:
+                tara_buffer_fullness = AacAudioRtpPacket.read_latm_value(reader)
+            stream_cnt = 0
+            all_streams_same_time_framing = reader.read(1)
+            num_sub_frames = reader.read(6)
+            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:
+                latm_buffer_fullness = reader.read(8)
+            elif frame_length_type == 1:
+                frame_length = reader.read(9)
+            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:
+                crc_checksum = reader.read(8)
+
+            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

@@ -0,0 +1,107 @@
+# Copyright (c) 2012 Giorgos Verigakis <verigak@gmail.com>
+#
+# Permission to use, copy, modify, and distribute this software for any
+# purpose with or without fee is hereby granted, provided that the above
+# copyright notice and this permission notice appear in all copies.
+#
+# THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+# WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+# MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+# ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+# WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+# ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+# 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"
+COLORS = ('black', 'red', 'green', 'yellow', 'blue', 'magenta', 'cyan', 'white')
+
+# ANSI style names
+STYLES = (
+    'none',
+    'bold',
+    'faint',
+    'italic',
+    'underline',
+    'blink',
+    'blink2',
+    'negative',
+    'concealed',
+    'crossed',
+)
+
+
+ColorSpec = Union[str, int]
+
+
+def _join(*values: ColorSpec) -> str:
+    return ';'.join(str(v) for v in values)
+
+
+def _color_code(spec: ColorSpec, base: int) -> str:
+    if isinstance(spec, str):
+        spec = spec.strip().lower()
+
+    if spec == 'default':
+        return _join(base + 9)
+    elif spec in COLORS:
+        return _join(base + COLORS.index(spec))
+    elif isinstance(spec, int) and 0 <= spec <= 255:
+        return _join(base + 8, 5, spec)
+    else:
+        raise ColorError('Invalid color spec "%s"' % spec)
+
+
+def color(
+    s: str,
+    fg: Optional[ColorSpec] = None,
+    bg: Optional[ColorSpec] = None,
+    style: Optional[str] = None,
+) -> str:
+    codes: List[ColorSpec] = []
+
+    if fg:
+        codes.append(_color_code(fg, 30))
+    if bg:
+        codes.append(_color_code(bg, 40))
+    if style:
+        for style_part in style.split('+'):
+            if style_part in STYLES:
+                codes.append(STYLES.index(style_part))
+            else:
+                raise ColorError('Invalid style "%s"' % style_part)
+
+    if codes:
+        return '\x1b[{0}m{1}\x1b[0m'.format(_join(*codes), s)
+    else:
+        return s
+
+
+# Foreground color shortcuts
+black = partial(color, fg='black')
+red = partial(color, fg='red')
+green = partial(color, fg='green')
+yellow = partial(color, fg='yellow')
+blue = partial(color, fg='blue')
+magenta = partial(color, fg='magenta')
+cyan = partial(color, fg='cyan')
+white = partial(color, fg='white')
+
+# Style shortcuts
+bold = partial(color, style='bold')
+none = partial(color, style='none')
+faint = partial(color, style='faint')
+italic = partial(color, style='italic')
+underline = partial(color, style='underline')
+blink = partial(color, style='blink')
+blink2 = partial(color, style='blink2')
+negative = partial(color, style='negative')
+concealed = partial(color, style='concealed')
+crossed = partial(color, style='crossed')

bumble/crypto.py

@@ -21,27 +21,24 @@
 # -----------------------------------------------------------------------------
 # Imports
 # -----------------------------------------------------------------------------
+from __future__ import annotations
+
 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
+
+import secrets
+from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
+from cryptography.hazmat.primitives.asymmetric.ec import (
+    generate_private_key,
+    ECDH,
+    EllipticCurvePrivateKey,
+    EllipticCurvePublicNumbers,
+    EllipticCurvePrivateNumbers,
+    SECP256R1,
+)
+from cryptography.hazmat.primitives import cmac
+from typing import Tuple
+
 
 # -----------------------------------------------------------------------------
 # Logging
@@ -53,31 +50,43 @@ logger = logging.getLogger(__name__)
 # Classes
 # -----------------------------------------------------------------------------
 class EccKey:
-    def __init__(self, private_key):
+    def __init__(self, private_key: EllipticCurvePrivateKey) -> None:
         self.private_key = private_key
 
     @classmethod
-    def generate(cls):
+    def generate(cls) -> EccKey:
         private_key = generate_private_key(SECP256R1())
         return cls(private_key)
 
     @classmethod
-    def from_private_key_bytes(cls, d_bytes, x_bytes, y_bytes):
+    def from_private_key_bytes(
+        cls, d_bytes: bytes, x_bytes: bytes, y_bytes: bytes
+    ) -> EccKey:
         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()
+        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')
+    def x(self) -> bytes:
+        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 y(self) -> bytes:
+        return (
+            self.private_key.public_key()
+            .public_numbers()
+            .y.to_bytes(32, byteorder='big')
+        )
 
-    def dh(self, public_key_x, public_key_y):
+    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)
         public_key = EllipticCurvePublicNumbers(x, y, SECP256R1()).public_key()
@@ -90,14 +99,33 @@ class EccKey:
 # Functions
 # -----------------------------------------------------------------------------
 
+
 # -----------------------------------------------------------------------------
-def xor(x, y):
-    assert(len(x) == len(y))
+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 r():
+def reverse(input: bytes) -> bytes:
+    '''
+    Returns bytes of input in reversed endianness.
+    '''
+    return input[::-1]
+
+
+# -----------------------------------------------------------------------------
+def r() -> bytes:
     '''
     Generate 16 bytes of random data
     '''
@@ -105,20 +133,20 @@ def r():
 
 
 # -----------------------------------------------------------------------------
-def e(key, data):
+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 = Cipher(algorithms.AES(bytes(reversed(key))), modes.ECB())
+    cipher = Cipher(algorithms.AES(reverse(key)), modes.ECB())
     encryptor = cipher.encryptor()
-    return bytes(reversed(encryptor.update(bytes(reversed(data)))))
+    return reverse(encryptor.update(reverse(data)))
 
 
 # -----------------------------------------------------------------------------
-def ah(k, r):
+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
     '''
@@ -129,9 +157,19 @@ def ah(k, r):
 
 
 # -----------------------------------------------------------------------------
-def c1(k, r, preq, pres, iat, rat, ia, ra):
+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
+    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
@@ -140,16 +178,17 @@ def c1(k, r, preq, pres, iat, rat, ia, ra):
 
 
 # -----------------------------------------------------------------------------
-def s1(k, r1, r2):
+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
+    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):
+def aes_cmac(m: bytes, k: bytes) -> bytes:
     '''
     See Bluetooth spec, Vol 3, Part H - 2.2.5 FunctionAES-CMAC
 
@@ -161,83 +200,100 @@ def aes_cmac(m, k):
 
 
 # -----------------------------------------------------------------------------
-def f4(u, v, x, z):
+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
+    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)))))
+    return reverse(aes_cmac(reverse(u) + reverse(v) + z, reverse(x)))
 
 
 # -----------------------------------------------------------------------------
-def f5(w, n1, n2, a1, a2):
+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
+    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])
+    t = aes_cmac(reverse(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
-        )))
+        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, n1, n2, r, io_cap, a1, a2):
+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
+    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))
-    )))
+    return reverse(
+        aes_cmac(
+            reverse(n1)
+            + reverse(n2)
+            + reverse(r)
+            + reverse(io_cap)
+            + reverse(a1)
+            + reverse(a2),
+            reverse(w),
+        )
+    )
 
 
 # -----------------------------------------------------------------------------
-def g2(u, v, x, y):
+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
+    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'
+        aes_cmac(
+            reverse(u) + reverse(v) + reverse(y),
+            reverse(x),
+        )[-4:],
+        byteorder='big',
     )
 
+
 # -----------------------------------------------------------------------------
-def h6(w, key_id):
+def h6(w: bytes, key_id: bytes) -> bytes:
     '''
     See Bluetooth spec, Vol 3, Part H - 2.2.10 Link key conversion function h6
     '''
-    return aes_cmac(key_id, w)
+    return reverse(aes_cmac(key_id, reverse(w)))
+
 
 # -----------------------------------------------------------------------------
-def h7(salt, w):
+def h7(salt: bytes, w: bytes) -> bytes:
     '''
     See Bluetooth spec, Vol 3, Part H - 2.2.11 Link key conversion function h7
     '''
-    return aes_cmac(w, salt)
+    return reverse(aes_cmac(reverse(w), salt))

bumble/decoder.py

@@ -0,0 +1,420 @@
+# 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 typing import Union
+
+# -----------------------------------------------------------------------------
+# Constants
+# -----------------------------------------------------------------------------
+# fmt: off
+
+WL = [-60, -30, 58, 172, 334, 538, 1198, 3042]
+RL42 = [0, 7, 6, 5, 4, 3, 2, 1, 7, 6, 5, 4, 3, 2, 1, 0]
+ILB = [
+    2048,
+    2093,
+    2139,
+    2186,
+    2233,
+    2282,
+    2332,
+    2383,
+    2435,
+    2489,
+    2543,
+    2599,
+    2656,
+    2714,
+    2774,
+    2834,
+    2896,
+    2960,
+    3025,
+    3091,
+    3158,
+    3228,
+    3298,
+    3371,
+    3444,
+    3520,
+    3597,
+    3676,
+    3756,
+    3838,
+    3922,
+    4008,
+]
+WH = [0, -214, 798]
+RH2 = [2, 1, 2, 1]
+# Values in QM2/QM4/QM6 left shift three bits than original g722 specification.
+QM2 = [-7408, -1616, 7408, 1616]
+QM4 = [
+    0,
+    -20456,
+    -12896,
+    -8968,
+    -6288,
+    -4240,
+    -2584,
+    -1200,
+    20456,
+    12896,
+    8968,
+    6288,
+    4240,
+    2584,
+    1200,
+    0,
+]
+QM6 = [
+    -136,
+    -136,
+    -136,
+    -136,
+    -24808,
+    -21904,
+    -19008,
+    -16704,
+    -14984,
+    -13512,
+    -12280,
+    -11192,
+    -10232,
+    -9360,
+    -8576,
+    -7856,
+    -7192,
+    -6576,
+    -6000,
+    -5456,
+    -4944,
+    -4464,
+    -4008,
+    -3576,
+    -3168,
+    -2776,
+    -2400,
+    -2032,
+    -1688,
+    -1360,
+    -1040,
+    -728,
+    24808,
+    21904,
+    19008,
+    16704,
+    14984,
+    13512,
+    12280,
+    11192,
+    10232,
+    9360,
+    8576,
+    7856,
+    7192,
+    6576,
+    6000,
+    5456,
+    4944,
+    4464,
+    4008,
+    3576,
+    3168,
+    2776,
+    2400,
+    2032,
+    1688,
+    1360,
+    1040,
+    728,
+    432,
+    136,
+    -432,
+    -136,
+]
+QMF_COEFFS = [3, -11, 12, 32, -210, 951, 3876, -805, 362, -156, 53, -11]
+
+# fmt: on
+
+
+# -----------------------------------------------------------------------------
+# Classes
+# -----------------------------------------------------------------------------
+class G722Decoder:
+    """G.722 decoder with bitrate 64kbit/s.
+
+    For the Blocks in the sub-band decoders, please refer to the G.722
+    specification for the required information. G722 specification:
+    https://www.itu.int/rec/T-REC-G.722-201209-I
+    """
+
+    def __init__(self) -> None:
+        self._x = [0] * 24
+        self._band = [Band(), Band()]
+        # The initial value in BLOCK 3L
+        self._band[0].det = 32
+        # The initial value in BLOCK 3H
+        self._band[1].det = 8
+
+    def decode_frame(self, encoded_data: Union[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: Union[bytes, bytearray]) -> int:
+        """Decode the data frame using g722 decoder."""
+        result_length = 0
+
+        for code in encoded_data:
+            higher_bits = (code >> 6) & 0x03
+            lower_bits = code & 0x3F
+
+            rlow = self.lower_sub_band_decoder(lower_bits)
+            rhigh = self.higher_sub_band_decoder(higher_bits)
+
+            # Apply the receive QMF
+            self._x[:22] = self._x[2:]
+            self._x[22] = rlow + rhigh
+            self._x[23] = rlow - rhigh
+
+            xout2 = sum(self._x[2 * i] * QMF_COEFFS[i] for i in range(12))
+            xout1 = sum(self._x[2 * i + 1] * QMF_COEFFS[11 - i] for i in range(12))
+
+            result_length = self.update_decoded_result(
+                xout1, result_length, result_array
+            )
+            result_length = self.update_decoded_result(
+                xout2, result_length, result_array
+            )
+
+        return result_length
+
+    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) -> int:
+        """Lower sub-band decoder for last six bits."""
+
+        # Block 5L
+        # INVQBL
+        wd1 = lower_bits
+        wd2 = QM6[wd1]
+        wd1 >>= 2
+        wd2 = (self._band[0].det * wd2) >> 15
+        # RECONS
+        rlow = self._band[0].s + wd2
+
+        # Block 6L
+        # LIMIT
+        if rlow > 16383:
+            rlow = 16383
+        elif rlow < -16384:
+            rlow = -16384
+
+        # Block 2L
+        # INVQAL
+        wd2 = QM4[wd1]
+        dlowt = (self._band[0].det * wd2) >> 15
+
+        # Block 3L
+        # LOGSCL
+        wd2 = RL42[wd1]
+        wd1 = (self._band[0].nb * 127) >> 7
+        wd1 += WL[wd2]
+
+        if wd1 < 0:
+            wd1 = 0
+        elif wd1 > 18432:
+            wd1 = 18432
+
+        self._band[0].nb = wd1
+
+        # SCALEL
+        wd1 = (self._band[0].nb >> 6) & 31
+        wd2 = 8 - (self._band[0].nb >> 11)
+
+        if wd2 < 0:
+            wd3 = ILB[wd1] << -wd2
+        else:
+            wd3 = ILB[wd1] >> wd2
+
+        self._band[0].det = wd3 << 2
+
+        # Block 4L
+        self._band[0].block4(dlowt)
+
+        return rlow
+
+    def higher_sub_band_decoder(self, higher_bits: int) -> int:
+        """Higher sub-band decoder for first two bits."""
+
+        # Block 2H
+        # INVQAH
+        wd2 = QM2[higher_bits]
+        dhigh = (self._band[1].det * wd2) >> 15
+
+        # Block 5H
+        # RECONS
+        rhigh = dhigh + self._band[1].s
+
+        # Block 6H
+        # LIMIT
+        if rhigh > 16383:
+            rhigh = 16383
+        elif rhigh < -16384:
+            rhigh = -16384
+
+        # Block 3H
+        # LOGSCH
+        wd2 = RH2[higher_bits]
+        wd1 = (self._band[1].nb * 127) >> 7
+        wd1 += WH[wd2]
+
+        if wd1 < 0:
+            wd1 = 0
+        elif wd1 > 22528:
+            wd1 = 22528
+        self._band[1].nb = wd1
+
+        # SCALEH
+        wd1 = (self._band[1].nb >> 6) & 31
+        wd2 = 10 - (self._band[1].nb >> 11)
+
+        if wd2 < 0:
+            wd3 = ILB[wd1] << -wd2
+        else:
+            wd3 = ILB[wd1] >> wd2
+        self._band[1].det = wd3 << 2
+
+        # Block 4H
+        self._band[1].block4(dhigh)
+
+        return rhigh
+
+
+# -----------------------------------------------------------------------------
+class Band:
+    """Structure for G722 decode processing."""
+
+    s: int = 0
+    nb: int = 0
+    det: int = 0
+
+    def __init__(self) -> None:
+        self._sp = 0
+        self._sz = 0
+        self._r = [0] * 3
+        self._a = [0] * 3
+        self._ap = [0] * 3
+        self._p = [0] * 3
+        self._d = [0] * 7
+        self._b = [0] * 7
+        self._bp = [0] * 7
+        self._sg = [0] * 7
+
+    def saturate(self, amp: int) -> int:
+        if amp > 32767:
+            return 32767
+        elif amp < -32768:
+            return -32768
+        else:
+            return amp
+
+    def block4(self, d: int) -> None:
+        """Block4 for both lower and higher sub-band decoder."""
+        wd1 = 0
+        wd2 = 0
+        wd3 = 0
+
+        # RECONS
+        self._d[0] = d
+        self._r[0] = self.saturate(self.s + d)
+
+        # PARREC
+        self._p[0] = self.saturate(self._sz + d)
+
+        # UPPOL2
+        for i in range(3):
+            self._sg[i] = (self._p[i]) >> 15
+        wd1 = self.saturate((self._a[1]) << 2)
+        wd2 = -wd1 if self._sg[0] == self._sg[1] else wd1
+
+        if wd2 > 32767:
+            wd2 = 32767
+
+        wd3 = 128 if self._sg[0] == self._sg[2] else -128
+        wd3 += wd2 >> 7
+        wd3 += (self._a[2] * 32512) >> 15
+
+        if wd3 > 12288:
+            wd3 = 12288
+        elif wd3 < -12288:
+            wd3 = -12288
+        self._ap[2] = wd3
+
+        # UPPOL1
+        self._sg[0] = (self._p[0]) >> 15
+        self._sg[1] = (self._p[1]) >> 15
+        wd1 = 192 if self._sg[0] == self._sg[1] else -192
+        wd2 = (self._a[1] * 32640) >> 15
+
+        self._ap[1] = self.saturate(wd1 + wd2)
+        wd3 = self.saturate(15360 - self._ap[2])
+
+        if self._ap[1] > wd3:
+            self._ap[1] = wd3
+        elif self._ap[1] < -wd3:
+            self._ap[1] = -wd3
+
+        # UPZERO
+        wd1 = 0 if d == 0 else 128
+        self._sg[0] = d >> 15
+        for i in range(1, 7):
+            self._sg[i] = (self._d[i]) >> 15
+            wd2 = wd1 if self._sg[i] == self._sg[0] else -wd1
+            wd3 = (self._b[i] * 32640) >> 15
+            self._bp[i] = self.saturate(wd2 + wd3)
+
+        # DELAYA
+        for i in range(6, 0, -1):
+            self._d[i] = self._d[i - 1]
+            self._b[i] = self._bp[i]
+
+        for i in range(2, 0, -1):
+            self._r[i] = self._r[i - 1]
+            self._p[i] = self._p[i - 1]
+            self._a[i] = self._ap[i]
+
+        # FILTEP
+        self._sp = 0
+        for i in range(1, 3):
+            wd1 = self.saturate(self._r[i] + self._r[i])
+            self._sp += (self._a[i] * wd1) >> 15
+        self._sp = self.saturate(self._sp)
+
+        # FILTEZ
+        self._sz = 0
+        for i in range(6, 0, -1):
+            wd1 = self.saturate(self._d[i] + self._d[i])
+            self._sz += (self._b[i] * wd1) >> 15
+        self._sz = self.saturate(self._sz)
+
+        # PREDIC
+        self.s = self.saturate(self._sp + self._sz)

bumble/drivers/__init__.py

@@ -0,0 +1,87 @@
+# 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 typing import Dict, Iterable, Optional, Type, TYPE_CHECKING
+
+from . import rtk, intel
+from .common import Driver
+
+if TYPE_CHECKING:
+    from bumble.host import Host
+
+# -----------------------------------------------------------------------------
+# Logging
+# -----------------------------------------------------------------------------
+logger = logging.getLogger(__name__)
+
+
+# -----------------------------------------------------------------------------
+# Functions
+# -----------------------------------------------------------------------------
+async def get_driver_for_host(host: Host) -> Optional[Driver]:
+    """Probe diver classes until one returns a valid instance for a host, or none is
+    found.
+    If a "driver" HCI metadata entry is present, only that driver class will be probed.
+    """
+    driver_classes: Dict[str, Type[Driver]] = {"rtk": rtk.Driver, "intel": intel.Driver}
+    probe_list: Iterable[str]
+    if driver_name := host.hci_metadata.get("driver"):
+        # Only probe a single driver
+        probe_list = [driver_name]
+    else:
+        # Probe all drivers
+        probe_list = driver_classes.keys()
+
+    for driver_name in probe_list:
+        if driver_class := driver_classes.get(driver_name):
+            logger.debug(f"Probing driver class: {driver_name}")
+            if driver := await driver_class.for_host(host):
+                logger.debug(f"Instantiated {driver_name} driver")
+                return driver
+        else:
+            logger.debug(f"Skipping unknown driver class: {driver_name}")
+
+    return None
+
+
+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,102 @@
+# Copyright 2024 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# -----------------------------------------------------------------------------
+# Imports
+# -----------------------------------------------------------------------------
+import logging
+
+from bumble.drivers import common
+from bumble.hci import (
+    hci_vendor_command_op_code,  # type: ignore
+    HCI_Command,
+    HCI_Reset_Command,
+)
+
+# -----------------------------------------------------------------------------
+# Logging
+# -----------------------------------------------------------------------------
+logger = logging.getLogger(__name__)
+
+# -----------------------------------------------------------------------------
+# Constant
+# -----------------------------------------------------------------------------
+
+INTEL_USB_PRODUCTS = {
+    # Intel AX210
+    (0x8087, 0x0032),
+    # Intel BE200
+    (0x8087, 0x0036),
+}
+
+# -----------------------------------------------------------------------------
+# HCI Commands
+# -----------------------------------------------------------------------------
+HCI_INTEL_DDC_CONFIG_WRITE_COMMAND = hci_vendor_command_op_code(0xFC8B)  # type: ignore
+HCI_INTEL_DDC_CONFIG_WRITE_PAYLOAD = [0x03, 0xE4, 0x02, 0x00]
+
+HCI_Command.register_commands(globals())
+
+
+@HCI_Command.command(  # type: ignore
+    fields=[("params", "*")],
+    return_parameters_fields=[
+        ("params", "*"),
+    ],
+)
+class Hci_Intel_DDC_Config_Write_Command(HCI_Command):
+    pass
+
+
+class Driver(common.Driver):
+    def __init__(self, host):
+        self.host = host
+
+    @staticmethod
+    def check(host):
+        driver = host.hci_metadata.get("driver")
+        if driver == "intel":
+            return True
+
+        vendor_id = host.hci_metadata.get("vendor_id")
+        product_id = host.hci_metadata.get("product_id")
+
+        if vendor_id is None or product_id is None:
+            logger.debug("USB metadata not sufficient")
+            return False
+
+        if (vendor_id, product_id) not in INTEL_USB_PRODUCTS:
+            logger.debug(
+                f"USB device ({vendor_id:04X}, {product_id:04X}) " "not in known list"
+            )
+            return False
+
+        return True
+
+    @classmethod
+    async def for_host(cls, host, force=False):  # type: ignore
+        # Only instantiate this driver if explicitly selected
+        if not force and not cls.check(host):
+            return None
+
+        return cls(host)
+
+    async def init_controller(self):
+        self.host.ready = True
+        await self.host.send_command(HCI_Reset_Command(), check_result=True)
+        await self.host.send_command(
+            Hci_Intel_DDC_Config_Write_Command(
+                params=HCI_INTEL_DDC_CONFIG_WRITE_PAYLOAD
+            )
+        )

bumble/drivers/rtk.py

@@ -0,0 +1,685 @@
+# 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`)
+"""
+
+# -----------------------------------------------------------------------------
+# Imports
+# -----------------------------------------------------------------------------
+from dataclasses import dataclass
+import asyncio
+import enum
+import logging
+import math
+import os
+import pathlib
+import platform
+import struct
+from typing import Tuple
+import weakref
+
+
+from bumble import core
+from bumble.hci import (
+    hci_vendor_command_op_code,
+    STATUS_SPEC,
+    HCI_SUCCESS,
+    HCI_Command,
+    HCI_Reset_Command,
+    HCI_Read_Local_Version_Information_Command,
+)
+from bumble.drivers import common
+
+# -----------------------------------------------------------------------------
+# 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
+
+
+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,
+}
+
+# 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),
+    (0x2230, 0x0016),
+    (0x2357, 0x0604),
+    (0x2550, 0x8761),
+    (0x2B89, 0x8761),
+    (0x7392, 0xC611),
+    (0x0BDA, 0x877B),
+    # 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_vendor_command_op_code(0x6D)
+HCI_RTK_DOWNLOAD_COMMAND = hci_vendor_command_op_code(0x20)
+HCI_RTK_DROP_FIRMWARE_COMMAND = hci_vendor_command_op_code(0x66)
+HCI_Command.register_commands(globals())
+
+
+@HCI_Command.command(return_parameters_fields=[("status", STATUS_SPEC), ("version", 1)])
+class HCI_RTK_Read_ROM_Version_Command(HCI_Command):
+    pass
+
+
+@HCI_Command.command(
+    fields=[("index", 1), ("payload", RTK_FRAGMENT_LENGTH)],
+    return_parameters_fields=[("status", STATUS_SPEC), ("index", 1)],
+)
+class HCI_RTK_Download_Command(HCI_Command):
+    pass
+
+
+@HCI_Command.command()
+class HCI_RTK_Drop_Firmware_Command(HCI_Command):
+    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",
+        ),
+        # 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,
+            ):
+                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):
+        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
+
+    @classmethod
+    async def driver_info_for_host(cls, host):
+        try:
+            await host.send_command(
+                HCI_Reset_Command(),
+                check_result=True,
+                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_command(HCI_Reset_Command(), check_result=True)
+            host.ready = True
+
+        command = HCI_Read_Local_Version_Information_Command()
+        response = await host.send_command(command, check_result=True)
+        if response.command_opcode != command.op_code:
+            logger.error("failed to probe local version information")
+            return None
+
+        local_version = response.return_parameters
+
+        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, force=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:
+            response = await self.host.send_command(
+                HCI_RTK_Read_ROM_Version_Command(), check_result=True
+            )
+            if response.return_parameters.status != HCI_SUCCESS:
+                logger.warning("can't get ROM version")
+                return
+            rom_version = response.return_parameters.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}")
+        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
+
+        # 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_command(
+                HCI_RTK_Download_Command(
+                    index=download_index, payload=fragment, check_result=True
+                )
+            )
+
+        logger.debug("download complete!")
+
+        # Read the version again
+        response = await self.host.send_command(
+            HCI_RTK_Read_ROM_Version_Command(), check_result=True
+        )
+        if response.return_parameters.status != HCI_SUCCESS:
+            logger.warning("can't get ROM version")
+        else:
+            rom_version = response.return_parameters.version
+            logger.debug(f"ROM version after download: {rom_version:04X}")
+
+    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_command(HCI_Reset_Command(), check_result=True)
+        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

@@ -23,7 +23,7 @@ from .gatt import (
     Characteristic,
     GATT_GENERIC_ACCESS_SERVICE,
     GATT_DEVICE_NAME_CHARACTERISTIC,
-    GATT_APPEARANCE_CHARACTERISTIC
+    GATT_APPEARANCE_CHARACTERISTIC,
 )
 
 # -----------------------------------------------------------------------------
@@ -36,24 +36,25 @@ logger = logging.getLogger(__name__)
 # Classes
 # -----------------------------------------------------------------------------
 
+
 # -----------------------------------------------------------------------------
 class GenericAccessService(Service):
-    def __init__(self, device_name, appearance = (0, 0)):
+    def __init__(self, device_name, appearance=(0, 0)):
         device_name_characteristic = Characteristic(
             GATT_DEVICE_NAME_CHARACTERISTIC,
-            Characteristic.READ,
+            Characteristic.Properties.READ,
             Characteristic.READABLE,
-            device_name.encode('utf-8')[:248]
+            device_name.encode('utf-8')[:248],
         )
 
         appearance_characteristic = Characteristic(
             GATT_APPEARANCE_CHARACTERISTIC,
-            Characteristic.READ,
+            Characteristic.Properties.READ,
             Characteristic.READABLE,
-            struct.pack('<H', (appearance[0] << 6) | appearance[1])
+            struct.pack('<H', (appearance[0] << 6) | appearance[1]),
         )
 
-        super().__init__(GATT_GENERIC_ACCESS_SERVICE, [
-            device_name_characteristic,
-            appearance_characteristic
-        ])
+        super().__init__(
+            GATT_GENERIC_ACCESS_SERVICE,
+            [device_name_characteristic, appearance_characteristic],
+        )

bumble/gatt.py

@@ -22,14 +22,30 @@
 # -----------------------------------------------------------------------------
 # Imports
 # -----------------------------------------------------------------------------
-import asyncio
-import types
+from __future__ import annotations
+import enum
+import functools
 import logging
-from colors import color
+import struct
+from typing import (
+    Callable,
+    Dict,
+    Iterable,
+    List,
+    Optional,
+    Sequence,
+    Union,
+    TYPE_CHECKING,
+)
+
+from bumble.colors import color
+from bumble.core import BaseBumbleError, UUID
+from bumble.att import Attribute, AttributeValue
+
+if TYPE_CHECKING:
+    from bumble.gatt_client import AttributeProxy
+    from bumble.device import Connection
 
-from .core import *
-from .hci import *
-from .att import *
 
 # -----------------------------------------------------------------------------
 # Logging
@@ -39,6 +55,9 @@ logger = logging.getLogger(__name__)
 # -----------------------------------------------------------------------------
 # Constants
 # -----------------------------------------------------------------------------
+# fmt: off
+# pylint: disable=line-too-long
+
 GATT_REQUEST_TIMEOUT = 30  # seconds
 
 GATT_MAX_ATTRIBUTE_VALUE_SIZE = 512
@@ -86,20 +105,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')
@@ -122,6 +156,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')
@@ -149,6 +185,109 @@ 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')
+GATT_CONTENT_CONTROL_ID_CHARACTERISTIC                    = UUID.from_16_bits(0x2BBA, 'Content Control Id')
+
+# 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')
+
+# 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')
+GATT_ASHA_AUDIO_CONTROL_POINT_CHARACTERISTIC  = UUID('f0d4de7e-4a88-476c-9d9f-1937b0996cc0', 'AudioControlPoint')
+GATT_ASHA_AUDIO_STATUS_CHARACTERISTIC         = UUID('38663f1a-e711-4cac-b641-326b56404837', 'AudioStatus')
+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')
+
 # Misc
 GATT_DEVICE_NAME_CHARACTERISTIC                                = UUID.from_16_bits(0x2A00, 'Device Name')
 GATT_APPEARANCE_CHARACTERISTIC                                 = UUID.from_16_bits(0x2A01, 'Appearance')
@@ -162,13 +301,20 @@ 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')
+
+# fmt: on
+# pylint: enable=line-too-long
 
 
 # -----------------------------------------------------------------------------
 # Utils
 # -----------------------------------------------------------------------------
 
-def show_services(services):
+
+def show_services(services: Iterable[Service]) -> None:
     for service in services:
         print(color(str(service), 'cyan'))
 
@@ -179,29 +325,61 @@ def show_services(services):
                 print(color('    ' + str(descriptor), 'green'))
 
 
+# -----------------------------------------------------------------------------
+class InvalidServiceError(BaseBumbleError):
+    """The service is not compliant with the spec/profile"""
+
+
 # -----------------------------------------------------------------------------
 class Service(Attribute):
     '''
     See Vol 3, Part G - 3.1 SERVICE DEFINITION
     '''
 
-    def __init__(self, uuid, characteristics, primary=True):
+    uuid: UUID
+    characteristics: List[Characteristic]
+    included_services: List[Service]
+
+    def __init__(
+        self,
+        uuid: Union[str, UUID],
+        characteristics: List[Characteristic],
+        primary=True,
+        included_services: Iterable[Service] = (),
+    ) -> None:
         # Convert the uuid to a UUID object if it isn't already
-        if type(uuid) is str:
+        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()
+            uuid.to_pdu_bytes(),
         )
-        self.uuid              = uuid
-        self.included_services = []
-        self.characteristics   = characteristics[:]
-        self.primary           = primary
+        self.uuid = uuid
+        self.included_services = list(included_services)
+        self.characteristics = characteristics[:]
+        self.primary = primary
 
-    def __str__(self):
-        return f'Service(handle=0x{self.handle:04X}, end=0x{self.end_group_handle:04X}, uuid={self.uuid}){"" if self.primary else "*"}'
+    def get_advertising_data(self) -> Optional[bytes]:
+        """
+        Get Service specific advertising data
+        Defined by each Service, default value is empty
+        :return Service data for advertising
+        """
+        return None
+
+    def __str__(self) -> str:
+        return (
+            f'Service(handle=0x{self.handle:04X}, '
+            f'end=0x{self.end_group_handle:04X}, '
+            f'uuid={self.uuid})'
+            f'{"" if self.primary else "*"}'
+        )
 
 
 # -----------------------------------------------------------------------------
@@ -210,10 +388,42 @@ class TemplateService(Service):
     Convenience abstract class that can be used by profile-specific subclasses that want
     to expose their UUID as a class property
     '''
-    UUID = None
 
-    def __init__(self, characteristics, primary=True):
-        super().__init__(self.UUID, characteristics, primary)
+    UUID: UUID
+
+    def __init__(
+        self,
+        characteristics: List[Characteristic],
+        primary: bool = True,
+        included_services: Iterable[Service] = (),
+    ) -> None:
+        super().__init__(self.UUID, characteristics, primary, included_services)
+
+
+# -----------------------------------------------------------------------------
+class IncludedServiceDeclaration(Attribute):
+    '''
+    See Vol 3, Part G - 3.2 INCLUDE DEFINITION
+    '''
+
+    service: Service
+
+    def __init__(self, service: Service) -> None:
+        declaration_bytes = struct.pack(
+            '<HH2s', service.handle, service.end_group_handle, service.uuid.to_bytes()
+        )
+        super().__init__(
+            GATT_INCLUDE_ATTRIBUTE_TYPE, Attribute.READABLE, declaration_bytes
+        )
+        self.service = service
+
+    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})'
+        )
 
 
 # -----------------------------------------------------------------------------
@@ -222,121 +432,192 @@ class Characteristic(Attribute):
     See Vol 3, Part G - 3.3 CHARACTERISTIC DEFINITION
     '''
 
-    # Property flags
-    BROADCAST                   = 0x01
-    READ                        = 0x02
-    WRITE_WITHOUT_RESPONSE      = 0x04
-    WRITE                       = 0x08
-    NOTIFY                      = 0x10
-    INDICATE                    = 0X20
-    AUTHENTICATED_SIGNED_WRITES = 0X40
-    EXTENDED_PROPERTIES         = 0X80
+    uuid: UUID
+    properties: Characteristic.Properties
 
-    PROPERTY_NAMES = {
-        BROADCAST:                   'BROADCAST',
-        READ:                        'READ',
-        WRITE_WITHOUT_RESPONSE:      'WRITE_WITHOUT_RESPONSE',
-        WRITE:                       'WRITE',
-        NOTIFY:                      'NOTIFY',
-        INDICATE:                    'INDICATE',
-        AUTHENTICATED_SIGNED_WRITES: 'AUTHENTICATED_SIGNED_WRITES',
-        EXTENDED_PROPERTIES:         'EXTENDED_PROPERTIES'
-    }
+    class Properties(enum.IntFlag):
+        """Property flags"""
 
-    @staticmethod
-    def property_name(property):
-        return Characteristic.PROPERTY_NAMES.get(property, '')
+        BROADCAST = 0x01
+        READ = 0x02
+        WRITE_WITHOUT_RESPONSE = 0x04
+        WRITE = 0x08
+        NOTIFY = 0x10
+        INDICATE = 0x20
+        AUTHENTICATED_SIGNED_WRITES = 0x40
+        EXTENDED_PROPERTIES = 0x80
 
-    @staticmethod
-    def properties_as_string(properties):
-        return ','.join([
-            Characteristic.property_name(p) for p in Characteristic.PROPERTY_NAMES.keys()
-            if properties & p
-        ])
+        @classmethod
+        def from_string(cls, properties_str: str) -> Characteristic.Properties:
+            try:
+                return functools.reduce(
+                    lambda x, y: x | cls[y],
+                    properties_str.replace("|", ",").split(","),
+                    Characteristic.Properties(0),
+                )
+            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 , or |: {enum_list_str}\nGot: {properties_str}"
+                )
 
-    def __init__(self, uuid, properties, permissions, value = b'', descriptors = []):
+        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
+    READ = Properties.READ
+    WRITE_WITHOUT_RESPONSE = Properties.WRITE_WITHOUT_RESPONSE
+    WRITE = Properties.WRITE
+    NOTIFY = Properties.NOTIFY
+    INDICATE = Properties.INDICATE
+    AUTHENTICATED_SIGNED_WRITES = Properties.AUTHENTICATED_SIGNED_WRITES
+    EXTENDED_PROPERTIES = Properties.EXTENDED_PROPERTIES
+
+    def __init__(
+        self,
+        uuid: Union[str, bytes, UUID],
+        properties: Characteristic.Properties,
+        permissions: Union[str, Attribute.Permissions],
+        value: Union[str, bytes, CharacteristicValue] = b'',
+        descriptors: Sequence[Descriptor] = (),
+    ):
         super().__init__(uuid, permissions, value)
-        self.uuid        = self.type
-        self.properties  = properties
+        self.uuid = self.type
+        self.properties = properties
         self.descriptors = descriptors
 
     def get_descriptor(self, descriptor_type):
         for descriptor in self.descriptors:
-            if descriptor.uuid == descriptor_type:
+            if descriptor.type == descriptor_type:
                 return descriptor
 
-    def __str__(self):
-        return f'Characteristic(handle=0x{self.handle:04X}, end=0x{self.end_group_handle:04X}, uuid={self.uuid}, properties={Characteristic.properties_as_string(self.properties)})'
+        return None
+
+    def has_properties(self, properties: Characteristic.Properties) -> bool:
+        return self.properties & properties == properties
+
+    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})'
+        )
 
 
 # -----------------------------------------------------------------------------
-class CharacteristicValue:
+class CharacteristicDeclaration(Attribute):
     '''
-    Characteristic value where reading and/or writing is delegated to functions
-    passed as arguments to the constructor.
+    See Vol 3, Part G - 3.3.1 CHARACTERISTIC DECLARATION
     '''
-    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''
+    characteristic: Characteristic
 
-    def write(self, connection, value):
-        if self._write:
-            self._write(connection, value)
+    def __init__(self, characteristic: Characteristic, value_handle: int) -> None:
+        declaration_bytes = (
+            struct.pack('<BH', characteristic.properties, value_handle)
+            + characteristic.uuid.to_pdu_bytes()
+        )
+        super().__init__(
+            GATT_CHARACTERISTIC_ATTRIBUTE_TYPE, Attribute.READABLE, declaration_bytes
+        )
+        self.value_handle = value_handle
+        self.characteristic = characteristic
+
+    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})'
+        )
+
+
+# -----------------------------------------------------------------------------
+class CharacteristicValue(AttributeValue):
+    """Same as AttributeValue, for backward compatibility"""
 
 
 # -----------------------------------------------------------------------------
 class CharacteristicAdapter:
     '''
-    An adapter that can adapt any object with `read_value` and `write_value`
-    methods (like Characteristic and CharacteristicProxy objects) by wrapping
-    those methods with ones that return/accept encoded/decoded values.
-    Objects with async methods are considered proxies, so the adaptation is one
-    where the return value of `read_value` is decoded and the value passed to
-    `write_value` is encoded. Other objects are considered local characteristics
-    so the adaptation is one where the return value of `read_value` is encoded
-    and the value passed to `write_value` is decoded.
-    If the characteristic has a `subscribe` method, it is wrapped with one where
-    the values are decoded before being passed to the subscriber.
+    An adapter that can adapt Characteristic and AttributeProxy objects
+    by wrapping their `read_value()` and `write_value()` methods with ones that
+    return/accept encoded/decoded values.
+
+    For proxies (i.e used by a GATT client), the adaptation is one where the return
+    value of `read_value()` is decoded and the value passed to `write_value()` is
+    encoded. The `subscribe()` method, is wrapped with one where the values are decoded
+    before being passed to the subscriber.
+
+    For local values (i.e hosted by a GATT server) the adaptation is one where the
+    return value of `read_value()` is encoded and the value passed to `write_value()`
+    is decoded.
     '''
-    def __init__(self, characteristic):
+
+    read_value: Callable
+    write_value: Callable
+
+    def __init__(self, characteristic: Union[Characteristic, AttributeProxy]):
         self.wrapped_characteristic = characteristic
+        self.subscribers: Dict[Callable, Callable] = (
+            {}
+        )  # Map from subscriber to proxy subscriber
 
-        if (
-            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
+        if isinstance(characteristic, Characteristic):
+            self.read_value = self.read_encoded_value
             self.write_value = self.write_encoded_value
-
-        if hasattr(self.wrapped_characteristic, 'subscribe'):
+        else:
+            self.read_value = self.read_decoded_value
+            self.write_value = self.write_decoded_value
             self.subscribe = self.wrapped_subscribe
+            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', 'read_value', 'write_value', 'subscribe'}:
+        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))
+    async def read_encoded_value(self, connection):
+        return self.encode_value(
+            await self.wrapped_characteristic.read_value(connection)
+        )
 
-    def write_encoded_value(self, connection, value):
-        return self.wrapped_characteristic.write_value(connection, self.decode_value(value))
+    async def write_encoded_value(self, connection, value):
+        return await self.wrapped_characteristic.write_value(
+            connection, self.decode_value(value)
+        )
 
     async def read_decoded_value(self):
         return self.decode_value(await self.wrapped_characteristic.read_value())
 
-    async def write_decoded_value(self, value):
-        return await self.wrapped_characteristic.write_value(self.encode_value(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
@@ -345,11 +626,29 @@ class CharacteristicAdapter:
         return value
 
     def wrapped_subscribe(self, subscriber=None):
-        return self.wrapped_characteristic.subscribe(
-            None if subscriber is None else lambda value: subscriber(self.decode_value(value))
-        )
+        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 __str__(self):
+                def on_change(value):
+                    original_subscriber(self.decode_value(value))
+
+                self.subscribers[subscriber] = on_change
+                subscriber = on_change
+
+        return self.wrapped_characteristic.subscribe(subscriber)
+
+    def wrapped_unsubscribe(self, subscriber=None):
+        if subscriber in self.subscribers:
+            subscriber = self.subscribers.pop(subscriber)
+
+        return self.wrapped_characteristic.unsubscribe(subscriber)
+
+    def __str__(self) -> str:
         wrapped = str(self.wrapped_characteristic)
         return f'{self.__class__.__name__}({wrapped})'
 
@@ -359,6 +658,7 @@ 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
@@ -381,9 +681,10 @@ class PackedCharacteristicAdapter(CharacteristicAdapter):
     they return/accept a tuple with the same number of elements as is required for
     the format.
     '''
-    def __init__(self, characteristic, format):
+
+    def __init__(self, characteristic, pack_format):
         super().__init__(characteristic)
-        self.struct = struct.Struct(format)
+        self.struct = struct.Struct(pack_format)
 
     def pack(self, *values):
         return self.struct.pack(*values)
@@ -392,7 +693,7 @@ class PackedCharacteristicAdapter(CharacteristicAdapter):
         return self.struct.unpack(buffer)
 
     def encode_value(self, value):
-        return self.pack(*value if type(value) is tuple else (value,))
+        return self.pack(*value if isinstance(value, tuple) else (value,))
 
     def decode_value(self, value):
         unpacked = self.unpack(value)
@@ -405,13 +706,15 @@ 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.
+    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, format, keys):
-        super().__init__(characteristic, format)
+
+    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))
 
@@ -424,10 +727,11 @@ class UTF8CharacteristicAdapter(CharacteristicAdapter):
     '''
     Adapter that converts strings to/from bytes using UTF-8 encoding
     '''
-    def encode_value(self, value):
+
+    def encode_value(self, value: str) -> bytes:
         return value.encode('utf-8')
 
-    def decode_value(self, value):
+    def decode_value(self, value: bytes) -> str:
         return value.decode('utf-8')
 
 
@@ -437,8 +741,31 @@ class Descriptor(Attribute):
     See Vol 3, Part G - 3.3.3 Characteristic Descriptor Declarations
     '''
 
-    def __init__(self, descriptor_type, permissions, value = b''):
-        super().__init__(descriptor_type, permissions, value)
+    def __str__(self) -> str:
+        if isinstance(self.value, bytes):
+            value_str = self.value.hex()
+        elif isinstance(self.value, CharacteristicValue):
+            value = self.value.read(None)
+            if isinstance(value, bytes):
+                value_str = value.hex()
+            else:
+                value_str = '<async>'
+        else:
+            value_str = '<...>'
+        return (
+            f'Descriptor(handle=0x{self.handle:04X}, '
+            f'type={self.type}, '
+            f'value={value_str})'
+        )
 
-    def __str__(self):
-        return f'Descriptor(handle=0x{self.handle:04X}, type={self.type}, value={self.read_value(None).hex()})'
+
+# -----------------------------------------------------------------------------
+class ClientCharacteristicConfigurationBits(enum.IntFlag):
+    '''
+    See Vol 3, Part G - 3.3.3.3 - Table 3.11 Client Characteristic Configuration bit
+    field definition
+    '''
+
+    DEFAULT = 0x0000
+    NOTIFICATION = 0x0001
+    INDICATION = 0x0002

bumble/helpers.py

@@ -15,35 +15,47 @@
 # -----------------------------------------------------------------------------
 # Imports
 # -----------------------------------------------------------------------------
+from __future__ import annotations
+
+from collections.abc import Callable, MutableMapping
+import datetime
+from typing import cast, Any, Optional
 import logging
-from colors import color
 
+from bumble import avc
+from bumble import avctp
+from bumble import avdtp
+from bumble import avrcp
+from bumble import crypto
+from bumble import rfcomm
+from bumble import sdp
+from bumble.colors import color
+from bumble.att import ATT_CID, ATT_PDU
 from bumble.smp import SMP_CID, SMP_Command
-
-from .core import name_or_number
-from .gatt import ATT_PDU, ATT_CID
-from .l2cap import (
+from bumble.core import name_or_number
+from bumble.l2cap import (
     L2CAP_PDU,
     L2CAP_CONNECTION_REQUEST,
     L2CAP_CONNECTION_RESPONSE,
     L2CAP_SIGNALING_CID,
     L2CAP_LE_SIGNALING_CID,
     L2CAP_Control_Frame,
-    L2CAP_Connection_Response
+    L2CAP_Connection_Request,
+    L2CAP_Connection_Response,
 )
-from .hci import (
+from bumble.hci import (
+    Address,
     HCI_EVENT_PACKET,
     HCI_ACL_DATA_PACKET,
     HCI_DISCONNECTION_COMPLETE_EVENT,
-    HCI_AclDataPacketAssembler
-)
-from .rfcomm import RFCOMM_Frame, RFCOMM_PSM
-from .sdp import SDP_PDU, SDP_PSM
-from .avdtp import (
-    MessageAssembler as AVDTP_MessageAssembler,
-    AVDTP_PSM
+    HCI_AclDataPacketAssembler,
+    HCI_Packet,
+    HCI_Event,
+    HCI_AclDataPacket,
+    HCI_Disconnection_Complete_Event,
 )
 
+
 # -----------------------------------------------------------------------------
 # Logging
 # -----------------------------------------------------------------------------
@@ -52,25 +64,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):
-            self.analyzer         = analyzer
-            self.packet_assembler = HCI_AclDataPacketAssembler(self.on_acl_pdu)
-            self.avdtp_assemblers = {}    # AVDTP assemblers, by source_cid
-            self.psms             = {}    # PSM, by source_cid
-            self.peer             = None  # ACL stream in the other direction
+        psms: MutableMapping[int, int]
+        peer: Optional[PacketTracer.AclStream]
+        avdtp_assemblers: MutableMapping[int, avdtp.MessageAssembler]
+        avctp_assemblers: MutableMapping[int, avctp.MessageAssembler]
 
-        def on_acl_pdu(self, pdu):
+        def __init__(self, analyzer: PacketTracer.Analyzer) -> None:
+            self.analyzer = analyzer
+            self.packet_assembler = HCI_AclDataPacketAssembler(self.on_acl_pdu)
+            self.avdtp_assemblers = {}  # AVDTP assemblers, by source_cid
+            self.avctp_assemblers = {}  # AVCTP assemblers, by source_cid
+            self.psms = {}  # PSM, by source_cid
+            self.peer = None
+
+        # pylint: disable=too-many-nested-blocks
+        def on_acl_pdu(self, pdu: bytes) -> None:
             l2cap_pdu = L2CAP_PDU.from_bytes(pdu)
+            self.analyzer.emit(l2cap_pdu)
 
             if l2cap_pdu.cid == ATT_CID:
                 att_pdu = ATT_PDU.from_bytes(l2cap_pdu.payload)
@@ -78,60 +101,121 @@ class PacketTracer:
             elif l2cap_pdu.cid == SMP_CID:
                 smp_command = SMP_Command.from_bytes(l2cap_pdu.payload)
                 self.analyzer.emit(smp_command)
-            elif l2cap_pdu.cid == L2CAP_SIGNALING_CID or l2cap_pdu.cid == L2CAP_LE_SIGNALING_CID:
+            elif l2cap_pdu.cid in (L2CAP_SIGNALING_CID, L2CAP_LE_SIGNALING_CID):
                 control_frame = L2CAP_Control_Frame.from_bytes(l2cap_pdu.payload)
                 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
+                    connection_request = cast(L2CAP_Connection_Request, control_frame)
+                    self.psms[connection_request.source_cid] = connection_request.psm
                 elif control_frame.code == L2CAP_CONNECTION_RESPONSE:
-                    if control_frame.result == L2CAP_Connection_Response.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)
+                    connection_response = cast(L2CAP_Connection_Response, control_frame)
+                    if (
+                        connection_response.result
+                        == L2CAP_Connection_Response.CONNECTION_SUCCESSFUL
+                    ):
+                        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:
-                        self.analyzer.emit(f'{color("L2CAP", "green")} [CID={l2cap_pdu.cid}, PSM=AVDTP]: {l2cap_pdu.payload.hex()}')
-                        assembler = self.avdtp_assemblers.get(l2cap_pdu.cid)
-                        if assembler:
-                            assembler.on_pdu(l2cap_pdu.payload)
+                    elif psm == avdtp.AVDTP_PSM:
+                        self.analyzer.emit(
+                            f'{color("L2CAP", "green")} [CID={l2cap_pdu.cid}, '
+                            f'PSM=AVDTP]: {l2cap_pdu.payload.hex()}'
+                        )
+                        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(f'{color("L2CAP", "green")} [CID={l2cap_pdu.cid}, PSM={psm_string}]: {l2cap_pdu.payload.hex()}')
+                        self.analyzer.emit(
+                            f'{color("L2CAP", "green")} [CID={l2cap_pdu.cid}, '
+                            f'PSM={psm_string}]: {l2cap_pdu.payload.hex()}'
+                        )
                 else:
                     self.analyzer.emit(l2cap_pdu)
 
-        def on_avdtp_message(self, transaction_label, message):
-            self.analyzer.emit(f'{color("AVDTP", "green")} [{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):
-            self.label        = label
-            self.emit_message = emit_message
-            self.acl_streams  = {}    # ACL streams, by connection handle
-            self.peer         = None  # Analyzer in the other direction
+        acl_streams: MutableMapping[int, PacketTracer.AclStream]
+        peer: PacketTracer.Analyzer
 
-        def start_acl_stream(self, connection_handle):
-            logger.info(f'[{self.label}] +++ Creating ACL stream for connection 0x{connection_handle:04X}')
+        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.packet_timestamp: Optional[datetime.datetime] = None
+
+        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}'
+            )
             stream = PacketTracer.AclStream(self)
             self.acl_streams[connection_handle] = stream
 
@@ -142,43 +226,80 @@ 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 0x{connection_handle:04X}')
+                logger.info(
+                    f'[{self.label}] --- Removing ACL stream for connection '
+                    f'0x{connection_handle:04X}'
+                )
                 del self.acl_streams[connection_handle]
 
                 # 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: Optional[datetime.datetime], 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: Optional[datetime.datetime] = None,
+    ) -> None:
         if direction == 0:
-            self.host_to_controller_analyzer.on_packet(packet)
+            self.host_to_controller_analyzer.on_packet(timestamp, packet)
         else:
-            self.controller_to_host_analyzer.on_packet(packet)
+            self.controller_to_host_analyzer.on_packet(timestamp, packet)
 
     def __init__(
         self,
-        host_to_controller_label=color('HOST->CONTROLLER', 'blue'),
-        controller_to_host_label=color('CONTROLLER->HOST', 'cyan'),
-        emit_message=logger.info
-    ):
-        self.host_to_controller_analyzer = PacketTracer.Analyzer(host_to_controller_label, emit_message)
-        self.controller_to_host_analyzer = PacketTracer.Analyzer(controller_to_host_label, emit_message)
+        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
+        )
+        self.controller_to_host_analyzer = PacketTracer.Analyzer(
+            controller_to_host_label, emit_message
+        )
         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,551 @@
+# 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
+from dataclasses import dataclass
+import logging
+import enum
+import struct
+
+from abc import ABC, abstractmethod
+from pyee import EventEmitter
+from typing import Optional, Callable
+from typing_extensions import override
+
+from bumble import l2cap, device
+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, EventEmitter):
+    l2cap_ctrl_channel: Optional[l2cap.ClassicChannel] = None
+    l2cap_intr_channel: Optional[l2cap.ClassicChannel] = None
+    connection: Optional[device.Connection] = None
+
+    class Role(enum.IntEnum):
+        HOST = 0x00
+        DEVICE = 0x01
+
+    def __init__(self, device: device.Device, role: Role) -> None:
+        super().__init__()
+        self.remote_device_bd_address: Optional[Address] = None
+        self.device = device
+        self.role = role
+
+        # Register ourselves with the L2CAP channel manager
+        device.register_l2cap_server(HID_CONTROL_PSM, self.on_l2cap_connection)
+        device.register_l2cap_server(HID_INTERRUPT_PSM, self.on_l2cap_connection)
+
+        device.on('connection', self.on_device_connection)
+
+    async def connect_control_channel(self) -> None:
+        # Create a new L2CAP connection - control channel
+        try:
+            channel = await self.device.l2cap_channel_manager.connect(
+                self.connection, HID_CONTROL_PSM
+            )
+            channel.sink = self.on_ctrl_pdu
+            self.l2cap_ctrl_channel = channel
+        except ProtocolError:
+            logging.exception(f'L2CAP connection failed.')
+            raise
+
+    async def connect_interrupt_channel(self) -> None:
+        # Create a new L2CAP connection - interrupt channel
+        try:
+            channel = await self.device.l2cap_channel_manager.connect(
+                self.connection, HID_INTERRUPT_PSM
+            )
+            channel.sink = self.on_intr_pdu
+            self.l2cap_intr_channel = channel
+        except ProtocolError:
+            logging.exception(f'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('disconnection', self.on_device_disconnection)
+
+    def on_device_disconnection(self, reason: int) -> None:
+        self.connection = None
+
+    def on_l2cap_connection(self, l2cap_channel: l2cap.ClassicChannel) -> None:
+        logger.debug(f'+++ New L2CAP connection: {l2cap_channel}')
+        l2cap_channel.on('open', lambda: self.on_l2cap_channel_open(l2cap_channel))
+        l2cap_channel.on('close', lambda: self.on_l2cap_channel_close(l2cap_channel))
+
+    def on_l2cap_channel_open(self, l2cap_channel: l2cap.ClassicChannel) -> None:
+        if l2cap_channel.psm == HID_CONTROL_PSM:
+            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("interrupt_data", pdu)
+
+    def send_pdu_on_ctrl(self, msg: bytes) -> None:
+        assert self.l2cap_ctrl_channel
+        self.l2cap_ctrl_channel.send_pdu(msg)
+
+    def send_pdu_on_intr(self, msg: bytes) -> None:
+        assert self.l2cap_intr_channel
+        self.l2cap_intr_channel.send_pdu(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: Optional[Callable[[int, int, int], GetSetStatus]] = None
+    set_report_cb: Optional[Callable[[int, int, int, bytes], GetSetStatus]] = None
+    get_protocol_cb: Optional[Callable[[], GetSetStatus]] = None
+    set_protocol_cb: Optional[Callable[[int], GetSetStatus]] = 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('control_data', pdu)
+        elif message_type == Message.MessageType.CONTROL:
+            if param == Message.ControlCommand.SUSPEND:
+                logger.debug('<<< HID SUSPEND')
+                self.emit('suspend')
+            elif param == Message.ControlCommand.EXIT_SUSPEND:
+                logger.debug('<<< HID EXIT SUSPEND')
+                self.emit('exit_suspend')
+            elif param == Message.ControlCommand.VIRTUAL_CABLE_UNPLUG:
+                logger.debug('<<< HID VIRTUAL CABLE UNPLUG')
+                self.emit('virtual_cable_unplug')
+            else:
+                logger.debug('<<< HID CONTROL OPERATION UNSUPPORTED')
+        else:
+            logger.debug('<<< HID MESSAGE TYPE UNSUPPORTED')
+            self.send_handshake_message(Message.Handshake.ERR_UNSUPPORTED_REQUEST)
+
+    def send_handshake_message(self, result_code: int) -> None:
+        msg = SendHandshakeMessage(result_code)
+        hid_message = bytes(msg)
+        logger.debug(f'>>> HID HANDSHAKE MESSAGE, PDU: {hid_message.hex()}')
+        self.send_pdu_on_ctrl(hid_message)
+
+    def send_control_data(self, report_type: int, data: bytes):
+        msg = SendControlData(report_type=report_type, data=data)
+        hid_message = bytes(msg)
+        logger.debug(f'>>> HID CONTROL DATA: {hid_message.hex()}')
+        self.send_pdu_on_ctrl(hid_message)
+
+    def handle_get_report(self, pdu: bytes):
+        if self.get_report_cb is None:
+            logger.debug("GetReport callback not registered !!")
+            self.send_handshake_message(Message.Handshake.ERR_UNSUPPORTED_REQUEST)
+            return
+        report_type = pdu[0] & 0x03
+        buffer_flag = (pdu[0] & 0x08) >> 3
+        report_id = pdu[1]
+        logger.debug(f"buffer_flag: {buffer_flag}")
+        if buffer_flag == 1:
+            buffer_size = (pdu[3] << 8) | pdu[2]
+        else:
+            buffer_size = 0
+
+        ret = self.get_report_cb(report_id, report_type, buffer_size)
+        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('handshake', Message.Handshake(param))
+        elif message_type == Message.MessageType.DATA:
+            logger.debug('<<< HID CONTROL DATA')
+            self.emit('control_data', pdu)
+        elif message_type == Message.MessageType.CONTROL:
+            if param == Message.ControlCommand.VIRTUAL_CABLE_UNPLUG:
+                logger.debug('<<< HID VIRTUAL CABLE UNPLUG')
+                self.emit('virtual_cable_unplug')
+            else:
+                logger.debug('<<< HID CONTROL OPERATION UNSUPPORTED')
+        else:
+            logger.debug('<<< HID MESSAGE TYPE UNSUPPORTED')

bumble/keys.py

@@ -20,13 +20,20 @@
 # -----------------------------------------------------------------------------
 # Imports
 # -----------------------------------------------------------------------------
+from __future__ import annotations
+import asyncio
 import logging
 import os
 import json
-from colors import color
+from typing import TYPE_CHECKING, Dict, List, Optional, Tuple, Type
+from typing_extensions import Self
 
+from .colors import color
 from .hci import Address
 
+if TYPE_CHECKING:
+    from .device import Device
+
 
 # -----------------------------------------------------------------------------
 # Logging
@@ -38,10 +45,10 @@ logger = logging.getLogger(__name__)
 class PairingKeys:
     class Key:
         def __init__(self, value, authenticated=False, ediv=None, rand=None):
-            self.value         = value
+            self.value = value
             self.authenticated = authenticated
-            self.ediv          = ediv
-            self.rand          = rand
+            self.ediv = ediv
+            self.rand = rand
 
         @classmethod
         def from_dict(cls, key_dict):
@@ -64,31 +71,33 @@ class PairingKeys:
             return key_dict
 
     def __init__(self):
-        self.address_type   = None
-        self.ltk            = None
-        self.ltk_central    = None
+        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
+        self.irk = None
+        self.csrk = None
+        self.link_key = None  # Classic
 
     @staticmethod
     def key_from_dict(keys_dict, key_name):
         key_dict = keys_dict.get(key_name)
-        if key_dict is not None:
-            return PairingKeys.Key.from_dict(key_dict)
+        if key_dict is None:
+            return None
+
+        return PairingKeys.Key.from_dict(key_dict)
 
     @staticmethod
     def from_dict(keys_dict):
         keys = PairingKeys()
 
-        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.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')
+        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
 
@@ -120,33 +129,37 @@ class PairingKeys:
 
     def print(self, prefix=''):
         keys_dict = self.to_dict()
-        for (property, value) in keys_dict.items():
-            if type(value) is dict:
-                print(f'{prefix}{color(property, "cyan")}:')
-                for (key_property, key_value) in value.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():
                     print(f'{prefix}  {color(key_property, "green")}: {key_value}')
             else:
-                print(f'{prefix}{color(property, "cyan")}: {value}')
+                print(f'{prefix}{color(container_property, "cyan")}: {value}')
 
 
 # -----------------------------------------------------------------------------
 class KeyStore:
-    async def delete(self, name):
+    async def delete(self, name: str):
         pass
 
-    async def update(self, name, keys):
+    async def update(self, name: str, keys: PairingKeys) -> None:
         pass
 
-    async def get(self, name):
-        return PairingKeys()
+    async def get(self, _name: str) -> Optional[PairingKeys]:
+        return None
 
-    async def get_all(self):
+    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):
         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
@@ -159,41 +172,81 @@ class KeyStore:
     async def print(self, prefix=''):
         entries = await self.get_all()
         separator = ''
-        for (name, keys) in entries:
+        for name, keys in entries:
             print(separator + prefix + color(name, 'yellow'))
-            keys.print(prefix = prefix + '  ')
+            keys.print(prefix=prefix + '  ')
             separator = '\n'
 
     @staticmethod
-    def create_for_device(device_config):
-        if device_config.keystore is None:
-            return None
+    def create_for_device(device: Device) -> KeyStore:
+        if device.config.keystore is None:
+            return MemoryKeyStore()
 
-        keystore_type = device_config.keystore.split(':', 1)[0]
+        keystore_type = device.config.keystore.split(':', 1)[0]
         if keystore_type == 'JsonKeyStore':
-            return JsonKeyStore.from_device_config(device_config)
+            return JsonKeyStore.from_device(device)
 
-        return None
+        return MemoryKeyStore()
 
 
 # -----------------------------------------------------------------------------
 class JsonKeyStore(KeyStore):
-    APP_NAME          = 'Bumble'
-    APP_AUTHOR        = 'Google'
-    KEYS_DIR          = 'Pairing'
+    """
+    KeyStore implementation that is backed by a JSON file.
+
+    This implementation supports storing a hierarchy of key sets in a single file.
+    A key set is a representation of a PairingKeys object. Each key set is stored
+    in a map, with the address of paired peer as the key. Maps are themselves grouped
+    into namespaces, grouping pairing keys by controller addresses.
+    The JSON object model looks like:
+    {
+        "<namespace>": {
+            "peer-address": {
+                "address_type": <n>,
+                "irk" : {
+                    "authenticated": <true/false>,
+                    "value": "hex-encoded-key"
+                },
+                ... other keys ...
+            },
+            ... other peers ...
+        }
+        ... other namespaces ...
+    }
+
+    A namespace is typically the BD_ADDR of a controller, since that is a convenient
+    unique identifier, but it may be something else.
+    A special namespace, called the "default" namespace, is used when instantiating this
+    class without a namespace. With the default namespace, reading from a file will
+    load an existing namespace if there is only one, which may be convenient for reading
+    from a file with a single key set and for which the namespace isn't known. If the
+    file does not include any existing key set, or if there are more than one and none
+    has the default name, a new one will be created with the name "__DEFAULT__".
+    """
+
+    APP_NAME = 'Bumble'
+    APP_AUTHOR = 'Google'
+    KEYS_DIR = 'Pairing'
     DEFAULT_NAMESPACE = '__DEFAULT__'
+    DEFAULT_BASE_NAME = "keys"
 
     def __init__(self, namespace, filename=None):
         self.namespace = namespace if namespace is not None else self.DEFAULT_NAMESPACE
 
         if filename is None:
             # Use a default for the current user
+
+            # Import here because this may not exist on all platforms
+            # pylint: disable=import-outside-toplevel
             import appdirs
+
             self.directory_name = os.path.join(
-                appdirs.user_data_dir(self.APP_NAME, self.APP_AUTHOR),
-                self.KEYS_DIR
+                appdirs.user_data_dir(self.APP_NAME, self.APP_AUTHOR), self.KEYS_DIR
+            )
+            base_name = self.DEFAULT_BASE_NAME if namespace is None else self.namespace
+            json_filename = (
+                f'{base_name}.json'.lower().replace(':', '-').replace('/p', '-p')
             )
-            json_filename = f'{self.namespace}.json'.lower().replace(':', '-')
             self.filename = os.path.join(self.directory_name, json_filename)
         else:
             self.filename = filename
@@ -201,23 +254,49 @@ class JsonKeyStore(KeyStore):
 
         logger.debug(f'JSON keystore: {self.filename}')
 
-    @staticmethod
-    def from_device_config(device_config):
-        params = device_config.keystore.split(':', 1)[1:]
-        namespace = str(device_config.address)
-        if params:
-            filename = params[1]
-        else:
-            filename = None
+    @classmethod
+    def from_device(
+        cls: Type[Self], device: Device, filename: Optional[str] = None
+    ) -> Self:
+        if not filename:
+            # Extract the filename from the config if there is one
+            if device.config.keystore is not None:
+                params = device.config.keystore.split(':', 1)[1:]
+                if params:
+                    filename = params[0]
 
-        return JsonKeyStore(namespace, filename)
+        # Use a namespace based on the device address
+        if device.public_address not in (Address.ANY, Address.ANY_RANDOM):
+            namespace = str(device.public_address)
+        elif device.random_address != Address.ANY_RANDOM:
+            namespace = str(device.random_address)
+        else:
+            namespace = JsonKeyStore.DEFAULT_NAMESPACE
+
+        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') as json_file:
-                return json.load(json_file)
+            with open(self.filename, 'r', encoding='utf-8') as json_file:
+                db = json.load(json_file)
         except FileNotFoundError:
-            return {}
+            db = {}
+
+        # First, look for a namespace match
+        if self.namespace in db:
+            return (db, db[self.namespace])
+
+        # Then, if the namespace is the default namespace, and there's
+        # only one entry in the db, use that
+        if self.namespace == self.DEFAULT_NAMESPACE and len(db) == 1:
+            return next(iter(db.items()))
+
+        # Finally, just create an empty key map for the namespace
+        key_map = {}
+        db[self.namespace] = key_map
+        return (db, key_map)
 
     async def save(self, db):
         # Create the directory if it doesn't exist
@@ -226,48 +305,55 @@ class JsonKeyStore(KeyStore):
 
         # Save to a temporary file
         temp_filename = self.filename + '.tmp'
-        with open(temp_filename, 'w') as output:
+        with open(temp_filename, 'w', encoding='utf-8') as output:
             json.dump(db, output, sort_keys=True, indent=4)
 
         # Atomically replace the previous file
-        os.rename(temp_filename, self.filename)
+        os.replace(temp_filename, self.filename)
 
-    async def delete(self, name):
-        db = await self.load()
-
-        namespace = db.get(self.namespace)
-        if namespace is None:
-            raise KeyError(name)
-
-        del namespace[name]
+    async def delete(self, name: str) -> None:
+        db, key_map = await self.load()
+        del key_map[name]
         await self.save(db)
 
     async def update(self, name, keys):
-        db = await self.load()
-
-        namespace = db.setdefault(self.namespace, {})
-        namespace[name] = keys.to_dict()
-
+        db, key_map = await self.load()
+        key_map.setdefault(name, {}).update(keys.to_dict())
         await self.save(db)
 
     async def get_all(self):
-        db = await self.load()
+        _, key_map = await self.load()
+        return [(name, PairingKeys.from_dict(keys)) for (name, keys) in key_map.items()]
 
-        namespace = db.get(self.namespace)
-        if namespace is None:
-            return []
+    async def delete_all(self):
+        db, key_map = await self.load()
+        key_map.clear()
+        await self.save(db)
 
-        return [(name, PairingKeys.from_dict(keys)) for (name, keys) in namespace.items()]
-
-    async def get(self, name):
-        db = await self.load()
-
-        namespace = db.get(self.namespace)
-        if namespace is None:
+    async def get(self, name: str) -> Optional[PairingKeys]:
+        _, key_map = await self.load()
+        if name not in key_map:
             return None
 
-        keys = namespace.get(name)
-        if keys is None:
-            return None
+        return PairingKeys.from_dict(key_map[name])
 
-        return PairingKeys.from_dict(keys)
+
+# -----------------------------------------------------------------------------
+class MemoryKeyStore(KeyStore):
+    all_keys: Dict[str, PairingKeys]
+
+    def __init__(self) -> None:
+        self.all_keys = {}
+
+    async def delete(self, name: str) -> None:
+        if name in self.all_keys:
+            del self.all_keys[name]
+
+    async def update(self, name: str, keys: PairingKeys) -> None:
+        self.all_keys[name] = keys
+
+    async def get(self, name: str) -> Optional[PairingKeys]:
+        return self.all_keys.get(name)
+
+    async def get_all(self) -> List[Tuple[str, PairingKeys]]:
+        return list(self.all_keys.items())

bumble/link.py

@@ -17,16 +17,27 @@
 # -----------------------------------------------------------------------------
 import logging
 import asyncio
-import websockets
 from functools import partial
-from colors import color
 
+from bumble.core import (
+    BT_PERIPHERAL_ROLE,
+    BT_BR_EDR_TRANSPORT,
+    BT_LE_TRANSPORT,
+    InvalidStateError,
+)
+from bumble.colors import color
 from bumble.hci import (
     Address,
     HCI_SUCCESS,
     HCI_CONNECTION_ACCEPT_TIMEOUT_ERROR,
-    HCI_CONNECTION_TIMEOUT_ERROR
+    HCI_CONNECTION_TIMEOUT_ERROR,
+    HCI_UNKNOWN_CONNECTION_IDENTIFIER_ERROR,
+    HCI_PAGE_TIMEOUT_ERROR,
+    HCI_Connection_Complete_Event,
 )
+from bumble import controller
+
+from typing import Optional, Set
 
 # -----------------------------------------------------------------------------
 # Logging
@@ -47,16 +58,24 @@ def parse_parameters(params_str):
 
 
 # -----------------------------------------------------------------------------
-# TODO: add more support for various LL exchanges (see Vol 6, Part B - 2.4 DATA CHANNEL PDU)
+# TODO: add more support for various LL exchanges
+# (see Vol 6, Part B - 2.4 DATA CHANNEL PDU)
 # -----------------------------------------------------------------------------
 class LocalLink:
     '''
     Link bus for controllers to communicate with each other
     '''
 
+    controllers: Set[controller.Controller]
+
     def __init__(self):
-        self.controllers        = set()
+        self.controllers = set()
         self.pending_connection = None
+        self.pending_classic_connection = None
+
+    ############################################################
+    # Common utils
+    ############################################################
 
     def add_controller(self, controller):
         logger.debug(f'new controller: {controller}')
@@ -71,22 +90,43 @@ class LocalLink:
                 return controller
         return None
 
-    def on_address_changed(self, controller):
-        pass
+    def find_classic_controller(
+        self, address: Address
+    ) -> Optional[controller.Controller]:
+        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
+    ############################################################
+
+    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_address, destination_address, data):
+    def send_acl_data(self, sender_controller, destination_address, transport, data):
         # Send the data to the first controller with a matching address
-        if controller := self.find_controller(destination_address):
-            controller.on_link_acl_data(sender_address, data)
+        if transport == BT_LE_TRANSPORT:
+            destination_controller = self.find_controller(destination_address)
+            source_address = sender_controller.random_address
+        elif transport == BT_BR_EDR_TRANSPORT:
+            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
@@ -103,23 +143,31 @@ class LocalLink:
             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)
+        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
+            le_create_connection_command, HCI_CONNECTION_ACCEPT_TIMEOUT_ERROR
         )
 
     def connect(self, central_address, le_create_connection_command):
-        logger.debug(f'$$$ CONNECTION {central_address} -> {le_create_connection_command.peer_address}')
+        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):
+    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')
@@ -127,16 +175,26 @@ class LocalLink:
 
         # 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)
+            peripheral_controller.on_link_central_disconnected(
+                central_address, disconnect_command.reason
+            )
 
-        central_controller.on_link_peripheral_disconnection_complete(disconnect_command, HCI_SUCCESS)
+        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} -> {peripheral_address}: reason = {disconnect_command.reason}')
+        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)
 
-    def on_connection_encrypted(self, central_address, peripheral_address, rand, ediv, ltk):
+    # pylint: disable=too-many-arguments
+    def on_connection_encrypted(
+        self, central_address, peripheral_address, rand, ediv, ltk
+    ):
         logger.debug(f'*** ENCRYPTION {central_address} -> {peripheral_address}')
 
         if central_controller := self.find_controller(central_address):
@@ -145,6 +203,189 @@ class LocalLink:
         if peripheral_controller := self.find_controller(peripheral_address):
             peripheral_controller.on_link_encrypted(central_address, rand, ediv, ltk)
 
+    def create_cis(
+        self,
+        central_controller: controller.Controller,
+        peripheral_address: Address,
+        cig_id: int,
+        cis_id: int,
+    ) -> None:
+        logger.debug(
+            f'$$$ CIS Request {central_controller.random_address} -> {peripheral_address}'
+        )
+        if peripheral_controller := self.find_controller(peripheral_address):
+            asyncio.get_running_loop().call_soon(
+                peripheral_controller.on_link_cis_request,
+                central_controller.random_address,
+                cig_id,
+                cis_id,
+            )
+
+    def accept_cis(
+        self,
+        peripheral_controller: controller.Controller,
+        central_address: Address,
+        cig_id: int,
+        cis_id: int,
+    ) -> None:
+        logger.debug(
+            f'$$$ CIS Accept {peripheral_controller.random_address} -> {central_address}'
+        )
+        if central_controller := self.find_controller(central_address):
+            asyncio.get_running_loop().call_soon(
+                central_controller.on_link_cis_established, cig_id, cis_id
+            )
+            asyncio.get_running_loop().call_soon(
+                peripheral_controller.on_link_cis_established, cig_id, cis_id
+            )
+
+    def disconnect_cis(
+        self,
+        initiator_controller: controller.Controller,
+        peer_address: Address,
+        cig_id: int,
+        cis_id: int,
+    ) -> None:
+        logger.debug(
+            f'$$$ CIS Disconnect {initiator_controller.random_address} -> {peer_address}'
+        )
+        if peer_controller := self.find_controller(peer_address):
+            asyncio.get_running_loop().call_soon(
+                initiator_controller.on_link_cis_disconnected, cig_id, cis_id
+            )
+            asyncio.get_running_loop().call_soon(
+                peer_controller.on_link_cis_disconnected, cig_id, cis_id
+            )
+
+    ############################################################
+    # Classic handlers
+    ############################################################
+
+    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
+    ):
+        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
+            )
+            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))
+        )
+
+    def classic_sco_connect(
+        self,
+        initiator_controller: controller.Controller,
+        responder_address: Address,
+        link_type: int,
+    ):
+        logger.debug(
+            f'[Classic] {initiator_controller.public_address} connects SCO to {responder_address}'
+        )
+        responder_controller = self.find_classic_controller(responder_address)
+        # Initiator controller should handle it.
+        assert responder_controller
+
+        responder_controller.on_classic_connection_request(
+            initiator_controller.public_address,
+            link_type,
+        )
+
+    def classic_accept_sco_connection(
+        self,
+        responder_controller: controller.Controller,
+        initiator_address: Address,
+        link_type: int,
+    ):
+        logger.debug(
+            f'[Classic] {responder_controller.public_address} accepts to connect SCO {initiator_address}'
+        )
+        initiator_controller = self.find_classic_controller(initiator_address)
+        if initiator_controller is None:
+            responder_controller.on_classic_sco_connection_complete(
+                responder_controller.public_address,
+                HCI_UNKNOWN_CONNECTION_IDENTIFIER_ERROR,
+                link_type,
+            )
+            return
+
+        async def task():
+            initiator_controller.on_classic_sco_connection_complete(
+                responder_controller.public_address, HCI_SUCCESS, link_type
+            )
+
+        asyncio.create_task(task())
+        responder_controller.on_classic_sco_connection_complete(
+            initiator_controller.public_address, HCI_SUCCESS, link_type
+        )
+
 
 # -----------------------------------------------------------------------------
 class RemoteLink:
@@ -152,15 +393,18 @@ 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
+        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())
@@ -168,17 +412,20 @@ class RemoteLink:
 
     def add_controller(self, controller):
         if self.controller:
-            raise ValueError('controller already set')
+            raise InvalidStateError('controller already set')
         self.controller = controller
 
     def remove_controller(self, controller):
         if self.controller != controller:
-            raise ValueError('controller mismatch')
+            raise InvalidStateError('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
 
@@ -192,11 +439,16 @@ class RemoteLink:
             try:
                 await item
             except Exception as error:
-                logger.warning(f'{color("!!! Exception in async handler:", "red")} {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}')
@@ -227,7 +479,9 @@ class RemoteLink:
             self.central_connections.remove(address)
 
         if address in self.peripheral_connections:
-            self.controller.on_link_central_disconnected(address, HCI_CONNECTION_TIMEOUT_ERROR)
+            self.controller.on_link_central_disconnected(
+                address, HCI_CONNECTION_TIMEOUT_ERROR
+            )
             self.peripheral_connections.remove(address)
 
     async def on_unreachable_received(self, target):
@@ -244,7 +498,9 @@ class RemoteLink:
 
     async def on_advertisement_message_received(self, sender, advertisement):
         try:
-            self.controller.on_link_advertising_data(Address(sender), bytes.fromhex(advertisement))
+            self.controller.on_link_advertising_data(
+                Address(sender), bytes.fromhex(advertisement)
+            )
         except Exception:
             logger.exception('exception')
 
@@ -263,11 +519,11 @@ class RemoteLink:
         self.controller.on_link_central_connected(Address(sender))
 
         # Accept the connection by responding to it
-        await self.send_targetted_message(sender, 'connected')
+        await self.send_targeted_message(sender, 'connected')
 
     async def on_connected_message_received(self, sender, _):
         if not self.pending_connection:
-            logger.warn('received a connection ack, but no connection is pending')
+            logger.warning('received a connection ack, but no connection is pending')
             return
 
         # Remember the connection
@@ -275,7 +531,9 @@ class RemoteLink:
 
         # 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)
+        self.controller.on_link_peripheral_connection_complete(
+            self.pending_connection, HCI_SUCCESS
+        )
 
     async def on_disconnect_message_received(self, sender, message):
         # Notify the controller
@@ -287,7 +545,7 @@ class RemoteLink:
         if sender in self.peripheral_connections:
             self.peripheral_connections.remove(sender)
 
-    async def on_encrypted_message_received(self, sender, message):
+    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))
 
@@ -296,7 +554,7 @@ class RemoteLink:
         websocket = await self.websocket
 
         # Create a future value to hold the eventual result
-        assert(self.rpc_result is None)
+        assert self.rpc_result is None
         self.rpc_result = asyncio.get_running_loop().create_future()
 
         # Send the command
@@ -309,7 +567,7 @@ class RemoteLink:
 
         # TODO: parse the result
 
-    async def send_targetted_message(self, target, message):
+    async def send_targeted_message(self, target, message):
         # Ensure we have a connection
         websocket = await self.websocket
 
@@ -326,35 +584,62 @@ class RemoteLink:
         self.execute(self.notify_address_changed)
 
     async def send_advertising_data_to_relay(self, data):
-        await self.send_targetted_message('*', f'advertisement:{data.hex()}')
+        await self.send_targeted_message('*', f'advertisement:{data.hex()}')
 
-    def send_advertising_data(self, sender_address, data):
+    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_targetted_message(peer_address, f'acl:{data.hex()}')
+        await self.send_targeted_message(peer_address, f'acl:{data.hex()}')
 
-    def send_acl_data(self, sender_address, peer_address, data):
+    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_targetted_message(peer_address, 'connect')
+        await self.send_targeted_message(peer_address, 'connect')
 
-    def connect(self, central_address, le_create_connection_command):
+    def connect(self, _, le_create_connection_command):
         if self.pending_connection:
-            logger.warn('connection already pending')
+            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)))
+        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)
+        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} -> {peripheral_address}: reason = {disconnect_command.reason}')
-        self.execute(partial(self.send_targetted_message, peripheral_address, f'disconnect:reason={disconnect_command.reason}'))
-        asyncio.get_running_loop().call_soon(self.on_disconnection_complete, 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, central_address, 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_targetted_message, peripheral_address, f'encrypted:ltk={ltk.hex()}'))
+    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()}',
+            )
+        )

bumble/pairing.py

@@ -0,0 +1,262 @@
+# 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
+from dataclasses import dataclass
+from typing import Optional, Tuple
+
+from .hci import (
+    Address,
+    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,
+    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_LINK_KEY_DISTRIBUTION_FLAG,
+    OobContext,
+    OobLegacyContext,
+    OobSharedData,
+)
+from .core import AdvertisingData, LeRole
+
+
+# -----------------------------------------------------------------------------
+@dataclass
+class OobData:
+    """OOB data that can be sent from one device to another."""
+
+    address: Optional[Address] = None
+    role: Optional[LeRole] = None
+    shared_data: Optional[OobSharedData] = None
+    legacy_context: Optional[OobLegacyContext] = None
+
+    @classmethod
+    def from_ad(cls, ad: AdvertisingData) -> OobData:
+        instance = cls()
+        shared_data_c: Optional[bytes] = None
+        shared_data_r: Optional[bytes] = None
+        for ad_type, ad_data in ad.ad_structures:
+            if ad_type == AdvertisingData.LE_BLUETOOTH_DEVICE_ADDRESS:
+                instance.address = 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 = []
+        if self.address is not None:
+            ad_structures.append(
+                (AdvertisingData.LE_BLUETOOTH_DEVICE_ADDRESS, bytes(self.address))
+            )
+        if self.role is not None:
+            ad_structures.append((AdvertisingData.LE_ROLE, bytes([self.role])))
+        if self.shared_data is not None:
+            ad_structures.extend(self.shared_data.to_ad().ad_structures)
+        if self.legacy_context is not None:
+            ad_structures.append(
+                (AdvertisingData.SECURITY_MANAGER_TK_VALUE, self.legacy_context.tk)
+            )
+
+        return AdvertisingData(ad_structures)
+
+
+# -----------------------------------------------------------------------------
+class PairingDelegate:
+    """Abstract base class for Pairing Delegates."""
+
+    # I/O Capabilities.
+    # These are defined abstractly, and can be mapped to specific Classic pairing
+    # and/or SMP constants.
+    class IoCapability(enum.IntEnum):
+        NO_OUTPUT_NO_INPUT = SMP_NO_INPUT_NO_OUTPUT_IO_CAPABILITY
+        KEYBOARD_INPUT_ONLY = SMP_KEYBOARD_ONLY_IO_CAPABILITY
+        DISPLAY_OUTPUT_ONLY = SMP_DISPLAY_ONLY_IO_CAPABILITY
+        DISPLAY_OUTPUT_AND_YES_NO_INPUT = SMP_DISPLAY_YES_NO_IO_CAPABILITY
+        DISPLAY_OUTPUT_AND_KEYBOARD_INPUT = SMP_KEYBOARD_DISPLAY_IO_CAPABILITY
+
+    # Direct names for backward compatibility.
+    NO_OUTPUT_NO_INPUT = IoCapability.NO_OUTPUT_NO_INPUT
+    KEYBOARD_INPUT_ONLY = IoCapability.KEYBOARD_INPUT_ONLY
+    DISPLAY_OUTPUT_ONLY = IoCapability.DISPLAY_OUTPUT_ONLY
+    DISPLAY_OUTPUT_AND_YES_NO_INPUT = IoCapability.DISPLAY_OUTPUT_AND_YES_NO_INPUT
+    DISPLAY_OUTPUT_AND_KEYBOARD_INPUT = IoCapability.DISPLAY_OUTPUT_AND_KEYBOARD_INPUT
+
+    # Key Distribution [LE only]
+    class KeyDistribution(enum.IntFlag):
+        DISTRIBUTE_ENCRYPTION_KEY = SMP_ENC_KEY_DISTRIBUTION_FLAG
+        DISTRIBUTE_IDENTITY_KEY = SMP_ID_KEY_DISTRIBUTION_FLAG
+        DISTRIBUTE_SIGNING_KEY = SMP_SIGN_KEY_DISTRIBUTION_FLAG
+        DISTRIBUTE_LINK_KEY = SMP_LINK_KEY_DISTRIBUTION_FLAG
+
+    DEFAULT_KEY_DISTRIBUTION: KeyDistribution = (
+        KeyDistribution.DISTRIBUTE_ENCRYPTION_KEY
+        | KeyDistribution.DISTRIBUTE_IDENTITY_KEY
+    )
+
+    # 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,
+    }
+
+    io_capability: IoCapability
+    local_initiator_key_distribution: KeyDistribution
+    local_responder_key_distribution: KeyDistribution
+
+    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,
+    ) -> None:
+        self.io_capability = io_capability
+        self.local_initiator_key_distribution = local_initiator_key_distribution
+        self.local_responder_key_distribution = local_responder_key_distribution
+
+    @property
+    def classic_io_capability(self) -> int:
+        """Map the abstract I/O capability to a Classic constant."""
+
+        # pylint: disable=line-too-long
+        return self.CLASSIC_IO_CAPABILITIES_MAP.get(
+            self.io_capability, HCI_NO_INPUT_NO_OUTPUT_IO_CAPABILITY
+        )
+
+    @property
+    def smp_io_capability(self) -> int:
+        """Map the abstract I/O capability to an SMP constant."""
+
+        # This is just a 1-1 direct mapping
+        return self.io_capability
+
+    async def accept(self) -> bool:
+        """Accept or reject a Pairing request."""
+        return True
+
+    async def confirm(self, auto: bool = False) -> bool:
+        """
+        Respond yes or no to a Pairing confirmation question.
+        The `auto` parameter stands for automatic confirmation.
+        """
+        return True
+
+    # pylint: disable-next=unused-argument
+    async def compare_numbers(self, number: int, digits: int) -> bool:
+        """Compare two numbers."""
+        return True
+
+    async def get_number(self) -> Optional[int]:
+        """
+        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]:
+        """
+        Return a string whose utf-8 encoding is up to max_length bytes.
+        """
+        return None
+
+    # pylint: disable-next=unused-argument
+    async def display_number(self, number: int, digits: int) -> None:
+        """Display a number."""
+
+    # [LE only]
+    async def key_distribution_response(
+        self, peer_initiator_key_distribution: int, peer_responder_key_distribution: int
+    ) -> Tuple[int, int]:
+        """
+        Return the key distribution response in an SMP protocol context.
+
+        NOTE: since it is only used by the SMP protocol, this method's input and output
+        are directly as integers, using the SMP constants, rather than the abstract
+        KeyDistribution enums.
+        """
+        return (
+            int(
+                peer_initiator_key_distribution & self.local_initiator_key_distribution
+            ),
+            int(
+                peer_responder_key_distribution & self.local_responder_key_distribution
+            ),
+        )
+
+
+# -----------------------------------------------------------------------------
+class PairingConfig:
+    """Configuration for the Pairing protocol."""
+
+    class AddressType(enum.IntEnum):
+        PUBLIC = Address.PUBLIC_DEVICE_ADDRESS
+        RANDOM = Address.RANDOM_DEVICE_ADDRESS
+
+    @dataclass
+    class OobConfig:
+        """Config for OOB pairing."""
+
+        our_context: Optional[OobContext]
+        peer_data: Optional[OobSharedData]
+        legacy_context: Optional[OobLegacyContext]
+
+    def __init__(
+        self,
+        sc: bool = True,
+        mitm: bool = True,
+        bonding: bool = True,
+        delegate: Optional[PairingDelegate] = None,
+        identity_address_type: Optional[AddressType] = None,
+        oob: Optional[OobConfig] = 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'identity_address_type={self.identity_address_type}, '
+            f'delegate[{self.delegate.io_capability}]), '
+            f'oob[{self.oob}])'
+        )

bumble/pandora/__init__.py

@@ -0,0 +1,108 @@
+# Copyright 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.
+
+"""
+Bumble Pandora server.
+This module implement the Pandora Bluetooth test APIs for the Bumble stack.
+"""
+
+__version__ = "0.0.1"
+
+import grpc
+import grpc.aio
+
+from .config import Config
+from .device import PandoraDevice
+from .host import HostService
+from .l2cap import L2CAPService
+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
+
+# public symbols
+__all__ = [
+    'register_servicer_hook',
+    'serve',
+    'Config',
+    'PandoraDevice',
+]
+
+
+# Add servicers hooks.
+_SERVICERS_HOOKS: List[Callable[[PandoraDevice, Config, grpc.aio.Server], None]] = []
+
+
+def register_servicer_hook(
+    hook: Callable[[PandoraDevice, Config, grpc.aio.Server], None]
+) -> None:
+    _SERVICERS_HOOKS.append(hook)
+
+
+async def serve(
+    bumble: PandoraDevice,
+    config: Config = Config(),
+    grpc_server: Optional[grpc.aio.Server] = None,
+    port: int = 0,
+) -> None:
+    # initialize a gRPC server if not provided.
+    server = grpc_server if grpc_server is not None else grpc.aio.server()
+    port = server.add_insecure_port(f'localhost:{port}')
+
+    try:
+        while True:
+            # load server config from dict.
+            config.load_from_dict(bumble.config.get('server', {}))
+
+            # add Pandora services to the gRPC server.
+            add_HostServicer_to_server(
+                HostService(server, bumble.device, config), server
+            )
+            add_SecurityServicer_to_server(
+                SecurityService(bumble.device, config), server
+            )
+            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:
+                hook(bumble, config, server)
+
+            # open device.
+            await bumble.open()
+            try:
+                # Pandora require classic devices to be discoverable & connectable.
+                if bumble.device.classic_enabled:
+                    await bumble.device.set_discoverable(True)
+                    await bumble.device.set_connectable(True)
+
+                # start & serve gRPC server.
+                await server.start()
+                await server.wait_for_termination()
+            finally:
+                # close device.
+                await bumble.close()
+
+            # re-initialize the gRPC server.
+            server = grpc.aio.server()
+            server.add_insecure_port(f'localhost:{port}')
+    finally:
+        # stop server.
+        await server.stop(None)

bumble/pandora/config.py

@@ -0,0 +1,56 @@
+# Copyright 2022 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import annotations
+from bumble.pairing import PairingConfig, PairingDelegate
+from dataclasses import dataclass
+from typing import Any, Dict
+
+
+@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
+    smp_local_initiator_key_distribution: PairingDelegate.KeyDistribution = (
+        PairingDelegate.DEFAULT_KEY_DISTRIBUTION
+    )
+    smp_local_responder_key_distribution: PairingDelegate.KeyDistribution = (
+        PairingDelegate.DEFAULT_KEY_DISTRIBUTION
+    )
+
+    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)
+        self.smp_local_initiator_key_distribution = config.get(
+            'smp_local_initiator_key_distribution',
+            PairingDelegate.DEFAULT_KEY_DISTRIBUTION,
+        )
+        self.smp_local_responder_key_distribution = config.get(
+            'smp_local_responder_key_distribution',
+            PairingDelegate.DEFAULT_KEY_DISTRIBUTION,
+        )

bumble/pandora/device.py

@@ -0,0 +1,164 @@
+# Copyright 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.
+
+"""Generic & dependency free Bumble (reference) device."""
+
+from __future__ import annotations
+from bumble import transport
+from bumble.core import (
+    BT_GENERIC_AUDIO_SERVICE,
+    BT_HANDSFREE_SERVICE,
+    BT_L2CAP_PROTOCOL_ID,
+    BT_RFCOMM_PROTOCOL_ID,
+)
+from bumble.device import Device, DeviceConfiguration
+from bumble.host import Host
+from bumble.sdp import (
+    SDP_BLUETOOTH_PROFILE_DESCRIPTOR_LIST_ATTRIBUTE_ID,
+    SDP_PROTOCOL_DESCRIPTOR_LIST_ATTRIBUTE_ID,
+    SDP_SERVICE_CLASS_ID_LIST_ATTRIBUTE_ID,
+    SDP_SERVICE_RECORD_HANDLE_ATTRIBUTE_ID,
+    DataElement,
+    ServiceAttribute,
+)
+from typing import Any, Dict, List, Optional
+
+
+# Default rootcanal HCI TCP address
+ROOTCANAL_HCI_ADDRESS = "localhost:6402"
+
+
+class PandoraDevice:
+    """
+    Small wrapper around a Bumble device and it's HCI transport.
+    Notes:
+      - The Bumble device is idle by default.
+      - Repetitive calls to `open`/`close` will result on new Bumble device instances.
+    """
+
+    # Bumble device instance & configuration.
+    device: Device
+    config: Dict[str, Any]
+
+    # HCI transport name & instance.
+    _hci_name: str
+    _hci: Optional[transport.Transport]  # type: ignore[name-defined]
+
+    def __init__(self, config: Dict[str, Any]) -> None:
+        self.config = config
+        self.device = _make_device(config)
+        self._hci_name = config.get(
+            'transport', f"tcp-client:{config.get('tcp', ROOTCANAL_HCI_ADDRESS)}"
+        )
+        self._hci = None
+
+    @property
+    def idle(self) -> bool:
+        return self._hci is None
+
+    async def open(self) -> None:
+        if self._hci is not None:
+            return
+
+        # 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]
+
+        # power-on.
+        await self.device.power_on()
+
+    async def close(self) -> None:
+        if self._hci is None:
+            return
+
+        # flush & re-initialize device.
+        await self.device.host.flush()
+        self.device.host = None  # type: ignore[assignment]
+        self.device = _make_device(self.config)
+
+        # close HCI transport.
+        await self._hci.close()
+        self._hci = None
+
+    async def reset(self) -> None:
+        await self.close()
+        await self.open()
+
+    def info(self) -> Optional[Dict[str, str]]:
+        return {
+            'public_bd_address': str(self.device.public_address),
+            'random_address': str(self.device.random_address),
+        }
+
+
+def _make_device(config: Dict[str, Any]) -> Device:
+    """Initialize an idle Bumble device instance."""
+
+    # initialize bumble device.
+    device_config = DeviceConfiguration()
+    device_config.load_from_dict(config)
+    device = Device(config=device_config, host=None)
+
+    # Add fake a2dp service to avoid Android disconnect
+    device.sdp_service_records = _make_sdp_records(1)
+
+    return device
+
+
+# TODO(b/267540823): remove when Pandora A2dp is supported
+def _make_sdp_records(rfcomm_channel: int) -> Dict[int, List[ServiceAttribute]]:
+    return {
+        0x00010001: [
+            ServiceAttribute(
+                SDP_SERVICE_RECORD_HANDLE_ATTRIBUTE_ID,
+                DataElement.unsigned_integer_32(0x00010001),
+            ),
+            ServiceAttribute(
+                SDP_SERVICE_CLASS_ID_LIST_ATTRIBUTE_ID,
+                DataElement.sequence(
+                    [
+                        DataElement.uuid(BT_HANDSFREE_SERVICE),
+                        DataElement.uuid(BT_GENERIC_AUDIO_SERVICE),
+                    ]
+                ),
+            ),
+            ServiceAttribute(
+                SDP_PROTOCOL_DESCRIPTOR_LIST_ATTRIBUTE_ID,
+                DataElement.sequence(
+                    [
+                        DataElement.sequence([DataElement.uuid(BT_L2CAP_PROTOCOL_ID)]),
+                        DataElement.sequence(
+                            [
+                                DataElement.uuid(BT_RFCOMM_PROTOCOL_ID),
+                                DataElement.unsigned_integer_8(rfcomm_channel),
+                            ]
+                        ),
+                    ]
+                ),
+            ),
+            ServiceAttribute(
+                SDP_BLUETOOTH_PROFILE_DESCRIPTOR_LIST_ATTRIBUTE_ID,
+                DataElement.sequence(
+                    [
+                        DataElement.sequence(
+                            [
+                                DataElement.uuid(BT_HANDSFREE_SERVICE),
+                                DataElement.unsigned_integer_16(0x0105),
+                            ]
+                        )
+                    ]
+                ),
+            ),
+        ]
+    }

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 grpc
+import json
+import logging
+
+from asyncio import Queue as AsyncQueue, Future
+
+from . import utils
+from .config import Config
+from bumble.core import OutOfResourcesError, InvalidArgumentError
+from bumble.device import Device
+from bumble.l2cap import (
+    ClassicChannel,
+    ClassicChannelServer,
+    ClassicChannelSpec,
+    LeCreditBasedChannel,
+    LeCreditBasedChannelServer,
+    LeCreditBasedChannelSpec,
+)
+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 (  # pytype: disable=pyi-error
+    COMMAND_NOT_UNDERSTOOD,
+    INVALID_CID_IN_REQUEST,
+    Channel as PandoraChannel,
+    ConnectRequest,
+    ConnectResponse,
+    CreditBasedChannelRequest,
+    DisconnectRequest,
+    DisconnectResponse,
+    ReceiveRequest,
+    ReceiveResponse,
+    SendRequest,
+    SendResponse,
+    WaitConnectionRequest,
+    WaitConnectionResponse,
+    WaitDisconnectionRequest,
+    WaitDisconnectionResponse,
+)
+from typing import AsyncGenerator, Dict, Optional, Union
+from dataclasses import dataclass
+
+L2capChannel = Union[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('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: Optional[Union[ClassicChannelSpec, LeCreditBasedChannelSpec]] = None
+        l2cap_server: Optional[
+            Union[ClassicChannelServer, LeCreditBasedChannelServer]
+        ] = 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('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: Optional[Union[ClassicChannelSpec, LeCreditBasedChannelSpec]] = 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.send_pdu(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

@@ -0,0 +1,559 @@
+# Copyright 2022 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import annotations
+import asyncio
+import contextlib
+import grpc
+import logging
+
+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,
+)
+from bumble.device import Connection as BumbleConnection, Device
+from bumble.hci import HCI_Error
+from bumble.utils import EventWatcher
+from bumble.pairing import PairingConfig, PairingDelegate as BasePairingDelegate
+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 (
+    LE_LEVEL1,
+    LE_LEVEL2,
+    LE_LEVEL3,
+    LE_LEVEL4,
+    LEVEL0,
+    LEVEL1,
+    LEVEL2,
+    LEVEL3,
+    LEVEL4,
+    DeleteBondRequest,
+    IsBondedRequest,
+    LESecurityLevel,
+    PairingEvent,
+    PairingEventAnswer,
+    SecureRequest,
+    SecureResponse,
+    SecurityLevel,
+    WaitSecurityRequest,
+    WaitSecurityResponse,
+)
+from typing import Any, AsyncGenerator, AsyncIterator, Callable, Dict, Optional, Union
+
+
+class PairingDelegate(BasePairingDelegate):
+    def __init__(
+        self,
+        connection: BumbleConnection,
+        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,
+    ) -> None:
+        self.log = utils.BumbleServerLoggerAdapter(
+            logging.getLogger(),
+            {'service_name': 'Security', 'device': connection.device},
+        )
+        self.connection = connection
+        self.service = service
+        super().__init__(
+            io_capability,
+            local_initiator_key_distribution,
+            local_responder_key_distribution,
+        )
+
+    async def accept(self) -> bool:
+        return True
+
+    def add_origin(self, ev: PairingEvent) -> PairingEvent:
+        if not self.connection.is_incomplete:
+            assert ev.connection
+            ev.connection.CopyFrom(
+                Connection(
+                    cookie=any_pb2.Any(value=self.connection.handle.to_bytes(4, 'big'))
+                )
+            )
+        else:
+            # In BR/EDR, connection may not be complete,
+            # use address instead
+            assert self.connection.transport == BT_BR_EDR_TRANSPORT
+            ev.address = bytes(reversed(bytes(self.connection.peer_address)))
+
+        return ev
+
+    async def confirm(self, auto: bool = False) -> bool:
+        self.log.debug(
+            f"Pairing event: `just_works` (io_capability: {self.io_capability})"
+        )
+
+        if self.service.event_queue is None or self.service.event_answer is None:
+            return True
+
+        event = self.add_origin(PairingEvent(just_works=empty_pb2.Empty()))
+        self.service.event_queue.put_nowait(event)
+        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.debug(
+            f"Pairing event: `numeric_comparison` (io_capability: {self.io_capability})"
+        )
+
+        if self.service.event_queue is None or self.service.event_answer is None:
+            raise RuntimeError('security: unhandled number comparison request')
+
+        event = self.add_origin(PairingEvent(numeric_comparison=number))
+        self.service.event_queue.put_nowait(event)
+        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.debug(
+            f"Pairing event: `passkey_entry_request` (io_capability: {self.io_capability})"
+        )
+
+        if self.service.event_queue is None or self.service.event_answer is None:
+            raise RuntimeError('security: unhandled number request')
+
+        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)  # 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.debug(
+            f"Pairing event: `pin_code_request` (io_capability: {self.io_capability})"
+        )
+
+        if self.service.event_queue is None or self.service.event_answer is None:
+            raise RuntimeError('security: unhandled pin_code request')
+
+        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)  # type: ignore
+        assert answer.event == event
+        if answer.answer_variant() is None:
+            return None
+        assert answer.answer_variant() == 'pin'
+
+        if answer.pin is None:
+            return None
+
+        pin = answer.pin.decode('utf-8')
+        if not pin or len(pin) > max_length:
+            raise ValueError(f'Pin must be utf-8 encoded up to {max_length} bytes')
+
+        return pin
+
+    async def display_number(self, number: int, digits: int = 6) -> None:
+        if (
+            self.connection.transport == BT_BR_EDR_TRANSPORT
+            and self.io_capability == BasePairingDelegate.DISPLAY_OUTPUT_ONLY
+        ):
+            return
+
+        self.log.debug(
+            f"Pairing event: `passkey_entry_notification` (io_capability: {self.io_capability})"
+        )
+
+        if self.service.event_queue is None:
+            raise RuntimeError('security: unhandled number display request')
+
+        event = self.add_origin(PairingEvent(passkey_entry_notification=number))
+        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.device = device
+        self.config = config
+
+        def pairing_config_factory(connection: BumbleConnection) -> PairingConfig:
+            return PairingConfig(
+                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,
+                    io_capability=config.io_capability,
+                    local_initiator_key_distribution=config.smp_local_initiator_key_distribution,
+                    local_responder_key_distribution=config.smp_local_responder_key_distribution,
+                ),
+            )
+
+        self.device.pairing_config_factory = pairing_config_factory
+
+    @utils.rpc
+    async def OnPairing(
+        self, request: AsyncIterator[PairingEventAnswer], context: grpc.ServicerContext
+    ) -> AsyncGenerator[PairingEvent, None]:
+        self.log.debug('OnPairing')
+
+        if self.event_queue is not None:
+            raise RuntimeError('already streaming pairing events')
+
+        if len(self.device.connections):
+            raise RuntimeError(
+                'the `OnPairing` method shall be initiated before establishing any connections.'
+            )
+
+        self.event_queue = asyncio.Queue()
+        self.event_answer = request
+
+        try:
+            while event := await self.event_queue.get():
+                yield event
+
+        finally:
+            self.event_queue = None
+            self.event_answer = None
+
+    @utils.rpc
+    async def Secure(
+        self, request: SecureRequest, context: grpc.ServicerContext
+    ) -> SecureResponse:
+        connection_handle = int.from_bytes(request.connection.cookie.value, 'big')
+        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'}[
+            connection.transport
+        ] == oneof
+
+        # security level already reached
+        if 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.debug('Pair...')
+
+                security_result = asyncio.get_running_loop().create_future()
+
+                with contextlib.closing(EventWatcher()) as watcher:
+
+                    @watcher.on(connection, 'pairing')
+                    def on_pairing(*_: Any) -> None:
+                        security_result.set_result('success')
+
+                    @watcher.on(connection, 'pairing_failure')
+                    def on_pairing_failure(*_: Any) -> None:
+                        security_result.set_result('pairing_failure')
+
+                    @watcher.on(connection, 'disconnection')
+                    def on_disconnection(*_: Any) -> None:
+                        security_result.set_result('connection_died')
+
+                    if (
+                        connection.transport == BT_LE_TRANSPORT
+                        and connection.role == BT_PERIPHERAL_ROLE
+                    ):
+                        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())
+            except (HCI_Error, ProtocolError) as e:
+                self.log.warning(f"Pairing failure: {e}")
+                return SecureResponse(pairing_failure=empty_pb2.Empty())
+
+        # trigger authentication if needed
+        if self.need_authentication(connection, level):
+            try:
+                self.log.debug('Authenticate...')
+                await connection.authenticate()
+                self.log.debug('Authenticated')
+            except asyncio.CancelledError:
+                self.log.warning("Connection died during authentication")
+                return SecureResponse(connection_died=empty_pb2.Empty())
+            except (HCI_Error, ProtocolError) as e:
+                self.log.warning(f"Authentication failure: {e}")
+                return SecureResponse(authentication_failure=empty_pb2.Empty())
+
+        # trigger encryption if needed
+        if self.need_encryption(connection, level):
+            try:
+                self.log.debug('Encrypt...')
+                await connection.encrypt()
+                self.log.debug('Encrypted')
+            except asyncio.CancelledError:
+                self.log.warning("Connection died during encryption")
+                return SecureResponse(connection_died=empty_pb2.Empty())
+            except (HCI_Error, ProtocolError) as e:
+                self.log.warning(f"Encryption failure: {e}")
+                return SecureResponse(encryption_failure=empty_pb2.Empty())
+
+        # security level has been reached ?
+        if self.reached_security_level(connection, level):
+            return SecureResponse(success=empty_pb2.Empty())
+        return SecureResponse(not_reached=empty_pb2.Empty())
+
+    @utils.rpc
+    async def WaitSecurity(
+        self, request: WaitSecurityRequest, context: grpc.ServicerContext
+    ) -> WaitSecurityResponse:
+        connection_handle = int.from_bytes(request.connection.cookie.value, 'big')
+        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'}[
+            connection.transport
+        ] == request.level_variant()
+
+        wait_for_security: asyncio.Future[str] = (
+            asyncio.get_running_loop().create_future()
+        )
+        authenticate_task: Optional[asyncio.Future[None]] = None
+        pair_task: Optional[asyncio.Future[None]] = None
+
+        async def authenticate() -> None:
+            assert connection
+            if (encryption := connection.encryption) != 0:
+                self.log.debug('Disable encryption...')
+                try:
+                    await connection.encrypt(enable=False)
+                except:
+                    pass
+                self.log.debug('Disable encryption: done')
+
+            self.log.debug('Authenticate...')
+            await connection.authenticate()
+            self.log.debug('Authenticate: done')
+
+            if encryption != 0 and connection.encryption != encryption:
+                self.log.debug('Re-enable encryption...')
+                await connection.encrypt()
+                self.log.debug('Re-enable encryption: done')
+
+        def set_failure(name: str) -> Callable[..., None]:
+            def wrapper(*args: Any) -> None:
+                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.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.debug('Wait for security: done')
+                wait_for_security.set_result('success')
+            elif (
+                connection.transport == BT_BR_EDR_TRANSPORT
+                and self.need_authentication(connection, level)
+            ):
+                nonlocal authenticate_task
+                if authenticate_task is None:
+                    authenticate_task = asyncio.create_task(authenticate())
+
+        def pair(*_: Any) -> None:
+            if self.need_pairing(connection, level):
+                pair_task = asyncio.create_task(connection.pair())
+
+        listeners: Dict[str, Callable[..., None]] = {
+            'disconnection': set_failure('connection_died'),
+            'pairing_failure': set_failure('pairing_failure'),
+            'connection_authentication_failure': set_failure('authentication_failure'),
+            'connection_encryption_failure': set_failure('encryption_failure'),
+            '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,
+        }
+
+        with contextlib.closing(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())
+
+            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.debug('Wait for authentication...')
+            try:
+                await authenticate_task  # type: ignore
+            except:
+                pass
+            self.log.debug('Authenticated')
+
+        # wait for `pair` to finish if any
+        if pair_task is not None:
+            self.log.debug('Wait for authentication...')
+            try:
+                await pair_task  # type: ignore
+            except:
+                pass
+            self.log.debug('paired')
+
+        return WaitSecurityResponse(**kwargs)
+
+    def reached_security_level(
+        self, connection: BumbleConnection, level: Union[SecurityLevel, LESecurityLevel]
+    ) -> bool:
+        self.log.debug(
+            str(
+                {
+                    'level': level,
+                    '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 BR_LEVEL_REACHED[level](connection)
+
+    def need_pairing(self, connection: BumbleConnection, level: int) -> bool:
+        if connection.transport == BT_LE_TRANSPORT:
+            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:
+            return False
+        if level == LEVEL2 and connection.encryption != 0:
+            return not connection.authenticated
+        return level >= LEVEL2 and not connection.authenticated
+
+    def need_encryption(self, connection: BumbleConnection, level: int) -> bool:
+        # TODO(abel): need to support MITM
+        if connection.transport == BT_LE_TRANSPORT:
+            return level == LE_LEVEL2 and not connection.encryption
+        return level >= LEVEL2 and not connection.encryption
+
+
+class SecurityStorageService(SecurityStorageServicer):
+    def __init__(self, device: Device, config: Config) -> None:
+        self.log = utils.BumbleServerLoggerAdapter(
+            logging.getLogger(), {'service_name': 'SecurityStorage', 'device': device}
+        )
+        self.device = device
+        self.config = config
+
+    @utils.rpc
+    async def IsBonded(
+        self, request: IsBondedRequest, context: grpc.ServicerContext
+    ) -> wrappers_pb2.BoolValue:
+        address = utils.address_from_request(request, request.WhichOneof("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
+        else:
+            is_bonded = False
+
+        return wrappers_pb2.BoolValue(value=is_bonded)
+
+    @utils.rpc
+    async def DeleteBond(
+        self, request: DeleteBondRequest, context: grpc.ServicerContext
+    ) -> empty_pb2.Empty:
+        address = utils.address_from_request(request, request.WhichOneof("address"))
+        self.log.debug(f"DeleteBond: {address}")
+
+        if self.device.keystore is not None:
+            with contextlib.suppress(KeyError):
+                await self.device.keystore.delete(str(address))
+
+        return empty_pb2.Empty()

bumble/pandora/utils.py

@@ -0,0 +1,113 @@
+# Copyright 2022 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import annotations
+import contextlib
+import functools
+import grpc
+import inspect
+import logging
+
+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
+
+ADDRESS_TYPES: Dict[str, int] = {
+    "public": Address.PUBLIC_DEVICE_ADDRESS,
+    "random": Address.RANDOM_DEVICE_ADDRESS,
+    "public_identity": Address.PUBLIC_IDENTITY_ADDRESS,
+    "random_static_identity": Address.RANDOM_IDENTITY_ADDRESS,
+}
+
+
+def address_from_request(request: Message, field: Optional[str]) -> Address:
+    if field is None:
+        return Address.ANY
+    return Address(bytes(reversed(getattr(request, field))), ADDRESS_TYPES[field])
+
+
+class BumbleServerLoggerAdapter(logging.LoggerAdapter):  # type: ignore
+    """Formats logs from the PandoraClient."""
+
+    def process(
+        self, msg: str, kwargs: MutableMapping[str, Any]
+    ) -> Tuple[str, MutableMapping[str, Any]]:
+        assert self.extra
+        service_name = self.extra['service_name']
+        assert isinstance(service_name, str)
+        device = self.extra['device']
+        assert isinstance(device, Device)
+        addr_bytes = bytes(
+            reversed(bytes(device.public_address))
+        )  # pytype: disable=attribute-error
+        addr = ':'.join([f'{x:02X}' for x in addr_bytes[4:]])
+        return (f'[bumble.{service_name}:{addr}] {msg}', kwargs)
+
+
+@contextlib.contextmanager
+def exception_to_rpc_error(
+    context: grpc.ServicerContext,
+) -> Generator[None, None, None]:
+    try:
+        yield None
+    except NotImplementedError as e:
+        context.set_code(grpc.StatusCode.UNIMPLEMENTED)  # type: ignore
+        context.set_details(str(e))  # type: ignore
+    except ValueError as e:
+        context.set_code(grpc.StatusCode.INVALID_ARGUMENT)  # type: ignore
+        context.set_details(str(e))  # type: ignore
+    except RuntimeError as e:
+        context.set_code(grpc.StatusCode.ABORTED)  # type: ignore
+        context.set_details(str(e))  # type: ignore
+
+
+# Decorate an RPC servicer method with a wrapper that transform exceptions to gRPC errors.
+def rpc(func: Any) -> Any:
+    @functools.wraps(func)
+    async def asyncgen_wrapper(
+        self: Any, request: Any, context: grpc.ServicerContext
+    ) -> Any:
+        with exception_to_rpc_error(context):
+            async for v in func(self, request, context):
+                yield v
+
+    @functools.wraps(func)
+    async def async_wrapper(
+        self: Any, request: Any, context: grpc.ServicerContext
+    ) -> Any:
+        with exception_to_rpc_error(context):
+            return await func(self, request, context)
+
+    @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
+
+    @functools.wraps(func)
+    def wrapper(self: Any, request: Any, context: grpc.ServicerContext) -> Any:
+        with exception_to_rpc_error(context):
+            return func(self, request, context)
+
+    if inspect.isasyncgenfunction(func):
+        return asyncgen_wrapper
+
+    if inspect.iscoroutinefunction(func):
+        return async_wrapper
+
+    if inspect.isgenerator(func):
+        return gen_wrapper
+
+    return wrapper

bumble/profiles/aics.py

@@ -0,0 +1,520 @@
+# 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
+# -----------------------------------------------------------------------------
+import logging
+import struct
+
+from dataclasses import dataclass
+from typing import Optional
+
+from bumble import gatt
+from bumble.device import Connection
+from bumble.att import ATT_Error
+from bumble.gatt import (
+    Characteristic,
+    DelegatedCharacteristicAdapter,
+    TemplateService,
+    CharacteristicValue,
+    PackedCharacteristicAdapter,
+    GATT_AUDIO_INPUT_CONTROL_SERVICE,
+    GATT_AUDIO_INPUT_STATE_CHARACTERISTIC,
+    GATT_GAIN_SETTINGS_ATTRIBUTE_CHARACTERISTIC,
+    GATT_AUDIO_INPUT_TYPE_CHARACTERISTIC,
+    GATT_AUDIO_INPUT_STATUS_CHARACTERISTIC,
+    GATT_AUDIO_INPUT_CONTROL_POINT_CHARACTERISTIC,
+    GATT_AUDIO_INPUT_DESCRIPTION_CHARACTERISTIC,
+)
+from bumble.gatt_client import ProfileServiceProxy, ServiceProxy
+from bumble.utils import OpenIntEnum
+
+# -----------------------------------------------------------------------------
+# Logging
+# -----------------------------------------------------------------------------
+logger = logging.getLogger(__name__)
+
+
+# -----------------------------------------------------------------------------
+# Constants
+# -----------------------------------------------------------------------------
+CHANGE_COUNTER_MAX_VALUE = 0xFF
+GAIN_SETTINGS_MIN_VALUE = 0
+GAIN_SETTINGS_MAX_VALUE = 255
+
+
+class ErrorCode(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(OpenIntEnum):
+    '''
+    Cf. 2.2.1.2 Mute Field
+    '''
+
+    NOT_MUTED = 0x00
+    MUTED = 0x01
+    DISABLED = 0x02
+
+
+class GainMode(OpenIntEnum):
+    '''
+    Cf. 2.2.1.3 Gain Mode
+    '''
+
+    MANUAL_ONLY = 0x00
+    AUTOMATIC_ONLY = 0x01
+    MANUAL = 0x02
+    AUTOMATIC = 0x03
+
+
+class AudioInputStatus(OpenIntEnum):
+    '''
+    Cf. 3.4 Audio Input Status
+    '''
+
+    INATIVE = 0x00
+    ACTIVE = 0x01
+
+
+class AudioInputControlPointOpCode(OpenIntEnum):
+    '''
+    Cf. 3.5.1 Audio Input Control Point procedure requirements
+    '''
+
+    SET_GAIN_SETTING = 0x00
+    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_value: Optional[CharacteristicValue] = 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_value is not None
+        await connection.device.notify_subscribers(
+            attribute=self.attribute_value, value=bytes(self)
+        )
+
+    def on_read(self, _connection: Optional[Connection]) -> bytes:
+        return bytes(self)
+
+
+@dataclass
+class 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)
+        )
+        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,
+            ]
+        )
+
+    def on_read(self, _connection: Optional[Connection]) -> bytes:
+        return bytes(self)
+
+
+@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: Optional[Connection], value: bytes) -> None:
+        assert connection
+
+        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_seetings 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_value: Optional[CharacteristicValue] = None
+
+    @classmethod
+    def from_bytes(cls, data: bytes):
+        return cls(audio_input_description=data.decode('utf-8'))
+
+    def __bytes__(self) -> bytes:
+        return self.audio_input_description.encode('utf-8')
+
+    def on_read(self, _connection: Optional[Connection]) -> bytes:
+        return self.audio_input_description.encode('utf-8')
+
+    async def on_write(self, connection: Optional[Connection], value: bytes) -> None:
+        assert connection
+        assert self.attribute_value
+
+        self.audio_input_description = value.decode('utf-8')
+        await connection.device.notify_subscribers(
+            attribute=self.attribute_value, value=value
+        )
+
+
+class AICSService(TemplateService):
+    UUID = GATT_AUDIO_INPUT_CONTROL_SERVICE
+
+    def __init__(
+        self,
+        audio_input_state: Optional[AudioInputState] = None,
+        gain_settings_properties: Optional[GainSettingsProperties] = None,
+        audio_input_type: str = "local",
+        audio_input_status: Optional[AudioInputStatus] = None,
+        audio_input_description: Optional[AudioInputDescription] = 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 = DelegatedCharacteristicAdapter(
+            Characteristic(
+                uuid=GATT_AUDIO_INPUT_STATE_CHARACTERISTIC,
+                properties=Characteristic.Properties.READ
+                | Characteristic.Properties.NOTIFY,
+                permissions=Characteristic.Permissions.READ_REQUIRES_ENCRYPTION,
+                value=CharacteristicValue(read=self.audio_input_state.on_read),
+            ),
+            encode=lambda value: bytes(value),
+        )
+        self.audio_input_state.attribute_value = (
+            self.audio_input_state_characteristic.value
+        )
+
+        self.gain_settings_properties_characteristic = DelegatedCharacteristicAdapter(
+            Characteristic(
+                uuid=GATT_GAIN_SETTINGS_ATTRIBUTE_CHARACTERISTIC,
+                properties=Characteristic.Properties.READ,
+                permissions=Characteristic.Permissions.READ_REQUIRES_ENCRYPTION,
+                value=CharacteristicValue(read=self.gain_settings_properties.on_read),
+            )
+        )
+
+        self.audio_input_type_characteristic = Characteristic(
+            uuid=GATT_AUDIO_INPUT_TYPE_CHARACTERISTIC,
+            properties=Characteristic.Properties.READ,
+            permissions=Characteristic.Permissions.READ_REQUIRES_ENCRYPTION,
+            value=audio_input_type,
+        )
+
+        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 = DelegatedCharacteristicAdapter(
+            Characteristic(
+                uuid=GATT_AUDIO_INPUT_CONTROL_POINT_CHARACTERISTIC,
+                properties=Characteristic.Properties.WRITE,
+                permissions=Characteristic.Permissions.WRITE_REQUIRES_ENCRYPTION,
+                value=CharacteristicValue(
+                    write=self.audio_input_control_point.on_write
+                ),
+            )
+        )
+
+        self.audio_input_description_characteristic = DelegatedCharacteristicAdapter(
+            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_value = (
+            self.audio_input_control_point_characteristic.value
+        )
+
+        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
+
+    def __init__(self, service_proxy: ServiceProxy) -> None:
+        self.service_proxy = service_proxy
+
+        if not (
+            characteristics := service_proxy.get_characteristics_by_uuid(
+                GATT_AUDIO_INPUT_STATE_CHARACTERISTIC
+            )
+        ):
+            raise gatt.InvalidServiceError("Audio Input State Characteristic not found")
+        self.audio_input_state = DelegatedCharacteristicAdapter(
+            characteristic=characteristics[0], decode=AudioInputState.from_bytes
+        )
+
+        if not (
+            characteristics := service_proxy.get_characteristics_by_uuid(
+                GATT_GAIN_SETTINGS_ATTRIBUTE_CHARACTERISTIC
+            )
+        ):
+            raise gatt.InvalidServiceError(
+                "Gain Settings Attribute Characteristic not found"
+            )
+        self.gain_settings_properties = PackedCharacteristicAdapter(
+            characteristics[0],
+            'BBB',
+        )
+
+        if not (
+            characteristics := service_proxy.get_characteristics_by_uuid(
+                GATT_AUDIO_INPUT_STATUS_CHARACTERISTIC
+            )
+        ):
+            raise gatt.InvalidServiceError(
+                "Audio Input Status Characteristic not found"
+            )
+        self.audio_input_status = PackedCharacteristicAdapter(
+            characteristics[0],
+            'B',
+        )
+
+        if not (
+            characteristics := service_proxy.get_characteristics_by_uuid(
+                GATT_AUDIO_INPUT_CONTROL_POINT_CHARACTERISTIC
+            )
+        ):
+            raise gatt.InvalidServiceError(
+                "Audio Input Control Point Characteristic not found"
+            )
+        self.audio_input_control_point = characteristics[0]
+
+        if not (
+            characteristics := service_proxy.get_characteristics_by_uuid(
+                GATT_AUDIO_INPUT_DESCRIPTION_CHARACTERISTIC
+            )
+        ):
+            raise gatt.InvalidServiceError(
+                "Audio Input Description Characteristic not found"
+            )
+        self.audio_input_description = characteristics[0]

bumble/profiles/ascs.py

@@ -0,0 +1,739 @@
+# 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 logging
+import struct
+from typing import Any, Dict, List, Optional, Sequence, Tuple, Type, Union
+
+from bumble import colors
+from bumble.profiles.bap import CodecSpecificConfiguration
+from bumble.profiles import le_audio
+from bumble import device
+from bumble import gatt
+from bumble import gatt_client
+from bumble import hci
+
+# -----------------------------------------------------------------------------
+# 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: int
+    name: str
+    fields: Optional[Sequence[Any]] = None
+    ase_id: List[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
+
+    @staticmethod
+    def from_bytes(pdu: bytes) -> ASE_Operation:
+        op_code = pdu[0]
+
+        cls = ASE_Operation.classes.get(op_code)
+        if cls is None:
+            instance = ASE_Operation(pdu)
+            instance.name = ASE_Operation.Opcode(op_code).name
+            instance.op_code = op_code
+            return instance
+        self = cls.__new__(cls)
+        ASE_Operation.__init__(self, pdu)
+        if self.fields is not None:
+            self.init_from_bytes(pdu, 1)
+        return self
+
+    @staticmethod
+    def subclass(fields):
+        def inner(cls: Type[ASE_Operation]):
+            try:
+                operation = ASE_Operation.Opcode[cls.__name__[4:].upper()]
+                cls.name = operation.name
+                cls.op_code = operation
+            except:
+                raise KeyError(f'PDU name {cls.name} not found in Ase_Operation.Opcode')
+            cls.fields = fields
+
+            # Register a factory for this class
+            ASE_Operation.classes[cls.op_code] = cls
+
+            return cls
+
+        return inner
+
+    def __init__(self, pdu: Optional[bytes] = None, **kwargs) -> None:
+        if self.fields is not None and kwargs:
+            hci.HCI_Object.init_from_fields(self, self.fields, kwargs)
+        if pdu is None:
+            pdu = bytes([self.op_code]) + hci.HCI_Object.dict_to_bytes(
+                kwargs, self.fields
+            )
+        self.pdu = pdu
+
+    def init_from_bytes(self, pdu: bytes, offset: int):
+        return hci.HCI_Object.init_from_bytes(self, pdu, offset, 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(
+    [
+        [
+            ('ase_id', 1),
+            ('target_latency', 1),
+            ('target_phy', 1),
+            ('codec_id', hci.CodingFormat.parse_from_bytes),
+            ('codec_specific_configuration', 'v'),
+        ],
+    ]
+)
+class ASE_Config_Codec(ASE_Operation):
+    '''
+    See Audio Stream Control Service 5.1 - Config Codec Operation
+    '''
+
+    target_latency: List[int]
+    target_phy: List[int]
+    codec_id: List[hci.CodingFormat]
+    codec_specific_configuration: List[bytes]
+
+
+@ASE_Operation.subclass(
+    [
+        [
+            ('ase_id', 1),
+            ('cig_id', 1),
+            ('cis_id', 1),
+            ('sdu_interval', 3),
+            ('framing', 1),
+            ('phy', 1),
+            ('max_sdu', 2),
+            ('retransmission_number', 1),
+            ('max_transport_latency', 2),
+            ('presentation_delay', 3),
+        ],
+    ]
+)
+class ASE_Config_QOS(ASE_Operation):
+    '''
+    See Audio Stream Control Service 5.2 - Config Qos Operation
+    '''
+
+    cig_id: List[int]
+    cis_id: List[int]
+    sdu_interval: List[int]
+    framing: List[int]
+    phy: List[int]
+    max_sdu: List[int]
+    retransmission_number: List[int]
+    max_transport_latency: List[int]
+    presentation_delay: List[int]
+
+
+@ASE_Operation.subclass([[('ase_id', 1), ('metadata', 'v')]])
+class ASE_Enable(ASE_Operation):
+    '''
+    See Audio Stream Control Service 5.3 - Enable Operation
+    '''
+
+    metadata: bytes
+
+
+@ASE_Operation.subclass([[('ase_id', 1)]])
+class ASE_Receiver_Start_Ready(ASE_Operation):
+    '''
+    See Audio Stream Control Service 5.4 - Receiver Start Ready Operation
+    '''
+
+
+@ASE_Operation.subclass([[('ase_id', 1)]])
+class ASE_Disable(ASE_Operation):
+    '''
+    See Audio Stream Control Service 5.5 - Disable Operation
+    '''
+
+
+@ASE_Operation.subclass([[('ase_id', 1)]])
+class ASE_Receiver_Stop_Ready(ASE_Operation):
+    '''
+    See Audio Stream Control Service 5.6 - Receiver Stop Ready Operation
+    '''
+
+
+@ASE_Operation.subclass([[('ase_id', 1), ('metadata', 'v')]])
+class ASE_Update_Metadata(ASE_Operation):
+    '''
+    See Audio Stream Control Service 5.7 - Update Metadata Operation
+    '''
+
+    metadata: List[bytes]
+
+
+@ASE_Operation.subclass([[('ase_id', 1)]])
+class ASE_Release(ASE_Operation):
+    '''
+    See Audio Stream Control Service 5.8 - Release Operation
+    '''
+
+
+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 = hci.HCI_LE_Setup_ISO_Data_Path_Command.Direction.CONTROLLER_TO_HOST
+    SOURCE = hci.HCI_LE_Setup_ISO_Data_Path_Command.Direction.HOST_TO_CONTROLLER
+
+
+# -----------------------------------------------------------------------------
+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
+
+    cis_link: Optional[device.CisLink] = 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: Union[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
+
+        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('cis_request', self.on_cis_request)
+        self.service.device.on('cis_establishment', self.on_cis_establishment)
+
+    def on_cis_request(
+        self,
+        acl_connection: device.Connection,
+        cis_handle: int,
+        cig_id: int,
+        cis_id: int,
+    ) -> None:
+        if (
+            cig_id == self.cig_id
+            and cis_id == self.cis_id
+            and self.state == self.State.ENABLING
+        ):
+            acl_connection.abort_on(
+                'flush', self.service.device.accept_cis_request(cis_handle)
+            )
+
+    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('disconnection', self.on_cis_disconnection)
+
+            async def post_cis_established():
+                await self.service.device.send_command(
+                    hci.HCI_LE_Setup_ISO_Data_Path_Command(
+                        connection_handle=cis_link.handle,
+                        data_path_direction=self.role,
+                        data_path_id=0x00,  # Fixed HCI
+                        codec_id=hci.CodingFormat(hci.CodecID.TRANSPARENT),
+                        controller_delay=0,
+                        codec_configuration=b'',
+                    )
+                )
+                if self.role == AudioRole.SINK:
+                    self.state = self.State.STREAMING
+                await self.service.device.notify_subscribers(self, self.value)
+
+            cis_link.acl_connection.abort_on('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
+
+        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():
+            await self.service.device.send_command(
+                hci.HCI_LE_Remove_ISO_Data_Path_Command(
+                    connection_handle=self.cis_link.handle,
+                    data_path_direction=self.role,
+                )
+            )
+            self.state = self.State.IDLE
+            await self.service.device.notify_subscribers(self, self.value)
+
+        self.service.device.abort_on('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('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, _: Optional[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
+    _active_client: Optional[device.Connection] = 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, data):
+        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 operation.op_code == ASE_Operation.Opcode.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 operation.op_code == ASE_Operation.Opcode.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 operation.op_code in (
+            ASE_Operation.Opcode.ENABLE,
+            ASE_Operation.Opcode.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 operation.op_code in (
+            ASE_Operation.Opcode.RECEIVER_START_READY,
+            ASE_Operation.Opcode.DISABLE,
+            ASE_Operation.Opcode.RECEIVER_STOP_READY,
+            ASE_Operation.Opcode.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))
+        self.device.abort_on(
+            '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):
+                self.device.abort_on(
+                    'flush',
+                    self.device.notify_subscribers(ase, ase.value),
+                )
+
+
+# -----------------------------------------------------------------------------
+class AudioStreamControlServiceProxy(gatt_client.ProfileServiceProxy):
+    SERVICE_CLASS = AudioStreamControlService
+
+    sink_ase: List[gatt_client.CharacteristicProxy]
+    source_ase: List[gatt_client.CharacteristicProxy]
+    ase_control_point: gatt_client.CharacteristicProxy
+
+    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,295 @@
+# 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 struct
+import logging
+from typing import List, Optional, Callable, Union, Any
+
+from bumble import l2cap
+from bumble import utils
+from bumble import gatt
+from bumble import gatt_client
+from bumble.core import AdvertisingData
+from bumble.device import Device, Connection
+
+# -----------------------------------------------------------------------------
+# 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
+
+    audio_sink: Optional[Callable[[bytes], Any]]
+    active_codec: Optional[Codec] = None
+    audio_type: Optional[AudioType] = None
+    volume: Optional[int] = None
+    other_state: Optional[int] = None
+    connection: Optional[Connection] = None
+
+    def __init__(
+        self,
+        capability: int,
+        hisyncid: Union[List[int], bytes],
+        device: Device,
+        psm: int = 0,
+        audio_sink: Optional[Callable[[bytes], Any]] = 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(
+            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(
+            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(
+                [
+                    (
+                        AdvertisingData.SERVICE_DATA_16_BIT_UUID,
+                        bytes(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: Optional[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('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('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('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: Optional[Connection], value: bytes) -> None:
+        _logger.debug(f'--- VOLUME Write:{value[0]}')
+        self.volume = value[0]
+        self.emit('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
+    audio_control_point_characteristic: gatt_client.CharacteristicProxy
+    audio_status_point_characteristic: gatt_client.CharacteristicProxy
+    volume_characteristic: gatt_client.CharacteristicProxy
+    psm_characteristic: gatt_client.CharacteristicProxy
+
+    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',
+            ),
+        ):
+            if not (
+                characteristics := self.service_proxy.get_characteristics_by_uuid(uuid)
+            ):
+                raise gatt.InvalidServiceError(f"Missing {uuid} Characteristic")
+            setattr(self, attribute_name, characteristics[0])

bumble/profiles/bap.py

@@ -0,0 +1,550 @@
+# Copyright 2021-2023 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+# -----------------------------------------------------------------------------
+# Imports
+# -----------------------------------------------------------------------------
+from __future__ import annotations
+
+from collections.abc import Sequence
+import dataclasses
+import enum
+import struct
+import functools
+import logging
+from typing import List
+from typing_extensions import Self
+
+from bumble import core
+from bumble import hci
+from bumble import gatt
+from bumble import 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
+    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(
+                [
+                    (
+                        core.AdvertisingData.SERVICE_DATA_16_BIT_UUID,
+                        struct.pack(
+                            '<2sBIB',
+                            gatt.GATT_AUDIO_STREAM_CONTROL_SERVICE.to_bytes(),
+                            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
+    frame_duration: FrameDuration
+    audio_channel_allocation: AudioLocation
+    octets_per_codec_frame: int
+    codec_frames_per_sdu: int
+
+    @classmethod
+    def from_bytes(cls, data: bytes) -> CodecSpecificConfiguration:
+        offset = 0
+        # Allowed default values.
+        audio_channel_allocation = AudioLocation.NOT_ALLOWED
+        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 == 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
+
+        # 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 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 struct.pack(
+            '<BBBBBBBBIBBHBBB',
+            2,
+            CodecSpecificConfiguration.Type.SAMPLING_FREQUENCY,
+            self.sampling_frequency,
+            2,
+            CodecSpecificConfiguration.Type.FRAME_DURATION,
+            self.frame_duration,
+            5,
+            CodecSpecificConfiguration.Type.AUDIO_CHANNEL_ALLOCATION,
+            self.audio_channel_allocation,
+            3,
+            CodecSpecificConfiguration.Type.OCTETS_PER_FRAME,
+            self.octets_per_codec_frame,
+            2,
+            CodecSpecificConfiguration.Type.CODEC_FRAMES_PER_SDU,
+            self.codec_frames_per_sdu,
+        )
+
+
+@dataclasses.dataclass
+class BroadcastAudioAnnouncement:
+    broadcast_id: int
+
+    @classmethod
+    def from_bytes(cls, data: bytes) -> Self:
+        return cls(int.from_bytes(data[:3], 'little'))
+
+
+@dataclasses.dataclass
+class BasicAudioAnnouncement:
+    @dataclasses.dataclass
+    class BIS:
+        index: int
+        codec_specific_configuration: CodecSpecificConfiguration
+
+    @dataclasses.dataclass
+    class CodecInfo:
+        coding_format: hci.CodecID
+        company_id: int
+        vendor_specific_codec_id: int
+
+        @classmethod
+        def from_bytes(cls, data: bytes) -> Self:
+            coding_format = hci.CodecID(data[0])
+            company_id = int.from_bytes(data[1:3], 'little')
+            vendor_specific_codec_id = int.from_bytes(data[3:5], 'little')
+            return cls(coding_format, company_id, vendor_specific_codec_id)
+
+    @dataclasses.dataclass
+    class Subgroup:
+        codec_id: BasicAudioAnnouncement.CodecInfo
+        codec_specific_configuration: CodecSpecificConfiguration
+        metadata: le_audio.Metadata
+        bis: List[BasicAudioAnnouncement.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 = cls.CodecInfo.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)

bumble/profiles/bass.py

@@ -0,0 +1,440 @@
+# 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 typing import ClassVar, List, Optional, Sequence
+
+from bumble import core
+from bumble import device
+from bumble import gatt
+from bumble import gatt_client
+from bumble import hci
+from bumble import 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) -> Optional[BroadcastReceiveState]:
+        if not data:
+            return None
+
+        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.battery_level_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
+    broadcast_receive_states: List[gatt.DelegatedCharacteristicAdapter]
+
+    def __init__(self, service_proxy: gatt_client.ServiceProxy):
+        self.service_proxy = service_proxy
+
+        if not (
+            characteristics := service_proxy.get_characteristics_by_uuid(
+                gatt.GATT_BROADCAST_AUDIO_SCAN_CONTROL_POINT_CHARACTERISTIC
+            )
+        ):
+            raise gatt.InvalidServiceError(
+                "Broadcast Audio Scan Control Point characteristic not found"
+            )
+        self.broadcast_audio_scan_control_point = characteristics[0]
+
+        if not (
+            characteristics := service_proxy.get_characteristics_by_uuid(
+                gatt.GATT_BROADCAST_RECEIVE_STATE_CHARACTERISTIC
+            )
+        ):
+            raise gatt.InvalidServiceError(
+                "Broadcast Receive State characteristic not found"
+            )
+        self.broadcast_receive_states = [
+            gatt.DelegatedCharacteristicAdapter(
+                characteristic, decode=BroadcastReceiveState.from_bytes
+            )
+            for characteristic in characteristics
+        ]
+
+    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))

bumble/profiles/battery_service.py

@@ -23,7 +23,7 @@ from ..gatt import (
     TemplateService,
     Characteristic,
     CharacteristicValue,
-    PackedCharacteristicAdapter
+    PackedCharacteristicAdapter,
 )
 
 
@@ -36,11 +36,11 @@ class BatteryService(TemplateService):
         self.battery_level_characteristic = PackedCharacteristicAdapter(
             Characteristic(
                 GATT_BATTERY_LEVEL_CHARACTERISTIC,
-                Characteristic.READ | Characteristic.NOTIFY,
+                Characteristic.Properties.READ | Characteristic.Properties.NOTIFY,
                 Characteristic.READABLE,
-                CharacteristicValue(read=read_battery_level)
+                CharacteristicValue(read=read_battery_level),
             ),
-            format=BatteryService.BATTERY_LEVEL_FORMAT
+            pack_format=BatteryService.BATTERY_LEVEL_FORMAT,
         )
         super().__init__([self.battery_level_characteristic])
 
@@ -52,10 +52,11 @@ class BatteryServiceProxy(ProfileServiceProxy):
     def __init__(self, service_proxy):
         self.service_proxy = service_proxy
 
-        if characteristics := service_proxy.get_characteristics_by_uuid(GATT_BATTERY_LEVEL_CHARACTERISTIC):
+        if characteristics := service_proxy.get_characteristics_by_uuid(
+            GATT_BATTERY_LEVEL_CHARACTERISTIC
+        ):
             self.battery_level = PackedCharacteristicAdapter(
-                characteristics[0],
-                format=BatteryService.BATTERY_LEVEL_FORMAT
+                characteristics[0], pack_format=BatteryService.BATTERY_LEVEL_FORMAT
             )
         else:
             self.battery_level = None

bumble/profiles/cap.py

@@ -0,0 +1,52 @@
+# Copyright 2021-2023 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+# -----------------------------------------------------------------------------
+# Imports
+# -----------------------------------------------------------------------------
+from __future__ import annotations
+
+from bumble import gatt
+from bumble import gatt_client
+from bumble.profiles import csip
+
+
+# -----------------------------------------------------------------------------
+# Server
+# -----------------------------------------------------------------------------
+class CommonAudioServiceService(gatt.TemplateService):
+    UUID = gatt.GATT_COMMON_AUDIO_SERVICE
+
+    def __init__(
+        self,
+        coordinated_set_identification_service: csip.CoordinatedSetIdentificationService,
+    ) -> None:
+        self.coordinated_set_identification_service = (
+            coordinated_set_identification_service
+        )
+        super().__init__(
+            characteristics=[],
+            included_services=[coordinated_set_identification_service],
+        )
+
+
+# -----------------------------------------------------------------------------
+# Client
+# -----------------------------------------------------------------------------
+class CommonAudioServiceServiceProxy(gatt_client.ProfileServiceProxy):
+    SERVICE_CLASS = CommonAudioServiceService
+
+    def __init__(self, service_proxy: gatt_client.ServiceProxy) -> None:
+        self.service_proxy = service_proxy

bumble/profiles/csip.py

@@ -0,0 +1,257 @@
+# Copyright 2021-2023 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+# -----------------------------------------------------------------------------
+# Imports
+# -----------------------------------------------------------------------------
+from __future__ import annotations
+import enum
+import struct
+from typing import Optional, Tuple
+
+from bumble import core
+from bumble import crypto
+from bumble import device
+from bumble import gatt
+from bumble import gatt_client
+
+
+# -----------------------------------------------------------------------------
+# Constants
+# -----------------------------------------------------------------------------
+SET_IDENTITY_RESOLVING_KEY_LENGTH = 16
+
+
+class SirkType(enum.IntEnum):
+    '''Coordinated Set Identification Service - 5.1 Set Identity Resolving Key.'''
+
+    ENCRYPTED = 0x00
+    PLAINTEXT = 0x01
+
+
+class MemberLock(enum.IntEnum):
+    '''Coordinated Set Identification Service - 5.3 Set Member Lock.'''
+
+    UNLOCKED = 0x01
+    LOCKED = 0x02
+
+
+# -----------------------------------------------------------------------------
+# Crypto Toolbox
+# -----------------------------------------------------------------------------
+def s1(m: bytes) -> bytes:
+    '''
+    Coordinated Set Identification Service - 4.3 s1 SALT generation function.
+    '''
+    return crypto.aes_cmac(m[::-1], bytes(16))[::-1]
+
+
+def k1(n: bytes, salt: bytes, p: bytes) -> bytes:
+    '''
+    Coordinated Set Identification Service - 4.4 k1 derivation function.
+    '''
+    t = crypto.aes_cmac(n[::-1], salt[::-1])
+    return crypto.aes_cmac(p[::-1], t)[::-1]
+
+
+def sef(k: bytes, r: bytes) -> bytes:
+    '''
+    Coordinated Set Identification Service - 4.5 SIRK encryption function sef.
+
+    SIRK decryption function sdf shares the same algorithm. The only difference is that argument r is:
+      * Plaintext in encryption
+      * Cipher in decryption
+    '''
+    return crypto.xor(k1(k, s1(b'SIRKenc'[::-1]), b'csis'[::-1]), r)
+
+
+def sih(k: bytes, r: bytes) -> bytes:
+    '''
+    Coordinated Set Identification Service - 4.7 Resolvable Set Identifier hash function sih.
+    '''
+    return crypto.e(k, r + bytes(13))[:3]
+
+
+def generate_rsi(sirk: bytes) -> bytes:
+    '''
+    Coordinated Set Identification Service - 4.8 Resolvable Set Identifier generation operation.
+    '''
+    prand = crypto.generate_prand()
+    return sih(sirk, prand) + prand
+
+
+# -----------------------------------------------------------------------------
+# Server
+# -----------------------------------------------------------------------------
+class CoordinatedSetIdentificationService(gatt.TemplateService):
+    UUID = gatt.GATT_COORDINATED_SET_IDENTIFICATION_SERVICE
+
+    set_identity_resolving_key: bytes
+    set_identity_resolving_key_characteristic: gatt.Characteristic
+    coordinated_set_size_characteristic: Optional[gatt.Characteristic] = None
+    set_member_lock_characteristic: Optional[gatt.Characteristic] = None
+    set_member_rank_characteristic: Optional[gatt.Characteristic] = None
+
+    def __init__(
+        self,
+        set_identity_resolving_key: bytes,
+        set_identity_resolving_key_type: SirkType,
+        coordinated_set_size: Optional[int] = None,
+        set_member_lock: Optional[MemberLock] = None,
+        set_member_rank: Optional[int] = None,
+    ) -> None:
+        if len(set_identity_resolving_key) != SET_IDENTITY_RESOLVING_KEY_LENGTH:
+            raise core.InvalidArgumentError(
+                f'Invalid SIRK length {len(set_identity_resolving_key)}, expected {SET_IDENTITY_RESOLVING_KEY_LENGTH}'
+            )
+
+        characteristics = []
+
+        self.set_identity_resolving_key = set_identity_resolving_key
+        self.set_identity_resolving_key_type = set_identity_resolving_key_type
+        self.set_identity_resolving_key_characteristic = gatt.Characteristic(
+            uuid=gatt.GATT_SET_IDENTITY_RESOLVING_KEY_CHARACTERISTIC,
+            properties=gatt.Characteristic.Properties.READ
+            | gatt.Characteristic.Properties.NOTIFY,
+            permissions=gatt.Characteristic.Permissions.READ_REQUIRES_ENCRYPTION,
+            value=gatt.CharacteristicValue(read=self.on_sirk_read),
+        )
+        characteristics.append(self.set_identity_resolving_key_characteristic)
+
+        if coordinated_set_size is not None:
+            self.coordinated_set_size_characteristic = gatt.Characteristic(
+                uuid=gatt.GATT_COORDINATED_SET_SIZE_CHARACTERISTIC,
+                properties=gatt.Characteristic.Properties.READ
+                | gatt.Characteristic.Properties.NOTIFY,
+                permissions=gatt.Characteristic.Permissions.READ_REQUIRES_ENCRYPTION,
+                value=struct.pack('B', coordinated_set_size),
+            )
+            characteristics.append(self.coordinated_set_size_characteristic)
+
+        if set_member_lock is not None:
+            self.set_member_lock_characteristic = gatt.Characteristic(
+                uuid=gatt.GATT_SET_MEMBER_LOCK_CHARACTERISTIC,
+                properties=gatt.Characteristic.Properties.READ
+                | gatt.Characteristic.Properties.NOTIFY
+                | gatt.Characteristic.Properties.WRITE,
+                permissions=gatt.Characteristic.Permissions.READ_REQUIRES_ENCRYPTION
+                | gatt.Characteristic.Permissions.WRITEABLE,
+                value=struct.pack('B', set_member_lock),
+            )
+            characteristics.append(self.set_member_lock_characteristic)
+
+        if set_member_rank is not None:
+            self.set_member_rank_characteristic = gatt.Characteristic(
+                uuid=gatt.GATT_SET_MEMBER_RANK_CHARACTERISTIC,
+                properties=gatt.Characteristic.Properties.READ
+                | gatt.Characteristic.Properties.NOTIFY,
+                permissions=gatt.Characteristic.Permissions.READ_REQUIRES_ENCRYPTION,
+                value=struct.pack('B', set_member_rank),
+            )
+            characteristics.append(self.set_member_rank_characteristic)
+
+        super().__init__(characteristics)
+
+    async def on_sirk_read(self, connection: Optional[device.Connection]) -> bytes:
+        if self.set_identity_resolving_key_type == SirkType.PLAINTEXT:
+            sirk_bytes = self.set_identity_resolving_key
+        else:
+            assert connection
+
+            if connection.transport == core.BT_LE_TRANSPORT:
+                key = await connection.device.get_long_term_key(
+                    connection_handle=connection.handle, rand=b'', ediv=0
+                )
+            else:
+                key = await connection.device.get_link_key(connection.peer_address)
+
+            if not key:
+                raise core.InvalidOperationError('LTK or LinkKey is not present')
+
+            sirk_bytes = sef(key, self.set_identity_resolving_key)
+
+        return bytes([self.set_identity_resolving_key_type]) + sirk_bytes
+
+    def get_advertising_data(self) -> bytes:
+        return bytes(
+            core.AdvertisingData(
+                [
+                    (
+                        core.AdvertisingData.RESOLVABLE_SET_IDENTIFIER,
+                        generate_rsi(self.set_identity_resolving_key),
+                    ),
+                ]
+            )
+        )
+
+
+# -----------------------------------------------------------------------------
+# Client
+# -----------------------------------------------------------------------------
+class CoordinatedSetIdentificationProxy(gatt_client.ProfileServiceProxy):
+    SERVICE_CLASS = CoordinatedSetIdentificationService
+
+    set_identity_resolving_key: gatt_client.CharacteristicProxy
+    coordinated_set_size: Optional[gatt_client.CharacteristicProxy] = None
+    set_member_lock: Optional[gatt_client.CharacteristicProxy] = None
+    set_member_rank: Optional[gatt_client.CharacteristicProxy] = None
+
+    def __init__(self, service_proxy: gatt_client.ServiceProxy) -> None:
+        self.service_proxy = service_proxy
+
+        self.set_identity_resolving_key = service_proxy.get_characteristics_by_uuid(
+            gatt.GATT_SET_IDENTITY_RESOLVING_KEY_CHARACTERISTIC
+        )[0]
+
+        if characteristics := service_proxy.get_characteristics_by_uuid(
+            gatt.GATT_COORDINATED_SET_SIZE_CHARACTERISTIC
+        ):
+            self.coordinated_set_size = characteristics[0]
+
+        if characteristics := service_proxy.get_characteristics_by_uuid(
+            gatt.GATT_SET_MEMBER_LOCK_CHARACTERISTIC
+        ):
+            self.set_member_lock = characteristics[0]
+
+        if characteristics := service_proxy.get_characteristics_by_uuid(
+            gatt.GATT_SET_MEMBER_RANK_CHARACTERISTIC
+        ):
+            self.set_member_rank = characteristics[0]
+
+    async def read_set_identity_resolving_key(self) -> Tuple[SirkType, bytes]:
+        '''Reads SIRK and decrypts if encrypted.'''
+        response = await self.set_identity_resolving_key.read_value()
+        if len(response) != SET_IDENTITY_RESOLVING_KEY_LENGTH + 1:
+            raise core.InvalidPacketError('Invalid SIRK value')
+
+        sirk_type = SirkType(response[0])
+        if sirk_type == SirkType.PLAINTEXT:
+            sirk = response[1:]
+        else:
+            connection = self.service_proxy.client.connection
+            device = connection.device
+            if connection.transport == core.BT_LE_TRANSPORT:
+                key = await device.get_long_term_key(
+                    connection_handle=connection.handle, rand=b'', ediv=0
+                )
+            else:
+                key = await device.get_link_key(connection.peer_address)
+
+            if not key:
+                raise core.InvalidOperationError('LTK or LinkKey is not present')
+
+            sirk = sef(key, response[1:])
+
+        return (sirk_type, sirk)

bumble/profiles/device_information_service.py

@@ -17,10 +17,10 @@
 # Imports
 # -----------------------------------------------------------------------------
 import struct
-from typing import Tuple
+from typing import Optional, Tuple
 
-from ..gatt_client import ProfileServiceProxy
-from ..gatt import (
+from bumble.gatt_client import ServiceProxy, ProfileServiceProxy, CharacteristicProxy
+from bumble.gatt import (
     GATT_DEVICE_INFORMATION_SERVICE,
     GATT_FIRMWARE_REVISION_STRING_CHARACTERISTIC,
     GATT_HARDWARE_REVISION_STRING_CHARACTERISTIC,
@@ -33,7 +33,7 @@ from ..gatt import (
     TemplateService,
     Characteristic,
     DelegatedCharacteristicAdapter,
-    UTF8CharacteristicAdapter
+    UTF8CharacteristicAdapter,
 )
 
 
@@ -52,49 +52,50 @@ class DeviceInformationService(TemplateService):
 
     def __init__(
         self,
-        manufacturer_name: str = None,
-        model_number: str = None,
-        serial_number: str = None,
-        hardware_revision: str = None,
-        firmware_revision: str = None,
-        software_revision: str = None,
-        system_id: Tuple[int, int] = None,  # (OUI, Manufacturer ID)
-        ieee_regulatory_certification_data_list: bytes = None
+        manufacturer_name: Optional[str] = None,
+        model_number: Optional[str] = None,
+        serial_number: Optional[str] = None,
+        hardware_revision: Optional[str] = None,
+        firmware_revision: Optional[str] = None,
+        software_revision: Optional[str] = None,
+        system_id: Optional[Tuple[int, int]] = None,  # (OUI, Manufacturer ID)
+        ieee_regulatory_certification_data_list: Optional[bytes] = None,
         # TODO: pnp_id
     ):
         characteristics = [
             Characteristic(
-                uuid,
-                Characteristic.READ,
-                Characteristic.READABLE,
-                field
+                uuid, Characteristic.Properties.READ, Characteristic.READABLE, field
             )
             for (field, uuid) in (
                 (manufacturer_name, GATT_MANUFACTURER_NAME_STRING_CHARACTERISTIC),
-                (model_number,      GATT_MODEL_NUMBER_STRING_CHARACTERISTIC),
-                (serial_number,     GATT_SERIAL_NUMBER_STRING_CHARACTERISTIC),
+                (model_number, GATT_MODEL_NUMBER_STRING_CHARACTERISTIC),
+                (serial_number, GATT_SERIAL_NUMBER_STRING_CHARACTERISTIC),
                 (hardware_revision, GATT_HARDWARE_REVISION_STRING_CHARACTERISTIC),
                 (firmware_revision, GATT_FIRMWARE_REVISION_STRING_CHARACTERISTIC),
-                (software_revision, GATT_SOFTWARE_REVISION_STRING_CHARACTERISTIC)
+                (software_revision, GATT_SOFTWARE_REVISION_STRING_CHARACTERISTIC),
             )
             if field is not None
         ]
 
         if system_id is not None:
-            characteristics.append(Characteristic(
-                GATT_SYSTEM_ID_CHARACTERISTIC,
-                Characteristic.READ,
-                Characteristic.READABLE,
-                self.pack_system_id(*system_id)
-            ))
+            characteristics.append(
+                Characteristic(
+                    GATT_SYSTEM_ID_CHARACTERISTIC,
+                    Characteristic.Properties.READ,
+                    Characteristic.READABLE,
+                    self.pack_system_id(*system_id),
+                )
+            )
 
         if ieee_regulatory_certification_data_list is not None:
-            characteristics.append(Characteristic(
-                GATT_REGULATORY_CERTIFICATION_DATA_LIST_CHARACTERISTIC,
-                Characteristic.READ,
-                Characteristic.READABLE,
-                ieee_regulatory_certification_data_list
-            ))
+            characteristics.append(
+                Characteristic(
+                    GATT_REGULATORY_CERTIFICATION_DATA_LIST_CHARACTERISTIC,
+                    Characteristic.Properties.READ,
+                    Characteristic.READABLE,
+                    ieee_regulatory_certification_data_list,
+                )
+            )
 
         super().__init__(characteristics)
 
@@ -103,16 +104,25 @@ class DeviceInformationService(TemplateService):
 class DeviceInformationServiceProxy(ProfileServiceProxy):
     SERVICE_CLASS = DeviceInformationService
 
-    def __init__(self, service_proxy):
+    manufacturer_name: Optional[UTF8CharacteristicAdapter]
+    model_number: Optional[UTF8CharacteristicAdapter]
+    serial_number: Optional[UTF8CharacteristicAdapter]
+    hardware_revision: Optional[UTF8CharacteristicAdapter]
+    firmware_revision: Optional[UTF8CharacteristicAdapter]
+    software_revision: Optional[UTF8CharacteristicAdapter]
+    system_id: Optional[DelegatedCharacteristicAdapter]
+    ieee_regulatory_certification_data_list: Optional[CharacteristicProxy]
+
+    def __init__(self, service_proxy: ServiceProxy):
         self.service_proxy = service_proxy
 
-        for (field, uuid) in (
+        for field, uuid in (
             ('manufacturer_name', GATT_MANUFACTURER_NAME_STRING_CHARACTERISTIC),
-            ('model_number',      GATT_MODEL_NUMBER_STRING_CHARACTERISTIC),
-            ('serial_number',     GATT_SERIAL_NUMBER_STRING_CHARACTERISTIC),
+            ('model_number', GATT_MODEL_NUMBER_STRING_CHARACTERISTIC),
+            ('serial_number', GATT_SERIAL_NUMBER_STRING_CHARACTERISTIC),
             ('hardware_revision', GATT_HARDWARE_REVISION_STRING_CHARACTERISTIC),
             ('firmware_revision', GATT_FIRMWARE_REVISION_STRING_CHARACTERISTIC),
-            ('software_revision', GATT_SOFTWARE_REVISION_STRING_CHARACTERISTIC)
+            ('software_revision', GATT_SOFTWARE_REVISION_STRING_CHARACTERISTIC),
         ):
             if characteristics := service_proxy.get_characteristics_by_uuid(uuid):
                 characteristic = UTF8CharacteristicAdapter(characteristics[0])
@@ -120,16 +130,20 @@ class DeviceInformationServiceProxy(ProfileServiceProxy):
                 characteristic = None
             self.__setattr__(field, characteristic)
 
-        if characteristics := service_proxy.get_characteristics_by_uuid(GATT_SYSTEM_ID_CHARACTERISTIC):
+        if characteristics := service_proxy.get_characteristics_by_uuid(
+            GATT_SYSTEM_ID_CHARACTERISTIC
+        ):
             self.system_id = DelegatedCharacteristicAdapter(
                 characteristics[0],
                 encode=lambda v: DeviceInformationService.pack_system_id(*v),
-                decode=DeviceInformationService.unpack_system_id
+                decode=DeviceInformationService.unpack_system_id,
             )
         else:
             self.system_id = None
 
-        if characteristics := service_proxy.get_characteristics_by_uuid(GATT_REGULATORY_CERTIFICATION_DATA_LIST_CHARACTERISTIC):
+        if characteristics := service_proxy.get_characteristics_by_uuid(
+            GATT_REGULATORY_CERTIFICATION_DATA_LIST_CHARACTERISTIC
+        ):
             self.ieee_regulatory_certification_data_list = characteristics[0]
         else:
             self.ieee_regulatory_certification_data_list = None

bumble/profiles/gap.py

@@ -0,0 +1,110 @@
+# 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.
+
+"""Generic Access Profile"""
+
+# -----------------------------------------------------------------------------
+# Imports
+# -----------------------------------------------------------------------------
+import logging
+import struct
+from typing import Optional, Tuple, Union
+
+from bumble.core import Appearance
+from bumble.gatt import (
+    TemplateService,
+    Characteristic,
+    CharacteristicAdapter,
+    DelegatedCharacteristicAdapter,
+    UTF8CharacteristicAdapter,
+    GATT_GENERIC_ACCESS_SERVICE,
+    GATT_DEVICE_NAME_CHARACTERISTIC,
+    GATT_APPEARANCE_CHARACTERISTIC,
+)
+from bumble.gatt_client import ProfileServiceProxy, ServiceProxy
+
+# -----------------------------------------------------------------------------
+# Logging
+# -----------------------------------------------------------------------------
+logger = logging.getLogger(__name__)
+
+
+# -----------------------------------------------------------------------------
+# Classes
+# -----------------------------------------------------------------------------
+
+
+# -----------------------------------------------------------------------------
+class GenericAccessService(TemplateService):
+    UUID = GATT_GENERIC_ACCESS_SERVICE
+
+    def __init__(
+        self, device_name: str, appearance: Union[Appearance, Tuple[int, int], int] = 0
+    ):
+        if isinstance(appearance, int):
+            appearance_int = appearance
+        elif isinstance(appearance, tuple):
+            appearance_int = (appearance[0] << 6) | appearance[1]
+        elif isinstance(appearance, Appearance):
+            appearance_int = int(appearance)
+        else:
+            raise TypeError()
+
+        self.device_name_characteristic = Characteristic(
+            GATT_DEVICE_NAME_CHARACTERISTIC,
+            Characteristic.Properties.READ,
+            Characteristic.READABLE,
+            device_name.encode('utf-8')[:248],
+        )
+
+        self.appearance_characteristic = Characteristic(
+            GATT_APPEARANCE_CHARACTERISTIC,
+            Characteristic.Properties.READ,
+            Characteristic.READABLE,
+            struct.pack('<H', appearance_int),
+        )
+
+        super().__init__(
+            [self.device_name_characteristic, self.appearance_characteristic]
+        )
+
+
+# -----------------------------------------------------------------------------
+class GenericAccessServiceProxy(ProfileServiceProxy):
+    SERVICE_CLASS = GenericAccessService
+
+    device_name: Optional[CharacteristicAdapter]
+    appearance: Optional[DelegatedCharacteristicAdapter]
+
+    def __init__(self, service_proxy: ServiceProxy):
+        self.service_proxy = service_proxy
+
+        if characteristics := service_proxy.get_characteristics_by_uuid(
+            GATT_DEVICE_NAME_CHARACTERISTIC
+        ):
+            self.device_name = UTF8CharacteristicAdapter(characteristics[0])
+        else:
+            self.device_name = None
+
+        if characteristics := service_proxy.get_characteristics_by_uuid(
+            GATT_APPEARANCE_CHARACTERISTIC
+        ):
+            self.appearance = DelegatedCharacteristicAdapter(
+                characteristics[0],
+                decode=lambda value: Appearance.from_int(
+                    struct.unpack_from('<H', value, 0)[0],
+                ),
+            )
+        else:
+            self.appearance = None

bumble/profiles/hap.py

@@ -0,0 +1,674 @@
+# 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 functools
+from bumble import att, gatt, gatt_client
+from bumble.core import InvalidArgumentError, InvalidStateError
+from bumble.device import Device, Connection
+from bumble.utils import AsyncRunner, OpenIntEnum
+from bumble.hci import Address
+from dataclasses import dataclass, field
+import logging
+from typing import Any, Dict, List, Optional, Set, Union
+
+
+# -----------------------------------------------------------------------------
+# Constants
+# -----------------------------------------------------------------------------
+class ErrorCode(OpenIntEnum):
+    '''See Hearing Access Service 2.4. Attribute Profile error codes.'''
+
+    INVALID_OPCODE = 0x80
+    WRITE_NAME_NOT_ALLOWED = 0x81
+    PRESET_SYNCHRONIZATION_NOT_SUPPORTED = 0x82
+    PRESET_OPERATION_NOT_POSSIBLE = 0x83
+    INVALID_PARAMETERS_LENGTH = 0x84
+
+
+class HearingAidType(OpenIntEnum):
+    '''See Hearing Access Service 3.1. Hearing Aid Features.'''
+
+    BINAURAL_HEARING_AID = 0b00
+    MONAURAL_HEARING_AID = 0b01
+    BANDED_HEARING_AID = 0b10
+
+
+class PresetSynchronizationSupport(OpenIntEnum):
+    '''See Hearing Access Service 3.1. Hearing Aid Features.'''
+
+    PRESET_SYNCHRONIZATION_IS_NOT_SUPPORTED = 0b0
+    PRESET_SYNCHRONIZATION_IS_SUPPORTED = 0b1
+
+
+class IndependentPresets(OpenIntEnum):
+    '''See Hearing Access Service 3.1. Hearing Aid Features.'''
+
+    IDENTICAL_PRESET_RECORD = 0b0
+    DIFFERENT_PRESET_RECORD = 0b1
+
+
+class DynamicPresets(OpenIntEnum):
+    '''See Hearing Access Service 3.1. Hearing Aid Features.'''
+
+    PRESET_RECORDS_DOES_NOT_CHANGE = 0b0
+    PRESET_RECORDS_MAY_CHANGE = 0b1
+
+
+class WritablePresetsSupport(OpenIntEnum):
+    '''See Hearing Access Service 3.1. Hearing Aid Features.'''
+
+    WRITABLE_PRESET_RECORDS_NOT_SUPPORTED = 0b0
+    WRITABLE_PRESET_RECORDS_SUPPORTED = 0b1
+
+
+class HearingAidPresetControlPointOpcode(OpenIntEnum):
+    '''See Hearing Access Service 3.3.1 Hearing Aid Preset Control Point operation requirements.'''
+
+    # fmt: off
+    READ_PRESETS_REQUEST                     = 0x01
+    READ_PRESET_RESPONSE                     = 0x02
+    PRESET_CHANGED                           = 0x03
+    WRITE_PRESET_NAME                        = 0x04
+    SET_ACTIVE_PRESET                        = 0x05
+    SET_NEXT_PRESET                          = 0x06
+    SET_PREVIOUS_PRESET                      = 0x07
+    SET_ACTIVE_PRESET_SYNCHRONIZED_LOCALLY   = 0x08
+    SET_NEXT_PRESET_SYNCHRONIZED_LOCALLY     = 0x09
+    SET_PREVIOUS_PRESET_SYNCHRONIZED_LOCALLY = 0x0A
+
+
+@dataclass
+class HearingAidFeatures:
+    '''See Hearing Access Service 3.1. Hearing Aid Features.'''
+
+    hearing_aid_type: HearingAidType
+    preset_synchronization_support: PresetSynchronizationSupport
+    independent_presets: IndependentPresets
+    dynamic_presets: DynamicPresets
+    writable_presets_support: WritablePresetsSupport
+
+    def __bytes__(self) -> bytes:
+        return bytes(
+            [
+                (self.hearing_aid_type << 0)
+                | (self.preset_synchronization_support << 2)
+                | (self.independent_presets << 3)
+                | (self.dynamic_presets << 4)
+                | (self.writable_presets_support << 5)
+            ]
+        )
+
+
+def HearingAidFeatures_from_bytes(data: int) -> HearingAidFeatures:
+    return HearingAidFeatures(
+        HearingAidType(data & 0b11),
+        PresetSynchronizationSupport(data >> 2 & 0b1),
+        IndependentPresets(data >> 3 & 0b1),
+        DynamicPresets(data >> 4 & 0b1),
+        WritablePresetsSupport(data >> 5 & 0b1),
+    )
+
+
+@dataclass
+class PresetChangedOperation:
+    '''See Hearing Access Service 3.2.2.2. Preset Changed operation.'''
+
+    class ChangeId(OpenIntEnum):
+        # fmt: off
+        GENERIC_UPDATE            = 0x00
+        PRESET_RECORD_DELETED     = 0x01
+        PRESET_RECORD_AVAILABLE   = 0x02
+        PRESET_RECORD_UNAVAILABLE = 0x03
+
+    @dataclass
+    class Generic:
+        prev_index: int
+        preset_record: PresetRecord
+
+        def __bytes__(self) -> bytes:
+            return bytes([self.prev_index]) + bytes(self.preset_record)
+
+    change_id: ChangeId
+    additional_parameters: Union[Generic, int]
+
+    def to_bytes(self, is_last: bool) -> bytes:
+        if isinstance(self.additional_parameters, PresetChangedOperation.Generic):
+            additional_parameters_bytes = bytes(self.additional_parameters)
+        else:
+            additional_parameters_bytes = bytes([self.additional_parameters])
+
+        return (
+            bytes(
+                [
+                    HearingAidPresetControlPointOpcode.PRESET_CHANGED,
+                    self.change_id,
+                    is_last,
+                ]
+            )
+            + additional_parameters_bytes
+        )
+
+
+class PresetChangedOperationDeleted(PresetChangedOperation):
+    def __init__(self, index) -> None:
+        self.change_id = PresetChangedOperation.ChangeId.PRESET_RECORD_DELETED
+        self.additional_parameters = index
+
+
+class PresetChangedOperationAvailable(PresetChangedOperation):
+    def __init__(self, index) -> None:
+        self.change_id = PresetChangedOperation.ChangeId.PRESET_RECORD_AVAILABLE
+        self.additional_parameters = index
+
+
+class PresetChangedOperationUnavailable(PresetChangedOperation):
+    def __init__(self, index) -> None:
+        self.change_id = PresetChangedOperation.ChangeId.PRESET_RECORD_UNAVAILABLE
+        self.additional_parameters = index
+
+
+@dataclass
+class PresetRecord:
+    '''See Hearing Access Service 2.8. Preset record.'''
+
+    @dataclass
+    class Property:
+        class Writable(OpenIntEnum):
+            CANNOT_BE_WRITTEN = 0b0
+            CAN_BE_WRITTEN = 0b1
+
+        class IsAvailable(OpenIntEnum):
+            IS_UNAVAILABLE = 0b0
+            IS_AVAILABLE = 0b1
+
+        writable: Writable = Writable.CAN_BE_WRITTEN
+        is_available: IsAvailable = IsAvailable.IS_AVAILABLE
+
+        def __bytes__(self) -> bytes:
+            return bytes([self.writable | (self.is_available << 1)])
+
+    index: int
+    name: str
+    properties: Property = field(default_factory=Property)
+
+    def __bytes__(self) -> bytes:
+        return bytes([self.index]) + bytes(self.properties) + self.name.encode('utf-8')
+
+    def is_available(self) -> bool:
+        return (
+            self.properties.is_available
+            == PresetRecord.Property.IsAvailable.IS_AVAILABLE
+        )
+
+
+# -----------------------------------------------------------------------------
+# Server
+# -----------------------------------------------------------------------------
+class HearingAccessService(gatt.TemplateService):
+    UUID = gatt.GATT_HEARING_ACCESS_SERVICE
+
+    hearing_aid_features_characteristic: gatt.Characteristic
+    hearing_aid_preset_control_point: gatt.Characteristic
+    active_preset_index_characteristic: gatt.Characteristic
+    active_preset_index: int
+    active_preset_index_per_device: Dict[Address, int]
+
+    device: Device
+
+    server_features: HearingAidFeatures
+    preset_records: Dict[int, PresetRecord]  # key is the preset index
+    read_presets_request_in_progress: bool
+
+    preset_changed_operations_history_per_device: Dict[
+        Address, List[PresetChangedOperation]
+    ]
+
+    # Keep an updated list of connected client to send notification to
+    currently_connected_clients: Set[Connection]
+
+    def __init__(
+        self, device: Device, features: HearingAidFeatures, presets: List[PresetRecord]
+    ) -> None:
+        self.active_preset_index_per_device = {}
+        self.read_presets_request_in_progress = False
+        self.preset_changed_operations_history_per_device = {}
+        self.currently_connected_clients = set()
+
+        self.device = device
+        self.server_features = features
+        if len(presets) < 1:
+            raise InvalidArgumentError(f'Invalid presets: {presets}')
+
+        self.preset_records = {}
+        for p in presets:
+            if len(p.name.encode()) < 1 or len(p.name.encode()) > 40:
+                raise InvalidArgumentError(f'Invalid name: {p.name}')
+
+            self.preset_records[p.index] = p
+
+        # associate the lowest index as the current active preset at startup
+        self.active_preset_index = sorted(self.preset_records.keys())[0]
+
+        @device.on('connection')  # type: ignore
+        def on_connection(connection: Connection) -> None:
+            @connection.on('disconnection')  # type: ignore
+            def on_disconnection(_reason) -> None:
+                self.currently_connected_clients.remove(connection)
+
+            @connection.on('pairing')  # type: ignore
+            def on_pairing(*_: Any) -> None:
+                self.on_incoming_paired_connection(connection)
+
+            if connection.peer_resolvable_address:
+                self.on_incoming_paired_connection(connection)
+
+        self.hearing_aid_features_characteristic = gatt.Characteristic(
+            uuid=gatt.GATT_HEARING_AID_FEATURES_CHARACTERISTIC,
+            properties=gatt.Characteristic.Properties.READ,
+            permissions=gatt.Characteristic.Permissions.READ_REQUIRES_ENCRYPTION,
+            value=bytes(self.server_features),
+        )
+        self.hearing_aid_preset_control_point = gatt.Characteristic(
+            uuid=gatt.GATT_HEARING_AID_PRESET_CONTROL_POINT_CHARACTERISTIC,
+            properties=(
+                gatt.Characteristic.Properties.WRITE
+                | gatt.Characteristic.Properties.INDICATE
+            ),
+            permissions=gatt.Characteristic.Permissions.WRITE_REQUIRES_ENCRYPTION,
+            value=gatt.CharacteristicValue(
+                write=self._on_write_hearing_aid_preset_control_point
+            ),
+        )
+        self.active_preset_index_characteristic = gatt.Characteristic(
+            uuid=gatt.GATT_ACTIVE_PRESET_INDEX_CHARACTERISTIC,
+            properties=(
+                gatt.Characteristic.Properties.READ
+                | gatt.Characteristic.Properties.NOTIFY
+            ),
+            permissions=gatt.Characteristic.Permissions.READ_REQUIRES_ENCRYPTION,
+            value=gatt.CharacteristicValue(read=self._on_read_active_preset_index),
+        )
+
+        super().__init__(
+            [
+                self.hearing_aid_features_characteristic,
+                self.hearing_aid_preset_control_point,
+                self.active_preset_index_characteristic,
+            ]
+        )
+
+    def on_incoming_paired_connection(self, connection: Connection):
+        '''Setup initial operations to handle a remote bonded HAP device'''
+        # TODO Should we filter on HAP device only ?
+        self.currently_connected_clients.add(connection)
+        if (
+            connection.peer_address
+            not in self.preset_changed_operations_history_per_device
+        ):
+            self.preset_changed_operations_history_per_device[
+                connection.peer_address
+            ] = []
+            return
+
+        async def on_connection_async() -> None:
+            # Send all the PresetChangedOperation that occur when not connected
+            await self._preset_changed_operation(connection)
+            # Update the active preset index if needed
+            await self.notify_active_preset_for_connection(connection)
+
+        connection.abort_on('disconnection', on_connection_async())
+
+    def _on_read_active_preset_index(
+        self, __connection__: Optional[Connection]
+    ) -> bytes:
+        return bytes([self.active_preset_index])
+
+    # TODO this need to be triggered when device is unbonded
+    def on_forget(self, addr: Address) -> None:
+        self.preset_changed_operations_history_per_device.pop(addr)
+
+    async def _on_write_hearing_aid_preset_control_point(
+        self, connection: Optional[Connection], value: bytes
+    ):
+        assert connection
+
+        opcode = HearingAidPresetControlPointOpcode(value[0])
+        handler = getattr(self, '_on_' + opcode.name.lower())
+        await handler(connection, value)
+
+    async def _on_read_presets_request(
+        self, connection: Optional[Connection], value: bytes
+    ):
+        assert connection
+        if connection.att_mtu < 49:  # 2.5. GATT sub-procedure requirements
+            logging.warning(f'HAS require MTU >= 49: {connection}')
+
+        if self.read_presets_request_in_progress:
+            raise att.ATT_Error(att.ErrorCode.PROCEDURE_ALREADY_IN_PROGRESS)
+        self.read_presets_request_in_progress = True
+
+        start_index = value[1]
+        if start_index == 0x00:
+            raise att.ATT_Error(att.ErrorCode.OUT_OF_RANGE)
+
+        num_presets = value[2]
+        if num_presets == 0x00:
+            raise att.ATT_Error(att.ErrorCode.OUT_OF_RANGE)
+
+        # Sending `num_presets` presets ordered by increasing index field, starting from start_index
+        presets = [
+            self.preset_records[key]
+            for key in sorted(self.preset_records.keys())
+            if self.preset_records[key].index >= start_index
+        ]
+        del presets[num_presets:]
+        if len(presets) == 0:
+            raise att.ATT_Error(att.ErrorCode.OUT_OF_RANGE)
+
+        AsyncRunner.spawn(self._read_preset_response(connection, presets))
+
+    async def _read_preset_response(
+        self, connection: Connection, presets: List[PresetRecord]
+    ):
+        # If the ATT bearer is terminated before all notifications or indications are sent, then the server shall consider the Read Presets Request operation aborted and shall not either continue or restart the operation when the client reconnects.
+        try:
+            for i, preset in enumerate(presets):
+                await connection.device.indicate_subscriber(
+                    connection,
+                    self.hearing_aid_preset_control_point,
+                    value=bytes(
+                        [
+                            HearingAidPresetControlPointOpcode.READ_PRESET_RESPONSE,
+                            i == len(presets) - 1,
+                        ]
+                    )
+                    + bytes(preset),
+                )
+
+        finally:
+            # indicate_subscriber can raise a TimeoutError, we need to gracefully terminate the operation
+            self.read_presets_request_in_progress = False
+
+    async def generic_update(self, op: PresetChangedOperation) -> None:
+        '''Server API to perform a generic update. It is the responsibility of the caller to modify the preset_records to match the PresetChangedOperation being sent'''
+        await self._notifyPresetOperations(op)
+
+    async def delete_preset(self, index: int) -> None:
+        '''Server API to delete a preset. It should not be the current active preset'''
+
+        if index == self.active_preset_index:
+            raise InvalidStateError('Cannot delete active preset')
+
+        del self.preset_records[index]
+        await self._notifyPresetOperations(PresetChangedOperationDeleted(index))
+
+    async def available_preset(self, index: int) -> None:
+        '''Server API to make a preset available'''
+
+        preset = self.preset_records[index]
+        preset.properties.is_available = PresetRecord.Property.IsAvailable.IS_AVAILABLE
+        await self._notifyPresetOperations(PresetChangedOperationAvailable(index))
+
+    async def unavailable_preset(self, index: int) -> None:
+        '''Server API to make a preset unavailable. It should not be the current active preset'''
+
+        if index == self.active_preset_index:
+            raise InvalidStateError('Cannot set active preset as unavailable')
+
+        preset = self.preset_records[index]
+        preset.properties.is_available = (
+            PresetRecord.Property.IsAvailable.IS_UNAVAILABLE
+        )
+        await self._notifyPresetOperations(PresetChangedOperationUnavailable(index))
+
+    async def _preset_changed_operation(self, connection: Connection) -> None:
+        '''Send all PresetChangedOperation saved for a given connection'''
+        op_list = self.preset_changed_operations_history_per_device.get(
+            connection.peer_address, []
+        )
+
+        # Notification will be sent in index order
+        def get_op_index(op: PresetChangedOperation) -> int:
+            if isinstance(op.additional_parameters, PresetChangedOperation.Generic):
+                return op.additional_parameters.prev_index
+            return op.additional_parameters
+
+        op_list.sort(key=get_op_index)
+        # If the ATT bearer is terminated before all notifications or indications are sent, then the server shall consider the Preset Changed operation aborted and shall continue the operation when the client reconnects.
+        while len(op_list) > 0:
+            try:
+                await connection.device.indicate_subscriber(
+                    connection,
+                    self.hearing_aid_preset_control_point,
+                    value=op_list[0].to_bytes(len(op_list) == 1),
+                )
+                # Remove item once sent, and keep the non sent item in the list
+                op_list.pop(0)
+            except TimeoutError:
+                break
+
+    async def _notifyPresetOperations(self, op: PresetChangedOperation) -> None:
+        for historyList in self.preset_changed_operations_history_per_device.values():
+            historyList.append(op)
+
+        for connection in self.currently_connected_clients:
+            await self._preset_changed_operation(connection)
+
+    async def _on_write_preset_name(
+        self, connection: Optional[Connection], value: bytes
+    ):
+        assert connection
+
+        if self.read_presets_request_in_progress:
+            raise att.ATT_Error(att.ErrorCode.PROCEDURE_ALREADY_IN_PROGRESS)
+
+        index = value[1]
+        preset = self.preset_records.get(index, None)
+        if (
+            not preset
+            or preset.properties.writable
+            == PresetRecord.Property.Writable.CANNOT_BE_WRITTEN
+        ):
+            raise att.ATT_Error(ErrorCode.WRITE_NAME_NOT_ALLOWED)
+
+        name = value[2:].decode('utf-8')
+        if not name or len(name) > 40:
+            raise att.ATT_Error(ErrorCode.INVALID_PARAMETERS_LENGTH)
+
+        preset.name = name
+
+        await self.generic_update(
+            PresetChangedOperation(
+                PresetChangedOperation.ChangeId.GENERIC_UPDATE,
+                PresetChangedOperation.Generic(index, preset),
+            )
+        )
+
+    async def notify_active_preset_for_connection(self, connection: Connection) -> None:
+        if (
+            self.active_preset_index_per_device.get(connection.peer_address, 0x00)
+            == self.active_preset_index
+        ):
+            # Nothing to do, peer is already updated
+            return
+
+        await connection.device.notify_subscriber(
+            connection,
+            attribute=self.active_preset_index_characteristic,
+            value=bytes([self.active_preset_index]),
+        )
+        self.active_preset_index_per_device[connection.peer_address] = (
+            self.active_preset_index
+        )
+
+    async def notify_active_preset(self) -> None:
+        for connection in self.currently_connected_clients:
+            await self.notify_active_preset_for_connection(connection)
+
+    async def set_active_preset(
+        self, connection: Optional[Connection], value: bytes
+    ) -> None:
+        assert connection
+        index = value[1]
+        preset = self.preset_records.get(index, None)
+        if (
+            not preset
+            or preset.properties.is_available
+            != PresetRecord.Property.IsAvailable.IS_AVAILABLE
+        ):
+            raise att.ATT_Error(ErrorCode.PRESET_OPERATION_NOT_POSSIBLE)
+
+        if index == self.active_preset_index:
+            # Already at correct value
+            return
+
+        self.active_preset_index = index
+        await self.notify_active_preset()
+
+    async def _on_set_active_preset(
+        self, connection: Optional[Connection], value: bytes
+    ):
+        await self.set_active_preset(connection, value)
+
+    async def set_next_or_previous_preset(
+        self, connection: Optional[Connection], is_previous
+    ):
+        '''Set the next or the previous preset as active'''
+        assert connection
+
+        if self.active_preset_index == 0x00:
+            raise att.ATT_Error(ErrorCode.PRESET_OPERATION_NOT_POSSIBLE)
+
+        first_preset: Optional[PresetRecord] = None  # To loop to first preset
+        next_preset: Optional[PresetRecord] = None
+        for index, record in sorted(self.preset_records.items(), reverse=is_previous):
+            if not record.is_available():
+                continue
+            if first_preset == None:
+                first_preset = record
+            if is_previous:
+                if index >= self.active_preset_index:
+                    continue
+            elif index <= self.active_preset_index:
+                continue
+            next_preset = record
+            break
+
+        if not first_preset:  # If no other preset are available
+            raise att.ATT_Error(ErrorCode.PRESET_OPERATION_NOT_POSSIBLE)
+
+        if next_preset:
+            self.active_preset_index = next_preset.index
+        else:
+            self.active_preset_index = first_preset.index
+        await self.notify_active_preset()
+
+    async def _on_set_next_preset(
+        self, connection: Optional[Connection], __value__: bytes
+    ) -> None:
+        await self.set_next_or_previous_preset(connection, False)
+
+    async def _on_set_previous_preset(
+        self, connection: Optional[Connection], __value__: bytes
+    ) -> None:
+        await self.set_next_or_previous_preset(connection, True)
+
+    async def _on_set_active_preset_synchronized_locally(
+        self, connection: Optional[Connection], value: bytes
+    ):
+        if (
+            self.server_features.preset_synchronization_support
+            == PresetSynchronizationSupport.PRESET_SYNCHRONIZATION_IS_SUPPORTED
+        ):
+            raise att.ATT_Error(ErrorCode.PRESET_SYNCHRONIZATION_NOT_SUPPORTED)
+        await self.set_active_preset(connection, value)
+        # TODO (low priority) inform other server of the change
+
+    async def _on_set_next_preset_synchronized_locally(
+        self, connection: Optional[Connection], __value__: bytes
+    ):
+        if (
+            self.server_features.preset_synchronization_support
+            == PresetSynchronizationSupport.PRESET_SYNCHRONIZATION_IS_SUPPORTED
+        ):
+            raise att.ATT_Error(ErrorCode.PRESET_SYNCHRONIZATION_NOT_SUPPORTED)
+        await self.set_next_or_previous_preset(connection, False)
+        # TODO (low priority) inform other server of the change
+
+    async def _on_set_previous_preset_synchronized_locally(
+        self, connection: Optional[Connection], __value__: bytes
+    ):
+        if (
+            self.server_features.preset_synchronization_support
+            == PresetSynchronizationSupport.PRESET_SYNCHRONIZATION_IS_SUPPORTED
+        ):
+            raise att.ATT_Error(ErrorCode.PRESET_SYNCHRONIZATION_NOT_SUPPORTED)
+        await self.set_next_or_previous_preset(connection, True)
+        # TODO (low priority) inform other server of the change
+
+
+# -----------------------------------------------------------------------------
+# Client
+# -----------------------------------------------------------------------------
+class HearingAccessServiceProxy(gatt_client.ProfileServiceProxy):
+    SERVICE_CLASS = HearingAccessService
+
+    hearing_aid_preset_control_point: gatt_client.CharacteristicProxy
+    preset_control_point_indications: asyncio.Queue
+
+    def __init__(self, service_proxy: gatt_client.ServiceProxy) -> None:
+        self.service_proxy = service_proxy
+
+        self.server_features = gatt.PackedCharacteristicAdapter(
+            service_proxy.get_characteristics_by_uuid(
+                gatt.GATT_HEARING_AID_FEATURES_CHARACTERISTIC
+            )[0],
+            'B',
+        )
+
+        self.hearing_aid_preset_control_point = (
+            service_proxy.get_characteristics_by_uuid(
+                gatt.GATT_HEARING_AID_PRESET_CONTROL_POINT_CHARACTERISTIC
+            )[0]
+        )
+
+        self.active_preset_index = gatt.PackedCharacteristicAdapter(
+            service_proxy.get_characteristics_by_uuid(
+                gatt.GATT_ACTIVE_PRESET_INDEX_CHARACTERISTIC
+            )[0],
+            'B',
+        )
+
+    async def setup_subscription(self):
+        self.preset_control_point_indications = asyncio.Queue()
+        self.active_preset_index_notification = asyncio.Queue()
+
+        def on_active_preset_index_notification(data: bytes):
+            self.active_preset_index_notification.put_nowait(data)
+
+        def on_preset_control_point_indication(data: bytes):
+            self.preset_control_point_indications.put_nowait(data)
+
+        await self.hearing_aid_preset_control_point.subscribe(
+            functools.partial(on_preset_control_point_indication), prefer_notify=False
+        )
+
+        await self.active_preset_index.subscribe(
+            functools.partial(on_active_preset_index_notification)
+        )

bumble/profiles/heart_rate_service.py

@@ -19,6 +19,7 @@
 from enum import IntEnum
 import struct
 
+from bumble import core
 from ..gatt_client import ProfileServiceProxy
 from ..att import ATT_Error
 from ..gatt import (
@@ -30,25 +31,25 @@ from ..gatt import (
     Characteristic,
     CharacteristicValue,
     DelegatedCharacteristicAdapter,
-    PackedCharacteristicAdapter
+    PackedCharacteristicAdapter,
 )
 
 
 # -----------------------------------------------------------------------------
 class HeartRateService(TemplateService):
-    UUID                            = GATT_HEART_RATE_SERVICE
+    UUID = GATT_HEART_RATE_SERVICE
     HEART_RATE_CONTROL_POINT_FORMAT = 'B'
-    CONTROL_POINT_NOT_SUPPORTED     = 0x80
-    RESET_ENERGY_EXPENDED           = 0x01
+    CONTROL_POINT_NOT_SUPPORTED = 0x80
+    RESET_ENERGY_EXPENDED = 0x01
 
     class BodySensorLocation(IntEnum):
-        OTHER    = 0,
-        CHEST    = 1,
-        WRIST    = 2,
-        FINGER   = 3,
-        HAND     = 4,
-        EAR_LOBE = 5,
-        FOOT     = 6
+        OTHER = 0
+        CHEST = 1
+        WRIST = 2
+        FINGER = 3
+        HAND = 4
+        EAR_LOBE = 5
+        FOOT = 6
 
     class HeartRateMeasurement:
         def __init__(
@@ -56,23 +57,25 @@ class HeartRateService(TemplateService):
             heart_rate,
             sensor_contact_detected=None,
             energy_expended=None,
-            rr_intervals=None
+            rr_intervals=None,
         ):
             if heart_rate < 0 or heart_rate > 0xFFFF:
-                raise ValueError('heart_rate out of range')
+                raise core.InvalidArgumentError('heart_rate out of range')
 
-            if energy_expended is not None and (energy_expended < 0 or energy_expended > 0xFFFF):
-                raise ValueError('energy_expended out of range')
+            if energy_expended is not None and (
+                energy_expended < 0 or energy_expended > 0xFFFF
+            ):
+                raise core.InvalidArgumentError('energy_expended out of range')
 
             if rr_intervals:
                 for rr_interval in rr_intervals:
                     if rr_interval < 0 or rr_interval * 1024 > 0xFFFF:
-                        raise ValueError('rr_intervals out of range')
+                        raise core.InvalidArgumentError('rr_intervals out of range')
 
-            self.heart_rate              = heart_rate
+            self.heart_rate = heart_rate
             self.sensor_contact_detected = sensor_contact_detected
-            self.energy_expended         = energy_expended
-            self.rr_intervals            = rr_intervals
+            self.energy_expended = energy_expended
+            self.rr_intervals = rr_intervals
 
         @classmethod
         def from_bytes(cls, data):
@@ -87,7 +90,7 @@ class HeartRateService(TemplateService):
                 offset += 1
 
             if flags & (1 << 2):
-                sensor_contact_detected = (flags & (1 << 1) != 0)
+                sensor_contact_detected = flags & (1 << 1) != 0
             else:
                 sensor_contact_detected = None
 
@@ -119,51 +122,57 @@ class HeartRateService(TemplateService):
                 flags |= ((1 if self.sensor_contact_detected else 0) << 1) | (1 << 2)
 
             if self.energy_expended is not None:
-                flags |= (1 << 3)
+                flags |= 1 << 3
                 data += struct.pack('<H', self.energy_expended)
 
             if self.rr_intervals:
-                flags |= (1 << 4)
-                data += b''.join([
-                    struct.pack('<H', int(rr_interval * 1024))
-                    for rr_interval in self.rr_intervals
-                ])
+                flags |= 1 << 4
+                data += b''.join(
+                    [
+                        struct.pack('<H', int(rr_interval * 1024))
+                        for rr_interval in self.rr_intervals
+                    ]
+                )
 
             return bytes([flags]) + data
 
         def __str__(self):
-            return f'HeartRateMeasurement(heart_rate={self.heart_rate},'\
-                f' sensor_contact_detected={self.sensor_contact_detected},'\
-                f' energy_expended={self.energy_expended},'\
+            return (
+                f'HeartRateMeasurement(heart_rate={self.heart_rate},'
+                f' sensor_contact_detected={self.sensor_contact_detected},'
+                f' energy_expended={self.energy_expended},'
                 f' rr_intervals={self.rr_intervals})'
+            )
 
     def __init__(
         self,
         read_heart_rate_measurement,
         body_sensor_location=None,
-        reset_energy_expended=None
+        reset_energy_expended=None,
     ):
         self.heart_rate_measurement_characteristic = DelegatedCharacteristicAdapter(
             Characteristic(
                 GATT_HEART_RATE_MEASUREMENT_CHARACTERISTIC,
-                Characteristic.NOTIFY,
+                Characteristic.Properties.NOTIFY,
                 0,
-                CharacteristicValue(read=read_heart_rate_measurement)
+                CharacteristicValue(read=read_heart_rate_measurement),
             ),
-            encode=lambda value: bytes(value)
+            # pylint: disable=unnecessary-lambda
+            encode=lambda value: bytes(value),
         )
         characteristics = [self.heart_rate_measurement_characteristic]
 
         if body_sensor_location is not None:
             self.body_sensor_location_characteristic = Characteristic(
                 GATT_BODY_SENSOR_LOCATION_CHARACTERISTIC,
-                Characteristic.READ,
+                Characteristic.Properties.READ,
                 Characteristic.READABLE,
-                bytes([int(body_sensor_location)])
+                bytes([int(body_sensor_location)]),
             )
             characteristics.append(self.body_sensor_location_characteristic)
 
         if reset_energy_expended:
+
             def write_heart_rate_control_point_value(connection, value):
                 if value == self.RESET_ENERGY_EXPENDED:
                     if reset_energy_expended is not None:
@@ -174,11 +183,11 @@ class HeartRateService(TemplateService):
             self.heart_rate_control_point_characteristic = PackedCharacteristicAdapter(
                 Characteristic(
                     GATT_HEART_RATE_CONTROL_POINT_CHARACTERISTIC,
-                    Characteristic.WRITE,
+                    Characteristic.Properties.WRITE,
                     Characteristic.WRITEABLE,
-                    CharacteristicValue(write=write_heart_rate_control_point_value)
+                    CharacteristicValue(write=write_heart_rate_control_point_value),
                 ),
-                format=HeartRateService.HEART_RATE_CONTROL_POINT_FORMAT
+                pack_format=HeartRateService.HEART_RATE_CONTROL_POINT_FORMAT,
             )
             characteristics.append(self.heart_rate_control_point_characteristic)
 
@@ -192,30 +201,38 @@ class HeartRateServiceProxy(ProfileServiceProxy):
     def __init__(self, service_proxy):
         self.service_proxy = service_proxy
 
-        if characteristics := service_proxy.get_characteristics_by_uuid(GATT_HEART_RATE_MEASUREMENT_CHARACTERISTIC):
+        if characteristics := service_proxy.get_characteristics_by_uuid(
+            GATT_HEART_RATE_MEASUREMENT_CHARACTERISTIC
+        ):
             self.heart_rate_measurement = DelegatedCharacteristicAdapter(
                 characteristics[0],
-                decode=HeartRateService.HeartRateMeasurement.from_bytes
+                decode=HeartRateService.HeartRateMeasurement.from_bytes,
             )
         else:
             self.heart_rate_measurement = None
 
-        if characteristics := service_proxy.get_characteristics_by_uuid(GATT_BODY_SENSOR_LOCATION_CHARACTERISTIC):
+        if characteristics := service_proxy.get_characteristics_by_uuid(
+            GATT_BODY_SENSOR_LOCATION_CHARACTERISTIC
+        ):
             self.body_sensor_location = DelegatedCharacteristicAdapter(
                 characteristics[0],
-                decode=lambda value: HeartRateService.BodySensorLocation(value[0])
+                decode=lambda value: HeartRateService.BodySensorLocation(value[0]),
             )
         else:
             self.body_sensor_location = None
 
-        if characteristics := service_proxy.get_characteristics_by_uuid(GATT_HEART_RATE_CONTROL_POINT_CHARACTERISTIC):
+        if characteristics := service_proxy.get_characteristics_by_uuid(
+            GATT_HEART_RATE_CONTROL_POINT_CHARACTERISTIC
+        ):
             self.heart_rate_control_point = PackedCharacteristicAdapter(
                 characteristics[0],
-                format=HeartRateService.HEART_RATE_CONTROL_POINT_FORMAT
+                pack_format=HeartRateService.HEART_RATE_CONTROL_POINT_FORMAT,
             )
         else:
             self.heart_rate_control_point = None
 
     async def reset_energy_expended(self):
         if self.heart_rate_control_point is not None:
-            return await self.heart_rate_control_point.write_value(HeartRateService.RESET_ENERGY_EXPENDED)
+            return await self.heart_rate_control_point.write_value(
+                HeartRateService.RESET_ENERGY_EXPENDED
+            )

bumble/profiles/le_audio.py

@@ -0,0 +1,83 @@
+# Copyright 2024 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# -----------------------------------------------------------------------------
+# Imports
+# -----------------------------------------------------------------------------
+from __future__ import annotations
+import dataclasses
+import struct
+from typing import List, Type
+from typing_extensions import Self
+
+from bumble import utils
+
+
+# -----------------------------------------------------------------------------
+# Classes
+# -----------------------------------------------------------------------------
+@dataclasses.dataclass
+class Metadata:
+    '''Bluetooth Assigned Numbers, Section 6.12.6 - Metadata LTV structures.
+
+    As Metadata fields may extend, and Spec doesn't forbid duplication, we don't parse
+    Metadata into a key-value style dataclass here. Rather, we encourage users to parse
+    again outside the lib.
+    '''
+
+    class Tag(utils.OpenIntEnum):
+        # fmt: off
+        PREFERRED_AUDIO_CONTEXTS                 = 0x01
+        STREAMING_AUDIO_CONTEXTS                 = 0x02
+        PROGRAM_INFO                             = 0x03
+        LANGUAGE                                 = 0x04
+        CCID_LIST                                = 0x05
+        PARENTAL_RATING                          = 0x06
+        PROGRAM_INFO_URI                         = 0x07
+        AUDIO_ACTIVE_STATE                       = 0x08
+        BROADCAST_AUDIO_IMMEDIATE_RENDERING_FLAG = 0x09
+        ASSISTED_LISTENING_STREAM                = 0x0A
+        BROADCAST_NAME                           = 0x0B
+        EXTENDED_METADATA                        = 0xFE
+        VENDOR_SPECIFIC                          = 0xFF
+
+    @dataclasses.dataclass
+    class Entry:
+        tag: Metadata.Tag
+        data: bytes
+
+        @classmethod
+        def from_bytes(cls: Type[Self], data: bytes) -> Self:
+            return cls(tag=Metadata.Tag(data[0]), data=data[1:])
+
+        def __bytes__(self) -> bytes:
+            return bytes([len(self.data) + 1, self.tag]) + self.data
+
+    entries: List[Entry] = dataclasses.field(default_factory=list)
+
+    @classmethod
+    def from_bytes(cls: Type[Self], data: bytes) -> Self:
+        entries = []
+        offset = 0
+        length = len(data)
+        while offset < length:
+            entry_length = data[offset]
+            offset += 1
+            entries.append(cls.Entry.from_bytes(data[offset : offset + entry_length]))
+            offset += entry_length
+
+        return cls(entries)
+
+    def __bytes__(self) -> bytes:
+        return b''.join([bytes(entry) for entry in self.entries])

bumble/profiles/mcp.py

@@ -0,0 +1,448 @@
+# 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 dataclasses
+import enum
+import struct
+
+from bumble import core
+from bumble import device
+from bumble import gatt
+from bumble import gatt_client
+from bumble import utils
+
+from typing import Type, Optional, ClassVar, Dict, TYPE_CHECKING
+from typing_extensions import Self
+
+# -----------------------------------------------------------------------------
+# Constants
+# -----------------------------------------------------------------------------
+
+
+class PlayingOrder(utils.OpenIntEnum):
+    '''See Media Control Service 3.15. Playing Order.'''
+
+    SINGLE_ONCE = 0x01
+    SINGLE_REPEAT = 0x02
+    IN_ORDER_ONCE = 0x03
+    IN_ORDER_REPEAT = 0x04
+    OLDEST_ONCE = 0x05
+    OLDEST_REPEAT = 0x06
+    NEWEST_ONCE = 0x07
+    NEWEST_REPEAT = 0x08
+    SHUFFLE_ONCE = 0x09
+    SHUFFLE_REPEAT = 0x0A
+
+
+class PlayingOrderSupported(enum.IntFlag):
+    '''See Media Control Service 3.16. Playing Orders Supported.'''
+
+    SINGLE_ONCE = 0x0001
+    SINGLE_REPEAT = 0x0002
+    IN_ORDER_ONCE = 0x0004
+    IN_ORDER_REPEAT = 0x0008
+    OLDEST_ONCE = 0x0010
+    OLDEST_REPEAT = 0x0020
+    NEWEST_ONCE = 0x0040
+    NEWEST_REPEAT = 0x0080
+    SHUFFLE_ONCE = 0x0100
+    SHUFFLE_REPEAT = 0x0200
+
+
+class MediaState(utils.OpenIntEnum):
+    '''See Media Control Service 3.17. Media State.'''
+
+    INACTIVE = 0x00
+    PLAYING = 0x01
+    PAUSED = 0x02
+    SEEKING = 0x03
+
+
+class MediaControlPointOpcode(utils.OpenIntEnum):
+    '''See Media Control Service 3.18. Media Control Point.'''
+
+    PLAY = 0x01
+    PAUSE = 0x02
+    FAST_REWIND = 0x03
+    FAST_FORWARD = 0x04
+    STOP = 0x05
+    MOVE_RELATIVE = 0x10
+    PREVIOUS_SEGMENT = 0x20
+    NEXT_SEGMENT = 0x21
+    FIRST_SEGMENT = 0x22
+    LAST_SEGMENT = 0x23
+    GOTO_SEGMENT = 0x24
+    PREVIOUS_TRACK = 0x30
+    NEXT_TRACK = 0x31
+    FIRST_TRACK = 0x32
+    LAST_TRACK = 0x33
+    GOTO_TRACK = 0x34
+    PREVIOUS_GROUP = 0x40
+    NEXT_GROUP = 0x41
+    FIRST_GROUP = 0x42
+    LAST_GROUP = 0x43
+    GOTO_GROUP = 0x44
+
+
+class MediaControlPointResultCode(enum.IntFlag):
+    '''See Media Control Service 3.18.2. Media Control Point Notification.'''
+
+    SUCCESS = 0x01
+    OPCODE_NOT_SUPPORTED = 0x02
+    MEDIA_PLAYER_INACTIVE = 0x03
+    COMMAND_CANNOT_BE_COMPLETED = 0x04
+
+
+class MediaControlPointOpcodeSupported(enum.IntFlag):
+    '''See Media Control Service 3.19. Media Control Point Opcodes Supported.'''
+
+    PLAY = 0x00000001
+    PAUSE = 0x00000002
+    FAST_REWIND = 0x00000004
+    FAST_FORWARD = 0x00000008
+    STOP = 0x00000010
+    MOVE_RELATIVE = 0x00000020
+    PREVIOUS_SEGMENT = 0x00000040
+    NEXT_SEGMENT = 0x00000080
+    FIRST_SEGMENT = 0x00000100
+    LAST_SEGMENT = 0x00000200
+    GOTO_SEGMENT = 0x00000400
+    PREVIOUS_TRACK = 0x00000800
+    NEXT_TRACK = 0x00001000
+    FIRST_TRACK = 0x00002000
+    LAST_TRACK = 0x00004000
+    GOTO_TRACK = 0x00008000
+    PREVIOUS_GROUP = 0x00010000
+    NEXT_GROUP = 0x00020000
+    FIRST_GROUP = 0x00040000
+    LAST_GROUP = 0x00080000
+    GOTO_GROUP = 0x00100000
+
+
+class SearchControlPointItemType(utils.OpenIntEnum):
+    '''See Media Control Service 3.20. Search Control Point.'''
+
+    TRACK_NAME = 0x01
+    ARTIST_NAME = 0x02
+    ALBUM_NAME = 0x03
+    GROUP_NAME = 0x04
+    EARLIEST_YEAR = 0x05
+    LATEST_YEAR = 0x06
+    GENRE = 0x07
+    ONLY_TRACKS = 0x08
+    ONLY_GROUPS = 0x09
+
+
+class ObjectType(utils.OpenIntEnum):
+    '''See Media Control Service 4.4.1. Object Type field.'''
+
+    TASK = 0
+    GROUP = 1
+
+
+# -----------------------------------------------------------------------------
+# Classes
+# -----------------------------------------------------------------------------
+
+
+class ObjectId(int):
+    '''See Media Control Service 4.4.2. Object ID field.'''
+
+    @classmethod
+    def create_from_bytes(cls: Type[Self], data: bytes) -> Self:
+        return cls(int.from_bytes(data, byteorder='little', signed=False))
+
+    def __bytes__(self) -> bytes:
+        return self.to_bytes(6, 'little')
+
+
+@dataclasses.dataclass
+class GroupObjectType:
+    '''See Media Control Service 4.4. Group Object Type.'''
+
+    object_type: ObjectType
+    object_id: ObjectId
+
+    @classmethod
+    def from_bytes(cls: Type[Self], data: bytes) -> Self:
+        return cls(
+            object_type=ObjectType(data[0]),
+            object_id=ObjectId.create_from_bytes(data[1:]),
+        )
+
+    def __bytes__(self) -> bytes:
+        return bytes([self.object_type]) + bytes(self.object_id)
+
+
+# -----------------------------------------------------------------------------
+# Server
+# -----------------------------------------------------------------------------
+class MediaControlService(gatt.TemplateService):
+    '''Media Control Service server implementation, only for testing currently.'''
+
+    UUID = gatt.GATT_MEDIA_CONTROL_SERVICE
+
+    def __init__(self, media_player_name: Optional[str] = None) -> None:
+        self.track_position = 0
+
+        self.media_player_name_characteristic = gatt.Characteristic(
+            uuid=gatt.GATT_MEDIA_PLAYER_NAME_CHARACTERISTIC,
+            properties=gatt.Characteristic.Properties.READ
+            | gatt.Characteristic.Properties.NOTIFY,
+            permissions=gatt.Characteristic.Permissions.READ_REQUIRES_ENCRYPTION,
+            value=media_player_name or 'Bumble Player',
+        )
+        self.track_changed_characteristic = gatt.Characteristic(
+            uuid=gatt.GATT_TRACK_CHANGED_CHARACTERISTIC,
+            properties=gatt.Characteristic.Properties.NOTIFY,
+            permissions=gatt.Characteristic.Permissions.READ_REQUIRES_ENCRYPTION,
+            value=b'',
+        )
+        self.track_title_characteristic = gatt.Characteristic(
+            uuid=gatt.GATT_TRACK_TITLE_CHARACTERISTIC,
+            properties=gatt.Characteristic.Properties.READ
+            | gatt.Characteristic.Properties.NOTIFY,
+            permissions=gatt.Characteristic.Permissions.READ_REQUIRES_ENCRYPTION,
+            value=b'',
+        )
+        self.track_duration_characteristic = gatt.Characteristic(
+            uuid=gatt.GATT_TRACK_DURATION_CHARACTERISTIC,
+            properties=gatt.Characteristic.Properties.READ
+            | gatt.Characteristic.Properties.NOTIFY,
+            permissions=gatt.Characteristic.Permissions.READ_REQUIRES_ENCRYPTION,
+            value=b'',
+        )
+        self.track_position_characteristic = gatt.Characteristic(
+            uuid=gatt.GATT_TRACK_POSITION_CHARACTERISTIC,
+            properties=gatt.Characteristic.Properties.READ
+            | gatt.Characteristic.Properties.WRITE
+            | gatt.Characteristic.Properties.WRITE_WITHOUT_RESPONSE
+            | gatt.Characteristic.Properties.NOTIFY,
+            permissions=gatt.Characteristic.Permissions.READ_REQUIRES_ENCRYPTION
+            | gatt.Characteristic.Permissions.WRITE_REQUIRES_ENCRYPTION,
+            value=b'',
+        )
+        self.media_state_characteristic = gatt.Characteristic(
+            uuid=gatt.GATT_MEDIA_STATE_CHARACTERISTIC,
+            properties=gatt.Characteristic.Properties.READ
+            | gatt.Characteristic.Properties.NOTIFY,
+            permissions=gatt.Characteristic.Permissions.READ_REQUIRES_ENCRYPTION,
+            value=b'',
+        )
+        self.media_control_point_characteristic = gatt.Characteristic(
+            uuid=gatt.GATT_MEDIA_CONTROL_POINT_CHARACTERISTIC,
+            properties=gatt.Characteristic.Properties.WRITE
+            | gatt.Characteristic.Properties.WRITE_WITHOUT_RESPONSE
+            | gatt.Characteristic.Properties.NOTIFY,
+            permissions=gatt.Characteristic.Permissions.READ_REQUIRES_ENCRYPTION
+            | gatt.Characteristic.Permissions.WRITE_REQUIRES_ENCRYPTION,
+            value=gatt.CharacteristicValue(write=self.on_media_control_point),
+        )
+        self.media_control_point_opcodes_supported_characteristic = gatt.Characteristic(
+            uuid=gatt.GATT_MEDIA_CONTROL_POINT_OPCODES_SUPPORTED_CHARACTERISTIC,
+            properties=gatt.Characteristic.Properties.READ
+            | gatt.Characteristic.Properties.NOTIFY,
+            permissions=gatt.Characteristic.Permissions.READ_REQUIRES_ENCRYPTION,
+            value=b'',
+        )
+        self.content_control_id_characteristic = gatt.Characteristic(
+            uuid=gatt.GATT_CONTENT_CONTROL_ID_CHARACTERISTIC,
+            properties=gatt.Characteristic.Properties.READ,
+            permissions=gatt.Characteristic.Permissions.READ_REQUIRES_ENCRYPTION,
+            value=b'',
+        )
+
+        super().__init__(
+            [
+                self.media_player_name_characteristic,
+                self.track_changed_characteristic,
+                self.track_title_characteristic,
+                self.track_duration_characteristic,
+                self.track_position_characteristic,
+                self.media_state_characteristic,
+                self.media_control_point_characteristic,
+                self.media_control_point_opcodes_supported_characteristic,
+                self.content_control_id_characteristic,
+            ]
+        )
+
+    async def on_media_control_point(
+        self, connection: Optional[device.Connection], data: bytes
+    ) -> None:
+        if not connection:
+            raise core.InvalidStateError()
+
+        opcode = MediaControlPointOpcode(data[0])
+
+        await connection.device.notify_subscriber(
+            connection,
+            self.media_control_point_characteristic,
+            value=bytes([opcode, MediaControlPointResultCode.SUCCESS]),
+        )
+
+
+class GenericMediaControlService(MediaControlService):
+    UUID = gatt.GATT_GENERIC_MEDIA_CONTROL_SERVICE
+
+
+# -----------------------------------------------------------------------------
+# Client
+# -----------------------------------------------------------------------------
+class MediaControlServiceProxy(
+    gatt_client.ProfileServiceProxy, utils.CompositeEventEmitter
+):
+    SERVICE_CLASS = MediaControlService
+
+    _CHARACTERISTICS: ClassVar[Dict[str, core.UUID]] = {
+        'media_player_name': gatt.GATT_MEDIA_PLAYER_NAME_CHARACTERISTIC,
+        'media_player_icon_object_id': gatt.GATT_MEDIA_PLAYER_ICON_OBJECT_ID_CHARACTERISTIC,
+        'media_player_icon_url': gatt.GATT_MEDIA_PLAYER_ICON_URL_CHARACTERISTIC,
+        'track_changed': gatt.GATT_TRACK_CHANGED_CHARACTERISTIC,
+        'track_title': gatt.GATT_TRACK_TITLE_CHARACTERISTIC,
+        'track_duration': gatt.GATT_TRACK_DURATION_CHARACTERISTIC,
+        'track_position': gatt.GATT_TRACK_POSITION_CHARACTERISTIC,
+        'playback_speed': gatt.GATT_PLAYBACK_SPEED_CHARACTERISTIC,
+        'seeking_speed': gatt.GATT_SEEKING_SPEED_CHARACTERISTIC,
+        'current_track_segments_object_id': gatt.GATT_CURRENT_TRACK_SEGMENTS_OBJECT_ID_CHARACTERISTIC,
+        'current_track_object_id': gatt.GATT_CURRENT_TRACK_OBJECT_ID_CHARACTERISTIC,
+        'next_track_object_id': gatt.GATT_NEXT_TRACK_OBJECT_ID_CHARACTERISTIC,
+        'parent_group_object_id': gatt.GATT_PARENT_GROUP_OBJECT_ID_CHARACTERISTIC,
+        'current_group_object_id': gatt.GATT_CURRENT_GROUP_OBJECT_ID_CHARACTERISTIC,
+        'playing_order': gatt.GATT_PLAYING_ORDER_CHARACTERISTIC,
+        'playing_orders_supported': gatt.GATT_PLAYING_ORDERS_SUPPORTED_CHARACTERISTIC,
+        'media_state': gatt.GATT_MEDIA_STATE_CHARACTERISTIC,
+        'media_control_point': gatt.GATT_MEDIA_CONTROL_POINT_CHARACTERISTIC,
+        'media_control_point_opcodes_supported': gatt.GATT_MEDIA_CONTROL_POINT_OPCODES_SUPPORTED_CHARACTERISTIC,
+        'search_control_point': gatt.GATT_SEARCH_CONTROL_POINT_CHARACTERISTIC,
+        'search_results_object_id': gatt.GATT_SEARCH_RESULTS_OBJECT_ID_CHARACTERISTIC,
+        'content_control_id': gatt.GATT_CONTENT_CONTROL_ID_CHARACTERISTIC,
+    }
+
+    media_player_name: Optional[gatt_client.CharacteristicProxy] = None
+    media_player_icon_object_id: Optional[gatt_client.CharacteristicProxy] = None
+    media_player_icon_url: Optional[gatt_client.CharacteristicProxy] = None
+    track_changed: Optional[gatt_client.CharacteristicProxy] = None
+    track_title: Optional[gatt_client.CharacteristicProxy] = None
+    track_duration: Optional[gatt_client.CharacteristicProxy] = None
+    track_position: Optional[gatt_client.CharacteristicProxy] = None
+    playback_speed: Optional[gatt_client.CharacteristicProxy] = None
+    seeking_speed: Optional[gatt_client.CharacteristicProxy] = None
+    current_track_segments_object_id: Optional[gatt_client.CharacteristicProxy] = None
+    current_track_object_id: Optional[gatt_client.CharacteristicProxy] = None
+    next_track_object_id: Optional[gatt_client.CharacteristicProxy] = None
+    parent_group_object_id: Optional[gatt_client.CharacteristicProxy] = None
+    current_group_object_id: Optional[gatt_client.CharacteristicProxy] = None
+    playing_order: Optional[gatt_client.CharacteristicProxy] = None
+    playing_orders_supported: Optional[gatt_client.CharacteristicProxy] = None
+    media_state: Optional[gatt_client.CharacteristicProxy] = None
+    media_control_point: Optional[gatt_client.CharacteristicProxy] = None
+    media_control_point_opcodes_supported: Optional[gatt_client.CharacteristicProxy] = (
+        None
+    )
+    search_control_point: Optional[gatt_client.CharacteristicProxy] = None
+    search_results_object_id: Optional[gatt_client.CharacteristicProxy] = None
+    content_control_id: Optional[gatt_client.CharacteristicProxy] = None
+
+    if TYPE_CHECKING:
+        media_control_point_notifications: asyncio.Queue[bytes]
+
+    def __init__(self, service_proxy: gatt_client.ServiceProxy) -> None:
+        utils.CompositeEventEmitter.__init__(self)
+        self.service_proxy = service_proxy
+        self.lock = asyncio.Lock()
+        self.media_control_point_notifications = asyncio.Queue()
+
+        for field, uuid in self._CHARACTERISTICS.items():
+            if characteristics := service_proxy.get_characteristics_by_uuid(uuid):
+                setattr(self, field, characteristics[0])
+
+    async def subscribe_characteristics(self) -> None:
+        if self.media_control_point:
+            await self.media_control_point.subscribe(self._on_media_control_point)
+        if self.media_state:
+            await self.media_state.subscribe(self._on_media_state)
+        if self.track_changed:
+            await self.track_changed.subscribe(self._on_track_changed)
+        if self.track_title:
+            await self.track_title.subscribe(self._on_track_title)
+        if self.track_duration:
+            await self.track_duration.subscribe(self._on_track_duration)
+        if self.track_position:
+            await self.track_position.subscribe(self._on_track_position)
+
+    async def write_control_point(
+        self, opcode: MediaControlPointOpcode
+    ) -> MediaControlPointResultCode:
+        '''Writes a Media Control Point Opcode to peer and waits for the notification.
+
+        The write operation will be executed when there isn't other pending commands.
+
+        Args:
+            opcode: opcode defined in `MediaControlPointOpcode`.
+
+        Returns:
+            Response code provided in `MediaControlPointResultCode`
+
+        Raises:
+            InvalidOperationError: Server does not have Media Control Point Characteristic.
+            InvalidStateError: Server replies a notification with mismatched opcode.
+        '''
+        if not self.media_control_point:
+            raise core.InvalidOperationError("Peer does not have media control point")
+
+        async with self.lock:
+            await self.media_control_point.write_value(
+                bytes([opcode]),
+                with_response=False,
+            )
+
+            (
+                response_opcode,
+                response_code,
+            ) = await self.media_control_point_notifications.get()
+            if response_opcode != opcode:
+                raise core.InvalidStateError(
+                    f"Expected {opcode} notification, but get {response_opcode}"
+                )
+            return MediaControlPointResultCode(response_code)
+
+    def _on_media_control_point(self, data: bytes) -> None:
+        self.media_control_point_notifications.put_nowait(data)
+
+    def _on_media_state(self, data: bytes) -> None:
+        self.emit('media_state', MediaState(data[0]))
+
+    def _on_track_changed(self, data: bytes) -> None:
+        del data
+        self.emit('track_changed')
+
+    def _on_track_title(self, data: bytes) -> None:
+        self.emit('track_title', data.decode("utf-8"))
+
+    def _on_track_duration(self, data: bytes) -> None:
+        self.emit('track_duration', struct.unpack_from('<i', data)[0])
+
+    def _on_track_position(self, data: bytes) -> None:
+        self.emit('track_position', struct.unpack_from('<i', data)[0])
+
+
+class GenericMediaControlServiceProxy(MediaControlServiceProxy):
+    SERVICE_CLASS = GenericMediaControlService

bumble/profiles/pacs.py

@@ -0,0 +1,210 @@
+# 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 - Published Audio Capabilities Service"""
+
+# -----------------------------------------------------------------------------
+# Imports
+# -----------------------------------------------------------------------------
+from __future__ import annotations
+import dataclasses
+import logging
+import struct
+from typing import Optional, Sequence, Union
+
+from bumble.profiles.bap import AudioLocation, CodecSpecificCapabilities, ContextType
+from bumble.profiles import le_audio
+from bumble import gatt
+from bumble import gatt_client
+from bumble import hci
+
+
+# -----------------------------------------------------------------------------
+# Logging
+# -----------------------------------------------------------------------------
+logger = logging.getLogger(__name__)
+
+
+# -----------------------------------------------------------------------------
+@dataclasses.dataclass
+class PacRecord:
+    '''Published Audio Capabilities Service, Table 3.2/3.4.'''
+
+    coding_format: hci.CodingFormat
+    codec_specific_capabilities: Union[CodecSpecificCapabilities, bytes]
+    metadata: le_audio.Metadata = dataclasses.field(default_factory=le_audio.Metadata)
+
+    @classmethod
+    def from_bytes(cls, data: bytes) -> PacRecord:
+        offset, coding_format = hci.CodingFormat.parse_from_bytes(data, 0)
+        codec_specific_capabilities_size = data[offset]
+
+        offset += 1
+        codec_specific_capabilities_bytes = data[
+            offset : offset + codec_specific_capabilities_size
+        ]
+        offset += codec_specific_capabilities_size
+        metadata_size = data[offset]
+        offset += 1
+        metadata = le_audio.Metadata.from_bytes(data[offset : offset + metadata_size])
+
+        codec_specific_capabilities: Union[CodecSpecificCapabilities, bytes]
+        if coding_format.codec_id == hci.CodecID.VENDOR_SPECIFIC:
+            codec_specific_capabilities = codec_specific_capabilities_bytes
+        else:
+            codec_specific_capabilities = CodecSpecificCapabilities.from_bytes(
+                codec_specific_capabilities_bytes
+            )
+
+        return PacRecord(
+            coding_format=coding_format,
+            codec_specific_capabilities=codec_specific_capabilities,
+            metadata=metadata,
+        )
+
+    def __bytes__(self) -> bytes:
+        capabilities_bytes = bytes(self.codec_specific_capabilities)
+        metadata_bytes = bytes(self.metadata)
+        return (
+            bytes(self.coding_format)
+            + bytes([len(capabilities_bytes)])
+            + capabilities_bytes
+            + bytes([len(metadata_bytes)])
+            + metadata_bytes
+        )
+
+
+# -----------------------------------------------------------------------------
+# Server
+# -----------------------------------------------------------------------------
+class PublishedAudioCapabilitiesService(gatt.TemplateService):
+    UUID = gatt.GATT_PUBLISHED_AUDIO_CAPABILITIES_SERVICE
+
+    sink_pac: Optional[gatt.Characteristic]
+    sink_audio_locations: Optional[gatt.Characteristic]
+    source_pac: Optional[gatt.Characteristic]
+    source_audio_locations: Optional[gatt.Characteristic]
+    available_audio_contexts: gatt.Characteristic
+    supported_audio_contexts: gatt.Characteristic
+
+    def __init__(
+        self,
+        supported_source_context: ContextType,
+        supported_sink_context: ContextType,
+        available_source_context: ContextType,
+        available_sink_context: ContextType,
+        sink_pac: Sequence[PacRecord] = (),
+        sink_audio_locations: Optional[AudioLocation] = None,
+        source_pac: Sequence[PacRecord] = (),
+        source_audio_locations: Optional[AudioLocation] = None,
+    ) -> None:
+        characteristics = []
+
+        self.supported_audio_contexts = gatt.Characteristic(
+            uuid=gatt.GATT_SUPPORTED_AUDIO_CONTEXTS_CHARACTERISTIC,
+            properties=gatt.Characteristic.Properties.READ,
+            permissions=gatt.Characteristic.Permissions.READABLE,
+            value=struct.pack('<HH', supported_sink_context, supported_source_context),
+        )
+        characteristics.append(self.supported_audio_contexts)
+
+        self.available_audio_contexts = gatt.Characteristic(
+            uuid=gatt.GATT_AVAILABLE_AUDIO_CONTEXTS_CHARACTERISTIC,
+            properties=gatt.Characteristic.Properties.READ
+            | gatt.Characteristic.Properties.NOTIFY,
+            permissions=gatt.Characteristic.Permissions.READABLE,
+            value=struct.pack('<HH', available_sink_context, available_source_context),
+        )
+        characteristics.append(self.available_audio_contexts)
+
+        if sink_pac:
+            self.sink_pac = gatt.Characteristic(
+                uuid=gatt.GATT_SINK_PAC_CHARACTERISTIC,
+                properties=gatt.Characteristic.Properties.READ,
+                permissions=gatt.Characteristic.Permissions.READABLE,
+                value=bytes([len(sink_pac)]) + b''.join(map(bytes, sink_pac)),
+            )
+            characteristics.append(self.sink_pac)
+
+        if sink_audio_locations is not None:
+            self.sink_audio_locations = gatt.Characteristic(
+                uuid=gatt.GATT_SINK_AUDIO_LOCATION_CHARACTERISTIC,
+                properties=gatt.Characteristic.Properties.READ,
+                permissions=gatt.Characteristic.Permissions.READABLE,
+                value=struct.pack('<I', sink_audio_locations),
+            )
+            characteristics.append(self.sink_audio_locations)
+
+        if source_pac:
+            self.source_pac = gatt.Characteristic(
+                uuid=gatt.GATT_SOURCE_PAC_CHARACTERISTIC,
+                properties=gatt.Characteristic.Properties.READ,
+                permissions=gatt.Characteristic.Permissions.READABLE,
+                value=bytes([len(source_pac)]) + b''.join(map(bytes, source_pac)),
+            )
+            characteristics.append(self.source_pac)
+
+        if source_audio_locations is not None:
+            self.source_audio_locations = gatt.Characteristic(
+                uuid=gatt.GATT_SOURCE_AUDIO_LOCATION_CHARACTERISTIC,
+                properties=gatt.Characteristic.Properties.READ,
+                permissions=gatt.Characteristic.Permissions.READABLE,
+                value=struct.pack('<I', source_audio_locations),
+            )
+            characteristics.append(self.source_audio_locations)
+
+        super().__init__(characteristics)
+
+
+# -----------------------------------------------------------------------------
+# Client
+# -----------------------------------------------------------------------------
+class PublishedAudioCapabilitiesServiceProxy(gatt_client.ProfileServiceProxy):
+    SERVICE_CLASS = PublishedAudioCapabilitiesService
+
+    sink_pac: Optional[gatt_client.CharacteristicProxy] = None
+    sink_audio_locations: Optional[gatt_client.CharacteristicProxy] = None
+    source_pac: Optional[gatt_client.CharacteristicProxy] = None
+    source_audio_locations: Optional[gatt_client.CharacteristicProxy] = None
+    available_audio_contexts: gatt_client.CharacteristicProxy
+    supported_audio_contexts: gatt_client.CharacteristicProxy
+
+    def __init__(self, service_proxy: gatt_client.ServiceProxy):
+        self.service_proxy = service_proxy
+
+        self.available_audio_contexts = service_proxy.get_characteristics_by_uuid(
+            gatt.GATT_AVAILABLE_AUDIO_CONTEXTS_CHARACTERISTIC
+        )[0]
+        self.supported_audio_contexts = service_proxy.get_characteristics_by_uuid(
+            gatt.GATT_SUPPORTED_AUDIO_CONTEXTS_CHARACTERISTIC
+        )[0]
+
+        if characteristics := service_proxy.get_characteristics_by_uuid(
+            gatt.GATT_SINK_PAC_CHARACTERISTIC
+        ):
+            self.sink_pac = characteristics[0]
+
+        if characteristics := service_proxy.get_characteristics_by_uuid(
+            gatt.GATT_SOURCE_PAC_CHARACTERISTIC
+        ):
+            self.source_pac = characteristics[0]
+
+        if characteristics := service_proxy.get_characteristics_by_uuid(
+            gatt.GATT_SINK_AUDIO_LOCATION_CHARACTERISTIC
+        ):
+            self.sink_audio_locations = characteristics[0]
+
+        if characteristics := service_proxy.get_characteristics_by_uuid(
+            gatt.GATT_SOURCE_AUDIO_LOCATION_CHARACTERISTIC
+        ):
+            self.source_audio_locations = characteristics[0]

bumble/profiles/pbp.py

@@ -0,0 +1,46 @@
+# Copyright 2024 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# -----------------------------------------------------------------------------
+# Imports
+# -----------------------------------------------------------------------------
+from __future__ import annotations
+import dataclasses
+import enum
+from typing_extensions import Self
+
+from bumble.profiles import le_audio
+
+
+# -----------------------------------------------------------------------------
+# Classes
+# -----------------------------------------------------------------------------
+@dataclasses.dataclass
+class PublicBroadcastAnnouncement:
+    class Features(enum.IntFlag):
+        ENCRYPTED = 1 << 0
+        STANDARD_QUALITY_CONFIGURATION = 1 << 1
+        HIGH_QUALITY_CONFIGURATION = 1 << 2
+
+    features: Features
+    metadata: le_audio.Metadata
+
+    @classmethod
+    def from_bytes(cls, data: bytes) -> Self:
+        features = cls.Features(data[0])
+        metadata_length = data[1]
+        metadata_ltv = data[1 : 1 + metadata_length]
+        return cls(
+            features=features, metadata=le_audio.Metadata.from_bytes(metadata_ltv)
+        )

bumble/profiles/tmap.py

@@ -0,0 +1,89 @@
+# 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.
+
+"""LE Audio - Telephony and Media Audio Profile"""
+
+# -----------------------------------------------------------------------------
+# Imports
+# -----------------------------------------------------------------------------
+import enum
+import logging
+import struct
+
+from bumble.gatt import (
+    TemplateService,
+    Characteristic,
+    DelegatedCharacteristicAdapter,
+    InvalidServiceError,
+    GATT_TELEPHONY_AND_MEDIA_AUDIO_SERVICE,
+    GATT_TMAP_ROLE_CHARACTERISTIC,
+)
+from bumble.gatt_client import ProfileServiceProxy, ServiceProxy
+
+
+# -----------------------------------------------------------------------------
+# Logging
+# -----------------------------------------------------------------------------
+logger = logging.getLogger(__name__)
+
+
+# -----------------------------------------------------------------------------
+# Classes
+# -----------------------------------------------------------------------------
+class Role(enum.IntFlag):
+    CALL_GATEWAY = 1 << 0
+    CALL_TERMINAL = 1 << 1
+    UNICAST_MEDIA_SENDER = 1 << 2
+    UNICAST_MEDIA_RECEIVER = 1 << 3
+    BROADCAST_MEDIA_SENDER = 1 << 4
+    BROADCAST_MEDIA_RECEIVER = 1 << 5
+
+
+# -----------------------------------------------------------------------------
+class TelephonyAndMediaAudioService(TemplateService):
+    UUID = GATT_TELEPHONY_AND_MEDIA_AUDIO_SERVICE
+
+    def __init__(self, role: Role):
+        self.role_characteristic = Characteristic(
+            GATT_TMAP_ROLE_CHARACTERISTIC,
+            Characteristic.Properties.READ,
+            Characteristic.READABLE,
+            struct.pack('<H', int(role)),
+        )
+
+        super().__init__([self.role_characteristic])
+
+
+# -----------------------------------------------------------------------------
+class TelephonyAndMediaAudioServiceProxy(ProfileServiceProxy):
+    SERVICE_CLASS = TelephonyAndMediaAudioService
+
+    role: DelegatedCharacteristicAdapter
+
+    def __init__(self, service_proxy: ServiceProxy):
+        self.service_proxy = service_proxy
+
+        if not (
+            characteristics := service_proxy.get_characteristics_by_uuid(
+                GATT_TMAP_ROLE_CHARACTERISTIC
+            )
+        ):
+            raise InvalidServiceError('TMAP Role characteristic not found')
+
+        self.role = DelegatedCharacteristicAdapter(
+            characteristics[0],
+            decode=lambda value: Role(
+                struct.unpack_from('<H', value, 0)[0],
+            ),
+        )