make cryptography a valid dependency for emscripten targets

run pre-commit tests with all supported Python versions

.github/workflows/code-check.yml

@@ -14,6 +14,10 @@ jobs:
   check:
     name: Check Code
     runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.8", "3.9", "3.10", "3.11"]
+      fail-fast: false
 
     steps:
     - name: Check out from Git

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

@@ -12,11 +12,11 @@ permissions:
 
 jobs:
   build:
-
-    runs-on: ubuntu-latest
+    runs-on: ${{ matrix.os }}
     strategy:
       matrix:
-        python-version: ["3.8", "3.9", "3.10"]
+        os: ['ubuntu-latest', 'macos-latest', 'windows-latest']
+        python-version: ["3.8", "3.9", "3.10", "3.11"]
       fail-fast: false
 
     steps:
@@ -41,3 +41,38 @@ jobs:
       run: |
         inv build
         inv build.mkdocs
+
+  build-rust:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: [ "3.8", "3.9", "3.10", "3.11" ]
+        rust-version: [ "1.70.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 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: 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
+      # 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

@@ -9,3 +9,4 @@ __pycache__
 # generated by setuptools_scm
 bumble/_version.py
 .vscode/launch.json
+/.idea

LICENSE

@@ -200,3 +200,22 @@
    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.
+
+
+---
+
+
+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.

apps/console.py

@@ -24,9 +24,12 @@ import logging
 import os
 import random
 import re
+import humanize
+from typing import Optional, Union
 from collections import OrderedDict
 
 import click
+from prettytable import PrettyTable
 
 from prompt_toolkit import Application
 from prompt_toolkit.history import FileHistory
@@ -58,6 +61,7 @@ from bumble.device import ConnectionParametersPreferences, Device, Connection, P
 from bumble.utils import AsyncRunner
 from bumble.transport import open_transport_or_link
 from bumble.gatt import Characteristic, Service, CharacteristicDeclaration, Descriptor
+from bumble.gatt_client import CharacteristicProxy
 from bumble.hci import (
     HCI_Constant,
     HCI_LE_1M_PHY,
@@ -119,9 +123,12 @@ def parse_phys(phys):
 # Console App
 # -----------------------------------------------------------------------------
 class ConsoleApp:
+    connected_peer: Optional[Peer]
+
     def __init__(self):
         self.known_addresses = set()
-        self.known_attributes = []
+        self.known_remote_attributes = []
+        self.known_local_attributes = []
         self.device = None
         self.connected_peer = None
         self.top_tab = 'device'
@@ -158,6 +165,8 @@ class ConsoleApp:
                         'device': None,
                         'local-services': None,
                         'remote-services': None,
+                        'local-values': None,
+                        'remote-values': None,
                     },
                     'filter': {
                         'address': None,
@@ -168,10 +177,11 @@ class ConsoleApp:
                     'disconnect': None,
                     'discover': {'services': None, 'attributes': None},
                     'request-mtu': None,
-                    'read': LiveCompleter(self.known_attributes),
-                    'write': LiveCompleter(self.known_attributes),
-                    'subscribe': LiveCompleter(self.known_attributes),
-                    'unsubscribe': LiveCompleter(self.known_attributes),
+                    'read': LiveCompleter(self.known_remote_attributes),
+                    'write': LiveCompleter(self.known_remote_attributes),
+                    'local-write': LiveCompleter(self.known_local_attributes),
+                    'subscribe': LiveCompleter(self.known_remote_attributes),
+                    'unsubscribe': LiveCompleter(self.known_remote_attributes),
                     'set-phy': {'1m': None, '2m': None, 'coded': None},
                     'set-default-phy': None,
                     'quit': None,
@@ -203,6 +213,8 @@ class ConsoleApp:
         self.log_text = FormattedTextControl(
             get_cursor_position=lambda: Point(0, max(0, len(self.log_lines) - 1))
         )
+        self.local_values_text = FormattedTextControl()
+        self.remote_values_text = FormattedTextControl()
         self.log_height = Dimension(min=7, weight=4)
         self.log_max_lines = 100
         self.log_lines = []
@@ -218,9 +230,17 @@ class ConsoleApp:
                     filter=Condition(lambda: self.top_tab == 'local-services'),
                 ),
                 ConditionalContainer(
-                    Frame(Window(self.remote_services_text), title='Remove Services'),
+                    Frame(Window(self.local_values_text), title='Local Values'),
+                    filter=Condition(lambda: self.top_tab == 'local-values'),
+                ),
+                ConditionalContainer(
+                    Frame(Window(self.remote_services_text), title='Remote Services'),
                     filter=Condition(lambda: self.top_tab == 'remote-services'),
                 ),
+                ConditionalContainer(
+                    Frame(Window(self.remote_values_text), title='Remote Values'),
+                    filter=Condition(lambda: self.top_tab == 'remote-values'),
+                ),
                 ConditionalContainer(
                     Frame(Window(self.log_text, height=self.log_height), title='Log'),
                     filter=Condition(lambda: self.top_tab == 'log'),
@@ -362,17 +382,19 @@ class ConsoleApp:
 
     def show_remote_services(self, services):
         lines = []
-        del self.known_attributes[:]
+        del self.known_remote_attributes[:]
         for service in services:
             lines.append(("ansicyan", f"{service}\n"))
 
             for characteristic in service.characteristics:
                 lines.append(('ansimagenta', f'  {characteristic} + \n'))
-                self.known_attributes.append(
+                self.known_remote_attributes.append(
                     f'{service.uuid.to_hex_str()}.{characteristic.uuid.to_hex_str()}'
                 )
-                self.known_attributes.append(f'*.{characteristic.uuid.to_hex_str()}')
-                self.known_attributes.append(f'#{characteristic.handle:X}')
+                self.known_remote_attributes.append(
+                    f'*.{characteristic.uuid.to_hex_str()}'
+                )
+                self.known_remote_attributes.append(f'#{characteristic.handle:X}')
                 for descriptor in characteristic.descriptors:
                     lines.append(("ansigreen", f"    {descriptor}\n"))
 
@@ -381,12 +403,31 @@ class ConsoleApp:
 
     def show_local_services(self, attributes):
         lines = []
+        del self.known_local_attributes[:]
         for attribute in attributes:
             if isinstance(attribute, Service):
+                # Save the most recent service for use later
+                service = attribute
                 lines.append(("ansicyan", f"{attribute}\n"))
-            elif isinstance(attribute, (Characteristic, CharacteristicDeclaration)):
+            elif isinstance(attribute, Characteristic):
+                # CharacteristicDeclaration includes all info from Characteristic
+                # no need to print it twice
+                continue
+            elif isinstance(attribute, CharacteristicDeclaration):
+                # Save the most recent characteristic declaration for use later
+                characteristic_declaration = attribute
+                self.known_local_attributes.append(
+                    f'{service.uuid.to_hex_str()}.{attribute.characteristic.uuid.to_hex_str()}'
+                )
+                self.known_local_attributes.append(
+                    f'#{attribute.characteristic.handle:X}'
+                )
                 lines.append(("ansimagenta", f"  {attribute}\n"))
             elif isinstance(attribute, Descriptor):
+                self.known_local_attributes.append(
+                    f'{service.uuid.to_hex_str()}.{characteristic_declaration.characteristic.uuid.to_hex_str()}.{attribute.type.to_hex_str()}'
+                )
+                self.known_local_attributes.append(f'#{attribute.handle:X}')
                 lines.append(("ansigreen", f"    {attribute}\n"))
             else:
                 lines.append(("ansiyellow", f"{attribute}\n"))
@@ -490,7 +531,9 @@ class ConsoleApp:
 
         self.show_attributes(attributes)
 
-    def find_characteristic(self, param):
+    def find_remote_characteristic(self, param) -> Optional[CharacteristicProxy]:
+        if not self.connected_peer:
+            return None
         parts = param.split('.')
         if len(parts) == 2:
             service_uuid = UUID(parts[0]) if parts[0] != '*' else None
@@ -510,6 +553,38 @@ class ConsoleApp:
 
         return None
 
+    def find_local_attribute(
+        self, param
+    ) -> Optional[Union[Characteristic, Descriptor]]:
+        parts = param.split('.')
+        if len(parts) == 3:
+            service_uuid = UUID(parts[0])
+            characteristic_uuid = UUID(parts[1])
+            descriptor_uuid = UUID(parts[2])
+            return self.device.gatt_server.get_descriptor_attribute(
+                service_uuid, characteristic_uuid, descriptor_uuid
+            )
+        if len(parts) == 2:
+            service_uuid = UUID(parts[0])
+            characteristic_uuid = UUID(parts[1])
+            characteristic_attributes = (
+                self.device.gatt_server.get_characteristic_attributes(
+                    service_uuid, characteristic_uuid
+                )
+            )
+            if characteristic_attributes:
+                return characteristic_attributes[1]
+            return None
+        elif len(parts) == 1:
+            if parts[0].startswith('#'):
+                attribute_handle = int(f'{parts[0][1:]}', 16)
+                attribute = self.device.gatt_server.get_attribute(attribute_handle)
+                if isinstance(attribute, (Characteristic, Descriptor)):
+                    return attribute
+                return None
+
+        return None
+
     async def rssi_monitor_loop(self):
         while True:
             if self.monitor_rssi and self.connected_peer:
@@ -668,10 +743,109 @@ class ConsoleApp:
                 'device',
                 'local-services',
                 'remote-services',
+                'local-values',
+                'remote-values',
             }:
                 self.top_tab = params[0]
                 self.ui.invalidate()
 
+        while self.top_tab == 'local-values':
+            await self.do_show_local_values()
+            await asyncio.sleep(1)
+
+        while self.top_tab == 'remote-values':
+            await self.do_show_remote_values()
+            await asyncio.sleep(1)
+
+    async def do_show_local_values(self):
+        prettytable = PrettyTable()
+        field_names = ["Service", "Characteristic", "Descriptor"]
+
+        # if there's no connections, add a column just for value
+        if not self.device.connections:
+            field_names.append("Value")
+
+        # if there are connections, add a column for each connection's value
+        for connection in self.device.connections.values():
+            field_names.append(f"Connection {connection.handle}")
+
+        for attribute in self.device.gatt_server.attributes:
+            if isinstance(attribute, Characteristic):
+                service = self.device.gatt_server.get_attribute_group(
+                    attribute.handle, Service
+                )
+                if not service:
+                    continue
+                values = [
+                    attribute.read_value(connection)
+                    for connection in self.device.connections.values()
+                ]
+                if not values:
+                    values = [attribute.read_value(None)]
+                prettytable.add_row([f"{service.uuid}", attribute.uuid, ""] + values)
+
+            elif isinstance(attribute, Descriptor):
+                service = self.device.gatt_server.get_attribute_group(
+                    attribute.handle, Service
+                )
+                if not service:
+                    continue
+                characteristic = self.device.gatt_server.get_attribute_group(
+                    attribute.handle, Characteristic
+                )
+                if not characteristic:
+                    continue
+                values = [
+                    attribute.read_value(connection)
+                    for connection in self.device.connections.values()
+                ]
+                if not values:
+                    values = [attribute.read_value(None)]
+
+                # TODO: future optimization: convert CCCD value to human readable string
+
+                prettytable.add_row(
+                    [service.uuid, characteristic.uuid, attribute.type] + values
+                )
+
+        prettytable.field_names = field_names
+        self.local_values_text.text = prettytable.get_string()
+        self.ui.invalidate()
+
+    async def do_show_remote_values(self):
+        prettytable = PrettyTable(
+            field_names=[
+                "Connection",
+                "Service",
+                "Characteristic",
+                "Descriptor",
+                "Time",
+                "Value",
+            ]
+        )
+        for connection in self.device.connections.values():
+            for handle, (time, value) in connection.gatt_client.cached_values.items():
+                row = [connection.handle]
+                attribute = connection.gatt_client.get_attributes(handle)
+                if not attribute:
+                    continue
+                if len(attribute) == 3:
+                    row.extend(
+                        [attribute[0].uuid, attribute[1].uuid, attribute[2].type]
+                    )
+                elif len(attribute) == 2:
+                    row.extend([attribute[0].uuid, attribute[1].uuid, ""])
+                elif len(attribute) == 1:
+                    row.extend([attribute[0].uuid, "", ""])
+                else:
+                    continue
+
+                row.extend([humanize.naturaltime(time), value])
+                prettytable.add_row(row)
+
+        self.remote_values_text.text = prettytable.get_string()
+        self.ui.invalidate()
+
     async def do_get_phy(self, _):
         if not self.connected_peer:
             self.show_error('not connected')
@@ -714,7 +888,7 @@ class ConsoleApp:
             self.show_error('not connected')
             return
 
-        characteristic = self.find_characteristic(params[0])
+        characteristic = self.find_remote_characteristic(params[0])
         if characteristic is None:
             self.show_error('no such characteristic')
             return
@@ -739,15 +913,43 @@ class ConsoleApp:
             except ValueError:
                 value = str.encode(params[1])  # must be a string
 
-        characteristic = self.find_characteristic(params[0])
+        characteristic = self.find_remote_characteristic(params[0])
         if characteristic is None:
             self.show_error('no such characteristic')
             return
 
         # use write with response if supported
-        with_response = characteristic.properties & Characteristic.WRITE
+        with_response = characteristic.properties & Characteristic.Properties.WRITE
         await characteristic.write_value(value, with_response=with_response)
 
+    async def do_local_write(self, params):
+        if len(params) != 2:
+            self.show_error(
+                'invalid syntax', 'expected local-write <attribute> <value>'
+            )
+            return
+
+        if params[1].upper().startswith("0X"):
+            value = bytes.fromhex(params[1][2:])  # parse as hex string
+        else:
+            try:
+                value = int(params[1]).to_bytes(2, "little")  # try as 2 byte integer
+            except ValueError:
+                value = str.encode(params[1])  # must be a string
+
+        attribute = self.find_local_attribute(params[0])
+        if not attribute:
+            self.show_error('invalid syntax', 'unable to find attribute')
+            return
+
+        # send data to any subscribers
+        if isinstance(attribute, Characteristic):
+            attribute.write_value(None, value)
+            if attribute.has_properties(Characteristic.NOTIFY):
+                await self.device.gatt_server.notify_subscribers(attribute)
+            if attribute.has_properties(Characteristic.INDICATE):
+                await self.device.gatt_server.indicate_subscribers(attribute)
+
     async def do_subscribe(self, params):
         if not self.connected_peer:
             self.show_error('not connected')
@@ -757,7 +959,7 @@ class ConsoleApp:
             self.show_error('invalid syntax', 'expected subscribe <attribute>')
             return
 
-        characteristic = self.find_characteristic(params[0])
+        characteristic = self.find_remote_characteristic(params[0])
         if characteristic is None:
             self.show_error('no such characteristic')
             return
@@ -777,7 +979,7 @@ class ConsoleApp:
             self.show_error('invalid syntax', 'expected subscribe <attribute>')
             return
 
-        characteristic = self.find_characteristic(params[0])
+        characteristic = self.find_remote_characteristic(params[0])
         if characteristic is None:
             self.show_error('no such characteristic')
             return

apps/controller_info.py

@@ -30,6 +30,8 @@ from bumble.hci import (
     HCI_VERSION_NAMES,
     LMP_VERSION_NAMES,
     HCI_Command,
+    HCI_Command_Complete_Event,
+    HCI_Command_Status_Event,
     HCI_READ_BD_ADDR_COMMAND,
     HCI_Read_BD_ADDR_Command,
     HCI_READ_LOCAL_NAME_COMMAND,
@@ -45,11 +47,20 @@ from bumble.host import Host
 from bumble.transport import open_transport_or_link
 
 
+# -----------------------------------------------------------------------------
+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):
     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
@@ -57,7 +68,7 @@ async def get_classic_info(host):
 
     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'),
@@ -73,7 +84,7 @@ async def get_le_info(host):
         response = await host.send_command(
             HCI_LE_Read_Number_Of_Supported_Advertising_Sets_Command()
         )
-        if response.return_parameters.status == HCI_SUCCESS:
+        if command_succeeded(response):
             print(
                 color('LE Number Of Supported Advertising Sets:', 'yellow'),
                 response.return_parameters.num_supported_advertising_sets,
@@ -84,7 +95,7 @@ async def get_le_info(host):
         response = await host.send_command(
             HCI_LE_Read_Maximum_Advertising_Data_Length_Command()
         )
-        if response.return_parameters.status == HCI_SUCCESS:
+        if command_succeeded(response):
             print(
                 color('LE Maximum Advertising Data Length:', 'yellow'),
                 response.return_parameters.max_advertising_data_length,
@@ -93,7 +104,7 @@ async def get_le_info(host):
 
     if host.supports_command(HCI_LE_READ_MAXIMUM_DATA_LENGTH_COMMAND):
         response = await host.send_command(HCI_LE_Read_Maximum_Data_Length_Command())
-        if response.return_parameters.status == HCI_SUCCESS:
+        if command_succeeded(response):
             print(
                 color('Maximum Data Length:', 'yellow'),
                 (

apps/gg_bridge.py

@@ -230,13 +230,13 @@ class GattlinkNodeBridge(GattlinkL2capEndpoint, Device.Listener):
         )
         self.tx_characteristic = Characteristic(
             GG_GATTLINK_TX_CHARACTERISTIC_UUID,
-            Characteristic.NOTIFY,
+            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.READ | Characteristic.NOTIFY,
+            Characteristic.Properties.READ | Characteristic.Properties.NOTIFY,
             Characteristic.READABLE,
             bytes([psm, 0]),
         )
@@ -339,8 +339,7 @@ async def run(
 
         # Create a UDP to TX bridge (receive from TX, send to UDP)
         bridge.tx_socket, _ = await loop.create_datagram_endpoint(
-            # pylint: disable-next=unnecessary-lambda
-            lambda: asyncio.DatagramProtocol(),
+            asyncio.DatagramProtocol,
             remote_addr=(send_host, send_port),
         )
 

apps/l2cap_bridge.py

@@ -105,7 +105,7 @@ class ServerBridge:
                             asyncio.create_task(self.pipe.l2cap_channel.disconnect())
 
                     def data_received(self, data):
-                        print(f'<<< Received on TCP: {len(data)}')
+                        print(color(f'<<< [TCP DATA]: {len(data)} bytes', 'blue'))
                         self.pipe.l2cap_channel.write(data)
 
                 try:
@@ -123,6 +123,7 @@ class ServerBridge:
                     await self.l2cap_channel.disconnect()
 
             def on_l2cap_close(self):
+                print(color('*** L2CAP channel closed', 'red'))
                 self.l2cap_channel = None
                 if self.tcp_transport is not None:
                     self.tcp_transport.close()

apps/pair.py

@@ -24,7 +24,7 @@ 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 PairingDelegate, PairingConfig
 from bumble.smp import error_name as smp_error_name
 from bumble.keys import JsonKeyStore
 from bumble.core import ProtocolError
@@ -157,6 +157,26 @@ class Delegate(PairingDelegate):
         self.print(f'### PIN: {number:0{digits}}')
         self.print('###-----------------------------------')
 
+    async def get_string(self, max_length: int):
+        await self.update_peer_name()
+
+        # Prompt a PIN (for legacy pairing in classic)
+        self.print('###-----------------------------------')
+        self.print(f'### Pairing with {self.peer_name}')
+        self.print('###-----------------------------------')
+        count = 0
+        while True:
+            response = await self.prompt('>>> Enter PIN (1-6 chars):')
+            if len(response) == 0:
+                count += 1
+                if count > 3:
+                    self.print('too many tries, stopping the pairing')
+                    return None
+
+                self.print('no PIN was entered, try again')
+                continue
+            return response
+
 
 # -----------------------------------------------------------------------------
 async def get_peer_name(peer, mode):
@@ -207,7 +227,7 @@ def on_connection(connection, request):
 
     # Listen for pairing events
     connection.on('pairing_start', on_pairing_start)
-    connection.on('pairing', on_pairing)
+    connection.on('pairing', lambda keys: on_pairing(connection.peer_address, keys))
     connection.on('pairing_failure', on_pairing_failure)
 
     # Listen for encryption changes
@@ -242,9 +262,9 @@ def on_pairing_start():
 
 
 # -----------------------------------------------------------------------------
-def on_pairing(keys):
+def on_pairing(address, keys):
     print(color('***-----------------------------------', 'cyan'))
-    print(color('*** Paired!', 'cyan'))
+    print(color(f'*** Paired! (peer identity={address})', 'cyan'))
     keys.print(prefix=color('*** ', 'cyan'))
     print(color('***-----------------------------------', 'cyan'))
     Waiter.instance.terminate()
@@ -264,6 +284,7 @@ async def pair(
     sc,
     mitm,
     bond,
+    ctkd,
     io,
     prompt,
     request,
@@ -282,17 +303,6 @@ async def pair(
         # Create a device to manage the host
         device = Device.from_config_file_with_hci(device_config, hci_source, hci_sink)
 
-        # Set a custom keystore if specified on the command line
-        if keystore_file:
-            device.keystore = JsonKeyStore(namespace=None, filename=keystore_file)
-
-        # Print the existing keys before pairing
-        if print_keys and device.keystore:
-            print(color('@@@-----------------------------------', 'blue'))
-            print(color('@@@ Pairing Keys:', 'blue'))
-            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':
@@ -302,7 +312,8 @@ async def pair(
                     [
                         Characteristic(
                             '552957FB-CF1F-4A31-9535-E78847E1A714',
-                            Characteristic.READ | Characteristic.WRITE,
+                            Characteristic.Properties.READ
+                            | Characteristic.Properties.WRITE,
                             Characteristic.READABLE | Characteristic.WRITEABLE,
                             CharacteristicValue(
                                 read=read_with_error, write=write_with_error
@@ -316,10 +327,22 @@ async def pair(
         if mode == 'classic':
             device.classic_enabled = True
             device.le_enabled = False
+            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.from_device(device, filename=keystore_file)
+
+        # Print the existing keys before pairing
+        if print_keys and device.keystore:
+            print(color('@@@-----------------------------------', 'blue'))
+            print(color('@@@ Pairing Keys:', 'blue'))
+            await device.keystore.print(prefix=color('@@@ ', 'blue'))
+            print(color('@@@-----------------------------------', 'blue'))
+
         # Set up a pairing config factory
         device.pairing_config_factory = lambda connection: PairingConfig(
             sc, mitm, bond, Delegate(mode, connection, io, prompt)
@@ -342,8 +365,13 @@ async def pair(
                     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)
+            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()
@@ -378,6 +406,13 @@ class LogHandler(logging.Handler):
 @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(
     '--io',
     type=click.Choice(
@@ -404,6 +439,7 @@ def main(
     sc,
     mitm,
     bond,
+    ctkd,
     io,
     prompt,
     request,
@@ -426,6 +462,7 @@ def main(
             sc,
             mitm,
             bond,
+            ctkd,
             io,
             prompt,
             request,

apps/pandora_server.py

@@ -0,0 +1,49 @@
+import asyncio
+import click
+import logging
+import json
+
+from bumble.pandora import PandoraDevice, 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)
+    if 'transport' not in bumble_config.keys():
+        bumble_config.update({'transport': transport})
+    device = PandoraDevice(bumble_config)
+
+    logging.basicConfig(level=logging.DEBUG)
+    asyncio.run(serve(device, 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/scan.py

@@ -133,15 +133,16 @@ async def scan(
                 '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:
+            resolver = None
 
         printer = AdvertisementPrinter(min_rssi, resolver)
         if raw:
@@ -149,8 +150,6 @@ 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:

apps/show.py

@@ -102,9 +102,21 @@ class SnoopPacketReader:
     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')
 # pylint: disable=redefined-builtin
-def main(format, filename):
+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)
@@ -124,7 +136,6 @@ def main(format, filename):
             if packet is None:
                 break
             tracer.trace(hci.HCI_Packet.from_bytes(packet), direction)
-
         except Exception as error:
             print(color(f'!!! {error}', 'red'))
 

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,737 @@
+# 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,
+    MediaPacket,
+    Protocol,
+)
+from bumble.a2dp import (
+    MPEG_2_AAC_LC_OBJECT_TYPE,
+    make_audio_sink_service_sdp_records,
+    A2DP_SBC_CODEC_TYPE,
+    A2DP_MPEG_2_4_AAC_CODEC_TYPE,
+    SBC_MONO_CHANNEL_MODE,
+    SBC_DUAL_CHANNEL_MODE,
+    SBC_SNR_ALLOCATION_METHOD,
+    SBC_LOUDNESS_ALLOCATION_METHOD,
+    SBC_STEREO_CHANNEL_MODE,
+    SBC_JOINT_STEREO_CHANNEL_MODE,
+    SbcMediaCodecInformation,
+    AacMediaCodecInformation,
+)
+from bumble.utils import AsyncRunner
+from bumble.codecs import AacAudioRtpPacket
+
+
+# -----------------------------------------------------------------------------
+# 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(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 = str(connection.peer_address).replace('/P', '')
+        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=str(connection.peer_address).replace('/P', ''),
+                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.from_lists(
+                object_types=[MPEG_2_AAC_LC_OBJECT_TYPE],
+                sampling_frequencies=[48000, 44100],
+                channels=[1, 2],
+                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.from_lists(
+                sampling_frequencies=[48000, 44100, 32000, 16000],
+                channel_modes=[
+                    SBC_MONO_CHANNEL_MODE,
+                    SBC_DUAL_CHANNEL_MODE,
+                    SBC_STEREO_CHANNEL_MODE,
+                    SBC_JOINT_STEREO_CHANNEL_MODE,
+                ],
+                block_lengths=[4, 8, 12, 16],
+                subbands=[4, 8],
+                allocation_methods=[
+                    SBC_LOUDNESS_ALLOCATION_METHOD,
+                    SBC_SNR_ALLOCATION_METHOD,
+                ],
+                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(Listener.create_registrar(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,58 @@ import click
 
 from bumble.device import Device
 from bumble.keys import JsonKeyStore
+from bumble.transport import open_transport
+
+# -----------------------------------------------------------------------------
+async def unbond_with_keystore(keystore, address):
+    if address is None:
+        return await keystore.print()
+
+    try:
+        await keystore.delete(address)
+    except KeyError:
+        print('!!! pairing not found')
 
 
 # -----------------------------------------------------------------------------
-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
+async def unbond(keystore_file, device_config, hci_transport, address):
+    # With a keystore file, we can instantiate the keystore directly
     if keystore_file:
-        keystore = JsonKeyStore(None, keystore_file)
-    else:
-        keystore = device.keystore
+        return await unbond_with_keystore(JsonKeyStore(None, keystore_file), address)
 
-    if keystore is None:
-        print('no keystore')
-        return
+    # 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)
 
-    if address is None:
-        await keystore.print()
-    else:
-        try:
-            await keystore.delete(address)
-        except KeyError:
-            print('!!! pairing not found')
+        # 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):
+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())
-    asyncio.run(unbond(keystore_file, device_config, address))
+
+    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))
 
 
 # -----------------------------------------------------------------------------

bumble/a2dp.py

@@ -432,6 +432,7 @@ class AacMediaCodecInformation(
                 cls.SAMPLING_FREQUENCY_BITS[x] for x in sampling_frequencies
             ),
             channels=sum(cls.CHANNELS_BITS[x] for x in channels),
+            rfa=0,
             vbr=vbr,
             bitrate=bitrate,
         )

bumble/at.py

@@ -0,0 +1,85 @@
+# 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
+
+
+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 ValueError 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 ValueError("open_paren following regular character")
+                tokens.append(char)
+            elif char == b'"':
+                if len(token) > 0:
+                    raise ValueError("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 ValueError 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 ValueError("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 ValueError("missing close_paren")
+    return accumulator[0]

bumble/att.py

@@ -23,12 +23,13 @@
 # Imports
 # -----------------------------------------------------------------------------
 from __future__ import annotations
+import functools
 import struct
 from pyee import EventEmitter
 from typing import Dict, Type, TYPE_CHECKING
 
-from bumble.core import UUID, name_or_number
-from bumble.hci import HCI_Object, key_with_value
+from bumble.core import UUID, name_or_number, get_dict_key_by_value, ProtocolError
+from bumble.hci import HCI_Object, key_with_value, HCI_Constant
 from bumble.colors import color
 
 if TYPE_CHECKING:
@@ -184,13 +185,18 @@ UUID_2_FIELD_SPEC    = lambda x, y: UUID.parse_uuid_2(x, y)  # noqa: E731
 # -----------------------------------------------------------------------------
 # 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}'
 
 
 # -----------------------------------------------------------------------------
@@ -725,11 +731,38 @@ class Attribute(EventEmitter):
     READ_REQUIRES_AUTHORIZATION = 0x40
     WRITE_REQUIRES_AUTHORIZATION = 0x80
 
+    PERMISSION_NAMES = {
+        READABLE: 'READABLE',
+        WRITEABLE: 'WRITEABLE',
+        READ_REQUIRES_ENCRYPTION: 'READ_REQUIRES_ENCRYPTION',
+        WRITE_REQUIRES_ENCRYPTION: 'WRITE_REQUIRES_ENCRYPTION',
+        READ_REQUIRES_AUTHENTICATION: 'READ_REQUIRES_AUTHENTICATION',
+        WRITE_REQUIRES_AUTHENTICATION: 'WRITE_REQUIRES_AUTHENTICATION',
+        READ_REQUIRES_AUTHORIZATION: 'READ_REQUIRES_AUTHORIZATION',
+        WRITE_REQUIRES_AUTHORIZATION: 'WRITE_REQUIRES_AUTHORIZATION',
+    }
+
+    @staticmethod
+    def string_to_permissions(permissions_str: str):
+        try:
+            return functools.reduce(
+                lambda x, y: x | get_dict_key_by_value(Attribute.PERMISSION_NAMES, y),
+                permissions_str.split(","),
+                0,
+            )
+        except TypeError as exc:
+            raise TypeError(
+                f"Attribute::permissions error:\nExpected a string containing any of the keys, separated by commas: {','.join(Attribute.PERMISSION_NAMES.values())}\nGot: {permissions_str}"
+            ) from exc
+
     def __init__(self, attribute_type, permissions, value=b''):
         EventEmitter.__init__(self)
         self.handle = 0
         self.end_group_handle = 0
-        self.permissions = permissions
+        if isinstance(permissions, str):
+            self.permissions = self.string_to_permissions(permissions)
+        else:
+            self.permissions = permissions
 
         # Convert the type to a UUID object if it isn't already
         if isinstance(attribute_type, str):

bumble/avdtp.py

@@ -1207,7 +1207,7 @@ class DelayReport_Reject(Simple_Reject):
 
 
 # -----------------------------------------------------------------------------
-class Protocol:
+class Protocol(EventEmitter):
     SINGLE_PACKET = 0
     START_PACKET = 1
     CONTINUE_PACKET = 2
@@ -1234,6 +1234,7 @@ class Protocol:
         return protocol
 
     def __init__(self, l2cap_channel, version=(1, 3)):
+        super().__init__()
         self.l2cap_channel = l2cap_channel
         self.version = version
         self.rtx_sig_timer = AVDTP_DEFAULT_RTX_SIG_TIMER
@@ -1250,6 +1251,7 @@ class Protocol:
         # 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 get_local_endpoint_by_seid(self, seid):
         if 0 < seid <= len(self.local_endpoints):
@@ -1392,11 +1394,18 @@ class Protocol:
 
     def on_l2cap_connection(self, channel):
         # Forward the channel to the endpoint that's expecting it
-        if self.channel_acceptor:
-            self.channel_acceptor.on_l2cap_connection(channel)
+        if self.channel_acceptor is None:
+            logger.warning(color('!!! l2cap connection with no acceptor', 'red'))
+            return
+        self.channel_acceptor.on_l2cap_connection(channel)
 
     def on_l2cap_channel_open(self):
         logger.debug(color('<<< L2CAP channel open', 'magenta'))
+        self.emit('open')
+
+    def on_l2cap_channel_close(self):
+        logger.debug(color('<<< L2CAP channel close', 'magenta'))
+        self.emit('close')
 
     def send_message(self, transaction_label, message):
         logger.debug(
@@ -1651,6 +1660,10 @@ class Listener(EventEmitter):
     def set_server(self, connection, server):
         self.servers[connection.handle] = server
 
+    def remove_server(self, connection):
+        if connection.handle in self.servers:
+            del self.servers[connection.handle]
+
     def __init__(self, registrar, version=(1, 3)):
         super().__init__()
         self.version = version
@@ -1669,11 +1682,17 @@ class Listener(EventEmitter):
         else:
             # This is a new command/response channel
             def on_channel_open():
+                logger.debug('setting up new Protocol for the connection')
                 server = Protocol(channel, self.version)
                 self.set_server(channel.connection, server)
                 self.emit('connection', server)
 
+            def on_channel_close():
+                logger.debug('removing Protocol for the connection')
+                self.remove_server(channel.connection)
+
             channel.on('open', on_channel_open)
+            channel.on('close', on_channel_close)
 
 
 # -----------------------------------------------------------------------------
@@ -1967,11 +1986,12 @@ class DiscoveredStreamEndPoint(StreamEndPoint, StreamEndPointProxy):
 
 
 # -----------------------------------------------------------------------------
-class LocalStreamEndPoint(StreamEndPoint):
+class LocalStreamEndPoint(StreamEndPoint, EventEmitter):
     def __init__(
         self, protocol, seid, media_type, tsep, capabilities, configuration=None
     ):
-        super().__init__(seid, media_type, tsep, 0, capabilities)
+        StreamEndPoint.__init__(self, seid, media_type, tsep, 0, capabilities)
+        EventEmitter.__init__(self)
         self.protocol = protocol
         self.configuration = configuration if configuration is not None else []
         self.stream = None
@@ -1988,40 +2008,47 @@ class LocalStreamEndPoint(StreamEndPoint):
     def on_reconfigure_command(self, command):
         pass
 
+    def on_set_configuration_command(self, configuration):
+        logger.debug(
+            '<<< received configuration: '
+            f'{",".join([str(capability) for capability in configuration])}'
+        )
+        self.configuration = configuration
+        self.emit('configuration')
+
     def on_get_configuration_command(self):
         return Get_Configuration_Response(self.configuration)
 
     def on_open_command(self):
-        pass
+        self.emit('open')
 
     def on_start_command(self):
-        pass
+        self.emit('start')
 
     def on_suspend_command(self):
-        pass
+        self.emit('suspend')
 
     def on_close_command(self):
-        pass
+        self.emit('close')
 
     def on_abort_command(self):
-        pass
+        self.emit('abort')
 
     def on_rtp_channel_open(self):
-        pass
+        self.emit('rtp_channel_open')
 
     def on_rtp_channel_close(self):
-        pass
+        self.emit('rtp_channel_close')
 
 
 # -----------------------------------------------------------------------------
-class LocalSource(LocalStreamEndPoint, EventEmitter):
+class LocalSource(LocalStreamEndPoint):
     def __init__(self, protocol, seid, codec_capabilities, packet_pump):
         capabilities = [
             ServiceCapabilities(AVDTP_MEDIA_TRANSPORT_SERVICE_CATEGORY),
             codec_capabilities,
         ]
-        LocalStreamEndPoint.__init__(
-            self,
+        super().__init__(
             protocol,
             seid,
             codec_capabilities.media_type,
@@ -2029,14 +2056,13 @@ class LocalSource(LocalStreamEndPoint, EventEmitter):
             capabilities,
             capabilities,
         )
-        EventEmitter.__init__(self)
         self.packet_pump = packet_pump
 
     async def start(self):
         if self.packet_pump:
             return await self.packet_pump.start(self.stream.rtp_channel)
 
-        self.emit('start', self.stream.rtp_channel)
+        self.emit('start')
 
     async def stop(self):
         if self.packet_pump:
@@ -2044,11 +2070,6 @@ class LocalSource(LocalStreamEndPoint, EventEmitter):
 
         self.emit('stop')
 
-    def on_set_configuration_command(self, configuration):
-        # For now, blindly accept the configuration
-        logger.debug(f'<<< received source configuration: {configuration}')
-        self.configuration = configuration
-
     def on_start_command(self):
         asyncio.create_task(self.start())
 
@@ -2057,30 +2078,28 @@ class LocalSource(LocalStreamEndPoint, EventEmitter):
 
 
 # -----------------------------------------------------------------------------
-class LocalSink(LocalStreamEndPoint, EventEmitter):
+class LocalSink(LocalStreamEndPoint):
     def __init__(self, protocol, seid, codec_capabilities):
         capabilities = [
             ServiceCapabilities(AVDTP_MEDIA_TRANSPORT_SERVICE_CATEGORY),
             codec_capabilities,
         ]
-        LocalStreamEndPoint.__init__(
-            self,
+        super().__init__(
             protocol,
             seid,
             codec_capabilities.media_type,
             AVDTP_TSEP_SNK,
             capabilities,
         )
-        EventEmitter.__init__(self)
-
-    def on_set_configuration_command(self, configuration):
-        # For now, blindly accept the configuration
-        logger.debug(f'<<< received sink configuration: {configuration}')
-        self.configuration = configuration
 
     def on_rtp_channel_open(self):
         logger.debug(color('<<< RTP channel open', 'magenta'))
         self.stream.rtp_channel.sink = self.on_avdtp_packet
+        super().on_rtp_channel_open()
+
+    def on_rtp_channel_close(self):
+        logger.debug(color('<<< RTP channel close', 'magenta'))
+        super().on_rtp_channel_close()
 
     def on_avdtp_packet(self, packet):
         rtp_packet = MediaPacket.from_bytes(packet)

bumble/codecs.py

@@ -0,0 +1,381 @@
+# 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
+
+
+# -----------------------------------------------------------------------------
+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 ValueError('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 ValueError('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 ValueError('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 AacAudioRtpPacket:
+    """AAC payload encapsulated in an RTP packet payload"""
+
+    @staticmethod
+    def 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 program_config_element(reader: BitReader):
+        raise ValueError('program_config_element not supported')
+
+    @dataclass
+    class GASpecificConfig:
+        def __init__(
+            self, reader: BitReader, channel_configuration: int, audio_object_type: int
+        ) -> None:
+            # 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:
+                self.core_coder_delay = reader.read(14)
+            extension_flag = reader.read(1)
+            if not channel_configuration:
+                AacAudioRtpPacket.program_config_element(reader)
+            if audio_object_type in (6, 20):
+                self.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 ValueError('extensionFlag3 == 1 not supported')
+
+    @staticmethod
+    def 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 AudioSpecificConfig:
+        audio_object_type: int
+        sampling_frequency_index: int
+        sampling_frequency: int
+        channel_configuration: int
+        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,
+        ]
+
+        def __init__(self, reader: BitReader) -> None:
+            # AudioSpecificConfig - ISO/EIC 14496-3 Table 1.15
+            self.audio_object_type = AacAudioRtpPacket.audio_object_type(reader)
+            self.sampling_frequency_index = reader.read(4)
+            if self.sampling_frequency_index == 0xF:
+                self.sampling_frequency = reader.read(24)
+            else:
+                self.sampling_frequency = self.SAMPLING_FREQUENCIES[
+                    self.sampling_frequency_index
+                ]
+            self.channel_configuration = reader.read(4)
+            self.sbr_present_flag = -1
+            self.ps_present_flag = -1
+            if self.audio_object_type in (5, 29):
+                self.extension_audio_object_type = 5
+                self.sbc_present_flag = 1
+                if self.audio_object_type == 29:
+                    self.ps_present_flag = 1
+                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.audio_object_type = AacAudioRtpPacket.audio_object_type(reader)
+                if self.audio_object_type == 22:
+                    self.extension_channel_configuration = reader.read(4)
+            else:
+                self.extension_audio_object_type = 0
+
+            if self.audio_object_type in (1, 2, 3, 4, 6, 7, 17, 19, 20, 21, 22, 23):
+                ga_specific_config = AacAudioRtpPacket.GASpecificConfig(
+                    reader, self.channel_configuration, self.audio_object_type
+                )
+            else:
+                raise ValueError(
+                    f'audioObjectType {self.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)
+
+    @dataclass
+    class StreamMuxConfig:
+        other_data_present: int
+        other_data_len_bits: int
+        audio_specific_config: AacAudioRtpPacket.AudioSpecificConfig
+
+        def __init__(self, reader: BitReader) -> None:
+            # 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 ValueError('audioMuxVersionA != 0 not supported')
+            if audio_mux_version == 1:
+                tara_buffer_fullness = AacAudioRtpPacket.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 ValueError('num_program != 0 not supported')
+            num_layer = reader.read(3)
+            if num_layer != 0:
+                raise ValueError('num_layer != 0 not supported')
+            if audio_mux_version == 0:
+                self.audio_specific_config = AacAudioRtpPacket.AudioSpecificConfig(
+                    reader
+                )
+            else:
+                asc_len = AacAudioRtpPacket.latm_value(reader)
+                marker = reader.bit_position
+                self.audio_specific_config = AacAudioRtpPacket.AudioSpecificConfig(
+                    reader
+                )
+                audio_specific_config_len = reader.bit_position - marker
+                if asc_len < audio_specific_config_len:
+                    raise ValueError('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 ValueError(f'frame_length_type {frame_length_type} not supported')
+
+            self.other_data_present = reader.read(1)
+            if self.other_data_present:
+                if audio_mux_version == 1:
+                    self.other_data_len_bits = AacAudioRtpPacket.latm_value(reader)
+                else:
+                    self.other_data_len_bits = 0
+                    while True:
+                        self.other_data_len_bits *= 256
+                        other_data_len_esc = reader.read(1)
+                        self.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)
+
+    @dataclass
+    class AudioMuxElement:
+        payload: bytes
+        stream_mux_config: AacAudioRtpPacket.StreamMuxConfig
+
+        def __init__(self, reader: BitReader, mux_config_present: int):
+            if mux_config_present == 0:
+                raise ValueError('muxConfigPresent == 0 not supported')
+
+            # AudioMuxElement - ISO/EIC 14496-3 Table 1.41
+            use_same_stream_mux = reader.read(1)
+            if use_same_stream_mux:
+                raise ValueError('useSameStreamMux == 1 not supported')
+            self.stream_mux_config = AacAudioRtpPacket.StreamMuxConfig(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
+
+            self.payload = reader.read_bytes(mux_slot_length_bytes)
+
+            if self.stream_mux_config.other_data_present:
+                reader.skip(self.stream_mux_config.other_data_len_bits)
+
+            # ByteAlign
+            while reader.bit_position % 8:
+                reader.read(1)
+
+    def __init__(self, data: bytes) -> None:
+        # Parse the bit stream
+        reader = BitReader(data)
+        self.audio_mux_element = self.AudioMuxElement(reader, mux_config_present=1)
+
+    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
+        )

bumble/controller.py

@@ -15,13 +15,20 @@
 # -----------------------------------------------------------------------------
 # Imports
 # -----------------------------------------------------------------------------
+from __future__ import annotations
+
 import logging
 import asyncio
 import itertools
 import random
 import struct
 from bumble.colors import color
-from bumble.core import BT_CENTRAL_ROLE, BT_PERIPHERAL_ROLE
+from bumble.core import (
+    BT_CENTRAL_ROLE,
+    BT_PERIPHERAL_ROLE,
+    BT_LE_TRANSPORT,
+    BT_BR_EDR_TRANSPORT,
+)
 
 from bumble.hci import (
     HCI_ACL_DATA_PACKET,
@@ -29,17 +36,21 @@ from bumble.hci import (
     HCI_COMMAND_PACKET,
     HCI_COMMAND_STATUS_PENDING,
     HCI_CONNECTION_TIMEOUT_ERROR,
+    HCI_CONTROLLER_BUSY_ERROR,
     HCI_EVENT_PACKET,
     HCI_INVALID_HCI_COMMAND_PARAMETERS_ERROR,
     HCI_LE_1M_PHY,
     HCI_SUCCESS,
     HCI_UNKNOWN_HCI_COMMAND_ERROR,
+    HCI_REMOTE_USER_TERMINATED_CONNECTION_ERROR,
     HCI_VERSION_BLUETOOTH_CORE_5_0,
     Address,
     HCI_AclDataPacket,
     HCI_AclDataPacketAssembler,
     HCI_Command_Complete_Event,
     HCI_Command_Status_Event,
+    HCI_Connection_Complete_Event,
+    HCI_Connection_Request_Event,
     HCI_Disconnection_Complete_Event,
     HCI_Encryption_Change_Event,
     HCI_LE_Advertising_Report_Event,
@@ -47,8 +58,12 @@ from bumble.hci import (
     HCI_LE_Read_Remote_Features_Complete_Event,
     HCI_Number_Of_Completed_Packets_Event,
     HCI_Packet,
+    HCI_Role_Change_Event,
 )
+from typing import Optional, Union, Dict, TYPE_CHECKING
 
+if TYPE_CHECKING:
+    from bumble.transport.common import TransportSink, TransportSource
 
 # -----------------------------------------------------------------------------
 # Logging
@@ -65,13 +80,14 @@ class DataObject:
 
 # -----------------------------------------------------------------------------
 class Connection:
-    def __init__(self, controller, handle, role, peer_address, link):
+    def __init__(self, controller, handle, role, peer_address, link, transport):
         self.controller = controller
         self.handle = handle
         self.role = role
         self.peer_address = peer_address
         self.link = link
         self.assembler = HCI_AclDataPacketAssembler(self.on_acl_pdu)
+        self.transport = transport
 
     def on_hci_acl_data_packet(self, packet):
         self.assembler.feed_packet(packet)
@@ -82,23 +98,33 @@ class Connection:
     def on_acl_pdu(self, data):
         if self.link:
             self.link.send_acl_data(
-                self.controller.random_address, self.peer_address, data
+                self.controller, self.peer_address, self.transport, data
             )
 
 
 # -----------------------------------------------------------------------------
 class Controller:
-    def __init__(self, name, host_source=None, host_sink=None, link=None):
+    def __init__(
+        self,
+        name,
+        host_source=None,
+        host_sink: Optional[TransportSink] = None,
+        link=None,
+        public_address: Optional[Union[bytes, str, Address]] = None,
+    ):
         self.name = name
         self.hci_sink = None
         self.link = link
 
-        self.central_connections = (
-            {}
-        )  # Connections where this controller is the central
-        self.peripheral_connections = (
-            {}
-        )  # Connections where this controller is the peripheral
+        self.central_connections: Dict[
+            Address, Connection
+        ] = {}  # Connections where this controller is the central
+        self.peripheral_connections: Dict[
+            Address, Connection
+        ] = {}  # Connections where this controller is the peripheral
+        self.classic_connections: Dict[
+            Address, Connection
+        ] = {}  # Connections in BR/EDR
 
         self.hci_version = HCI_VERSION_BLUETOOTH_CORE_5_0
         self.hci_revision = 0
@@ -148,7 +174,14 @@ class Controller:
         self.advertising_timer_handle = None
 
         self._random_address = Address('00:00:00:00:00:00')
-        self._public_address = None
+        if isinstance(public_address, Address):
+            self._public_address = public_address
+        elif public_address is not None:
+            self._public_address = Address(
+                public_address, Address.PUBLIC_DEVICE_ADDRESS
+            )
+        else:
+            self._public_address = Address('00:00:00:00:00:00')
 
         # Set the source and sink interfaces
         if host_source:
@@ -159,6 +192,8 @@ class Controller:
         if link:
             link.add_controller(self)
 
+        self.terminated = asyncio.get_running_loop().create_future()
+
     @property
     def host(self):
         return self.hci_sink
@@ -259,10 +294,9 @@ class Controller:
         if self.host:
             self.host.on_packet(packet.to_bytes())
 
-    # This method allow the controller to emulate the same API as a transport source
+    # This method allows the controller to emulate the same API as a transport source
     async def wait_for_termination(self):
-        # For now, just wait forever
-        await asyncio.get_running_loop().create_future()
+        await self.terminated
 
     ############################################################
     # Link connections
@@ -271,7 +305,9 @@ class Controller:
         handle = 0
         max_handle = 0
         for connection in itertools.chain(
-            self.central_connections.values(), self.peripheral_connections.values()
+            self.central_connections.values(),
+            self.peripheral_connections.values(),
+            self.classic_connections.values(),
         ):
             max_handle = max(max_handle, connection.handle)
             if connection.handle == handle:
@@ -279,14 +315,19 @@ class Controller:
                 handle = max_handle + 1
         return handle
 
-    def find_connection_by_address(self, address):
+    def find_le_connection_by_address(self, address):
         return self.central_connections.get(address) or self.peripheral_connections.get(
             address
         )
 
+    def find_classic_connection_by_address(self, address):
+        return self.classic_connections.get(address)
+
     def find_connection_by_handle(self, handle):
         for connection in itertools.chain(
-            self.central_connections.values(), self.peripheral_connections.values()
+            self.central_connections.values(),
+            self.peripheral_connections.values(),
+            self.classic_connections.values(),
         ):
             if connection.handle == handle:
                 return connection
@@ -298,6 +339,12 @@ class Controller:
                 return connection
         return None
 
+    def find_classic_connection_by_handle(self, handle):
+        for connection in self.classic_connections.values():
+            if connection.handle == handle:
+                return connection
+        return None
+
     def on_link_central_connected(self, central_address):
         '''
         Called when an incoming connection occurs from a central on the link
@@ -310,7 +357,12 @@ class Controller:
         if connection is None:
             connection_handle = self.allocate_connection_handle()
             connection = Connection(
-                self, connection_handle, BT_PERIPHERAL_ROLE, peer_address, self.link
+                self,
+                connection_handle,
+                BT_PERIPHERAL_ROLE,
+                peer_address,
+                self.link,
+                BT_LE_TRANSPORT,
             )
             self.peripheral_connections[peer_address] = connection
             logger.debug(f'New PERIPHERAL connection handle: 0x{connection_handle:04X}')
@@ -364,7 +416,12 @@ class Controller:
             if connection is None:
                 connection_handle = self.allocate_connection_handle()
                 connection = Connection(
-                    self, connection_handle, BT_CENTRAL_ROLE, peer_address, self.link
+                    self,
+                    connection_handle,
+                    BT_CENTRAL_ROLE,
+                    peer_address,
+                    self.link,
+                    BT_LE_TRANSPORT,
                 )
                 self.central_connections[peer_address] = connection
                 logger.debug(
@@ -432,16 +489,19 @@ class Controller:
 
     def on_link_encrypted(self, peer_address, _rand, _ediv, _ltk):
         # For now, just setup the encryption without asking the host
-        if connection := self.find_connection_by_address(peer_address):
+        if connection := self.find_le_connection_by_address(peer_address):
             self.send_hci_packet(
                 HCI_Encryption_Change_Event(
                     status=0, connection_handle=connection.handle, encryption_enabled=1
                 )
             )
 
-    def on_link_acl_data(self, sender_address, data):
+    def on_link_acl_data(self, sender_address, transport, data):
         # Look for the connection to which this data belongs
-        connection = self.find_connection_by_address(sender_address)
+        if transport == BT_LE_TRANSPORT:
+            connection = self.find_le_connection_by_address(sender_address)
+        else:
+            connection = self.find_classic_connection_by_address(sender_address)
         if connection is None:
             logger.warning(f'!!! no connection for {sender_address}')
             return
@@ -478,6 +538,87 @@ class Controller:
         )
         self.send_hci_packet(HCI_LE_Advertising_Report_Event([report]))
 
+    ############################################################
+    # Classic link connections
+    ############################################################
+
+    def on_classic_connection_request(self, peer_address, link_type):
+        self.send_hci_packet(
+            HCI_Connection_Request_Event(
+                bd_addr=peer_address,
+                class_of_device=0,
+                link_type=link_type,
+            )
+        )
+
+    def on_classic_connection_complete(self, peer_address, status):
+        if status == HCI_SUCCESS:
+            # Allocate (or reuse) a connection handle
+            peer_address = peer_address
+            connection = self.classic_connections.get(peer_address)
+            if connection is None:
+                connection_handle = self.allocate_connection_handle()
+                connection = Connection(
+                    controller=self,
+                    handle=connection_handle,
+                    # Role doesn't matter in Classic because they are managed by HCI_Role_Change and HCI_Role_Discovery
+                    role=BT_CENTRAL_ROLE,
+                    peer_address=peer_address,
+                    link=self.link,
+                    transport=BT_BR_EDR_TRANSPORT,
+                )
+                self.classic_connections[peer_address] = connection
+                logger.debug(
+                    f'New CLASSIC connection handle: 0x{connection_handle:04X}'
+                )
+            else:
+                connection_handle = connection.handle
+            self.send_hci_packet(
+                HCI_Connection_Complete_Event(
+                    status=status,
+                    connection_handle=connection_handle,
+                    bd_addr=peer_address,
+                    encryption_enabled=False,
+                    link_type=HCI_Connection_Complete_Event.ACL_LINK_TYPE,
+                )
+            )
+        else:
+            connection = None
+            self.send_hci_packet(
+                HCI_Connection_Complete_Event(
+                    status=status,
+                    connection_handle=0,
+                    bd_addr=peer_address,
+                    encryption_enabled=False,
+                    link_type=HCI_Connection_Complete_Event.ACL_LINK_TYPE,
+                )
+            )
+
+    def on_classic_disconnected(self, peer_address, reason):
+        # Send a disconnection complete event
+        if connection := self.classic_connections.get(peer_address):
+            self.send_hci_packet(
+                HCI_Disconnection_Complete_Event(
+                    status=HCI_SUCCESS,
+                    connection_handle=connection.handle,
+                    reason=reason,
+                )
+            )
+
+            # Remove the connection
+            del self.classic_connections[peer_address]
+        else:
+            logger.warning(f'!!! No classic connection found for {peer_address}')
+
+    def on_classic_role_change(self, peer_address, new_role):
+        self.send_hci_packet(
+            HCI_Role_Change_Event(
+                status=HCI_SUCCESS,
+                bd_addr=peer_address,
+                new_role=new_role,
+            )
+        )
+
     ############################################################
     # Advertising support
     ############################################################
@@ -518,14 +659,38 @@ class Controller:
 
     def on_hci_create_connection_command(self, command):
         '''
-        See Bluetooth spec Vol 2, Part E - 7.1.5 Create Connection command
+        See Bluetooth spec Vol 4, Part E - 7.1.5 Create Connection command
         '''
 
-        # TODO: classic mode not supported yet
+        if self.link is None:
+            return
+        logger.debug(f'Connection request to {command.bd_addr}')
+
+        # Check that we don't already have a pending connection
+        if self.link.get_pending_connection():
+            self.send_hci_packet(
+                HCI_Command_Status_Event(
+                    status=HCI_CONTROLLER_BUSY_ERROR,
+                    num_hci_command_packets=1,
+                    command_opcode=command.op_code,
+                )
+            )
+            return
+
+        self.link.classic_connect(self, command.bd_addr)
+
+        # Say that the connection is pending
+        self.send_hci_packet(
+            HCI_Command_Status_Event(
+                status=HCI_COMMAND_STATUS_PENDING,
+                num_hci_command_packets=1,
+                command_opcode=command.op_code,
+            )
+        )
 
     def on_hci_disconnect_command(self, command):
         '''
-        See Bluetooth spec Vol 2, Part E - 7.1.6 Disconnect Command
+        See Bluetooth spec Vol 4, Part E - 7.1.6 Disconnect Command
         '''
         # First, say that the disconnection is pending
         self.send_hci_packet(
@@ -537,37 +702,75 @@ class Controller:
         )
 
         # Notify the link of the disconnection
-        if not (
-            connection := self.find_central_connection_by_handle(
-                command.connection_handle
-            )
-        ):
-            logger.warning('connection not found')
-            return
+        handle = command.connection_handle
+        if connection := self.find_central_connection_by_handle(handle):
+            if self.link:
+                self.link.disconnect(
+                    self.random_address, connection.peer_address, command
+                )
+            else:
+                # Remove the connection
+                del self.central_connections[connection.peer_address]
+        elif connection := self.find_classic_connection_by_handle(handle):
+            if self.link:
+                self.link.classic_disconnect(
+                    self,
+                    connection.peer_address,
+                    HCI_REMOTE_USER_TERMINATED_CONNECTION_ERROR,
+                )
+            else:
+                # Remove the connection
+                del self.classic_connections[connection.peer_address]
 
-        if self.link:
-            self.link.disconnect(self.random_address, connection.peer_address, command)
-        else:
-            # Remove the connection
-            del self.central_connections[connection.peer_address]
+    def on_hci_accept_connection_request_command(self, command):
+        '''
+        See Bluetooth spec Vol 4, Part E - 7.1.8 Accept Connection Request command
+        '''
+
+        if self.link is None:
+            return
+        self.send_hci_packet(
+            HCI_Command_Status_Event(
+                status=HCI_SUCCESS,
+                num_hci_command_packets=1,
+                command_opcode=command.op_code,
+            )
+        )
+        self.link.classic_accept_connection(self, command.bd_addr, command.role)
+
+    def on_hci_switch_role_command(self, command):
+        '''
+        See Bluetooth spec Vol 4, Part E - 7.2.8 Switch Role command
+        '''
+
+        if self.link is None:
+            return
+        self.send_hci_packet(
+            HCI_Command_Status_Event(
+                status=HCI_SUCCESS,
+                num_hci_command_packets=1,
+                command_opcode=command.op_code,
+            )
+        )
+        self.link.classic_switch_role(self, command.bd_addr, command.role)
 
     def on_hci_set_event_mask_command(self, command):
         '''
-        See Bluetooth spec Vol 2, Part E - 7.3.1 Set Event Mask Command
+        See Bluetooth spec Vol 4, Part E - 7.3.1 Set Event Mask Command
         '''
         self.event_mask = command.event_mask
         return bytes([HCI_SUCCESS])
 
     def on_hci_reset_command(self, _command):
         '''
-        See Bluetooth spec Vol 2, Part E - 7.3.2 Reset Command
+        See Bluetooth spec Vol 4, Part E - 7.3.2 Reset Command
         '''
         # TODO: cleanup what needs to be reset
         return bytes([HCI_SUCCESS])
 
     def on_hci_write_local_name_command(self, command):
         '''
-        See Bluetooth spec Vol 2, Part E - 7.3.11 Write Local Name Command
+        See Bluetooth spec Vol 4, Part E - 7.3.11 Write Local Name Command
         '''
         local_name = command.local_name
         if len(local_name):
@@ -582,7 +785,7 @@ class Controller:
 
     def on_hci_read_local_name_command(self, _command):
         '''
-        See Bluetooth spec Vol 2, Part E - 7.3.12 Read Local Name Command
+        See Bluetooth spec Vol 4, Part E - 7.3.12 Read Local Name Command
         '''
         local_name = bytes(self.local_name, 'utf-8')[:248]
         if len(local_name) < 248:
@@ -592,19 +795,19 @@ class Controller:
 
     def on_hci_read_class_of_device_command(self, _command):
         '''
-        See Bluetooth spec Vol 2, Part E - 7.3.25 Read Class of Device Command
+        See Bluetooth spec Vol 4, Part E - 7.3.25 Read Class of Device Command
         '''
         return bytes([HCI_SUCCESS, 0, 0, 0])
 
     def on_hci_write_class_of_device_command(self, _command):
         '''
-        See Bluetooth spec Vol 2, Part E - 7.3.26 Write Class of Device Command
+        See Bluetooth spec Vol 4, Part E - 7.3.26 Write Class of Device Command
         '''
         return bytes([HCI_SUCCESS])
 
     def on_hci_read_synchronous_flow_control_enable_command(self, _command):
         '''
-        See Bluetooth spec Vol 2, Part E - 7.3.36 Read Synchronous Flow Control Enable
+        See Bluetooth spec Vol 4, Part E - 7.3.36 Read Synchronous Flow Control Enable
         Command
         '''
         if self.sync_flow_control:
@@ -615,7 +818,7 @@ class Controller:
 
     def on_hci_write_synchronous_flow_control_enable_command(self, command):
         '''
-        See Bluetooth spec Vol 2, Part E - 7.3.37 Write Synchronous Flow Control Enable
+        See Bluetooth spec Vol 4, Part E - 7.3.37 Write Synchronous Flow Control Enable
         Command
         '''
         ret = HCI_SUCCESS
@@ -627,35 +830,59 @@ class Controller:
             ret = HCI_INVALID_HCI_COMMAND_PARAMETERS_ERROR
         return bytes([ret])
 
+    def on_hci_set_controller_to_host_flow_control_command(self, _command):
+        '''
+        See Bluetooth spec Vol 4, Part E - 7.3.38 Set Controller To Host Flow Control
+        Command
+        '''
+        # For now we just accept the command but ignore the values.
+        # TODO: respect the passed in values.
+        return bytes([HCI_SUCCESS])
+
+    def on_hci_host_buffer_size_command(self, _command):
+        '''
+        See Bluetooth spec Vol 4, Part E - 7.3.39 Host Buffer Size Command
+        '''
+        # For now we just accept the command but ignore the values.
+        # TODO: respect the passed in values.
+        return bytes([HCI_SUCCESS])
+
+    def on_hci_write_extended_inquiry_response_command(self, _command):
+        '''
+        See Bluetooth spec Vol 4, Part E - 7.3.56 Write Extended Inquiry Response
+        Command
+        '''
+        return bytes([HCI_SUCCESS])
+
     def on_hci_write_simple_pairing_mode_command(self, _command):
         '''
-        See Bluetooth spec Vol 2, Part E - 7.3.59 Write Simple Pairing Mode Command
+        See Bluetooth spec Vol 4, Part E - 7.3.59 Write Simple Pairing Mode Command
         '''
         return bytes([HCI_SUCCESS])
 
     def on_hci_set_event_mask_page_2_command(self, command):
         '''
-        See Bluetooth spec Vol 2, Part E - 7.3.69 Set Event Mask Page 2 Command
+        See Bluetooth spec Vol 4, Part E - 7.3.69 Set Event Mask Page 2 Command
         '''
         self.event_mask_page_2 = command.event_mask_page_2
         return bytes([HCI_SUCCESS])
 
     def on_hci_read_le_host_support_command(self, _command):
         '''
-        See Bluetooth spec Vol 2, Part E - 7.3.78 Write LE Host Support Command
+        See Bluetooth spec Vol 4, Part E - 7.3.78 Write LE Host Support Command
         '''
         return bytes([HCI_SUCCESS, 1, 0])
 
     def on_hci_write_le_host_support_command(self, _command):
         '''
-        See Bluetooth spec Vol 2, Part E - 7.3.79 Write LE Host Support Command
+        See Bluetooth spec Vol 4, Part E - 7.3.79 Write LE Host Support Command
         '''
         # TODO / Just ignore for now
         return bytes([HCI_SUCCESS])
 
     def on_hci_write_authenticated_payload_timeout_command(self, command):
         '''
-        See Bluetooth spec Vol 2, Part E - 7.3.94 Write Authenticated Payload Timeout
+        See Bluetooth spec Vol 4, Part E - 7.3.94 Write Authenticated Payload Timeout
         Command
         '''
         # TODO
@@ -663,7 +890,7 @@ class Controller:
 
     def on_hci_read_local_version_information_command(self, _command):
         '''
-        See Bluetooth spec Vol 2, Part E - 7.4.1 Read Local Version Information Command
+        See Bluetooth spec Vol 4, Part E - 7.4.1 Read Local Version Information Command
         '''
         return struct.pack(
             '<BBHBHH',
@@ -677,19 +904,19 @@ class Controller:
 
     def on_hci_read_local_supported_commands_command(self, _command):
         '''
-        See Bluetooth spec Vol 2, Part E - 7.4.2 Read Local Supported Commands Command
+        See Bluetooth spec Vol 4, Part E - 7.4.2 Read Local Supported Commands Command
         '''
         return bytes([HCI_SUCCESS]) + self.supported_commands
 
     def on_hci_read_local_supported_features_command(self, _command):
         '''
-        See Bluetooth spec Vol 2, Part E - 7.4.3 Read Local Supported Features Command
+        See Bluetooth spec Vol 4, Part E - 7.4.3 Read Local Supported Features Command
         '''
         return bytes([HCI_SUCCESS]) + self.lmp_features
 
     def on_hci_read_bd_addr_command(self, _command):
         '''
-        See Bluetooth spec Vol 2, Part E - 7.4.6 Read BD_ADDR Command
+        See Bluetooth spec Vol 4, Part E - 7.4.6 Read BD_ADDR Command
         '''
         bd_addr = (
             self._public_address.to_bytes()
@@ -700,14 +927,14 @@ class Controller:
 
     def on_hci_le_set_event_mask_command(self, command):
         '''
-        See Bluetooth spec Vol 2, Part E - 7.8.1 LE Set Event Mask Command
+        See Bluetooth spec Vol 4, Part E - 7.8.1 LE Set Event Mask Command
         '''
         self.le_event_mask = command.le_event_mask
         return bytes([HCI_SUCCESS])
 
     def on_hci_le_read_buffer_size_command(self, _command):
         '''
-        See Bluetooth spec Vol 2, Part E - 7.8.2 LE Read Buffer Size Command
+        See Bluetooth spec Vol 4, Part E - 7.8.2 LE Read Buffer Size Command
         '''
         return struct.pack(
             '<BHB',
@@ -718,49 +945,49 @@ class Controller:
 
     def on_hci_le_read_local_supported_features_command(self, _command):
         '''
-        See Bluetooth spec Vol 2, Part E - 7.8.3 LE Read Local Supported Features
+        See Bluetooth spec Vol 4, Part E - 7.8.3 LE Read Local Supported Features
         Command
         '''
         return bytes([HCI_SUCCESS]) + self.le_features
 
     def on_hci_le_set_random_address_command(self, command):
         '''
-        See Bluetooth spec Vol 2, Part E - 7.8.4 LE Set Random Address Command
+        See Bluetooth spec Vol 4, Part E - 7.8.4 LE Set Random Address Command
         '''
         self.random_address = command.random_address
         return bytes([HCI_SUCCESS])
 
     def on_hci_le_set_advertising_parameters_command(self, command):
         '''
-        See Bluetooth spec Vol 2, Part E - 7.8.5 LE Set Advertising Parameters Command
+        See Bluetooth spec Vol 4, Part E - 7.8.5 LE Set Advertising Parameters Command
         '''
         self.advertising_parameters = command
         return bytes([HCI_SUCCESS])
 
     def on_hci_le_read_advertising_physical_channel_tx_power_command(self, _command):
         '''
-        See Bluetooth spec Vol 2, Part E - 7.8.6 LE Read Advertising Physical Channel
+        See Bluetooth spec Vol 4, Part E - 7.8.6 LE Read Advertising Physical Channel
         Tx Power Command
         '''
         return bytes([HCI_SUCCESS, self.advertising_channel_tx_power])
 
     def on_hci_le_set_advertising_data_command(self, command):
         '''
-        See Bluetooth spec Vol 2, Part E - 7.8.7 LE Set Advertising Data Command
+        See Bluetooth spec Vol 4, Part E - 7.8.7 LE Set Advertising Data Command
         '''
         self.advertising_data = command.advertising_data
         return bytes([HCI_SUCCESS])
 
     def on_hci_le_set_scan_response_data_command(self, command):
         '''
-        See Bluetooth spec Vol 2, Part E - 7.8.8 LE Set Scan Response Data Command
+        See Bluetooth spec Vol 4, Part E - 7.8.8 LE Set Scan Response Data Command
         '''
         self.le_scan_response_data = command.scan_response_data
         return bytes([HCI_SUCCESS])
 
     def on_hci_le_set_advertising_enable_command(self, command):
         '''
-        See Bluetooth spec Vol 2, Part E - 7.8.9 LE Set Advertising Enable Command
+        See Bluetooth spec Vol 4, Part E - 7.8.9 LE Set Advertising Enable Command
         '''
         if command.advertising_enable:
             self.start_advertising()
@@ -771,7 +998,7 @@ class Controller:
 
     def on_hci_le_set_scan_parameters_command(self, command):
         '''
-        See Bluetooth spec Vol 2, Part E - 7.8.10 LE Set Scan Parameters Command
+        See Bluetooth spec Vol 4, Part E - 7.8.10 LE Set Scan Parameters Command
         '''
         self.le_scan_type = command.le_scan_type
         self.le_scan_interval = command.le_scan_interval
@@ -782,7 +1009,7 @@ class Controller:
 
     def on_hci_le_set_scan_enable_command(self, command):
         '''
-        See Bluetooth spec Vol 2, Part E - 7.8.11 LE Set Scan Enable Command
+        See Bluetooth spec Vol 4, Part E - 7.8.11 LE Set Scan Enable Command
         '''
         self.le_scan_enable = command.le_scan_enable
         self.filter_duplicates = command.filter_duplicates
@@ -790,7 +1017,7 @@ class Controller:
 
     def on_hci_le_create_connection_command(self, command):
         '''
-        See Bluetooth spec Vol 2, Part E - 7.8.12 LE Create Connection Command
+        See Bluetooth spec Vol 4, Part E - 7.8.12 LE Create Connection Command
         '''
 
         if not self.link:
@@ -823,40 +1050,40 @@ class Controller:
 
     def on_hci_le_create_connection_cancel_command(self, _command):
         '''
-        See Bluetooth spec Vol 2, Part E - 7.8.13 LE Create Connection Cancel Command
+        See Bluetooth spec Vol 4, Part E - 7.8.13 LE Create Connection Cancel Command
         '''
         return bytes([HCI_SUCCESS])
 
     def on_hci_le_read_filter_accept_list_size_command(self, _command):
         '''
-        See Bluetooth spec Vol 2, Part E - 7.8.14 LE Read Filter Accept List Size
+        See Bluetooth spec Vol 4, Part E - 7.8.14 LE Read Filter Accept List Size
         Command
         '''
         return bytes([HCI_SUCCESS, self.filter_accept_list_size])
 
     def on_hci_le_clear_filter_accept_list_command(self, _command):
         '''
-        See Bluetooth spec Vol 2, Part E - 7.8.15 LE Clear Filter Accept List Command
+        See Bluetooth spec Vol 4, Part E - 7.8.15 LE Clear Filter Accept List Command
         '''
         return bytes([HCI_SUCCESS])
 
     def on_hci_le_add_device_to_filter_accept_list_command(self, _command):
         '''
-        See Bluetooth spec Vol 2, Part E - 7.8.16 LE Add Device To Filter Accept List
+        See Bluetooth spec Vol 4, Part E - 7.8.16 LE Add Device To Filter Accept List
         Command
         '''
         return bytes([HCI_SUCCESS])
 
     def on_hci_le_remove_device_from_filter_accept_list_command(self, _command):
         '''
-        See Bluetooth spec Vol 2, Part E - 7.8.17 LE Remove Device From Filter Accept
+        See Bluetooth spec Vol 4, Part E - 7.8.17 LE Remove Device From Filter Accept
         List Command
         '''
         return bytes([HCI_SUCCESS])
 
     def on_hci_le_read_remote_features_command(self, command):
         '''
-        See Bluetooth spec Vol 2, Part E - 7.8.21 LE Read Remote Features Command
+        See Bluetooth spec Vol 4, Part E - 7.8.21 LE Read Remote Features Command
         '''
 
         # First, say that the command is pending
@@ -879,13 +1106,13 @@ class Controller:
 
     def on_hci_le_rand_command(self, _command):
         '''
-        See Bluetooth spec Vol 2, Part E - 7.8.23 LE Rand Command
+        See Bluetooth spec Vol 4, Part E - 7.8.23 LE Rand Command
         '''
         return bytes([HCI_SUCCESS]) + struct.pack('Q', random.randint(0, 1 << 64))
 
     def on_hci_le_enable_encryption_command(self, command):
         '''
-        See Bluetooth spec Vol 2, Part E - 7.8.24 LE Enable Encryption Command
+        See Bluetooth spec Vol 4, Part E - 7.8.24 LE Enable Encryption Command
         '''
 
         # Check the parameters
@@ -918,13 +1145,13 @@ class Controller:
 
     def on_hci_le_read_supported_states_command(self, _command):
         '''
-        See Bluetooth spec Vol 2, Part E - 7.8.27 LE Read Supported States Command
+        See Bluetooth spec Vol 4, Part E - 7.8.27 LE Read Supported States Command
         '''
         return bytes([HCI_SUCCESS]) + self.le_states
 
     def on_hci_le_read_suggested_default_data_length_command(self, _command):
         '''
-        See Bluetooth spec Vol 2, Part E - 7.8.34 LE Read Suggested Default Data Length
+        See Bluetooth spec Vol 4, Part E - 7.8.34 LE Read Suggested Default Data Length
         Command
         '''
         return struct.pack(
@@ -936,7 +1163,7 @@ class Controller:
 
     def on_hci_le_write_suggested_default_data_length_command(self, command):
         '''
-        See Bluetooth spec Vol 2, Part E - 7.8.35 LE Write Suggested Default Data Length
+        See Bluetooth spec Vol 4, Part E - 7.8.35 LE Write Suggested Default Data Length
         Command
         '''
         self.suggested_max_tx_octets, self.suggested_max_tx_time = struct.unpack(
@@ -946,33 +1173,33 @@ class Controller:
 
     def on_hci_le_read_local_p_256_public_key_command(self, _command):
         '''
-        See Bluetooth spec Vol 2, Part E - 7.8.36 LE Read P-256 Public Key Command
+        See Bluetooth spec Vol 4, Part E - 7.8.36 LE Read P-256 Public Key Command
         '''
         # TODO create key and send HCI_LE_Read_Local_P-256_Public_Key_Complete event
         return bytes([HCI_SUCCESS])
 
     def on_hci_le_add_device_to_resolving_list_command(self, _command):
         '''
-        See Bluetooth spec Vol 2, Part E - 7.8.38 LE Add Device To Resolving List
+        See Bluetooth spec Vol 4, Part E - 7.8.38 LE Add Device To Resolving List
         Command
         '''
         return bytes([HCI_SUCCESS])
 
     def on_hci_le_clear_resolving_list_command(self, _command):
         '''
-        See Bluetooth spec Vol 2, Part E - 7.8.40 LE Clear Resolving List Command
+        See Bluetooth spec Vol 4, Part E - 7.8.40 LE Clear Resolving List Command
         '''
         return bytes([HCI_SUCCESS])
 
     def on_hci_le_read_resolving_list_size_command(self, _command):
         '''
-        See Bluetooth spec Vol 2, Part E - 7.8.41 LE Read Resolving List Size Command
+        See Bluetooth spec Vol 4, Part E - 7.8.41 LE Read Resolving List Size Command
         '''
         return bytes([HCI_SUCCESS, self.resolving_list_size])
 
     def on_hci_le_set_address_resolution_enable_command(self, command):
         '''
-        See Bluetooth spec Vol 2, Part E - 7.8.44 LE Set Address Resolution Enable
+        See Bluetooth spec Vol 4, Part E - 7.8.44 LE Set Address Resolution Enable
         Command
         '''
         ret = HCI_SUCCESS
@@ -986,7 +1213,7 @@ class Controller:
 
     def on_hci_le_set_resolvable_private_address_timeout_command(self, command):
         '''
-        See Bluetooth spec Vol 2, Part E - 7.8.45 LE Set Resolvable Private Address
+        See Bluetooth spec Vol 4, Part E - 7.8.45 LE Set Resolvable Private Address
         Timeout Command
         '''
         self.le_rpa_timeout = command.rpa_timeout
@@ -994,7 +1221,7 @@ class Controller:
 
     def on_hci_le_read_maximum_data_length_command(self, _command):
         '''
-        See Bluetooth spec Vol 2, Part E - 7.8.46 LE Read Maximum Data Length Command
+        See Bluetooth spec Vol 4, Part E - 7.8.46 LE Read Maximum Data Length Command
         '''
         return struct.pack(
             '<BHHHH',
@@ -1007,7 +1234,7 @@ class Controller:
 
     def on_hci_le_read_phy_command(self, command):
         '''
-        See Bluetooth spec Vol 2, Part E - 7.8.47 LE Read PHY Command
+        See Bluetooth spec Vol 4, Part E - 7.8.47 LE Read PHY Command
         '''
         return struct.pack(
             '<BHBB',
@@ -1019,7 +1246,7 @@ class Controller:
 
     def on_hci_le_set_default_phy_command(self, command):
         '''
-        See Bluetooth spec Vol 2, Part E - 7.8.48 LE Set Default PHY Command
+        See Bluetooth spec Vol 4, Part E - 7.8.48 LE Set Default PHY Command
         '''
         self.default_phy = {
             'all_phys': command.all_phys,
@@ -1030,6 +1257,6 @@ class Controller:
 
     def on_hci_le_read_transmit_power_command(self, _command):
         '''
-        See Bluetooth spec Vol 2, Part E - 7.8.74 LE Read Transmit Power Command
+        See Bluetooth spec Vol 4, Part E - 7.8.74 LE Read Transmit Power Command
         '''
         return struct.pack('<BBB', HCI_SUCCESS, 0, 0)

bumble/core.py

@@ -17,7 +17,7 @@
 # -----------------------------------------------------------------------------
 from __future__ import annotations
 import struct
-from typing import List, Optional, Tuple, Union, cast
+from typing import List, Optional, Tuple, Union, cast, Dict
 
 from .company_ids import COMPANY_IDENTIFIERS
 
@@ -53,7 +53,7 @@ def bit_flags_to_strings(bits, bit_flag_names):
     return names
 
 
-def name_or_number(dictionary, number, width=2):
+def name_or_number(dictionary: Dict[int, str], number: int, width: int = 2) -> str:
     name = dictionary.get(number)
     if name is not None:
         return name
@@ -78,7 +78,13 @@ def get_dict_key_by_value(dictionary, value):
 class BaseError(Exception):
     """Base class for errors with an error code, error name and namespace"""
 
-    def __init__(self, error_code, error_namespace='', error_name='', details=''):
+    def __init__(
+        self,
+        error_code: Optional[int],
+        error_namespace: str = '',
+        error_name: str = '',
+        details: str = '',
+    ):
         super().__init__()
         self.error_code = error_code
         self.error_namespace = error_namespace
@@ -90,12 +96,14 @@ class BaseError(Exception):
             namespace = f'{self.error_namespace}/'
         else:
             namespace = ''
-        if self.error_name:
-            name = f'{self.error_name} [0x{self.error_code:X}]'
-        else:
-            name = f'0x{self.error_code:X}'
+        error_text = {
+            (True, True): f'{self.error_name} [0x{self.error_code:X}]',
+            (True, False): self.error_name,
+            (False, True): f'0x{self.error_code:X}',
+            (False, False): '',
+        }[(self.error_name != '', self.error_code is not None)]
 
-        return f'{type(self).__name__}({namespace}{name})'
+        return f'{type(self).__name__}({namespace}{error_text})'
 
 
 class ProtocolError(BaseError):
@@ -134,6 +142,10 @@ class ConnectionError(BaseError):  # pylint: disable=redefined-builtin
         self.peer_address = peer_address
 
 
+class ConnectionParameterUpdateError(BaseError):
+    """Connection Parameter Update Error"""
+
+
 # -----------------------------------------------------------------------------
 # UUID
 #
@@ -152,7 +164,12 @@ class UUID:
     BASE_UUID = bytes.fromhex('00001000800000805F9B34FB')[::-1]  # little-endian
     UUIDS: List[UUID] = []  # Registry of all instances created
 
-    def __init__(self, uuid_str_or_int, name=None):
+    uuid_bytes: bytes
+    name: Optional[str]
+
+    def __init__(
+        self, uuid_str_or_int: Union[str, int], name: Optional[str] = None
+    ) -> None:
         if isinstance(uuid_str_or_int, int):
             self.uuid_bytes = struct.pack('<H', uuid_str_or_int)
         else:
@@ -172,7 +189,7 @@ class UUID:
             self.uuid_bytes = bytes(reversed(bytes.fromhex(uuid_str)))
         self.name = name
 
-    def register(self):
+    def register(self) -> UUID:
         # Register this object in the class registry, and update the entry's name if
         # it wasn't set already
         for uuid in self.UUIDS:
@@ -196,22 +213,22 @@ class UUID:
         raise ValueError('only 2, 4 and 16 bytes are allowed')
 
     @classmethod
-    def from_16_bits(cls, uuid_16, name=None):
+    def from_16_bits(cls, uuid_16: int, name: Optional[str] = None) -> UUID:
         return cls.from_bytes(struct.pack('<H', uuid_16), name)
 
     @classmethod
-    def from_32_bits(cls, uuid_32, name=None):
+    def from_32_bits(cls, uuid_32: int, name: Optional[str] = None) -> UUID:
         return cls.from_bytes(struct.pack('<I', uuid_32), name)
 
     @classmethod
-    def parse_uuid(cls, uuid_as_bytes, offset):
+    def parse_uuid(cls, uuid_as_bytes: bytes, offset: int) -> Tuple[int, UUID]:
         return len(uuid_as_bytes), cls.from_bytes(uuid_as_bytes[offset:])
 
     @classmethod
-    def parse_uuid_2(cls, uuid_as_bytes, offset):
+    def parse_uuid_2(cls, uuid_as_bytes: bytes, offset: int) -> Tuple[int, UUID]:
         return offset + 2, cls.from_bytes(uuid_as_bytes[offset : offset + 2])
 
-    def to_bytes(self, force_128=False):
+    def to_bytes(self, force_128: bool = False) -> bytes:
         '''
         Serialize UUID in little-endian byte-order
         '''
@@ -227,7 +244,7 @@ class UUID:
         else:
             assert False, "unreachable"
 
-    def to_pdu_bytes(self):
+    def to_pdu_bytes(self) -> bytes:
         '''
         Convert to bytes for use in an ATT PDU.
         According to Vol 3, Part F - 3.2.1 Attribute Type:
@@ -236,11 +253,11 @@ class UUID:
         '''
         return self.to_bytes(force_128=(len(self.uuid_bytes) == 4))
 
-    def to_hex_str(self) -> str:
+    def to_hex_str(self, separator: str = '') -> str:
         if len(self.uuid_bytes) == 2 or len(self.uuid_bytes) == 4:
             return bytes(reversed(self.uuid_bytes)).hex().upper()
 
-        return ''.join(
+        return separator.join(
             [
                 bytes(reversed(self.uuid_bytes[12:16])).hex(),
                 bytes(reversed(self.uuid_bytes[10:12])).hex(),
@@ -250,10 +267,10 @@ class UUID:
             ]
         ).upper()
 
-    def __bytes__(self):
+    def __bytes__(self) -> bytes:
         return self.to_bytes()
 
-    def __eq__(self, other):
+    def __eq__(self, other: object) -> bool:
         if isinstance(other, UUID):
             return self.to_bytes(force_128=True) == other.to_bytes(force_128=True)
 
@@ -262,35 +279,19 @@ class UUID:
 
         return False
 
-    def __hash__(self):
+    def __hash__(self) -> int:
         return hash(self.uuid_bytes)
 
-    def __str__(self):
+    def __str__(self) -> str:
+        result = self.to_hex_str(separator='-')
         if len(self.uuid_bytes) == 2:
-            uuid = struct.unpack('<H', self.uuid_bytes)[0]
-            result = f'UUID-16:{uuid:04X}'
+            result = 'UUID-16:' + result
         elif len(self.uuid_bytes) == 4:
-            uuid = struct.unpack('<I', self.uuid_bytes)[0]
-            result = f'UUID-32:{uuid:08X}'
-        else:
-            result = '-'.join(
-                [
-                    bytes(reversed(self.uuid_bytes[12:16])).hex(),
-                    bytes(reversed(self.uuid_bytes[10:12])).hex(),
-                    bytes(reversed(self.uuid_bytes[8:10])).hex(),
-                    bytes(reversed(self.uuid_bytes[6:8])).hex(),
-                    bytes(reversed(self.uuid_bytes[0:6])).hex(),
-                ]
-            ).upper()
-
+            result = 'UUID-32:' + result
         if self.name is not None:
-            return result + f' ({self.name})'
-
+            result += f' ({self.name})'
         return result
 
-    def __repr__(self):
-        return str(self)
-
 
 # -----------------------------------------------------------------------------
 # Common UUID constants
@@ -573,11 +574,82 @@ class DeviceClass:
         PERIPHERAL_HANDHELD_GESTURAL_INPUT_DEVICE_MINOR_DEVICE_CLASS: 'Handheld gestural input device'
     }
 
+    WEARABLE_UNCATEGORIZED_MINOR_DEVICE_CLASS = 0x00
+    WEARABLE_WRISTWATCH_MINOR_DEVICE_CLASS    = 0x01
+    WEARABLE_PAGER_MINOR_DEVICE_CLASS         = 0x02
+    WEARABLE_JACKET_MINOR_DEVICE_CLASS        = 0x03
+    WEARABLE_HELMET_MINOR_DEVICE_CLASS        = 0x04
+    WEARABLE_GLASSES_MINOR_DEVICE_CLASS       = 0x05
+
+    WEARABLE_MINOR_DEVICE_CLASS_NAMES = {
+        WEARABLE_UNCATEGORIZED_MINOR_DEVICE_CLASS: 'Uncategorized',
+        WEARABLE_WRISTWATCH_MINOR_DEVICE_CLASS:    'Wristwatch',
+        WEARABLE_PAGER_MINOR_DEVICE_CLASS:         'Pager',
+        WEARABLE_JACKET_MINOR_DEVICE_CLASS:        'Jacket',
+        WEARABLE_HELMET_MINOR_DEVICE_CLASS:        'Helmet',
+        WEARABLE_GLASSES_MINOR_DEVICE_CLASS:       'Glasses',
+    }
+
+    TOY_UNCATEGORIZED_MINOR_DEVICE_CLASS      = 0x00
+    TOY_ROBOT_MINOR_DEVICE_CLASS              = 0x01
+    TOY_VEHICLE_MINOR_DEVICE_CLASS            = 0x02
+    TOY_DOLL_ACTION_FIGURE_MINOR_DEVICE_CLASS = 0x03
+    TOY_CONTROLLER_MINOR_DEVICE_CLASS         = 0x04
+    TOY_GAME_MINOR_DEVICE_CLASS               = 0x05
+
+    TOY_MINOR_DEVICE_CLASS_NAMES = {
+        TOY_UNCATEGORIZED_MINOR_DEVICE_CLASS:      'Uncategorized',
+        TOY_ROBOT_MINOR_DEVICE_CLASS:              'Robot',
+        TOY_VEHICLE_MINOR_DEVICE_CLASS:            'Vehicle',
+        TOY_DOLL_ACTION_FIGURE_MINOR_DEVICE_CLASS: 'Doll/Action figure',
+        TOY_CONTROLLER_MINOR_DEVICE_CLASS:         'Controller',
+        TOY_GAME_MINOR_DEVICE_CLASS:               'Game',
+    }
+
+    HEALTH_UNDEFINED_MINOR_DEVICE_CLASS                 = 0x00
+    HEALTH_BLOOD_PRESSURE_MONITOR_MINOR_DEVICE_CLASS    = 0x01
+    HEALTH_THERMOMETER_MINOR_DEVICE_CLASS               = 0x02
+    HEALTH_WEIGHING_SCALE_MINOR_DEVICE_CLASS            = 0x03
+    HEALTH_GLUCOSE_METER_MINOR_DEVICE_CLASS             = 0x04
+    HEALTH_PULSE_OXIMETER_MINOR_DEVICE_CLASS            = 0x05
+    HEALTH_HEART_PULSE_RATE_MONITOR_MINOR_DEVICE_CLASS  = 0x06
+    HEALTH_HEALTH_DATA_DISPLAY_MINOR_DEVICE_CLASS       = 0x07
+    HEALTH_STEP_COUNTER_MINOR_DEVICE_CLASS              = 0x08
+    HEALTH_BODY_COMPOSITION_ANALYZER_MINOR_DEVICE_CLASS = 0x09
+    HEALTH_PEAK_FLOW_MONITOR_MINOR_DEVICE_CLASS         = 0x0A
+    HEALTH_MEDICATION_MONITOR_MINOR_DEVICE_CLASS        = 0x0B
+    HEALTH_KNEE_PROSTHESIS_MINOR_DEVICE_CLASS           = 0x0C
+    HEALTH_ANKLE_PROSTHESIS_MINOR_DEVICE_CLASS          = 0x0D
+    HEALTH_GENERIC_HEALTH_MANAGER_MINOR_DEVICE_CLASS    = 0x0E
+    HEALTH_PERSONAL_MOBILITY_DEVICE_MINOR_DEVICE_CLASS  = 0x0F
+
+    HEALTH_MINOR_DEVICE_CLASS_NAMES = {
+        HEALTH_UNDEFINED_MINOR_DEVICE_CLASS:                 'Undefined',
+        HEALTH_BLOOD_PRESSURE_MONITOR_MINOR_DEVICE_CLASS:    'Blood Pressure Monitor',
+        HEALTH_THERMOMETER_MINOR_DEVICE_CLASS:               'Thermometer',
+        HEALTH_WEIGHING_SCALE_MINOR_DEVICE_CLASS:            'Weighing Scale',
+        HEALTH_GLUCOSE_METER_MINOR_DEVICE_CLASS:             'Glucose Meter',
+        HEALTH_PULSE_OXIMETER_MINOR_DEVICE_CLASS:            'Pulse Oximeter',
+        HEALTH_HEART_PULSE_RATE_MONITOR_MINOR_DEVICE_CLASS:  'Heart/Pulse Rate Monitor',
+        HEALTH_HEALTH_DATA_DISPLAY_MINOR_DEVICE_CLASS:       'Health Data Display',
+        HEALTH_STEP_COUNTER_MINOR_DEVICE_CLASS:              'Step Counter',
+        HEALTH_BODY_COMPOSITION_ANALYZER_MINOR_DEVICE_CLASS: 'Body Composition Analyzer',
+        HEALTH_PEAK_FLOW_MONITOR_MINOR_DEVICE_CLASS:         'Peak Flow Monitor',
+        HEALTH_MEDICATION_MONITOR_MINOR_DEVICE_CLASS:        'Medication Monitor',
+        HEALTH_KNEE_PROSTHESIS_MINOR_DEVICE_CLASS:           'Knee Prosthesis',
+        HEALTH_ANKLE_PROSTHESIS_MINOR_DEVICE_CLASS:          'Ankle Prosthesis',
+        HEALTH_GENERIC_HEALTH_MANAGER_MINOR_DEVICE_CLASS:    'Generic Health Manager',
+        HEALTH_PERSONAL_MOBILITY_DEVICE_MINOR_DEVICE_CLASS:  'Personal Mobility Device',
+    }
+
     MINOR_DEVICE_CLASS_NAMES = {
         COMPUTER_MAJOR_DEVICE_CLASS:    COMPUTER_MINOR_DEVICE_CLASS_NAMES,
         PHONE_MAJOR_DEVICE_CLASS:       PHONE_MINOR_DEVICE_CLASS_NAMES,
         AUDIO_VIDEO_MAJOR_DEVICE_CLASS: AUDIO_VIDEO_MINOR_DEVICE_CLASS_NAMES,
-        PERIPHERAL_MAJOR_DEVICE_CLASS:  PERIPHERAL_MINOR_DEVICE_CLASS_NAMES
+        PERIPHERAL_MAJOR_DEVICE_CLASS:  PERIPHERAL_MINOR_DEVICE_CLASS_NAMES,
+        WEARABLE_MAJOR_DEVICE_CLASS:    WEARABLE_MINOR_DEVICE_CLASS_NAMES,
+        TOY_MAJOR_DEVICE_CLASS:         TOY_MINOR_DEVICE_CLASS_NAMES,
+        HEALTH_MAJOR_DEVICE_CLASS:      HEALTH_MINOR_DEVICE_CLASS_NAMES,
     }
 
     # fmt: on
@@ -773,7 +845,7 @@ class AdvertisingData:
     def uuid_list_to_objects(ad_data: bytes, uuid_size: int) -> List[UUID]:
         uuids = []
         offset = 0
-        while (uuid_size * (offset + 1)) <= len(ad_data):
+        while (offset + uuid_size) <= len(ad_data):
             uuids.append(UUID.from_bytes(ad_data[offset : offset + uuid_size]))
             offset += uuid_size
         return uuids

bumble/crypto.py

@@ -23,22 +23,18 @@
 # -----------------------------------------------------------------------------
 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,
+    EllipticCurvePublicNumbers,
+    EllipticCurvePrivateNumbers,
+    SECP256R1,
+)
+from cryptography.hazmat.primitives import cmac
+
 
 # -----------------------------------------------------------------------------
 # Logging

bumble/decoder.py

@@ -0,0 +1,416 @@
+# 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.
+
+# -----------------------------------------------------------------------------
+# 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(object):
+    """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):
+        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) -> bytearray:
+        result_array = bytearray(len(encoded_data) * 4)
+        self.g722_decode(result_array, encoded_data)
+        return result_array
+
+    def g722_decode(self, result_array, encoded_data) -> int:
+        """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, byte_length, byte_array) -> 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:
+        """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:
+        """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(object):
+    """Structure for G722 decode proccessing."""
+
+    s: int = 0
+    nb: int = 0
+    det: int = 0
+
+    def __init__(self):
+        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,91 @@
+# 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
+# -----------------------------------------------------------------------------
+import abc
+import logging
+import pathlib
+import platform
+from . import rtk
+
+
+# -----------------------------------------------------------------------------
+# Logging
+# -----------------------------------------------------------------------------
+logger = logging.getLogger(__name__)
+
+
+# -----------------------------------------------------------------------------
+# Classes
+# -----------------------------------------------------------------------------
+class Driver(abc.ABC):
+    """Base class for drivers."""
+
+    @staticmethod
+    async def for_host(_host):
+        """Return a driver instance for a host.
+
+        Args:
+            host: Host object for which a driver should be created.
+
+        Returns:
+            A Driver instance if a driver should be instantiated for this host, or
+            None if no driver instance of this class is needed.
+        """
+        return None
+
+    @abc.abstractmethod
+    async def init_controller(self):
+        """Initialize the controller."""
+
+
+# -----------------------------------------------------------------------------
+# Functions
+# -----------------------------------------------------------------------------
+async def get_driver_for_host(host):
+    """Probe all known diver classes until one returns a valid instance for a host,
+    or none is found.
+    """
+    if driver := await rtk.Driver.for_host(host):
+        logger.debug("Instantiated RTK driver")
+        return driver
+
+    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/rtk.py

@@ -0,0 +1,659 @@
+# 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.hci import (
+    hci_vendor_command_op_code,
+    STATUS_SPEC,
+    HCI_SUCCESS,
+    HCI_Command,
+    HCI_Reset_Command,
+    HCI_Read_Local_Version_Information_Command,
+)
+
+
+# -----------------------------------------------------------------------------
+# Logging
+# -----------------------------------------------------------------------------
+logger = logging.getLogger(__name__)
+
+
+# -----------------------------------------------------------------------------
+# 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 ValueError("Firmware does not start with epatch signature")
+
+        if not firmware.endswith(extension_sig):
+            raise ValueError("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 ValueError("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 ValueError("Invalid 0-length instruction")
+
+            if opcode == 0 and length == 1:
+                project_id = firmware[offset - 1]
+                break
+
+            offset -= length
+
+        if project_id < 0:
+            raise ValueError("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 ValueError("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 ValueError("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:
+    @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 = ""
+
+    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
+
+        vendor_id = host.hci_metadata.get("vendor_id", None)
+        product_id = host.hci_metadata.get("product_id", None)
+        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):
+        response = await host.send_command(
+            HCI_Read_Local_Version_Information_Command(), check_result=True
+        )
+        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 ValueError("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

@@ -41,14 +41,14 @@ class GenericAccessService(Service):
     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],
         )
 
         appearance_characteristic = Characteristic(
             GATT_APPEARANCE_CHARACTERISTIC,
-            Characteristic.READ,
+            Characteristic.Properties.READ,
             Characteristic.READABLE,
             struct.pack('<H', (appearance[0] << 6) | appearance[1]),
         )

bumble/gatt.py

@@ -28,7 +28,7 @@ import enum
 import functools
 import logging
 import struct
-from typing import Optional, Sequence
+from typing import Optional, Sequence, List
 
 from .colors import color
 from .core import UUID, get_dict_key_by_value
@@ -205,8 +205,16 @@ class Service(Attribute):
     '''
 
     uuid: UUID
+    characteristics: List[Characteristic]
+    included_services: List[Service]
 
-    def __init__(self, uuid, characteristics: list[Characteristic], primary=True):
+    def __init__(
+        self,
+        uuid,
+        characteristics: List[Characteristic],
+        primary=True,
+        included_services: List[Service] = [],
+    ):
         # Convert the uuid to a UUID object if it isn't already
         if isinstance(uuid, str):
             uuid = UUID(uuid)
@@ -219,7 +227,7 @@ class Service(Attribute):
             uuid.to_pdu_bytes(),
         )
         self.uuid = uuid
-        # self.included_services = []
+        self.included_services = included_services[:]
         self.characteristics = characteristics[:]
         self.primary = primary
 
@@ -247,75 +255,108 @@ class TemplateService(Service):
     to expose their UUID as a class property
     '''
 
-    UUID = None
+    UUID: Optional[UUID] = None
 
     def __init__(self, characteristics, primary=True):
         super().__init__(self.UUID, characteristics, primary)
 
 
+# -----------------------------------------------------------------------------
+class IncludedServiceDeclaration(Attribute):
+    '''
+    See Vol 3, Part G - 3.2 INCLUDE DEFINITION
+    '''
+
+    service: Service
+
+    def __init__(self, service):
+        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):
+        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})'
+        )
+
+
 # -----------------------------------------------------------------------------
 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_int):
-        return Characteristic.PROPERTY_NAMES.get(property_int, '')
+        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
-                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}"
+                )
 
-    @staticmethod
-    def string_to_properties(properties_str: str):
-        return functools.reduce(
-            lambda x, y: x | get_dict_key_by_value(Characteristic.PROPERTY_NAMES, y),
-            properties_str.split(","),
-            0,
-        )
+        def __str__(self):
+            # 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,
-        properties,
+        properties: Characteristic.Properties,
         permissions,
         value=b'',
         descriptors: Sequence[Descriptor] = (),
     ):
         super().__init__(uuid, permissions, value)
         self.uuid = self.type
-        if isinstance(properties, str):
-            self.properties = Characteristic.string_to_properties(properties)
-        else:
-            self.properties = properties
+        self.properties = properties
         self.descriptors = descriptors
 
     def get_descriptor(self, descriptor_type):
@@ -325,12 +366,15 @@ class Characteristic(Attribute):
 
         return None
 
+    def has_properties(self, properties: Characteristic.Properties) -> bool:
+        return self.properties & properties == properties
+
     def __str__(self):
         return (
             f'Characteristic(handle=0x{self.handle:04X}, '
             f'end=0x{self.end_group_handle:04X}, '
             f'uuid={self.uuid}, '
-            f'properties={Characteristic.properties_as_string(self.properties)})'
+            f'{self.properties})'
         )
 
 
@@ -340,6 +384,8 @@ class CharacteristicDeclaration(Attribute):
     See Vol 3, Part G - 3.3.1 CHARACTERISTIC DECLARATION
     '''
 
+    characteristic: Characteristic
+
     def __init__(self, characteristic, value_handle):
         declaration_bytes = (
             struct.pack('<BH', characteristic.properties, value_handle)
@@ -355,8 +401,8 @@ class CharacteristicDeclaration(Attribute):
         return (
             f'CharacteristicDeclaration(handle=0x{self.handle:04X}, '
             f'value_handle=0x{self.value_handle:04X}, '
-            f'uuid={self.characteristic.uuid}, properties='
-            f'{Characteristic.properties_as_string(self.characteristic.properties)})'
+            f'uuid={self.characteristic.uuid}, '
+            f'{self.characteristic.properties})'
         )
 
 

bumble/gatt_client.py

@@ -23,9 +23,12 @@
 # -----------------------------------------------------------------------------
 # Imports
 # -----------------------------------------------------------------------------
+from __future__ import annotations
 import asyncio
 import logging
 import struct
+from datetime import datetime
+from typing import List, Optional, Dict, Tuple, Callable, Union, Any
 
 from pyee import EventEmitter
 
@@ -50,6 +53,7 @@ from .att import (
     ATT_Read_Request,
     ATT_Write_Command,
     ATT_Write_Request,
+    ATT_Error,
 )
 from . import core
 from .core import UUID, InvalidStateError, ProtocolError
@@ -59,6 +63,7 @@ from .gatt import (
     GATT_PRIMARY_SERVICE_ATTRIBUTE_TYPE,
     GATT_REQUEST_TIMEOUT,
     GATT_SECONDARY_SERVICE_ATTRIBUTE_TYPE,
+    GATT_INCLUDE_ATTRIBUTE_TYPE,
     Characteristic,
     ClientCharacteristicConfigurationBits,
 )
@@ -73,6 +78,8 @@ logger = logging.getLogger(__name__)
 # Proxies
 # -----------------------------------------------------------------------------
 class AttributeProxy(EventEmitter):
+    client: Client
+
     def __init__(self, client, handle, end_group_handle, attribute_type):
         EventEmitter.__init__(self)
         self.client = client
@@ -101,6 +108,10 @@ class AttributeProxy(EventEmitter):
 
 
 class ServiceProxy(AttributeProxy):
+    uuid: UUID
+    characteristics: List[CharacteristicProxy]
+    included_services: List[ServiceProxy]
+
     @staticmethod
     def from_client(service_class, client, service_uuid):
         # The service and its characteristics are considered to have already been
@@ -130,10 +141,21 @@ class ServiceProxy(AttributeProxy):
 
 
 class CharacteristicProxy(AttributeProxy):
-    def __init__(self, client, handle, end_group_handle, uuid, properties):
+    properties: Characteristic.Properties
+    descriptors: List[DescriptorProxy]
+    subscribers: Dict[Any, Callable]
+
+    def __init__(
+        self,
+        client,
+        handle,
+        end_group_handle,
+        uuid,
+        properties: int,
+    ):
         super().__init__(client, handle, end_group_handle, uuid)
         self.uuid = uuid
-        self.properties = properties
+        self.properties = Characteristic.Properties(properties)
         self.descriptors = []
         self.descriptors_discovered = False
         self.subscribers = {}  # Map from subscriber to proxy subscriber
@@ -148,7 +170,9 @@ class CharacteristicProxy(AttributeProxy):
     async def discover_descriptors(self):
         return await self.client.discover_descriptors(self)
 
-    async def subscribe(self, subscriber=None, prefer_notify=True):
+    async def subscribe(
+        self, subscriber: Optional[Callable] = None, prefer_notify=True
+    ):
         if subscriber is not None:
             if subscriber in self.subscribers:
                 # We already have a proxy subscriber
@@ -175,7 +199,7 @@ class CharacteristicProxy(AttributeProxy):
         return (
             f'Characteristic(handle=0x{self.handle:04X}, '
             f'uuid={self.uuid}, '
-            f'properties={Characteristic.properties_as_string(self.properties)})'
+            f'{self.properties!s})'
         )
 
 
@@ -201,6 +225,9 @@ class ProfileServiceProxy:
 # GATT Client
 # -----------------------------------------------------------------------------
 class Client:
+    services: List[ServiceProxy]
+    cached_values: Dict[int, Tuple[datetime, bytes]]
+
     def __init__(self, connection):
         self.connection = connection
         self.mtu_exchange_done = False
@@ -212,6 +239,7 @@ class Client:
         )  # Notification subscribers, by attribute handle
         self.indication_subscribers = {}  # Indication subscribers, by attribute handle
         self.services = []
+        self.cached_values = {}
 
     def send_gatt_pdu(self, pdu):
         self.connection.send_l2cap_pdu(ATT_CID, pdu)
@@ -296,6 +324,35 @@ class Client:
             if c.uuid == uuid
         ]
 
+    def get_attribute_grouping(
+        self, attribute_handle: int
+    ) -> Optional[
+        Union[
+            ServiceProxy,
+            Tuple[ServiceProxy, CharacteristicProxy],
+            Tuple[ServiceProxy, CharacteristicProxy, DescriptorProxy],
+        ]
+    ]:
+        """
+        Get the attribute(s) associated with an attribute handle
+        """
+        for service in self.services:
+            if service.handle == attribute_handle:
+                return service
+            if service.handle <= attribute_handle <= service.end_group_handle:
+                for characteristic in service.characteristics:
+                    if characteristic.handle == attribute_handle:
+                        return (service, characteristic)
+                    if (
+                        characteristic.handle
+                        <= attribute_handle
+                        <= characteristic.end_group_handle
+                    ):
+                        for descriptor in characteristic.descriptors:
+                            if descriptor.handle == attribute_handle:
+                                return (service, characteristic, descriptor)
+        return None
+
     def on_service_discovered(self, service):
         '''Add a service to the service list if it wasn't already there'''
         already_known = False
@@ -306,7 +363,7 @@ class Client:
         if not already_known:
             self.services.append(service)
 
-    async def discover_services(self, uuids=None):
+    async def discover_services(self, uuids=None) -> List[ServiceProxy]:
         '''
         See Vol 3, Part G - 4.4.1 Discover All Primary Services
         '''
@@ -332,8 +389,10 @@ class Client:
                         '!!! unexpected error while discovering services: '
                         f'{HCI_Constant.error_name(response.error_code)}'
                     )
-                    # TODO raise appropriate exception
-                    return
+                    raise ATT_Error(
+                        error_code=response.error_code,
+                        message='Unexpected error while discovering services',
+                    )
                 break
 
             for (
@@ -349,7 +408,7 @@ class Client:
                     logger.warning(
                         f'bogus handle values: {attribute_handle} {end_group_handle}'
                     )
-                    return
+                    return []
 
                 # Create a service proxy for this service
                 service = ServiceProxy(
@@ -445,14 +504,73 @@ class Client:
 
         return services
 
-    async def discover_included_services(self, _service):
+    async def discover_included_services(
+        self, service: ServiceProxy
+    ) -> List[ServiceProxy]:
         '''
         See Vol 3, Part G - 4.5.1 Find Included Services
         '''
-        # TODO
-        return []
 
-    async def discover_characteristics(self, uuids, service):
+        starting_handle = service.handle
+        ending_handle = service.end_group_handle
+
+        included_services: List[ServiceProxy] = []
+        while starting_handle <= ending_handle:
+            response = await self.send_request(
+                ATT_Read_By_Type_Request(
+                    starting_handle=starting_handle,
+                    ending_handle=ending_handle,
+                    attribute_type=GATT_INCLUDE_ATTRIBUTE_TYPE,
+                )
+            )
+            if response is None:
+                # TODO raise appropriate exception
+                return []
+
+            # Check if we reached the end of the iteration
+            if response.op_code == ATT_ERROR_RESPONSE:
+                if response.error_code != ATT_ATTRIBUTE_NOT_FOUND_ERROR:
+                    # Unexpected end
+                    logger.warning(
+                        '!!! unexpected error while discovering included services: '
+                        f'{HCI_Constant.error_name(response.error_code)}'
+                    )
+                    raise ATT_Error(
+                        error_code=response.error_code,
+                        message='Unexpected error while discovering included services',
+                    )
+                break
+
+            # Stop if for some reason the list was empty
+            if not response.attributes:
+                break
+
+            # Process all included services returned in this iteration
+            for attribute_handle, attribute_value in response.attributes:
+                if attribute_handle < starting_handle:
+                    # Something's not right
+                    logger.warning(f'bogus handle value: {attribute_handle}')
+                    return []
+
+                group_starting_handle, group_ending_handle = struct.unpack_from(
+                    '<HH', attribute_value
+                )
+                service_uuid = UUID.from_bytes(attribute_value[4:])
+                included_service = ServiceProxy(
+                    self, group_starting_handle, group_ending_handle, service_uuid, True
+                )
+
+                included_services.append(included_service)
+
+            # Move on to the next included services
+            starting_handle = response.attributes[-1][0] + 1
+
+        service.included_services = included_services
+        return included_services
+
+    async def discover_characteristics(
+        self, uuids, service: Optional[ServiceProxy]
+    ) -> List[CharacteristicProxy]:
         '''
         See Vol 3, Part G - 4.6.1 Discover All Characteristics of a Service and 4.6.2
         Discover Characteristics by UUID
@@ -465,12 +583,12 @@ class Client:
         services = [service] if service else self.services
 
         # Perform characteristic discovery for each service
-        discovered_characteristics = []
+        discovered_characteristics: List[CharacteristicProxy] = []
         for service in services:
             starting_handle = service.handle
             ending_handle = service.end_group_handle
 
-            characteristics = []
+            characteristics: List[CharacteristicProxy] = []
             while starting_handle <= ending_handle:
                 response = await self.send_request(
                     ATT_Read_By_Type_Request(
@@ -491,8 +609,10 @@ class Client:
                             '!!! unexpected error while discovering characteristics: '
                             f'{HCI_Constant.error_name(response.error_code)}'
                         )
-                        # TODO raise appropriate exception
-                        return
+                        raise ATT_Error(
+                            error_code=response.error_code,
+                            message='Unexpected error while discovering characteristics',
+                        )
                     break
 
                 # Stop if for some reason the list was empty
@@ -535,8 +655,11 @@ class Client:
         return discovered_characteristics
 
     async def discover_descriptors(
-        self, characteristic=None, start_handle=None, end_handle=None
-    ):
+        self,
+        characteristic: Optional[CharacteristicProxy] = None,
+        start_handle=None,
+        end_handle=None,
+    ) -> List[DescriptorProxy]:
         '''
         See Vol 3, Part G - 4.7.1 Discover All Characteristic Descriptors
         '''
@@ -549,7 +672,7 @@ class Client:
         else:
             return []
 
-        descriptors = []
+        descriptors: List[DescriptorProxy] = []
         while starting_handle <= ending_handle:
             response = await self.send_request(
                 ATT_Find_Information_Request(
@@ -656,8 +779,8 @@ class Client:
             return
 
         if (
-            characteristic.properties & Characteristic.NOTIFY
-            and characteristic.properties & Characteristic.INDICATE
+            characteristic.properties & Characteristic.Properties.NOTIFY
+            and characteristic.properties & Characteristic.Properties.INDICATE
         ):
             if prefer_notify:
                 bits = ClientCharacteristicConfigurationBits.NOTIFICATION
@@ -665,10 +788,10 @@ class Client:
             else:
                 bits = ClientCharacteristicConfigurationBits.INDICATION
                 subscribers = self.indication_subscribers
-        elif characteristic.properties & Characteristic.NOTIFY:
+        elif characteristic.properties & Characteristic.Properties.NOTIFY:
             bits = ClientCharacteristicConfigurationBits.NOTIFICATION
             subscribers = self.notification_subscribers
-        elif characteristic.properties & Characteristic.INDICATE:
+        elif characteristic.properties & Characteristic.Properties.INDICATE:
             bits = ClientCharacteristicConfigurationBits.INDICATION
             subscribers = self.indication_subscribers
         else:
@@ -778,6 +901,7 @@ class Client:
 
                 offset += len(part)
 
+        self.cache_value(attribute_handle, attribute_value)
         # Return the value as bytes
         return attribute_value
 
@@ -912,6 +1036,8 @@ class Client:
         )
         if not subscribers:
             logger.warning('!!! received notification with no subscriber')
+
+        self.cache_value(notification.attribute_handle, notification.attribute_value)
         for subscriber in subscribers:
             if callable(subscriber):
                 subscriber(notification.attribute_value)
@@ -923,6 +1049,8 @@ class Client:
         subscribers = self.indication_subscribers.get(indication.attribute_handle, [])
         if not subscribers:
             logger.warning('!!! received indication with no subscriber')
+
+        self.cache_value(indication.attribute_handle, indication.attribute_value)
         for subscriber in subscribers:
             if callable(subscriber):
                 subscriber(indication.attribute_value)
@@ -931,3 +1059,9 @@ class Client:
 
         # Confirm that we received the indication
         self.send_confirmation(ATT_Handle_Value_Confirmation())
+
+    def cache_value(self, attribute_handle: int, value: bytes):
+        self.cached_values[attribute_handle] = (
+            datetime.now(),
+            value,
+        )

bumble/gatt_server.py

@@ -27,7 +27,7 @@ import asyncio
 import logging
 from collections import defaultdict
 import struct
-from typing import List, Tuple, Optional
+from typing import List, Tuple, Optional, TypeVar, Type
 from pyee import EventEmitter
 
 from .colors import color
@@ -68,6 +68,7 @@ from .gatt import (
     Characteristic,
     CharacteristicDeclaration,
     CharacteristicValue,
+    IncludedServiceDeclaration,
     Descriptor,
     Service,
 )
@@ -94,6 +95,7 @@ class Server(EventEmitter):
     def __init__(self, device):
         super().__init__()
         self.device = device
+        self.services = []
         self.attributes = []  # Attributes, ordered by increasing handle values
         self.attributes_by_handle = {}  # Map for fast attribute access by handle
         self.max_mtu = (
@@ -135,6 +137,21 @@ class Server(EventEmitter):
                 return attribute
         return None
 
+    AttributeGroupType = TypeVar('AttributeGroupType', Service, Characteristic)
+
+    def get_attribute_group(
+        self, handle: int, group_type: Type[AttributeGroupType]
+    ) -> Optional[AttributeGroupType]:
+        return next(
+            (
+                attribute
+                for attribute in self.attributes
+                if isinstance(attribute, group_type)
+                and attribute.handle <= handle <= attribute.end_group_handle
+            ),
+            None,
+        )
+
     def get_service_attribute(self, service_uuid: UUID) -> Optional[Service]:
         return next(
             (
@@ -207,7 +224,14 @@ class Server(EventEmitter):
         # Add the service attribute to the DB
         self.add_attribute(service)
 
-        # TODO: add included services
+        # Add all included service
+        for included_service in service.included_services:
+            # Not registered yet, register the included service first.
+            if included_service not in self.services:
+                self.add_service(included_service)
+                # TODO: Handle circular service reference
+            include_declaration = IncludedServiceDeclaration(included_service)
+            self.add_attribute(include_declaration)
 
         # Add all characteristics
         for characteristic in service.characteristics:
@@ -228,7 +252,10 @@ class Server(EventEmitter):
             # unless there is one already
             if (
                 characteristic.properties
-                & (Characteristic.NOTIFY | Characteristic.INDICATE)
+                & (
+                    Characteristic.Properties.NOTIFY
+                    | Characteristic.Properties.INDICATE
+                )
                 and characteristic.get_descriptor(
                     GATT_CLIENT_CHARACTERISTIC_CONFIGURATION_DESCRIPTOR
                 )
@@ -256,6 +283,7 @@ class Server(EventEmitter):
 
         # Update the service group end
         service.end_group_handle = self.attributes[-1].handle
+        self.services.append(service)
 
     def add_services(self, services):
         for service in services:
@@ -691,7 +719,7 @@ class Server(EventEmitter):
                 length=entry_size, attribute_data_list=b''.join(attribute_data_list)
             )
         else:
-            logging.warning(f"not found {request}")
+            logging.debug(f"not found {request}")
 
         self.send_response(connection, response)
 

bumble/hfp.py

@@ -1,4 +1,4 @@
-# Copyright 2021-2022 Google LLC
+# 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.
@@ -15,11 +15,35 @@
 # -----------------------------------------------------------------------------
 # Imports
 # -----------------------------------------------------------------------------
+import collections.abc
 import logging
 import asyncio
-import collections
+import dataclasses
+import enum
+import traceback
+import warnings
+from typing import Dict, List, Union, Set, TYPE_CHECKING
 
-from .colors import color
+from . import at
+from . import rfcomm
+
+from bumble.colors import color
+from bumble.core import (
+    ProtocolError,
+    BT_GENERIC_AUDIO_SERVICE,
+    BT_HANDSFREE_SERVICE,
+    BT_L2CAP_PROTOCOL_ID,
+    BT_RFCOMM_PROTOCOL_ID,
+)
+from bumble.sdp import (
+    DataElement,
+    ServiceAttribute,
+    SDP_SERVICE_RECORD_HANDLE_ATTRIBUTE_ID,
+    SDP_SERVICE_CLASS_ID_LIST_ATTRIBUTE_ID,
+    SDP_PROTOCOL_DESCRIPTOR_LIST_ATTRIBUTE_ID,
+    SDP_BLUETOOTH_PROFILE_DESCRIPTOR_LIST_ATTRIBUTE_ID,
+    SDP_SUPPORTED_FEATURES_ATTRIBUTE_ID,
+)
 
 
 # -----------------------------------------------------------------------------
@@ -27,6 +51,15 @@ from .colors import color
 # -----------------------------------------------------------------------------
 logger = logging.getLogger(__name__)
 
+# -----------------------------------------------------------------------------
+# Error
+# -----------------------------------------------------------------------------
+
+
+class HfpProtocolError(ProtocolError):
+    def __init__(self, error_name: str = '', details: str = ''):
+        super().__init__(None, 'hfp', error_name, details)
+
 
 # -----------------------------------------------------------------------------
 # Protocol Support
@@ -34,7 +67,13 @@ logger = logging.getLogger(__name__)
 
 # -----------------------------------------------------------------------------
 class HfpProtocol:
-    def __init__(self, dlc):
+    dlc: rfcomm.DLC
+    buffer: str
+    lines: collections.deque
+    lines_available: asyncio.Event
+
+    def __init__(self, dlc: rfcomm.DLC) -> None:
+        warnings.warn("See HfProtocol", DeprecationWarning)
         self.dlc = dlc
         self.buffer = ''
         self.lines = collections.deque()
@@ -42,7 +81,7 @@ class HfpProtocol:
 
         dlc.sink = self.feed
 
-    def feed(self, data):
+    def feed(self, data: Union[bytes, str]) -> None:
         # Convert the data to a string if needed
         if isinstance(data, bytes):
             data = data.decode('utf-8')
@@ -57,19 +96,19 @@ class HfpProtocol:
             if len(line) > 0:
                 self.on_line(line)
 
-    def on_line(self, line):
+    def on_line(self, line: str) -> None:
         self.lines.append(line)
         self.lines_available.set()
 
-    def send_command_line(self, line):
+    def send_command_line(self, line: str) -> None:
         logger.debug(color(f'>>> {line}', 'yellow'))
         self.dlc.write(line + '\r')
 
-    def send_response_line(self, line):
+    def send_response_line(self, line: str) -> None:
         logger.debug(color(f'>>> {line}', 'yellow'))
         self.dlc.write('\r\n' + line + '\r\n')
 
-    async def next_line(self):
+    async def next_line(self) -> str:
         await self.lines_available.wait()
         line = self.lines.popleft()
         if not self.lines:
@@ -77,19 +116,706 @@ class HfpProtocol:
         logger.debug(color(f'<<< {line}', 'green'))
         return line
 
-    async def initialize_service(self):
-        # Perform Service Level Connection Initialization
-        self.send_command_line('AT+BRSF=2072')  # Retrieve Supported Features
-        await (self.next_line())
-        await (self.next_line())
 
-        self.send_command_line('AT+CIND=?')
-        await (self.next_line())
-        await (self.next_line())
+# -----------------------------------------------------------------------------
+# Normative protocol definitions
+# -----------------------------------------------------------------------------
 
-        self.send_command_line('AT+CIND?')
-        await (self.next_line())
-        await (self.next_line())
 
-        self.send_command_line('AT+CMER=3,0,0,1')
-        await (self.next_line())
+# HF supported features (AT+BRSF=) (normative).
+# Hands-Free Profile v1.8, 4.34.2, AT Capabilities Re-Used from GSM 07.07
+# and 3GPP 27.007
+class HfFeature(enum.IntFlag):
+    EC_NR = 0x001  # Echo Cancel & Noise reduction
+    THREE_WAY_CALLING = 0x002
+    CLI_PRESENTATION_CAPABILITY = 0x004
+    VOICE_RECOGNITION_ACTIVATION = 0x008
+    REMOTE_VOLUME_CONTROL = 0x010
+    ENHANCED_CALL_STATUS = 0x020
+    ENHANCED_CALL_CONTROL = 0x040
+    CODEC_NEGOTIATION = 0x080
+    HF_INDICATORS = 0x100
+    ESCO_S4_SETTINGS_SUPPORTED = 0x200
+    ENHANCED_VOICE_RECOGNITION_STATUS = 0x400
+    VOICE_RECOGNITION_TEST = 0x800
+
+
+# AG supported features (+BRSF:) (normative).
+# Hands-Free Profile v1.8, 4.34.2, AT Capabilities Re-Used from GSM 07.07
+# and 3GPP 27.007
+class AgFeature(enum.IntFlag):
+    THREE_WAY_CALLING = 0x001
+    EC_NR = 0x002  # Echo Cancel & Noise reduction
+    VOICE_RECOGNITION_FUNCTION = 0x004
+    IN_BAND_RING_TONE_CAPABILITY = 0x008
+    VOICE_TAG = 0x010  # Attach a number to voice tag
+    REJECT_CALL = 0x020  # Ability to reject a call
+    ENHANCED_CALL_STATUS = 0x040
+    ENHANCED_CALL_CONTROL = 0x080
+    EXTENDED_ERROR_RESULT_CODES = 0x100
+    CODEC_NEGOTIATION = 0x200
+    HF_INDICATORS = 0x400
+    ESCO_S4_SETTINGS_SUPPORTED = 0x800
+    ENHANCED_VOICE_RECOGNITION_STATUS = 0x1000
+    VOICE_RECOGNITION_TEST = 0x2000
+
+
+# Audio Codec IDs (normative).
+# Hands-Free Profile v1.8, 10 Appendix B
+class AudioCodec(enum.IntEnum):
+    CVSD = 0x01  # Support for CVSD audio codec
+    MSBC = 0x02  # Support for mSBC audio codec
+
+
+# HF Indicators (normative).
+# Bluetooth Assigned Numbers, 6.10.1 HF Indicators
+class HfIndicator(enum.IntEnum):
+    ENHANCED_SAFETY = 0x01  # Enhanced safety feature
+    BATTERY_LEVEL = 0x02  # Battery level feature
+
+
+# Call Hold supported operations (normative).
+# AT Commands Reference Guide, 3.5.2.3.12 +CHLD - Call Holding Services
+class CallHoldOperation(enum.IntEnum):
+    RELEASE_ALL_HELD_CALLS = 0  # Release all held calls
+    RELEASE_ALL_ACTIVE_CALLS = 1  # Release all active calls, accept other
+    HOLD_ALL_ACTIVE_CALLS = 2  # Place all active calls on hold, accept other
+    ADD_HELD_CALL = 3  # Adds a held call to conversation
+
+
+# Response Hold status (normative).
+# Hands-Free Profile v1.8, 4.34.2, AT Capabilities Re-Used from GSM 07.07
+# and 3GPP 27.007
+class ResponseHoldStatus(enum.IntEnum):
+    INC_CALL_HELD = 0  # Put incoming call on hold
+    HELD_CALL_ACC = 1  # Accept a held incoming call
+    HELD_CALL_REJ = 2  # Reject a held incoming call
+
+
+# Values for the Call Setup AG indicator (normative).
+# Hands-Free Profile v1.8, 4.34.2, AT Capabilities Re-Used from GSM 07.07
+# and 3GPP 27.007
+class CallSetupAgIndicator(enum.IntEnum):
+    NOT_IN_CALL_SETUP = 0
+    INCOMING_CALL_PROCESS = 1
+    OUTGOING_CALL_SETUP = 2
+    REMOTE_ALERTED = 3  # Remote party alerted in an outgoing call
+
+
+# Values for the Call Held AG indicator (normative).
+# Hands-Free Profile v1.8, 4.34.2, AT Capabilities Re-Used from GSM 07.07
+# and 3GPP 27.007
+class CallHeldAgIndicator(enum.IntEnum):
+    NO_CALLS_HELD = 0
+    # Call is placed on hold or active/held calls swapped
+    # (The AG has both an active AND a held call)
+    CALL_ON_HOLD_AND_ACTIVE_CALL = 1
+    CALL_ON_HOLD_NO_ACTIVE_CALL = 2  # Call on hold, no active call
+
+
+# Call Info direction (normative).
+# AT Commands Reference Guide, 3.5.2.3.15 +CLCC - List Current Calls
+class CallInfoDirection(enum.IntEnum):
+    MOBILE_ORIGINATED_CALL = 0
+    MOBILE_TERMINATED_CALL = 1
+
+
+# Call Info status (normative).
+# AT Commands Reference Guide, 3.5.2.3.15 +CLCC - List Current Calls
+class CallInfoStatus(enum.IntEnum):
+    ACTIVE = 0
+    HELD = 1
+    DIALING = 2
+    ALERTING = 3
+    INCOMING = 4
+    WAITING = 5
+
+
+# Call Info mode (normative).
+# AT Commands Reference Guide, 3.5.2.3.15 +CLCC - List Current Calls
+class CallInfoMode(enum.IntEnum):
+    VOICE = 0
+    DATA = 1
+    FAX = 2
+    UNKNOWN = 9
+
+
+# -----------------------------------------------------------------------------
+# Hands-Free Control Interoperability Requirements
+# -----------------------------------------------------------------------------
+
+# Response codes.
+RESPONSE_CODES = [
+    "+APLSIRI",
+    "+BAC",
+    "+BCC",
+    "+BCS",
+    "+BIA",
+    "+BIEV",
+    "+BIND",
+    "+BINP",
+    "+BLDN",
+    "+BRSF",
+    "+BTRH",
+    "+BVRA",
+    "+CCWA",
+    "+CHLD",
+    "+CHUP",
+    "+CIND",
+    "+CLCC",
+    "+CLIP",
+    "+CMEE",
+    "+CMER",
+    "+CNUM",
+    "+COPS",
+    "+IPHONEACCEV",
+    "+NREC",
+    "+VGM",
+    "+VGS",
+    "+VTS",
+    "+XAPL",
+    "A",
+    "D",
+]
+
+# Unsolicited responses and statuses.
+UNSOLICITED_CODES = [
+    "+APLSIRI",
+    "+BCS",
+    "+BIND",
+    "+BSIR",
+    "+BTRH",
+    "+BVRA",
+    "+CCWA",
+    "+CIEV",
+    "+CLIP",
+    "+VGM",
+    "+VGS",
+    "BLACKLISTED",
+    "BUSY",
+    "DELAYED",
+    "NO ANSWER",
+    "NO CARRIER",
+    "RING",
+]
+
+# Status codes
+STATUS_CODES = [
+    "+CME ERROR",
+    "BLACKLISTED",
+    "BUSY",
+    "DELAYED",
+    "ERROR",
+    "NO ANSWER",
+    "NO CARRIER",
+    "OK",
+]
+
+
+@dataclasses.dataclass
+class Configuration:
+    supported_hf_features: List[HfFeature]
+    supported_hf_indicators: List[HfIndicator]
+    supported_audio_codecs: List[AudioCodec]
+
+
+class AtResponseType(enum.Enum):
+    """Indicate if a response is expected from an AT command, and if multiple
+    responses are accepted."""
+
+    NONE = 0
+    SINGLE = 1
+    MULTIPLE = 2
+
+
+class AtResponse:
+    code: str
+    parameters: list
+
+    def __init__(self, response: bytearray):
+        code_and_parameters = response.split(b':')
+        parameters = (
+            code_and_parameters[1] if len(code_and_parameters) > 1 else bytearray()
+        )
+        self.code = code_and_parameters[0].decode()
+        self.parameters = at.parse_parameters(parameters)
+
+
+@dataclasses.dataclass
+class AgIndicatorState:
+    description: str
+    index: int
+    supported_values: Set[int]
+    current_status: int
+
+
+@dataclasses.dataclass
+class HfIndicatorState:
+    supported: bool = False
+    enabled: bool = False
+
+
+class HfProtocol:
+    """Implementation for the Hands-Free side of the Hands-Free profile.
+    Reference specification Hands-Free Profile v1.8"""
+
+    supported_hf_features: int
+    supported_audio_codecs: List[AudioCodec]
+
+    supported_ag_features: int
+    supported_ag_call_hold_operations: List[CallHoldOperation]
+
+    ag_indicators: List[AgIndicatorState]
+    hf_indicators: Dict[HfIndicator, HfIndicatorState]
+
+    dlc: rfcomm.DLC
+    command_lock: asyncio.Lock
+    if TYPE_CHECKING:
+        response_queue: asyncio.Queue[AtResponse]
+        unsolicited_queue: asyncio.Queue[AtResponse]
+    else:
+        response_queue: asyncio.Queue
+        unsolicited_queue: asyncio.Queue
+    read_buffer: bytearray
+
+    def __init__(self, dlc: rfcomm.DLC, configuration: Configuration):
+        # Configure internal state.
+        self.dlc = dlc
+        self.command_lock = asyncio.Lock()
+        self.response_queue = asyncio.Queue()
+        self.unsolicited_queue = asyncio.Queue()
+        self.read_buffer = bytearray()
+
+        # Build local features.
+        self.supported_hf_features = sum(configuration.supported_hf_features)
+        self.supported_audio_codecs = configuration.supported_audio_codecs
+
+        self.hf_indicators = {
+            indicator: HfIndicatorState()
+            for indicator in configuration.supported_hf_indicators
+        }
+
+        # Clear remote features.
+        self.supported_ag_features = 0
+        self.supported_ag_call_hold_operations = []
+        self.ag_indicators = []
+
+        # Bind the AT reader to the RFCOMM channel.
+        self.dlc.sink = self._read_at
+
+    def supports_hf_feature(self, feature: HfFeature) -> bool:
+        return (self.supported_hf_features & feature) != 0
+
+    def supports_ag_feature(self, feature: AgFeature) -> bool:
+        return (self.supported_ag_features & feature) != 0
+
+    # Read AT messages from the RFCOMM channel.
+    # Enqueue AT commands, responses, unsolicited responses to their
+    # respective queues, and set the corresponding event.
+    def _read_at(self, data: bytes):
+        # Append to the read buffer.
+        self.read_buffer.extend(data)
+
+        # Locate header and trailer.
+        header = self.read_buffer.find(b'\r\n')
+        trailer = self.read_buffer.find(b'\r\n', header + 2)
+        if header == -1 or trailer == -1:
+            return
+
+        # Isolate the AT response code and parameters.
+        raw_response = self.read_buffer[header + 2 : trailer]
+        response = AtResponse(raw_response)
+        logger.debug(f"<<< {raw_response.decode()}")
+
+        # Consume the response bytes.
+        self.read_buffer = self.read_buffer[trailer + 2 :]
+
+        # Forward the received code to the correct queue.
+        if self.command_lock.locked() and (
+            response.code in STATUS_CODES or response.code in RESPONSE_CODES
+        ):
+            self.response_queue.put_nowait(response)
+        elif response.code in UNSOLICITED_CODES:
+            self.unsolicited_queue.put_nowait(response)
+        else:
+            logger.warning(f"dropping unexpected response with code '{response.code}'")
+
+    # Send an AT command and wait for the peer response.
+    # Wait for the AT responses sent by the peer, to the status code.
+    # Raises asyncio.TimeoutError if the status is not received
+    # after a timeout (default 1 second).
+    # Raises ProtocolError if the status is not OK.
+    async def execute_command(
+        self,
+        cmd: str,
+        timeout: float = 1.0,
+        response_type: AtResponseType = AtResponseType.NONE,
+    ) -> Union[None, AtResponse, List[AtResponse]]:
+        async with self.command_lock:
+            logger.debug(f">>> {cmd}")
+            self.dlc.write(cmd + '\r')
+            responses: List[AtResponse] = []
+
+            while True:
+                result = await asyncio.wait_for(
+                    self.response_queue.get(), timeout=timeout
+                )
+                if result.code == 'OK':
+                    if response_type == AtResponseType.SINGLE and len(responses) != 1:
+                        raise HfpProtocolError("NO ANSWER")
+
+                    if response_type == AtResponseType.MULTIPLE:
+                        return responses
+                    if response_type == AtResponseType.SINGLE:
+                        return responses[0]
+                    return None
+                if result.code in STATUS_CODES:
+                    raise HfpProtocolError(result.code)
+                responses.append(result)
+
+    # 4.2.1 Service Level Connection Initialization.
+    async def initiate_slc(self):
+        # 4.2.1.1 Supported features exchange
+        # First, in the initialization procedure, the HF shall send the
+        # AT+BRSF=<HF supported features> command to the AG to both notify
+        # the AG of the supported features in the HF, as well as to retrieve the
+        # supported features in the AG using the +BRSF result code.
+        response = await self.execute_command(
+            f"AT+BRSF={self.supported_hf_features}", response_type=AtResponseType.SINGLE
+        )
+
+        self.supported_ag_features = int(response.parameters[0])
+        logger.info(f"supported AG features: {self.supported_ag_features}")
+        for feature in AgFeature:
+            if self.supports_ag_feature(feature):
+                logger.info(f"  - {feature.name}")
+
+        # 4.2.1.2 Codec Negotiation
+        # Secondly, in the initialization procedure, if the HF supports the
+        # Codec Negotiation feature, it shall check if the AT+BRSF command
+        # response from the AG has indicated that it supports the Codec
+        # Negotiation feature.
+        if self.supports_hf_feature(
+            HfFeature.CODEC_NEGOTIATION
+        ) and self.supports_ag_feature(AgFeature.CODEC_NEGOTIATION):
+            # If both the HF and AG do support the Codec Negotiation feature
+            # then the HF shall send the AT+BAC=<HF available codecs> command to
+            # the AG to notify the AG of the available codecs in the HF.
+            codecs = [str(c) for c in self.supported_audio_codecs]
+            await self.execute_command(f"AT+BAC={','.join(codecs)}")
+
+        # 4.2.1.3 AG Indicators
+        # After having retrieved the supported features in the AG, the HF shall
+        # determine which indicators are supported by the AG, as well as the
+        # ordering of the supported indicators. This is because, according to
+        # the 3GPP 27.007 specification [2], the AG may support additional
+        # indicators not provided for by the Hands-Free Profile, and because the
+        # ordering of the indicators is implementation specific. The HF uses
+        # the AT+CIND=? Test command to retrieve information about the supported
+        # indicators and their ordering.
+        response = await self.execute_command(
+            "AT+CIND=?", response_type=AtResponseType.SINGLE
+        )
+
+        self.ag_indicators = []
+        for index, indicator in enumerate(response.parameters):
+            description = indicator[0].decode()
+            supported_values = []
+            for value in indicator[1]:
+                value = value.split(b'-')
+                value = [int(v) for v in value]
+                value_min = value[0]
+                value_max = value[1] if len(value) > 1 else value[0]
+                supported_values.extend([v for v in range(value_min, value_max + 1)])
+
+            self.ag_indicators.append(
+                AgIndicatorState(description, index, set(supported_values), 0)
+            )
+
+        # Once the HF has the necessary supported indicator and ordering
+        # information, it shall retrieve the current status of the indicators
+        # in the AG using the AT+CIND? Read command.
+        response = await self.execute_command(
+            "AT+CIND?", response_type=AtResponseType.SINGLE
+        )
+
+        for index, indicator in enumerate(response.parameters):
+            self.ag_indicators[index].current_status = int(indicator)
+
+        # After having retrieved the status of the indicators in the AG, the HF
+        # shall then enable the "Indicators status update" function in the AG by
+        # issuing the AT+CMER command, to which the AG shall respond with OK.
+        await self.execute_command("AT+CMER=3,,,1")
+
+        if self.supports_hf_feature(
+            HfFeature.THREE_WAY_CALLING
+        ) and self.supports_ag_feature(HfFeature.THREE_WAY_CALLING):
+            # After the HF has enabled the “Indicators status update” function in
+            # the AG, and if the “Call waiting and 3-way calling” bit was set in the
+            # supported features bitmap by both the HF and the AG, the HF shall
+            # issue the AT+CHLD=? test command to retrieve the information about how
+            # the call hold and multiparty services are supported in the AG. The HF
+            # shall not issue the AT+CHLD=? test command in case either the HF or
+            # the AG does not support the "Three-way calling" feature.
+            response = await self.execute_command(
+                "AT+CHLD=?", response_type=AtResponseType.SINGLE
+            )
+
+            self.supported_ag_call_hold_operations = [
+                CallHoldOperation(int(operation))
+                for operation in response.parameters[0]
+                if not b'x' in operation
+            ]
+
+        # 4.2.1.4 HF Indicators
+        # If the HF supports the HF indicator feature, it shall check the +BRSF
+        # response to see if the AG also supports the HF Indicator feature.
+        if self.supports_hf_feature(
+            HfFeature.HF_INDICATORS
+        ) and self.supports_ag_feature(AgFeature.HF_INDICATORS):
+            # If both the HF and AG support the HF Indicator feature, then the HF
+            # shall send the AT+BIND=<HF supported HF indicators> command to the AG
+            # to notify the AG of the supported indicators’ assigned numbers in the
+            # HF. The AG shall respond with OK
+            indicators = [str(i) for i in self.hf_indicators.keys()]
+            await self.execute_command(f"AT+BIND={','.join(indicators)}")
+
+            # After having provided the AG with the HF indicators it supports,
+            # the HF shall send the AT+BIND=? to request HF indicators supported
+            # by the AG. The AG shall reply with the +BIND response listing all
+            # HF indicators that it supports followed by an OK.
+            response = await self.execute_command(
+                "AT+BIND=?", response_type=AtResponseType.SINGLE
+            )
+
+            logger.info("supported HF indicators:")
+            for indicator in response.parameters[0]:
+                indicator = HfIndicator(int(indicator))
+                logger.info(f"  - {indicator.name}")
+                if indicator in self.hf_indicators:
+                    self.hf_indicators[indicator].supported = True
+
+            # Once the HF receives the supported HF indicators list from the AG,
+            # the HF shall send the AT+BIND? command to determine which HF
+            # indicators are enabled. The AG shall respond with one or more
+            # +BIND responses. The AG shall terminate the list with OK.
+            # (See Section 4.36.1.3).
+            responses = await self.execute_command(
+                "AT+BIND?", response_type=AtResponseType.MULTIPLE
+            )
+
+            logger.info("enabled HF indicators:")
+            for response in responses:
+                indicator = HfIndicator(int(response.parameters[0]))
+                enabled = int(response.parameters[1]) != 0
+                logger.info(f"  - {indicator.name}: {enabled}")
+                if indicator in self.hf_indicators:
+                    self.hf_indicators[indicator].enabled = True
+
+        logger.info("SLC setup completed")
+
+    # 4.11.2 Audio Connection Setup by HF
+    async def setup_audio_connection(self):
+        # When the HF triggers the establishment of the Codec Connection it
+        # shall send the AT command AT+BCC to the AG. The AG shall respond with
+        # OK if it will start the Codec Connection procedure, and with ERROR
+        # if it cannot start the Codec Connection procedure.
+        await self.execute_command("AT+BCC")
+
+    # 4.11.3 Codec Connection Setup
+    async def setup_codec_connection(self, codec_id: int):
+        # The AG shall send a +BCS=<Codec ID> unsolicited response to the HF.
+        # The HF shall then respond to the incoming unsolicited response with
+        # the AT command AT+BCS=<Codec ID>. The ID shall be the same as in the
+        # unsolicited response code as long as the ID is supported.
+        # If the received ID is not available, the HF shall respond with
+        # AT+BAC with its available codecs.
+        if codec_id not in self.supported_audio_codecs:
+            codecs = [str(c) for c in self.supported_audio_codecs]
+            await self.execute_command(f"AT+BAC={','.join(codecs)}")
+            return
+
+        await self.execute_command(f"AT+BCS={codec_id}")
+
+        # After sending the OK response, the AG shall open the
+        # Synchronous Connection with the settings that are determined by the
+        # ID. The HF shall be ready to accept the synchronous connection
+        # establishment as soon as it has sent the AT commands AT+BCS=<Codec ID>.
+
+        logger.info("codec connection setup completed")
+
+    # 4.13.1 Answer Incoming Call from the HF – In-Band Ringing
+    async def answer_incoming_call(self):
+        # The user accepts the incoming voice call by using the proper means
+        # provided by the HF. The HF shall then send the ATA command
+        # (see Section 4.34) to the AG. The AG shall then begin the procedure for
+        # accepting the incoming call.
+        await self.execute_command("ATA")
+
+    # 4.14.1 Reject an Incoming Call from the HF
+    async def reject_incoming_call(self):
+        # The user rejects the incoming call by using the User Interface on the
+        # Hands-Free unit. The HF shall then send the AT+CHUP command
+        # (see Section 4.34) to the AG. This may happen at any time during the
+        # procedures described in Sections 4.13.1 and 4.13.2.
+        await self.execute_command("AT+CHUP")
+
+    # 4.15.1 Terminate a Call Process from the HF
+    async def terminate_call(self):
+        # The user may abort the ongoing call process using whatever means
+        # provided by the Hands-Free unit. The HF shall send AT+CHUP command
+        # (see Section 4.34) to the AG, and the AG shall then start the
+        # procedure to terminate or interrupt the current call procedure.
+        # The AG shall then send the OK indication followed by the +CIEV result
+        # code, with the value indicating (call=0).
+        await self.execute_command("AT+CHUP")
+
+    async def update_ag_indicator(self, index: int, value: int):
+        self.ag_indicators[index].current_status = value
+        logger.info(
+            f"AG indicator updated: {self.ag_indicators[index].description}, {value}"
+        )
+
+    async def handle_unsolicited(self):
+        """Handle unsolicited result codes sent by the audio gateway."""
+        result = await self.unsolicited_queue.get()
+        if result.code == "+BCS":
+            await self.setup_codec_connection(int(result.parameters[0]))
+        elif result.code == "+CIEV":
+            await self.update_ag_indicator(
+                int(result.parameters[0]), int(result.parameters[1])
+            )
+        else:
+            logging.info(f"unhandled unsolicited response {result.code}")
+
+    async def run(self):
+        """Main rountine for the Hands-Free side of the HFP protocol.
+        Initiates the service level connection then loops handling
+        unsolicited AG responses."""
+
+        try:
+            await self.initiate_slc()
+            while True:
+                await self.handle_unsolicited()
+        except Exception:
+            logger.error("HFP-HF protocol failed with the following error:")
+            logger.error(traceback.format_exc())
+
+
+# -----------------------------------------------------------------------------
+# Normative SDP definitions
+# -----------------------------------------------------------------------------
+
+
+# Profile version (normative).
+# Hands-Free Profile v1.8, 5.3 SDP Interoperability Requirements
+class ProfileVersion(enum.IntEnum):
+    V1_5 = 0x0105
+    V1_6 = 0x0106
+    V1_7 = 0x0107
+    V1_8 = 0x0108
+    V1_9 = 0x0109
+
+
+# HF supported features (normative).
+# Hands-Free Profile v1.8, 5.3 SDP Interoperability Requirements
+class HfSdpFeature(enum.IntFlag):
+    EC_NR = 0x01  # Echo Cancel & Noise reduction
+    THREE_WAY_CALLING = 0x02
+    CLI_PRESENTATION_CAPABILITY = 0x04
+    VOICE_RECOGNITION_ACTIVATION = 0x08
+    REMOTE_VOLUME_CONTROL = 0x10
+    WIDE_BAND = 0x20  # Wide band speech
+    ENHANCED_VOICE_RECOGNITION_STATUS = 0x40
+    VOICE_RECOGNITION_TEST = 0x80
+
+
+# AG supported features (normative).
+# Hands-Free Profile v1.8, 5.3 SDP Interoperability Requirements
+class AgSdpFeature(enum.IntFlag):
+    THREE_WAY_CALLING = 0x01
+    EC_NR = 0x02  # Echo Cancel & Noise reduction
+    VOICE_RECOGNITION_FUNCTION = 0x04
+    IN_BAND_RING_TONE_CAPABILITY = 0x08
+    VOICE_TAG = 0x10  # Attach a number to voice tag
+    WIDE_BAND = 0x20  # Wide band speech
+    ENHANCED_VOICE_RECOGNITION_STATUS = 0x40
+    VOICE_RECOGNITION_TEST = 0x80
+
+
+def sdp_records(
+    service_record_handle: int, rfcomm_channel: int, configuration: Configuration
+) -> List[ServiceAttribute]:
+    """Generate the SDP record for HFP Hands-Free support.
+    The record exposes the features supported in the input configuration,
+    and the allocated RFCOMM channel."""
+
+    hf_supported_features = 0
+
+    if HfFeature.EC_NR in configuration.supported_hf_features:
+        hf_supported_features |= HfSdpFeature.EC_NR
+    if HfFeature.THREE_WAY_CALLING in configuration.supported_hf_features:
+        hf_supported_features |= HfSdpFeature.THREE_WAY_CALLING
+    if HfFeature.CLI_PRESENTATION_CAPABILITY in configuration.supported_hf_features:
+        hf_supported_features |= HfSdpFeature.CLI_PRESENTATION_CAPABILITY
+    if HfFeature.VOICE_RECOGNITION_ACTIVATION in configuration.supported_hf_features:
+        hf_supported_features |= HfSdpFeature.VOICE_RECOGNITION_ACTIVATION
+    if HfFeature.REMOTE_VOLUME_CONTROL in configuration.supported_hf_features:
+        hf_supported_features |= HfSdpFeature.REMOTE_VOLUME_CONTROL
+    if (
+        HfFeature.ENHANCED_VOICE_RECOGNITION_STATUS
+        in configuration.supported_hf_features
+    ):
+        hf_supported_features |= HfSdpFeature.ENHANCED_VOICE_RECOGNITION_STATUS
+    if HfFeature.VOICE_RECOGNITION_TEST in configuration.supported_hf_features:
+        hf_supported_features |= HfSdpFeature.VOICE_RECOGNITION_TEST
+
+    if AudioCodec.MSBC in configuration.supported_audio_codecs:
+        hf_supported_features |= HfSdpFeature.WIDE_BAND
+
+    return [
+        ServiceAttribute(
+            SDP_SERVICE_RECORD_HANDLE_ATTRIBUTE_ID,
+            DataElement.unsigned_integer_32(service_record_handle),
+        ),
+        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(ProfileVersion.V1_8),
+                        ]
+                    )
+                ]
+            ),
+        ),
+        ServiceAttribute(
+            SDP_SUPPORTED_FEATURES_ATTRIBUTE_ID,
+            DataElement.unsigned_integer_16(hf_supported_features),
+        ),
+    ]

bumble/host.py

@@ -15,19 +15,24 @@
 # -----------------------------------------------------------------------------
 # Imports
 # -----------------------------------------------------------------------------
+from __future__ import annotations
 import asyncio
 import collections
 import logging
 import struct
 
+from typing import Optional, TYPE_CHECKING, Dict, Callable, Awaitable
+
 from bumble.colors import color
 from bumble.l2cap import L2CAP_PDU
 from bumble.snoop import Snooper
+from bumble import drivers
 
 from .hci import (
+    Address,
     HCI_ACL_DATA_PACKET,
-    HCI_COMMAND_COMPLETE_EVENT,
     HCI_COMMAND_PACKET,
+    HCI_COMMAND_COMPLETE_EVENT,
     HCI_EVENT_PACKET,
     HCI_LE_READ_BUFFER_SIZE_COMMAND,
     HCI_LE_READ_LOCAL_SUPPORTED_FEATURES_COMMAND,
@@ -41,8 +46,11 @@ from .hci import (
     HCI_VERSION_BLUETOOTH_CORE_4_0,
     HCI_AclDataPacket,
     HCI_AclDataPacketAssembler,
+    HCI_Command,
+    HCI_Command_Complete_Event,
     HCI_Constant,
     HCI_Error,
+    HCI_Event,
     HCI_LE_Long_Term_Key_Request_Negative_Reply_Command,
     HCI_LE_Long_Term_Key_Request_Reply_Command,
     HCI_LE_Read_Buffer_Size_Command,
@@ -53,7 +61,6 @@ from .hci import (
     HCI_LE_Write_Suggested_Default_Data_Length_Command,
     HCI_Link_Key_Request_Negative_Reply_Command,
     HCI_Link_Key_Request_Reply_Command,
-    HCI_PIN_Code_Request_Negative_Reply_Command,
     HCI_Packet,
     HCI_Read_Buffer_Size_Command,
     HCI_Read_Local_Supported_Commands_Command,
@@ -63,12 +70,16 @@ from .hci import (
 )
 from .core import (
     BT_BR_EDR_TRANSPORT,
-    BT_CENTRAL_ROLE,
     BT_LE_TRANSPORT,
     ConnectionPHY,
     ConnectionParameters,
+    InvalidStateError,
 )
 from .utils import AbortableEventEmitter
+from .transport.common import TransportLostError
+
+if TYPE_CHECKING:
+    from .transport.common import TransportSink, TransportSource
 
 
 # -----------------------------------------------------------------------------
@@ -92,28 +103,39 @@ HOST_HC_TOTAL_NUM_ACL_DATA_PACKETS        = 1
 
 # -----------------------------------------------------------------------------
 class Connection:
-    def __init__(self, host, handle, role, peer_address, transport):
+    def __init__(self, host: Host, handle: int, peer_address: Address, transport: int):
         self.host = host
         self.handle = handle
-        self.role = role
         self.peer_address = peer_address
         self.assembler = HCI_AclDataPacketAssembler(self.on_acl_pdu)
         self.transport = transport
 
-    def on_hci_acl_data_packet(self, packet):
+    def on_hci_acl_data_packet(self, packet: HCI_AclDataPacket) -> None:
         self.assembler.feed_packet(packet)
 
-    def on_acl_pdu(self, pdu):
+    def on_acl_pdu(self, pdu: bytes) -> None:
         l2cap_pdu = L2CAP_PDU.from_bytes(pdu)
         self.host.on_l2cap_pdu(self, l2cap_pdu.cid, l2cap_pdu.payload)
 
 
 # -----------------------------------------------------------------------------
 class Host(AbortableEventEmitter):
-    def __init__(self, controller_source=None, controller_sink=None):
+    connections: Dict[int, Connection]
+    acl_packet_queue: collections.deque[HCI_AclDataPacket]
+    hci_sink: TransportSink
+    long_term_key_provider: Optional[
+        Callable[[int, bytes, int], Awaitable[Optional[bytes]]]
+    ]
+    link_key_provider: Optional[Callable[[Address], Awaitable[Optional[bytes]]]]
+
+    def __init__(
+        self,
+        controller_source: Optional[TransportSource] = None,
+        controller_sink: Optional[TransportSink] = None,
+    ) -> None:
         super().__init__()
 
-        self.hci_sink = None
+        self.hci_metadata = None
         self.ready = False  # True when we can accept incoming packets
         self.reset_done = False
         self.connections = {}  # Connections, by connection handle
@@ -139,9 +161,30 @@ class Host(AbortableEventEmitter):
         # Connect to the source and sink if specified
         if controller_source:
             controller_source.set_packet_sink(self)
+            self.hci_metadata = getattr(
+                controller_source, 'metadata', self.hci_metadata
+            )
         if controller_sink:
             self.set_packet_sink(controller_sink)
 
+    def find_connection_by_bd_addr(
+        self,
+        bd_addr: Address,
+        transport: Optional[int] = None,
+        check_address_type: bool = False,
+    ) -> Optional[Connection]:
+        for connection in self.connections.values():
+            if connection.peer_address.to_bytes() == bd_addr.to_bytes():
+                if (
+                    check_address_type
+                    and connection.peer_address.address_type != bd_addr.address_type
+                ):
+                    continue
+                if transport is None or connection.transport == transport:
+                    return connection
+
+        return None
+
     async def flush(self) -> None:
         # Make sure no command is pending
         await self.command_semaphore.acquire()
@@ -150,7 +193,7 @@ class Host(AbortableEventEmitter):
         self.emit('flush')
         self.command_semaphore.release()
 
-    async def reset(self):
+    async def reset(self, driver_factory=drivers.get_driver_for_host):
         if self.ready:
             self.ready = False
             await self.flush()
@@ -158,6 +201,15 @@ class Host(AbortableEventEmitter):
         await self.send_command(HCI_Reset_Command(), check_result=True)
         self.ready = True
 
+        # Instantiate and init a driver for the host if needed.
+        # NOTE: we don't keep a reference to the driver here, because we don't
+        # currently have a need for the driver later on. But if the driver interface
+        # evolves, it may be required, then, to store a reference to the driver in
+        # an object property.
+        if driver_factory is not None:
+            if driver := await driver_factory(self):
+                await driver.init_controller()
+
         response = await self.send_command(
             HCI_Read_Local_Supported_Commands_Command(), check_result=True
         )
@@ -262,7 +314,7 @@ class Host(AbortableEventEmitter):
         self.reset_done = True
 
     @property
-    def controller(self):
+    def controller(self) -> TransportSink:
         return self.hci_sink
 
     @controller.setter
@@ -271,14 +323,13 @@ class Host(AbortableEventEmitter):
         if controller:
             controller.set_packet_sink(self)
 
-    def set_packet_sink(self, sink):
+    def set_packet_sink(self, sink: TransportSink) -> None:
         self.hci_sink = sink
 
-    def send_hci_packet(self, packet):
+    def send_hci_packet(self, packet: HCI_Packet) -> None:
         if self.snooper:
-            self.snooper.snoop(packet, Snooper.Direction.HOST_TO_CONTROLLER)
-
-        self.hci_sink.on_packet(packet.to_bytes())
+            self.snooper.snoop(bytes(packet), Snooper.Direction.HOST_TO_CONTROLLER)
+        self.hci_sink.on_packet(bytes(packet))
 
     async def send_command(self, command, check_result=False):
         logger.debug(f'{color("### HOST -> CONTROLLER", "blue")}: {command}')
@@ -315,7 +366,7 @@ class Host(AbortableEventEmitter):
                 return response
             except Exception as error:
                 logger.warning(
-                    f'{color("!!! Exception while sending HCI packet:", "red")} {error}'
+                    f'{color("!!! Exception while sending command:", "red")} {error}'
                 )
                 raise error
             finally:
@@ -323,14 +374,14 @@ class Host(AbortableEventEmitter):
                 self.pending_response = None
 
     # Use this method to send a command from a task
-    def send_command_sync(self, command):
-        async def send_command(command):
+    def send_command_sync(self, command: HCI_Command) -> None:
+        async def send_command(command: HCI_Command) -> None:
             await self.send_command(command)
 
         asyncio.create_task(send_command(command))
 
-    def send_l2cap_pdu(self, connection_handle, cid, pdu):
-        l2cap_pdu = L2CAP_PDU(cid, pdu).to_bytes()
+    def send_l2cap_pdu(self, connection_handle: int, cid: int, pdu: bytes) -> None:
+        l2cap_pdu = bytes(L2CAP_PDU(cid, pdu))
 
         # Send the data to the controller via ACL packets
         bytes_remaining = len(l2cap_pdu)
@@ -354,7 +405,7 @@ class Host(AbortableEventEmitter):
             offset += data_total_length
             bytes_remaining -= data_total_length
 
-    def queue_acl_packet(self, acl_packet):
+    def queue_acl_packet(self, acl_packet: HCI_AclDataPacket) -> None:
         self.acl_packet_queue.appendleft(acl_packet)
         self.check_acl_packet_queue()
 
@@ -364,7 +415,7 @@ class Host(AbortableEventEmitter):
                 f'{len(self.acl_packet_queue)} in queue'
             )
 
-    def check_acl_packet_queue(self):
+    def check_acl_packet_queue(self) -> None:
         # Send all we can (TODO: support different LE/Classic limits)
         while (
             len(self.acl_packet_queue) > 0
@@ -376,8 +427,8 @@ class Host(AbortableEventEmitter):
 
     def supports_command(self, command):
         # Find the support flag position for this command
-        for (octet, flags) in enumerate(HCI_SUPPORTED_COMMANDS_FLAGS):
-            for (flag_position, value) in enumerate(flags):
+        for octet, flags in enumerate(HCI_SUPPORTED_COMMANDS_FLAGS):
+            for flag_position, value in enumerate(flags):
                 if value == command:
                     # Check if the flag is set
                     if octet < len(self.local_supported_commands) and flag_position < 8:
@@ -390,7 +441,7 @@ class Host(AbortableEventEmitter):
     @property
     def supported_commands(self):
         commands = []
-        for (octet, flags) in enumerate(self.local_supported_commands):
+        for octet, flags in enumerate(self.local_supported_commands):
             if octet < len(HCI_SUPPORTED_COMMANDS_FLAGS):
                 for flag in range(8):
                     if flags & (1 << flag) != 0:
@@ -410,47 +461,53 @@ class Host(AbortableEventEmitter):
         ]
 
     # Packet Sink protocol (packets coming from the controller via HCI)
-    def on_packet(self, packet):
+    def on_packet(self, packet: bytes) -> None:
         hci_packet = HCI_Packet.from_bytes(packet)
         if self.ready or (
-            hci_packet.hci_packet_type == HCI_EVENT_PACKET
-            and hci_packet.event_code == HCI_COMMAND_COMPLETE_EVENT
+            isinstance(hci_packet, HCI_Command_Complete_Event)
             and hci_packet.command_opcode == HCI_RESET_COMMAND
         ):
             self.on_hci_packet(hci_packet)
         else:
             logger.debug('reset not done, ignoring packet from controller')
 
-    def on_hci_packet(self, packet):
+    def on_transport_lost(self):
+        # Called by the source when the transport has been lost.
+        if self.pending_response:
+            self.pending_response.set_exception(TransportLostError('transport lost'))
+
+        self.emit('flush')
+
+    def on_hci_packet(self, packet: HCI_Packet) -> None:
         logger.debug(f'{color("### CONTROLLER -> HOST", "green")}: {packet}')
 
         if self.snooper:
-            self.snooper.snoop(packet, Snooper.Direction.CONTROLLER_TO_HOST)
+            self.snooper.snoop(bytes(packet), Snooper.Direction.CONTROLLER_TO_HOST)
 
         # If the packet is a command, invoke the handler for this packet
-        if packet.hci_packet_type == HCI_COMMAND_PACKET:
+        if isinstance(packet, HCI_Command):
             self.on_hci_command_packet(packet)
-        elif packet.hci_packet_type == HCI_EVENT_PACKET:
+        elif isinstance(packet, HCI_Event):
             self.on_hci_event_packet(packet)
-        elif packet.hci_packet_type == HCI_ACL_DATA_PACKET:
+        elif isinstance(packet, HCI_AclDataPacket):
             self.on_hci_acl_data_packet(packet)
         else:
             logger.warning(f'!!! unknown packet type {packet.hci_packet_type}')
 
-    def on_hci_command_packet(self, command):
+    def on_hci_command_packet(self, command: HCI_Command) -> None:
         logger.warning(f'!!! unexpected command packet: {command}')
 
-    def on_hci_event_packet(self, event):
+    def on_hci_event_packet(self, event: HCI_Event) -> None:
         handler_name = f'on_{event.name.lower()}'
         handler = getattr(self, handler_name, self.on_hci_event)
         handler(event)
 
-    def on_hci_acl_data_packet(self, packet):
+    def on_hci_acl_data_packet(self, packet: HCI_AclDataPacket) -> None:
         # Look for the connection to which this data belongs
         if connection := self.connections.get(packet.connection_handle):
             connection.on_hci_acl_data_packet(packet)
 
-    def on_l2cap_pdu(self, connection, cid, pdu):
+    def on_l2cap_pdu(self, connection: Connection, cid: int, pdu: bytes) -> None:
         self.emit('l2cap_pdu', connection.handle, cid, pdu)
 
     def on_command_processed(self, event):
@@ -514,7 +571,7 @@ class Host(AbortableEventEmitter):
         if event.status == HCI_SUCCESS:
             # Create/update the connection
             logger.debug(
-                f'### CONNECTION: [0x{event.connection_handle:04X}] '
+                f'### LE CONNECTION: [0x{event.connection_handle:04X}] '
                 f'{event.peer_address} as {HCI_Constant.role_name(event.role)}'
             )
 
@@ -523,7 +580,6 @@ class Host(AbortableEventEmitter):
                 connection = Connection(
                     self,
                     event.connection_handle,
-                    event.role,
                     event.peer_address,
                     BT_LE_TRANSPORT,
                 )
@@ -540,7 +596,6 @@ class Host(AbortableEventEmitter):
                 event.connection_handle,
                 BT_LE_TRANSPORT,
                 event.peer_address,
-                None,
                 event.role,
                 connection_parameters,
             )
@@ -569,7 +624,6 @@ class Host(AbortableEventEmitter):
                 connection = Connection(
                     self,
                     event.connection_handle,
-                    BT_CENTRAL_ROLE,
                     event.bd_addr,
                     BT_BR_EDR_TRANSPORT,
                 )
@@ -582,7 +636,6 @@ class Host(AbortableEventEmitter):
                 BT_BR_EDR_TRANSPORT,
                 event.bd_addr,
                 None,
-                BT_CENTRAL_ROLE,
                 None,
             )
         else:
@@ -602,8 +655,7 @@ class Host(AbortableEventEmitter):
         if event.status == HCI_SUCCESS:
             logger.debug(
                 f'### DISCONNECTION: [0x{event.connection_handle:04X}] '
-                f'{connection.peer_address} as '
-                f'{HCI_Constant.role_name(connection.role)}, '
+                f'{connection.peer_address} '
                 f'reason={event.reason}'
             )
             del self.connections[event.connection_handle]
@@ -719,12 +771,13 @@ class Host(AbortableEventEmitter):
                 f'role change for {event.bd_addr}: '
                 f'{HCI_Constant.role_name(event.new_role)}'
             )
-            # TODO: lookup the connection and update the role
+            self.emit('role_change', event.bd_addr, event.new_role)
         else:
             logger.debug(
                 f'role change for {event.bd_addr} failed: '
                 f'{HCI_Constant.error_name(event.status)}'
             )
+            self.emit('role_change_failure', event.bd_addr, event.status)
 
     def on_hci_le_data_length_change_event(self, event):
         self.emit(
@@ -792,13 +845,13 @@ class Host(AbortableEventEmitter):
             f'simple pairing complete for {event.bd_addr}: '
             f'status={HCI_Constant.status_name(event.status)}'
         )
+        if event.status == HCI_SUCCESS:
+            self.emit('classic_pairing', event.bd_addr)
+        else:
+            self.emit('classic_pairing_failure', event.bd_addr, event.status)
 
     def on_hci_pin_code_request_event(self, event):
-        # For now, just refuse all requests
-        # TODO: delegate the decision
-        self.send_command_sync(
-            HCI_PIN_Code_Request_Negative_Reply_Command(bd_addr=event.bd_addr)
-        )
+        self.emit('pin_code_request', event.bd_addr)
 
     def on_hci_link_key_request_event(self, event):
         async def send_link_key():
@@ -828,7 +881,12 @@ class Host(AbortableEventEmitter):
         self.emit('authentication_io_capability_request', event.bd_addr)
 
     def on_hci_io_capability_response_event(self, event):
-        pass
+        self.emit(
+            'authentication_io_capability_response',
+            event.bd_addr,
+            event.io_capability,
+            event.authentication_requirements,
+        )
 
     def on_hci_user_confirmation_request_event(self, event):
         self.emit(
@@ -871,7 +929,12 @@ class Host(AbortableEventEmitter):
         if event.status != HCI_SUCCESS:
             self.emit('remote_name_failure', event.bd_addr, event.status)
         else:
-            self.emit('remote_name', event.bd_addr, event.remote_name)
+            utf8_name = event.remote_name
+            terminator = utf8_name.find(0)
+            if terminator >= 0:
+                utf8_name = utf8_name[0:terminator]
+
+            self.emit('remote_name', event.bd_addr, utf8_name)
 
     def on_hci_remote_host_supported_features_notification_event(self, event):
         self.emit(

bumble/keys.py

@@ -20,15 +20,19 @@
 # -----------------------------------------------------------------------------
 # Imports
 # -----------------------------------------------------------------------------
+from __future__ import annotations
 import asyncio
 import logging
 import os
 import json
-from typing import Optional
+from typing import TYPE_CHECKING, Dict, List, Optional, Tuple
 
 from .colors import color
 from .hci import Address
 
+if TYPE_CHECKING:
+    from .device import Device
+
 
 # -----------------------------------------------------------------------------
 # Logging
@@ -135,19 +139,19 @@ class PairingKeys:
 
 # -----------------------------------------------------------------------------
 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):
+    async def delete_all(self) -> None:
         all_keys = await self.get_all()
         await asyncio.gather(*(self.delete(name) for (name, _) in all_keys))
 
@@ -173,23 +177,57 @@ class KeyStore:
             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):
+    """
+    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
@@ -204,7 +242,10 @@ class JsonKeyStore(KeyStore):
             self.directory_name = os.path.join(
                 appdirs.user_data_dir(self.APP_NAME, self.APP_AUTHOR), self.KEYS_DIR
             )
-            json_filename = f'{self.namespace}.json'.lower().replace(':', '-')
+            base_name = self.DEFAULT_BASE_NAME if namespace is None else self.namespace
+            json_filename = (
+                f'{base_name}.json'.lower().replace(':', '-').replace('/p', '-p')
+            )
             self.filename = os.path.join(self.directory_name, json_filename)
         else:
             self.filename = filename
@@ -213,22 +254,46 @@ 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[0]
+    def from_device(device: Device, filename=None) -> Optional[JsonKeyStore]:
+        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]
+
+        # 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:
-            filename = None
+            namespace = JsonKeyStore.DEFAULT_NAMESPACE
 
         return JsonKeyStore(namespace, filename)
 
     async def load(self):
+        # Try to open the file, without failing. If the file does not exist, it
+        # will be created upon saving.
         try:
             with open(self.filename, 'r', encoding='utf-8') as json_file:
-                return json.load(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
@@ -241,53 +306,51 @@ class JsonKeyStore(KeyStore):
             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: str) -> None:
-        db = await self.load()
-
-        namespace = db.get(self.namespace)
-        if namespace is None:
-            raise KeyError(name)
-
-        del namespace[name]
+        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()
-
-        namespace = db.get(self.namespace)
-        if namespace is None:
-            return []
-
-        return [
-            (name, PairingKeys.from_dict(keys)) for (name, keys) in namespace.items()
-        ]
+        _, key_map = await self.load()
+        return [(name, PairingKeys.from_dict(keys)) for (name, keys) in key_map.items()]
 
     async def delete_all(self):
-        db = await self.load()
-
-        db.pop(self.namespace, None)
-
+        db, key_map = await self.load()
+        key_map.clear()
         await self.save(db)
 
     async def get(self, name: str) -> Optional[PairingKeys]:
-        db = await self.load()
-
-        namespace = db.get(self.namespace)
-        if namespace is None:
+        _, 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/l2cap.py

@@ -22,7 +22,20 @@ import struct
 
 from collections import deque
 from pyee import EventEmitter
-from typing import Dict, Type
+from typing import (
+    Dict,
+    Type,
+    List,
+    Optional,
+    Tuple,
+    Callable,
+    Any,
+    Union,
+    Deque,
+    Iterable,
+    SupportsBytes,
+    TYPE_CHECKING,
+)
 
 from .colors import color
 from .core import BT_CENTRAL_ROLE, InvalidStateError, ProtocolError
@@ -33,6 +46,10 @@ from .hci import (
     name_or_number,
 )
 
+if TYPE_CHECKING:
+    from bumble.device import Connection
+    from bumble.host import Host
+
 # -----------------------------------------------------------------------------
 # Logging
 # -----------------------------------------------------------------------------
@@ -155,7 +172,7 @@ class L2CAP_PDU:
     '''
 
     @staticmethod
-    def from_bytes(data):
+    def from_bytes(data: bytes) -> L2CAP_PDU:
         # Sanity check
         if len(data) < 4:
             raise ValueError('not enough data for L2CAP header')
@@ -165,18 +182,18 @@ class L2CAP_PDU:
 
         return L2CAP_PDU(l2cap_pdu_cid, l2cap_pdu_payload)
 
-    def to_bytes(self):
+    def to_bytes(self) -> bytes:
         header = struct.pack('<HH', len(self.payload), self.cid)
         return header + self.payload
 
-    def __init__(self, cid, payload):
+    def __init__(self, cid: int, payload: bytes) -> None:
         self.cid = cid
         self.payload = payload
 
-    def __bytes__(self):
+    def __bytes__(self) -> bytes:
         return self.to_bytes()
 
-    def __str__(self):
+    def __str__(self) -> str:
         return f'{color("L2CAP", "green")} [CID={self.cid}]: {self.payload.hex()}'
 
 
@@ -188,10 +205,10 @@ class L2CAP_Control_Frame:
 
     classes: Dict[int, Type[L2CAP_Control_Frame]] = {}
     code = 0
-    name = None
+    name: str
 
     @staticmethod
-    def from_bytes(pdu):
+    def from_bytes(pdu: bytes) -> L2CAP_Control_Frame:
         code = pdu[0]
 
         cls = L2CAP_Control_Frame.classes.get(code)
@@ -216,11 +233,11 @@ class L2CAP_Control_Frame:
         return self
 
     @staticmethod
-    def code_name(code):
+    def code_name(code: int) -> str:
         return name_or_number(L2CAP_CONTROL_FRAME_NAMES, code)
 
     @staticmethod
-    def decode_configuration_options(data):
+    def decode_configuration_options(data: bytes) -> List[Tuple[int, bytes]]:
         options = []
         while len(data) >= 2:
             value_type = data[0]
@@ -232,7 +249,7 @@ class L2CAP_Control_Frame:
         return options
 
     @staticmethod
-    def encode_configuration_options(options):
+    def encode_configuration_options(options: List[Tuple[int, bytes]]) -> bytes:
         return b''.join(
             [bytes([option[0], len(option[1])]) + option[1] for option in options]
         )
@@ -256,29 +273,30 @@ class L2CAP_Control_Frame:
 
         return inner
 
-    def __init__(self, pdu=None, **kwargs):
+    def __init__(self, pdu=None, **kwargs) -> None:
         self.identifier = kwargs.get('identifier', 0)
-        if hasattr(self, 'fields') and kwargs:
-            HCI_Object.init_from_fields(self, self.fields, kwargs)
-        if pdu is None:
-            data = HCI_Object.dict_to_bytes(kwargs, self.fields)
-            pdu = (
-                bytes([self.code, self.identifier])
-                + struct.pack('<H', len(data))
-                + data
-            )
+        if hasattr(self, 'fields'):
+            if kwargs:
+                HCI_Object.init_from_fields(self, self.fields, kwargs)
+            if pdu is None:
+                data = HCI_Object.dict_to_bytes(kwargs, self.fields)
+                pdu = (
+                    bytes([self.code, self.identifier])
+                    + struct.pack('<H', len(data))
+                    + data
+                )
         self.pdu = pdu
 
     def init_from_bytes(self, pdu, offset):
         return HCI_Object.init_from_bytes(self, pdu, offset, self.fields)
 
-    def to_bytes(self):
+    def to_bytes(self) -> bytes:
         return self.pdu
 
-    def __bytes__(self):
+    def __bytes__(self) -> bytes:
         return self.to_bytes()
 
-    def __str__(self):
+    def __str__(self) -> str:
         result = f'{color(self.name, "yellow")} [ID={self.identifier}]'
         if fields := getattr(self, 'fields', None):
             result += ':\n' + HCI_Object.format_fields(self.__dict__, fields, '  ')
@@ -315,7 +333,7 @@ class L2CAP_Command_Reject(L2CAP_Control_Frame):
     }
 
     @staticmethod
-    def reason_name(reason):
+    def reason_name(reason: int) -> str:
         return name_or_number(L2CAP_Command_Reject.REASON_NAMES, reason)
 
 
@@ -343,7 +361,7 @@ class L2CAP_Connection_Request(L2CAP_Control_Frame):
     '''
 
     @staticmethod
-    def parse_psm(data, offset=0):
+    def parse_psm(data: bytes, offset: int = 0) -> Tuple[int, int]:
         psm_length = 2
         psm = data[offset] | data[offset + 1] << 8
 
@@ -355,7 +373,7 @@ class L2CAP_Connection_Request(L2CAP_Control_Frame):
         return offset + psm_length, psm
 
     @staticmethod
-    def serialize_psm(psm):
+    def serialize_psm(psm: int) -> bytes:
         serialized = struct.pack('<H', psm & 0xFFFF)
         psm >>= 16
         while psm:
@@ -405,7 +423,7 @@ class L2CAP_Connection_Response(L2CAP_Control_Frame):
     }
 
     @staticmethod
-    def result_name(result):
+    def result_name(result: int) -> str:
         return name_or_number(L2CAP_Connection_Response.RESULT_NAMES, result)
 
 
@@ -452,7 +470,7 @@ class L2CAP_Configure_Response(L2CAP_Control_Frame):
     }
 
     @staticmethod
-    def result_name(result):
+    def result_name(result: int) -> str:
         return name_or_number(L2CAP_Configure_Response.RESULT_NAMES, result)
 
 
@@ -529,7 +547,7 @@ class L2CAP_Information_Request(L2CAP_Control_Frame):
     }
 
     @staticmethod
-    def info_type_name(info_type):
+    def info_type_name(info_type: int) -> str:
         return name_or_number(L2CAP_Information_Request.INFO_TYPE_NAMES, info_type)
 
 
@@ -556,7 +574,7 @@ class L2CAP_Information_Response(L2CAP_Control_Frame):
     RESULT_NAMES = {SUCCESS: 'SUCCESS', NOT_SUPPORTED: 'NOT_SUPPORTED'}
 
     @staticmethod
-    def result_name(result):
+    def result_name(result: int) -> str:
         return name_or_number(L2CAP_Information_Response.RESULT_NAMES, result)
 
 
@@ -588,6 +606,8 @@ class L2CAP_LE_Credit_Based_Connection_Request(L2CAP_Control_Frame):
     (CODE 0x14)
     '''
 
+    source_cid: int
+
 
 # -----------------------------------------------------------------------------
 @L2CAP_Control_Frame.subclass(
@@ -640,7 +660,7 @@ class L2CAP_LE_Credit_Based_Connection_Response(L2CAP_Control_Frame):
     }
 
     @staticmethod
-    def result_name(result):
+    def result_name(result: int) -> str:
         return name_or_number(
             L2CAP_LE_Credit_Based_Connection_Response.RESULT_NAMES, result
         )
@@ -701,7 +721,22 @@ class Channel(EventEmitter):
         WAIT_CONTROL_IND: 'WAIT_CONTROL_IND',
     }
 
-    def __init__(self, manager, connection, signaling_cid, psm, source_cid, mtu):
+    connection_result: Optional[asyncio.Future[None]]
+    disconnection_result: Optional[asyncio.Future[None]]
+    response: Optional[asyncio.Future[bytes]]
+    sink: Optional[Callable[[bytes], Any]]
+    state: int
+    connection: Connection
+
+    def __init__(
+        self,
+        manager: ChannelManager,
+        connection: Connection,
+        signaling_cid: int,
+        psm: int,
+        source_cid: int,
+        mtu: int,
+    ) -> None:
         super().__init__()
         self.manager = manager
         self.connection = connection
@@ -716,19 +751,19 @@ class Channel(EventEmitter):
         self.disconnection_result = None
         self.sink = None
 
-    def change_state(self, new_state):
+    def change_state(self, new_state: int) -> None:
         logger.debug(
             f'{self} state change -> {color(Channel.STATE_NAMES[new_state], "cyan")}'
         )
         self.state = new_state
 
-    def send_pdu(self, pdu):
+    def send_pdu(self, pdu: Union[SupportsBytes, bytes]) -> None:
         self.manager.send_pdu(self.connection, self.destination_cid, pdu)
 
-    def send_control_frame(self, frame):
+    def send_control_frame(self, frame: L2CAP_Control_Frame) -> None:
         self.manager.send_control_frame(self.connection, self.signaling_cid, frame)
 
-    async def send_request(self, request):
+    async def send_request(self, request: SupportsBytes) -> bytes:
         # Check that there isn't already a request pending
         if self.response:
             raise InvalidStateError('request already pending')
@@ -739,7 +774,7 @@ class Channel(EventEmitter):
         self.send_pdu(request)
         return await self.response
 
-    def on_pdu(self, pdu):
+    def on_pdu(self, pdu: bytes) -> None:
         if self.response:
             self.response.set_result(pdu)
             self.response = None
@@ -751,7 +786,7 @@ class Channel(EventEmitter):
                 color('received pdu without a pending request or sink', 'red')
             )
 
-    async def connect(self):
+    async def connect(self) -> None:
         if self.state != Channel.CLOSED:
             raise InvalidStateError('invalid state')
 
@@ -778,7 +813,7 @@ class Channel(EventEmitter):
         finally:
             self.connection_result = None
 
-    async def disconnect(self):
+    async def disconnect(self) -> None:
         if self.state != Channel.OPEN:
             raise InvalidStateError('invalid state')
 
@@ -796,7 +831,12 @@ class Channel(EventEmitter):
         self.disconnection_result = asyncio.get_running_loop().create_future()
         return await self.disconnection_result
 
-    def send_configure_request(self):
+    def abort(self) -> None:
+        if self.state == self.OPEN:
+            self.change_state(self.CLOSED)
+            self.emit('close')
+
+    def send_configure_request(self) -> None:
         options = L2CAP_Control_Frame.encode_configuration_options(
             [
                 (
@@ -814,7 +854,7 @@ class Channel(EventEmitter):
             )
         )
 
-    def on_connection_request(self, request):
+    def on_connection_request(self, request) -> None:
         self.destination_cid = request.source_cid
         self.change_state(Channel.WAIT_CONNECT)
         self.send_control_frame(
@@ -853,7 +893,7 @@ class Channel(EventEmitter):
             )
             self.connection_result = None
 
-    def on_configure_request(self, request):
+    def on_configure_request(self, request) -> None:
         if self.state not in (
             Channel.WAIT_CONFIG,
             Channel.WAIT_CONFIG_REQ,
@@ -891,7 +931,7 @@ class Channel(EventEmitter):
         elif self.state == Channel.WAIT_CONFIG_REQ_RSP:
             self.change_state(Channel.WAIT_CONFIG_RSP)
 
-    def on_configure_response(self, response):
+    def on_configure_response(self, response) -> None:
         if response.result == L2CAP_Configure_Response.SUCCESS:
             if self.state == Channel.WAIT_CONFIG_REQ_RSP:
                 self.change_state(Channel.WAIT_CONFIG_REQ)
@@ -925,7 +965,7 @@ class Channel(EventEmitter):
             )
             # TODO: decide how to fail gracefully
 
-    def on_disconnection_request(self, request):
+    def on_disconnection_request(self, request) -> None:
         if self.state in (Channel.OPEN, Channel.WAIT_DISCONNECT):
             self.send_control_frame(
                 L2CAP_Disconnection_Response(
@@ -940,7 +980,7 @@ class Channel(EventEmitter):
         else:
             logger.warning(color('invalid state', 'red'))
 
-    def on_disconnection_response(self, response):
+    def on_disconnection_response(self, response) -> None:
         if self.state != Channel.WAIT_DISCONNECT:
             logger.warning(color('invalid state', 'red'))
             return
@@ -959,7 +999,7 @@ class Channel(EventEmitter):
         self.emit('close')
         self.manager.on_channel_closed(self)
 
-    def __str__(self):
+    def __str__(self) -> str:
         return (
             f'Channel({self.source_cid}->{self.destination_cid}, '
             f'PSM={self.psm}, '
@@ -990,25 +1030,32 @@ class LeConnectionOrientedChannel(EventEmitter):
         CONNECTION_ERROR: 'CONNECTION_ERROR',
     }
 
+    out_queue: Deque[bytes]
+    connection_result: Optional[asyncio.Future[LeConnectionOrientedChannel]]
+    disconnection_result: Optional[asyncio.Future[None]]
+    out_sdu: Optional[bytes]
+    state: int
+    connection: Connection
+
     @staticmethod
-    def state_name(state):
+    def state_name(state: int) -> str:
         return name_or_number(LeConnectionOrientedChannel.STATE_NAMES, state)
 
     def __init__(
         self,
-        manager,
-        connection,
-        le_psm,
-        source_cid,
-        destination_cid,
-        mtu,
-        mps,
-        credits,  # pylint: disable=redefined-builtin
-        peer_mtu,
-        peer_mps,
-        peer_credits,
-        connected,
-    ):
+        manager: ChannelManager,
+        connection: Connection,
+        le_psm: int,
+        source_cid: int,
+        destination_cid: int,
+        mtu: int,
+        mps: int,
+        credits: int,  # pylint: disable=redefined-builtin
+        peer_mtu: int,
+        peer_mps: int,
+        peer_credits: int,
+        connected: bool,
+    ) -> None:
         super().__init__()
         self.manager = manager
         self.connection = connection
@@ -1040,7 +1087,7 @@ class LeConnectionOrientedChannel(EventEmitter):
         else:
             self.state = LeConnectionOrientedChannel.INIT
 
-    def change_state(self, new_state):
+    def change_state(self, new_state: int) -> None:
         logger.debug(
             f'{self} state change -> {color(self.state_name(new_state), "cyan")}'
         )
@@ -1051,13 +1098,13 @@ class LeConnectionOrientedChannel(EventEmitter):
         elif new_state == self.DISCONNECTED:
             self.emit('close')
 
-    def send_pdu(self, pdu):
+    def send_pdu(self, pdu: Union[SupportsBytes, bytes]) -> None:
         self.manager.send_pdu(self.connection, self.destination_cid, pdu)
 
-    def send_control_frame(self, frame):
+    def send_control_frame(self, frame: L2CAP_Control_Frame) -> None:
         self.manager.send_control_frame(self.connection, L2CAP_LE_SIGNALING_CID, frame)
 
-    async def connect(self):
+    async def connect(self) -> LeConnectionOrientedChannel:
         # Check that we're in the right state
         if self.state != self.INIT:
             raise InvalidStateError('not in a connectable state')
@@ -1085,7 +1132,7 @@ class LeConnectionOrientedChannel(EventEmitter):
         # Wait for the connection to succeed or fail
         return await self.connection_result
 
-    async def disconnect(self):
+    async def disconnect(self) -> None:
         # Check that we're connected
         if self.state != self.CONNECTED:
             raise InvalidStateError('not connected')
@@ -1105,7 +1152,11 @@ class LeConnectionOrientedChannel(EventEmitter):
         self.disconnection_result = asyncio.get_running_loop().create_future()
         return await self.disconnection_result
 
-    def on_pdu(self, pdu):
+    def abort(self) -> None:
+        if self.state == self.CONNECTED:
+            self.change_state(self.DISCONNECTED)
+
+    def on_pdu(self, pdu: bytes) -> None:
         if self.sink is None:
             logger.warning('received pdu without a sink')
             return
@@ -1171,7 +1222,7 @@ class LeConnectionOrientedChannel(EventEmitter):
         self.in_sdu = None
         self.in_sdu_length = 0
 
-    def on_connection_response(self, response):
+    def on_connection_response(self, response) -> None:
         # Look for a matching pending response result
         if self.connection_result is None:
             logger.warning(
@@ -1205,14 +1256,14 @@ class LeConnectionOrientedChannel(EventEmitter):
         # Cleanup
         self.connection_result = None
 
-    def on_credits(self, credits):  # pylint: disable=redefined-builtin
+    def on_credits(self, credits: int) -> None:  # pylint: disable=redefined-builtin
         self.credits += credits
         logger.debug(f'received {credits} credits, total = {self.credits}')
 
         # Try to send more data if we have any queued up
         self.process_output()
 
-    def on_disconnection_request(self, request):
+    def on_disconnection_request(self, request) -> None:
         self.send_control_frame(
             L2CAP_Disconnection_Response(
                 identifier=request.identifier,
@@ -1223,7 +1274,7 @@ class LeConnectionOrientedChannel(EventEmitter):
         self.change_state(self.DISCONNECTED)
         self.flush_output()
 
-    def on_disconnection_response(self, response):
+    def on_disconnection_response(self, response) -> None:
         if self.state != self.DISCONNECTING:
             logger.warning(color('invalid state', 'red'))
             return
@@ -1240,11 +1291,11 @@ class LeConnectionOrientedChannel(EventEmitter):
             self.disconnection_result.set_result(None)
             self.disconnection_result = None
 
-    def flush_output(self):
+    def flush_output(self) -> None:
         self.out_queue.clear()
         self.out_sdu = None
 
-    def process_output(self):
+    def process_output(self) -> None:
         while self.credits > 0:
             if self.out_sdu is not None:
                 # Finish the current SDU
@@ -1287,7 +1338,7 @@ class LeConnectionOrientedChannel(EventEmitter):
                 self.drained.set()
                 return
 
-    def write(self, data):
+    def write(self, data: bytes) -> None:
         if self.state != self.CONNECTED:
             logger.warning('not connected, dropping data')
             return
@@ -1302,18 +1353,18 @@ class LeConnectionOrientedChannel(EventEmitter):
         # Send what we can
         self.process_output()
 
-    async def drain(self):
+    async def drain(self) -> None:
         await self.drained.wait()
 
-    def pause_reading(self):
+    def pause_reading(self) -> None:
         # TODO: not implemented yet
         pass
 
-    def resume_reading(self):
+    def resume_reading(self) -> None:
         # TODO: not implemented yet
         pass
 
-    def __str__(self):
+    def __str__(self) -> str:
         return (
             f'CoC({self.source_cid}->{self.destination_cid}, '
             f'State={self.state_name(self.state)}, '
@@ -1326,9 +1377,23 @@ class LeConnectionOrientedChannel(EventEmitter):
 
 # -----------------------------------------------------------------------------
 class ChannelManager:
+    identifiers: Dict[int, int]
+    channels: Dict[int, Dict[int, Union[Channel, LeConnectionOrientedChannel]]]
+    servers: Dict[int, Callable[[Channel], Any]]
+    le_coc_channels: Dict[int, Dict[int, LeConnectionOrientedChannel]]
+    le_coc_servers: Dict[
+        int, Tuple[Callable[[LeConnectionOrientedChannel], Any], int, int, int]
+    ]
+    le_coc_requests: Dict[int, L2CAP_LE_Credit_Based_Connection_Request]
+    fixed_channels: Dict[int, Optional[Callable[[int, bytes], Any]]]
+    _host: Optional[Host]
+    connection_parameters_update_response: Optional[asyncio.Future[int]]
+
     def __init__(
-        self, extended_features=(), connectionless_mtu=L2CAP_DEFAULT_CONNECTIONLESS_MTU
-    ):
+        self,
+        extended_features: Iterable[int] = (),
+        connectionless_mtu: int = L2CAP_DEFAULT_CONNECTIONLESS_MTU,
+    ) -> None:
         self._host = None
         self.identifiers = {}  # Incrementing identifier values by connection
         self.channels = {}  # All channels, mapped by connection and source cid
@@ -1344,33 +1409,35 @@ class ChannelManager:
         self.le_coc_requests = {}  # LE CoC connection requests, by identifier
         self.extended_features = extended_features
         self.connectionless_mtu = connectionless_mtu
+        self.connection_parameters_update_response = None
 
     @property
-    def host(self):
+    def host(self) -> Host:
+        assert self._host
         return self._host
 
     @host.setter
-    def host(self, host):
+    def host(self, host: Host) -> None:
         if self._host is not None:
             self._host.remove_listener('disconnection', self.on_disconnection)
         self._host = host
         if host is not None:
             host.on('disconnection', self.on_disconnection)
 
-    def find_channel(self, connection_handle, cid):
+    def find_channel(self, connection_handle: int, cid: int):
         if connection_channels := self.channels.get(connection_handle):
             return connection_channels.get(cid)
 
         return None
 
-    def find_le_coc_channel(self, connection_handle, cid):
+    def find_le_coc_channel(self, connection_handle: int, cid: int):
         if connection_channels := self.le_coc_channels.get(connection_handle):
             return connection_channels.get(cid)
 
         return None
 
     @staticmethod
-    def find_free_br_edr_cid(channels):
+    def find_free_br_edr_cid(channels: Iterable[int]) -> int:
         # Pick the smallest valid CID that's not already in the list
         # (not necessarily the most efficient algorithm, but the list of CID is
         # very small in practice)
@@ -1383,7 +1450,7 @@ class ChannelManager:
         raise RuntimeError('no free CID available')
 
     @staticmethod
-    def find_free_le_cid(channels):
+    def find_free_le_cid(channels: Iterable[int]) -> int:
         # Pick the smallest valid CID that's not already in the list
         # (not necessarily the most efficient algorithm, but the list of CID is
         # very small in practice)
@@ -1396,7 +1463,7 @@ class ChannelManager:
         raise RuntimeError('no free CID')
 
     @staticmethod
-    def check_le_coc_parameters(max_credits, mtu, mps):
+    def check_le_coc_parameters(max_credits: int, mtu: int, mps: int) -> None:
         if (
             max_credits < 1
             or max_credits > L2CAP_LE_CREDIT_BASED_CONNECTION_MAX_CREDITS
@@ -1410,19 +1477,21 @@ class ChannelManager:
         ):
             raise ValueError('MPS out of range')
 
-    def next_identifier(self, connection):
+    def next_identifier(self, connection: Connection) -> int:
         identifier = (self.identifiers.setdefault(connection.handle, 0) + 1) % 256
         self.identifiers[connection.handle] = identifier
         return identifier
 
-    def register_fixed_channel(self, cid, handler):
+    def register_fixed_channel(
+        self, cid: int, handler: Callable[[int, bytes], Any]
+    ) -> None:
         self.fixed_channels[cid] = handler
 
-    def deregister_fixed_channel(self, cid):
+    def deregister_fixed_channel(self, cid: int) -> None:
         if cid in self.fixed_channels:
             del self.fixed_channels[cid]
 
-    def register_server(self, psm, server):
+    def register_server(self, psm: int, server: Callable[[Channel], Any]) -> int:
         if psm == 0:
             # Find a free PSM
             for candidate in range(
@@ -1456,12 +1525,12 @@ class ChannelManager:
 
     def register_le_coc_server(
         self,
-        psm,
-        server,
-        max_credits=L2CAP_LE_CREDIT_BASED_CONNECTION_DEFAULT_INITIAL_CREDITS,
-        mtu=L2CAP_LE_CREDIT_BASED_CONNECTION_DEFAULT_MTU,
-        mps=L2CAP_LE_CREDIT_BASED_CONNECTION_DEFAULT_MPS,
-    ):
+        psm: int,
+        server: Callable[[LeConnectionOrientedChannel], Any],
+        max_credits: int = L2CAP_LE_CREDIT_BASED_CONNECTION_DEFAULT_INITIAL_CREDITS,
+        mtu: int = L2CAP_LE_CREDIT_BASED_CONNECTION_DEFAULT_MTU,
+        mps: int = L2CAP_LE_CREDIT_BASED_CONNECTION_DEFAULT_MPS,
+    ) -> int:
         self.check_le_coc_parameters(max_credits, mtu, mps)
 
         if psm == 0:
@@ -1489,16 +1558,20 @@ class ChannelManager:
 
         return psm
 
-    def on_disconnection(self, connection_handle, _reason):
+    def on_disconnection(self, connection_handle: int, _reason: int) -> None:
         logger.debug(f'disconnection from {connection_handle}, cleaning up channels')
         if connection_handle in self.channels:
+            for _, channel in self.channels[connection_handle].items():
+                channel.abort()
             del self.channels[connection_handle]
         if connection_handle in self.le_coc_channels:
+            for _, channel in self.le_coc_channels[connection_handle].items():
+                channel.abort()
             del self.le_coc_channels[connection_handle]
         if connection_handle in self.identifiers:
             del self.identifiers[connection_handle]
 
-    def send_pdu(self, connection, cid, pdu):
+    def send_pdu(self, connection, cid: int, pdu: Union[SupportsBytes, bytes]) -> None:
         pdu_str = pdu.hex() if isinstance(pdu, bytes) else str(pdu)
         logger.debug(
             f'{color(">>> Sending L2CAP PDU", "blue")} '
@@ -1507,14 +1580,16 @@ class ChannelManager:
         )
         self.host.send_l2cap_pdu(connection.handle, cid, bytes(pdu))
 
-    def on_pdu(self, connection, cid, pdu):
+    def on_pdu(self, connection: Connection, cid: int, pdu: bytes) -> None:
         if cid in (L2CAP_SIGNALING_CID, L2CAP_LE_SIGNALING_CID):
             # Parse the L2CAP payload into a Control Frame object
             control_frame = L2CAP_Control_Frame.from_bytes(pdu)
 
             self.on_control_frame(connection, cid, control_frame)
         elif cid in self.fixed_channels:
-            self.fixed_channels[cid](connection.handle, pdu)
+            handler = self.fixed_channels[cid]
+            assert handler is not None
+            handler(connection.handle, pdu)
         else:
             if (channel := self.find_channel(connection.handle, cid)) is None:
                 logger.warning(
@@ -1526,7 +1601,9 @@ class ChannelManager:
 
             channel.on_pdu(pdu)
 
-    def send_control_frame(self, connection, cid, control_frame):
+    def send_control_frame(
+        self, connection: Connection, cid: int, control_frame: L2CAP_Control_Frame
+    ) -> None:
         logger.debug(
             f'{color(">>> Sending L2CAP Signaling Control Frame", "blue")} '
             f'on connection [0x{connection.handle:04X}] (CID={cid}) '
@@ -1534,7 +1611,9 @@ class ChannelManager:
         )
         self.host.send_l2cap_pdu(connection.handle, cid, bytes(control_frame))
 
-    def on_control_frame(self, connection, cid, control_frame):
+    def on_control_frame(
+        self, connection: Connection, cid: int, control_frame: L2CAP_Control_Frame
+    ) -> None:
         logger.debug(
             f'{color("<<< Received L2CAP Signaling Control Frame", "green")} '
             f'on connection [0x{connection.handle:04X}] (CID={cid}) '
@@ -1571,10 +1650,14 @@ class ChannelManager:
                 ),
             )
 
-    def on_l2cap_command_reject(self, _connection, _cid, packet):
+    def on_l2cap_command_reject(
+        self, _connection: Connection, _cid: int, packet
+    ) -> None:
         logger.warning(f'{color("!!! Command rejected:", "red")} {packet.reason}')
 
-    def on_l2cap_connection_request(self, connection, cid, request):
+    def on_l2cap_connection_request(
+        self, connection: Connection, cid: int, request
+    ) -> None:
         # Check if there's a server for this PSM
         server = self.servers.get(request.psm)
         if server:
@@ -1626,7 +1709,9 @@ class ChannelManager:
                 ),
             )
 
-    def on_l2cap_connection_response(self, connection, cid, response):
+    def on_l2cap_connection_response(
+        self, connection: Connection, cid: int, response
+    ) -> None:
         if (
             channel := self.find_channel(connection.handle, response.source_cid)
         ) is None:
@@ -1641,7 +1726,9 @@ class ChannelManager:
 
         channel.on_connection_response(response)
 
-    def on_l2cap_configure_request(self, connection, cid, request):
+    def on_l2cap_configure_request(
+        self, connection: Connection, cid: int, request
+    ) -> None:
         if (
             channel := self.find_channel(connection.handle, request.destination_cid)
         ) is None:
@@ -1656,7 +1743,9 @@ class ChannelManager:
 
         channel.on_configure_request(request)
 
-    def on_l2cap_configure_response(self, connection, cid, response):
+    def on_l2cap_configure_response(
+        self, connection: Connection, cid: int, response
+    ) -> None:
         if (
             channel := self.find_channel(connection.handle, response.source_cid)
         ) is None:
@@ -1671,7 +1760,9 @@ class ChannelManager:
 
         channel.on_configure_response(response)
 
-    def on_l2cap_disconnection_request(self, connection, cid, request):
+    def on_l2cap_disconnection_request(
+        self, connection: Connection, cid: int, request
+    ) -> None:
         if (
             channel := self.find_channel(connection.handle, request.destination_cid)
         ) is None:
@@ -1686,7 +1777,9 @@ class ChannelManager:
 
         channel.on_disconnection_request(request)
 
-    def on_l2cap_disconnection_response(self, connection, cid, response):
+    def on_l2cap_disconnection_response(
+        self, connection: Connection, cid: int, response
+    ) -> None:
         if (
             channel := self.find_channel(connection.handle, response.source_cid)
         ) is None:
@@ -1701,7 +1794,7 @@ class ChannelManager:
 
         channel.on_disconnection_response(response)
 
-    def on_l2cap_echo_request(self, connection, cid, request):
+    def on_l2cap_echo_request(self, connection: Connection, cid: int, request) -> None:
         logger.debug(f'<<< Echo request: data={request.data.hex()}')
         self.send_control_frame(
             connection,
@@ -1709,11 +1802,15 @@ class ChannelManager:
             L2CAP_Echo_Response(identifier=request.identifier, data=request.data),
         )
 
-    def on_l2cap_echo_response(self, _connection, _cid, response):
+    def on_l2cap_echo_response(
+        self, _connection: Connection, _cid: int, response
+    ) -> None:
         logger.debug(f'<<< Echo response: data={response.data.hex()}')
         # TODO notify listeners
 
-    def on_l2cap_information_request(self, connection, cid, request):
+    def on_l2cap_information_request(
+        self, connection: Connection, cid: int, request
+    ) -> None:
         if request.info_type == L2CAP_Information_Request.CONNECTIONLESS_MTU:
             result = L2CAP_Information_Response.SUCCESS
             data = self.connectionless_mtu.to_bytes(2, 'little')
@@ -1737,7 +1834,9 @@ class ChannelManager:
             ),
         )
 
-    def on_l2cap_connection_parameter_update_request(self, connection, cid, request):
+    def on_l2cap_connection_parameter_update_request(
+        self, connection: Connection, cid: int, request
+    ):
         if connection.role == BT_CENTRAL_ROLE:
             self.send_control_frame(
                 connection,
@@ -1756,7 +1855,7 @@ class ChannelManager:
                     supervision_timeout=request.timeout,
                     min_ce_length=0,
                     max_ce_length=0,
-                )
+                )  # type: ignore[call-arg]
             )
         else:
             self.send_control_frame(
@@ -1768,11 +1867,49 @@ class ChannelManager:
                 ),
             )
 
-    def on_l2cap_connection_parameter_update_response(self, connection, cid, response):
-        # TODO: check response
-        pass
+    async def update_connection_parameters(
+        self,
+        connection: Connection,
+        interval_min: int,
+        interval_max: int,
+        latency: int,
+        timeout: int,
+    ) -> int:
+        # Check that there isn't already a request pending
+        if self.connection_parameters_update_response:
+            raise InvalidStateError('request already pending')
+        self.connection_parameters_update_response = (
+            asyncio.get_running_loop().create_future()
+        )
+        self.send_control_frame(
+            connection,
+            L2CAP_LE_SIGNALING_CID,
+            L2CAP_Connection_Parameter_Update_Request(
+                interval_min=interval_min,
+                interval_max=interval_max,
+                latency=latency,
+                timeout=timeout,
+            ),
+        )
+        return await self.connection_parameters_update_response
 
-    def on_l2cap_le_credit_based_connection_request(self, connection, cid, request):
+    def on_l2cap_connection_parameter_update_response(
+        self, connection: Connection, cid: int, response
+    ) -> None:
+        if self.connection_parameters_update_response:
+            self.connection_parameters_update_response.set_result(response.result)
+            self.connection_parameters_update_response = None
+        else:
+            logger.warning(
+                color(
+                    'received l2cap_connection_parameter_update_response without a pending request',
+                    'red',
+                )
+            )
+
+    def on_l2cap_le_credit_based_connection_request(
+        self, connection: Connection, cid: int, request
+    ) -> None:
         if request.le_psm in self.le_coc_servers:
             (server, max_credits, mtu, mps) = self.le_coc_servers[request.le_psm]
 
@@ -1874,7 +2011,9 @@ class ChannelManager:
                 ),
             )
 
-    def on_l2cap_le_credit_based_connection_response(self, connection, _cid, response):
+    def on_l2cap_le_credit_based_connection_response(
+        self, connection: Connection, _cid: int, response
+    ) -> None:
         # Find the pending request by identifier
         request = self.le_coc_requests.get(response.identifier)
         if request is None:
@@ -1897,7 +2036,9 @@ class ChannelManager:
         # Process the response
         channel.on_connection_response(response)
 
-    def on_l2cap_le_flow_control_credit(self, connection, _cid, credit):
+    def on_l2cap_le_flow_control_credit(
+        self, connection: Connection, _cid: int, credit
+    ) -> None:
         channel = self.find_le_coc_channel(connection.handle, credit.cid)
         if channel is None:
             logger.warning(f'received credits for an unknown channel (cid={credit.cid}')
@@ -1905,13 +2046,15 @@ class ChannelManager:
 
         channel.on_credits(credit.credits)
 
-    def on_channel_closed(self, channel):
+    def on_channel_closed(self, channel: Channel) -> None:
         connection_channels = self.channels.get(channel.connection.handle)
         if connection_channels:
             if channel.source_cid in connection_channels:
                 del connection_channels[channel.source_cid]
 
-    async def open_le_coc(self, connection, psm, max_credits, mtu, mps):
+    async def open_le_coc(
+        self, connection: Connection, psm: int, max_credits: int, mtu: int, mps: int
+    ) -> LeConnectionOrientedChannel:
         self.check_le_coc_parameters(max_credits, mtu, mps)
 
         # Find a free CID for the new channel
@@ -1952,7 +2095,7 @@ class ChannelManager:
 
         return channel
 
-    async def connect(self, connection, psm):
+    async def connect(self, connection: Connection, psm: int) -> Channel:
         # NOTE: this implementation hard-codes BR/EDR
 
         # Find a free CID for a new channel
@@ -1971,7 +2114,8 @@ class ChannelManager:
         # Connect
         try:
             await channel.connect()
-        except Exception:
+        except Exception as e:
             del connection_channels[source_cid]
+            raise e
 
         return channel

bumble/link.py

@@ -19,12 +19,15 @@ import logging
 import asyncio
 from functools import partial
 
+from bumble.core import BT_PERIPHERAL_ROLE, BT_BR_EDR_TRANSPORT, BT_LE_TRANSPORT
 from bumble.colors import color
 from bumble.hci import (
     Address,
     HCI_SUCCESS,
     HCI_CONNECTION_ACCEPT_TIMEOUT_ERROR,
     HCI_CONNECTION_TIMEOUT_ERROR,
+    HCI_PAGE_TIMEOUT_ERROR,
+    HCI_Connection_Complete_Event,
 )
 
 # -----------------------------------------------------------------------------
@@ -57,6 +60,11 @@ class LocalLink:
     def __init__(self):
         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 +79,39 @@ class LocalLink:
                 return controller
         return None
 
-    def on_address_changed(self, controller):
-        pass
+    def find_classic_controller(self, address):
+        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
+
+        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
@@ -163,6 +188,89 @@ class LocalLink:
         if peripheral_controller := self.find_controller(peripheral_address):
             peripheral_controller.on_link_encrypted(central_address, rand, ediv, ltk)
 
+    ############################################################
+    # 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))
+        )
+
 
 # -----------------------------------------------------------------------------
 class RemoteLink:
@@ -200,6 +308,9 @@ class RemoteLink:
     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
 
@@ -366,7 +477,8 @@ class RemoteLink:
     async def send_acl_data_to_relay(self, peer_address, data):
         await self.send_targeted_message(peer_address, f'acl:{data.hex()}')
 
-    def send_acl_data(self, _, peer_address, 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):

bumble/pairing.py

@@ -0,0 +1,196 @@
+# 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
+# -----------------------------------------------------------------------------
+import enum
+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,
+)
+
+
+# -----------------------------------------------------------------------------
+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
+
+    def __init__(
+        self,
+        sc: bool = True,
+        mitm: bool = True,
+        bonding: bool = True,
+        delegate: Optional[PairingDelegate] = None,
+        identity_address_type: Optional[AddressType] = None,
+    ) -> None:
+        self.sc = sc
+        self.mitm = mitm
+        self.bonding = bonding
+        self.delegate = delegate or PairingDelegate()
+        self.identity_address_type = identity_address_type
+
+    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}])'
+        )

bumble/pandora/__init__.py

@@ -0,0 +1,105 @@
+# 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 .security import SecurityService, SecurityStorageService
+from pandora.host_grpc_aio import add_HostServicer_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
+            )
+
+            # 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,55 @@
+# 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 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,163 @@
+# 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 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/host.py

@@ -0,0 +1,857 @@
+# 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.
+
+import asyncio
+import bumble.device
+import grpc
+import grpc.aio
+import logging
+import struct
+
+from . import utils
+from .config import Config
+from bumble.core import (
+    BT_BR_EDR_TRANSPORT,
+    BT_LE_TRANSPORT,
+    BT_PERIPHERAL_ROLE,
+    UUID,
+    AdvertisingData,
+    ConnectionError,
+)
+from bumble.device import (
+    DEVICE_DEFAULT_SCAN_INTERVAL,
+    DEVICE_DEFAULT_SCAN_WINDOW,
+    Advertisement,
+    AdvertisingType,
+    Device,
+)
+from bumble.gatt import Service
+from bumble.hci import (
+    HCI_CONNECTION_ALREADY_EXISTS_ERROR,
+    HCI_PAGE_TIMEOUT_ERROR,
+    HCI_REMOTE_USER_TERMINATED_CONNECTION_ERROR,
+    Address,
+)
+from google.protobuf import any_pb2  # pytype: disable=pyi-error
+from google.protobuf import empty_pb2  # pytype: disable=pyi-error
+from pandora.host_grpc_aio import HostServicer
+from pandora.host_pb2 import (
+    NOT_CONNECTABLE,
+    NOT_DISCOVERABLE,
+    PRIMARY_1M,
+    PRIMARY_CODED,
+    SECONDARY_1M,
+    SECONDARY_2M,
+    SECONDARY_CODED,
+    SECONDARY_NONE,
+    AdvertiseRequest,
+    AdvertiseResponse,
+    Connection,
+    ConnectLERequest,
+    ConnectLEResponse,
+    ConnectRequest,
+    ConnectResponse,
+    DataTypes,
+    DisconnectRequest,
+    InquiryResponse,
+    PrimaryPhy,
+    ReadLocalAddressResponse,
+    ScanningResponse,
+    ScanRequest,
+    SecondaryPhy,
+    SetConnectabilityModeRequest,
+    SetDiscoverabilityModeRequest,
+    WaitConnectionRequest,
+    WaitConnectionResponse,
+    WaitDisconnectionRequest,
+)
+from typing import AsyncGenerator, Dict, List, Optional, Set, Tuple, cast
+
+PRIMARY_PHY_MAP: Dict[int, PrimaryPhy] = {
+    # Default value reported by Bumble for legacy Advertising reports.
+    # FIXME(uael): `None` might be a better value, but Bumble need to change accordingly.
+    0: PRIMARY_1M,
+    1: PRIMARY_1M,
+    3: PRIMARY_CODED,
+}
+
+SECONDARY_PHY_MAP: Dict[int, SecondaryPhy] = {
+    0: SECONDARY_NONE,
+    1: SECONDARY_1M,
+    2: SECONDARY_2M,
+    3: SECONDARY_CODED,
+}
+
+
+class HostService(HostServicer):
+    waited_connections: Set[int]
+
+    def __init__(
+        self, grpc_server: grpc.aio.Server, device: Device, config: Config
+    ) -> None:
+        self.log = utils.BumbleServerLoggerAdapter(
+            logging.getLogger(), {'service_name': 'Host', 'device': device}
+        )
+        self.grpc_server = grpc_server
+        self.device = device
+        self.config = config
+        self.waited_connections = set()
+
+    @utils.rpc
+    async def FactoryReset(
+        self, request: empty_pb2.Empty, context: grpc.ServicerContext
+    ) -> empty_pb2.Empty:
+        self.log.debug('FactoryReset')
+
+        # delete all bonds
+        if self.device.keystore is not None:
+            await self.device.keystore.delete_all()
+
+        # trigger gRCP server stop then return
+        asyncio.create_task(self.grpc_server.stop(None))
+        return empty_pb2.Empty()
+
+    @utils.rpc
+    async def Reset(
+        self, request: empty_pb2.Empty, context: grpc.ServicerContext
+    ) -> empty_pb2.Empty:
+        self.log.debug('Reset')
+
+        # clear service.
+        self.waited_connections.clear()
+
+        # (re) power device on
+        await self.device.power_on()
+        return empty_pb2.Empty()
+
+    @utils.rpc
+    async def ReadLocalAddress(
+        self, request: empty_pb2.Empty, context: grpc.ServicerContext
+    ) -> ReadLocalAddressResponse:
+        self.log.debug('ReadLocalAddress')
+        return ReadLocalAddressResponse(
+            address=bytes(reversed(bytes(self.device.public_address)))
+        )
+
+    @utils.rpc
+    async def Connect(
+        self, request: ConnectRequest, context: grpc.ServicerContext
+    ) -> ConnectResponse:
+        # Need to reverse bytes order since Bumble Address is using MSB.
+        address = Address(
+            bytes(reversed(request.address)), address_type=Address.PUBLIC_DEVICE_ADDRESS
+        )
+        self.log.debug(f"Connect to {address}")
+
+        try:
+            connection = await self.device.connect(
+                address, transport=BT_BR_EDR_TRANSPORT
+            )
+        except ConnectionError as e:
+            if e.error_code == HCI_PAGE_TIMEOUT_ERROR:
+                self.log.warning(f"Peer not found: {e}")
+                return ConnectResponse(peer_not_found=empty_pb2.Empty())
+            if e.error_code == HCI_CONNECTION_ALREADY_EXISTS_ERROR:
+                self.log.warning(f"Connection already exists: {e}")
+                return ConnectResponse(connection_already_exists=empty_pb2.Empty())
+            raise e
+
+        self.log.debug(f"Connect to {address} done (handle={connection.handle})")
+
+        cookie = any_pb2.Any(value=connection.handle.to_bytes(4, 'big'))
+        return ConnectResponse(connection=Connection(cookie=cookie))
+
+    @utils.rpc
+    async def WaitConnection(
+        self, request: WaitConnectionRequest, context: grpc.ServicerContext
+    ) -> WaitConnectionResponse:
+        if not request.address:
+            raise ValueError('Request address field must be set')
+
+        # Need to reverse bytes order since Bumble Address is using MSB.
+        address = Address(
+            bytes(reversed(request.address)), address_type=Address.PUBLIC_DEVICE_ADDRESS
+        )
+        if address in (Address.NIL, Address.ANY):
+            raise ValueError('Invalid address')
+
+        self.log.debug(f"WaitConnection from {address}...")
+
+        connection = self.device.find_connection_by_bd_addr(
+            address, transport=BT_BR_EDR_TRANSPORT
+        )
+        if connection and id(connection) in self.waited_connections:
+            # this connection was already returned: wait for a new one.
+            connection = None
+
+        if not connection:
+            connection = await self.device.accept(address)
+
+        # save connection has waited and respond.
+        self.waited_connections.add(id(connection))
+
+        self.log.debug(
+            f"WaitConnection from {address} done (handle={connection.handle})"
+        )
+
+        cookie = any_pb2.Any(value=connection.handle.to_bytes(4, 'big'))
+        return WaitConnectionResponse(connection=Connection(cookie=cookie))
+
+    @utils.rpc
+    async def ConnectLE(
+        self, request: ConnectLERequest, context: grpc.ServicerContext
+    ) -> ConnectLEResponse:
+        address = utils.address_from_request(request, request.WhichOneof("address"))
+        if address in (Address.NIL, Address.ANY):
+            raise ValueError('Invalid address')
+
+        self.log.debug(f"ConnectLE to {address}...")
+
+        try:
+            connection = await self.device.connect(
+                address,
+                transport=BT_LE_TRANSPORT,
+                own_address_type=request.own_address_type,
+            )
+        except ConnectionError as e:
+            if e.error_code == HCI_PAGE_TIMEOUT_ERROR:
+                self.log.warning(f"Peer not found: {e}")
+                return ConnectLEResponse(peer_not_found=empty_pb2.Empty())
+            if e.error_code == HCI_CONNECTION_ALREADY_EXISTS_ERROR:
+                self.log.warning(f"Connection already exists: {e}")
+                return ConnectLEResponse(connection_already_exists=empty_pb2.Empty())
+            raise e
+
+        self.log.debug(f"ConnectLE to {address} done (handle={connection.handle})")
+
+        cookie = any_pb2.Any(value=connection.handle.to_bytes(4, 'big'))
+        return ConnectLEResponse(connection=Connection(cookie=cookie))
+
+    @utils.rpc
+    async def Disconnect(
+        self, request: DisconnectRequest, context: grpc.ServicerContext
+    ) -> empty_pb2.Empty:
+        connection_handle = int.from_bytes(request.connection.cookie.value, 'big')
+        self.log.debug(f"Disconnect: {connection_handle}")
+
+        self.log.debug("Disconnecting...")
+        if connection := self.device.lookup_connection(connection_handle):
+            await connection.disconnect(HCI_REMOTE_USER_TERMINATED_CONNECTION_ERROR)
+        self.log.debug("Disconnected")
+
+        return empty_pb2.Empty()
+
+    @utils.rpc
+    async def WaitDisconnection(
+        self, request: WaitDisconnectionRequest, context: grpc.ServicerContext
+    ) -> empty_pb2.Empty:
+        connection_handle = int.from_bytes(request.connection.cookie.value, 'big')
+        self.log.debug(f"WaitDisconnection: {connection_handle}")
+
+        if connection := self.device.lookup_connection(connection_handle):
+            disconnection_future: asyncio.Future[
+                None
+            ] = asyncio.get_running_loop().create_future()
+
+            def on_disconnection(_: None) -> None:
+                disconnection_future.set_result(None)
+
+            connection.on('disconnection', on_disconnection)
+            try:
+                await disconnection_future
+                self.log.debug("Disconnected")
+            finally:
+                connection.remove_listener('disconnection', on_disconnection)  # type: ignore
+
+        return empty_pb2.Empty()
+
+    @utils.rpc
+    async def Advertise(
+        self, request: AdvertiseRequest, context: grpc.ServicerContext
+    ) -> AsyncGenerator[AdvertiseResponse, None]:
+        if not request.legacy:
+            raise NotImplementedError(
+                "TODO: add support for extended advertising in Bumble"
+            )
+        if request.interval:
+            raise NotImplementedError("TODO: add support for `request.interval`")
+        if request.interval_range:
+            raise NotImplementedError("TODO: add support for `request.interval_range`")
+        if request.primary_phy:
+            raise NotImplementedError("TODO: add support for `request.primary_phy`")
+        if request.secondary_phy:
+            raise NotImplementedError("TODO: add support for `request.secondary_phy`")
+
+        if self.device.is_advertising:
+            raise NotImplementedError('TODO: add support for advertising sets')
+
+        if data := request.data:
+            self.device.advertising_data = bytes(self.unpack_data_types(data))
+
+            if scan_response_data := request.scan_response_data:
+                self.device.scan_response_data = bytes(
+                    self.unpack_data_types(scan_response_data)
+                )
+                scannable = True
+            else:
+                scannable = False
+
+            # Retrieve services data
+            for service in self.device.gatt_server.attributes:
+                if isinstance(service, Service) and (
+                    service_data := service.get_advertising_data()
+                ):
+                    service_uuid = service.uuid.to_hex_str('-')
+                    if (
+                        service_uuid in request.data.incomplete_service_class_uuids16
+                        or service_uuid in request.data.complete_service_class_uuids16
+                        or service_uuid in request.data.incomplete_service_class_uuids32
+                        or service_uuid in request.data.complete_service_class_uuids32
+                        or service_uuid
+                        in request.data.incomplete_service_class_uuids128
+                        or service_uuid in request.data.complete_service_class_uuids128
+                    ):
+                        self.device.advertising_data += service_data
+                    if (
+                        service_uuid
+                        in scan_response_data.incomplete_service_class_uuids16
+                        or service_uuid
+                        in scan_response_data.complete_service_class_uuids16
+                        or service_uuid
+                        in scan_response_data.incomplete_service_class_uuids32
+                        or service_uuid
+                        in scan_response_data.complete_service_class_uuids32
+                        or service_uuid
+                        in scan_response_data.incomplete_service_class_uuids128
+                        or service_uuid
+                        in scan_response_data.complete_service_class_uuids128
+                    ):
+                        self.device.scan_response_data += service_data
+
+            target = None
+            if request.connectable and scannable:
+                advertising_type = AdvertisingType.UNDIRECTED_CONNECTABLE_SCANNABLE
+            elif scannable:
+                advertising_type = AdvertisingType.UNDIRECTED_SCANNABLE
+            else:
+                advertising_type = AdvertisingType.UNDIRECTED
+        else:
+            target = None
+            advertising_type = AdvertisingType.UNDIRECTED
+
+        if request.target:
+            # Need to reverse bytes order since Bumble Address is using MSB.
+            target_bytes = bytes(reversed(request.target))
+            if request.target_variant() == "public":
+                target = Address(target_bytes, Address.PUBLIC_DEVICE_ADDRESS)
+                advertising_type = (
+                    AdvertisingType.DIRECTED_CONNECTABLE_HIGH_DUTY
+                )  # FIXME: HIGH_DUTY ?
+            else:
+                target = Address(target_bytes, Address.RANDOM_DEVICE_ADDRESS)
+                advertising_type = (
+                    AdvertisingType.DIRECTED_CONNECTABLE_HIGH_DUTY
+                )  # FIXME: HIGH_DUTY ?
+
+        if request.connectable:
+
+            def on_connection(connection: bumble.device.Connection) -> None:
+                if (
+                    connection.transport == BT_LE_TRANSPORT
+                    and connection.role == BT_PERIPHERAL_ROLE
+                ):
+                    pending_connection.set_result(connection)
+
+            self.device.on('connection', on_connection)
+
+        try:
+            while True:
+                if not self.device.is_advertising:
+                    self.log.debug('Advertise')
+                    await self.device.start_advertising(
+                        target=target,
+                        advertising_type=advertising_type,
+                        own_address_type=request.own_address_type,
+                    )
+
+                if not request.connectable:
+                    await asyncio.sleep(1)
+                    continue
+
+                pending_connection: asyncio.Future[
+                    bumble.device.Connection
+                ] = asyncio.get_running_loop().create_future()
+
+                self.log.debug('Wait for LE connection...')
+                connection = await pending_connection
+
+                self.log.debug(
+                    f"Advertise: Connected to {connection.peer_address} (handle={connection.handle})"
+                )
+
+                cookie = any_pb2.Any(value=connection.handle.to_bytes(4, 'big'))
+                yield AdvertiseResponse(connection=Connection(cookie=cookie))
+
+                # wait a small delay before restarting the advertisement.
+                await asyncio.sleep(1)
+        finally:
+            if request.connectable:
+                self.device.remove_listener('connection', on_connection)  # type: ignore
+
+            try:
+                self.log.debug('Stop advertising')
+                await self.device.abort_on('flush', self.device.stop_advertising())
+            except:
+                pass
+
+    @utils.rpc
+    async def Scan(
+        self, request: ScanRequest, context: grpc.ServicerContext
+    ) -> AsyncGenerator[ScanningResponse, None]:
+        # TODO: modify `start_scanning` to accept floats instead of int for ms values
+        if request.phys:
+            raise NotImplementedError("TODO: add support for `request.phys`")
+
+        self.log.debug('Scan')
+
+        scan_queue: asyncio.Queue[Advertisement] = asyncio.Queue()
+        handler = self.device.on('advertisement', scan_queue.put_nowait)
+        await self.device.start_scanning(
+            legacy=request.legacy,
+            active=not request.passive,
+            own_address_type=request.own_address_type,
+            scan_interval=int(request.interval)
+            if request.interval
+            else DEVICE_DEFAULT_SCAN_INTERVAL,
+            scan_window=int(request.window)
+            if request.window
+            else DEVICE_DEFAULT_SCAN_WINDOW,
+        )
+
+        try:
+            # TODO: add support for `direct_address` in Bumble
+            # TODO: add support for `periodic_advertising_interval` in Bumble
+            while adv := await scan_queue.get():
+                sr = ScanningResponse(
+                    legacy=adv.is_legacy,
+                    connectable=adv.is_connectable,
+                    scannable=adv.is_scannable,
+                    truncated=adv.is_truncated,
+                    sid=adv.sid,
+                    primary_phy=PRIMARY_PHY_MAP[adv.primary_phy],
+                    secondary_phy=SECONDARY_PHY_MAP[adv.secondary_phy],
+                    tx_power=adv.tx_power,
+                    rssi=adv.rssi,
+                    data=self.pack_data_types(adv.data),
+                )
+
+                if adv.address.address_type == Address.PUBLIC_DEVICE_ADDRESS:
+                    sr.public = bytes(reversed(bytes(adv.address)))
+                elif adv.address.address_type == Address.RANDOM_DEVICE_ADDRESS:
+                    sr.random = bytes(reversed(bytes(adv.address)))
+                elif adv.address.address_type == Address.PUBLIC_IDENTITY_ADDRESS:
+                    sr.public_identity = bytes(reversed(bytes(adv.address)))
+                else:
+                    sr.random_static_identity = bytes(reversed(bytes(adv.address)))
+
+                yield sr
+
+        finally:
+            self.device.remove_listener('advertisement', handler)  # type: ignore
+            try:
+                self.log.debug('Stop scanning')
+                await self.device.abort_on('flush', self.device.stop_scanning())
+            except:
+                pass
+
+    @utils.rpc
+    async def Inquiry(
+        self, request: empty_pb2.Empty, context: grpc.ServicerContext
+    ) -> AsyncGenerator[InquiryResponse, None]:
+        self.log.debug('Inquiry')
+
+        inquiry_queue: asyncio.Queue[
+            Optional[Tuple[Address, int, AdvertisingData, int]]
+        ] = asyncio.Queue()
+        complete_handler = self.device.on(
+            'inquiry_complete', lambda: inquiry_queue.put_nowait(None)
+        )
+        result_handler = self.device.on(  # type: ignore
+            'inquiry_result',
+            lambda address, class_of_device, eir_data, rssi: inquiry_queue.put_nowait(  # type: ignore
+                (address, class_of_device, eir_data, rssi)  # type: ignore
+            ),
+        )
+
+        await self.device.start_discovery(auto_restart=False)
+        try:
+            while inquiry_result := await inquiry_queue.get():
+                (address, class_of_device, eir_data, rssi) = inquiry_result
+                # FIXME: if needed, add support for `page_scan_repetition_mode` and `clock_offset` in Bumble
+                yield InquiryResponse(
+                    address=bytes(reversed(bytes(address))),
+                    class_of_device=class_of_device,
+                    rssi=rssi,
+                    data=self.pack_data_types(eir_data),
+                )
+
+        finally:
+            self.device.remove_listener('inquiry_complete', complete_handler)  # type: ignore
+            self.device.remove_listener('inquiry_result', result_handler)  # type: ignore
+            try:
+                self.log.debug('Stop inquiry')
+                await self.device.abort_on('flush', self.device.stop_discovery())
+            except:
+                pass
+
+    @utils.rpc
+    async def SetDiscoverabilityMode(
+        self, request: SetDiscoverabilityModeRequest, context: grpc.ServicerContext
+    ) -> empty_pb2.Empty:
+        self.log.debug("SetDiscoverabilityMode")
+        await self.device.set_discoverable(request.mode != NOT_DISCOVERABLE)
+        return empty_pb2.Empty()
+
+    @utils.rpc
+    async def SetConnectabilityMode(
+        self, request: SetConnectabilityModeRequest, context: grpc.ServicerContext
+    ) -> empty_pb2.Empty:
+        self.log.debug("SetConnectabilityMode")
+        await self.device.set_connectable(request.mode != NOT_CONNECTABLE)
+        return empty_pb2.Empty()
+
+    def unpack_data_types(self, dt: DataTypes) -> AdvertisingData:
+        ad_structures: List[Tuple[int, bytes]] = []
+
+        uuids: List[str]
+        datas: Dict[str, bytes]
+
+        def uuid128_from_str(uuid: str) -> bytes:
+            """Decode a 128-bit uuid encoded as XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
+            to byte format."""
+            return bytes(reversed(bytes.fromhex(uuid.replace('-', ''))))
+
+        def uuid32_from_str(uuid: str) -> bytes:
+            """Decode a 32-bit uuid encoded as XXXXXXXX to byte format."""
+            return bytes(reversed(bytes.fromhex(uuid)))
+
+        def uuid16_from_str(uuid: str) -> bytes:
+            """Decode a 16-bit uuid encoded as XXXX to byte format."""
+            return bytes(reversed(bytes.fromhex(uuid)))
+
+        if uuids := dt.incomplete_service_class_uuids16:
+            ad_structures.append(
+                (
+                    AdvertisingData.INCOMPLETE_LIST_OF_16_BIT_SERVICE_CLASS_UUIDS,
+                    b''.join([uuid16_from_str(uuid) for uuid in uuids]),
+                )
+            )
+        if uuids := dt.complete_service_class_uuids16:
+            ad_structures.append(
+                (
+                    AdvertisingData.COMPLETE_LIST_OF_16_BIT_SERVICE_CLASS_UUIDS,
+                    b''.join([uuid16_from_str(uuid) for uuid in uuids]),
+                )
+            )
+        if uuids := dt.incomplete_service_class_uuids32:
+            ad_structures.append(
+                (
+                    AdvertisingData.INCOMPLETE_LIST_OF_32_BIT_SERVICE_CLASS_UUIDS,
+                    b''.join([uuid32_from_str(uuid) for uuid in uuids]),
+                )
+            )
+        if uuids := dt.complete_service_class_uuids32:
+            ad_structures.append(
+                (
+                    AdvertisingData.COMPLETE_LIST_OF_32_BIT_SERVICE_CLASS_UUIDS,
+                    b''.join([uuid32_from_str(uuid) for uuid in uuids]),
+                )
+            )
+        if uuids := dt.incomplete_service_class_uuids128:
+            ad_structures.append(
+                (
+                    AdvertisingData.INCOMPLETE_LIST_OF_128_BIT_SERVICE_CLASS_UUIDS,
+                    b''.join([uuid128_from_str(uuid) for uuid in uuids]),
+                )
+            )
+        if uuids := dt.complete_service_class_uuids128:
+            ad_structures.append(
+                (
+                    AdvertisingData.COMPLETE_LIST_OF_128_BIT_SERVICE_CLASS_UUIDS,
+                    b''.join([uuid128_from_str(uuid) for uuid in uuids]),
+                )
+            )
+        if dt.HasField('include_shortened_local_name'):
+            ad_structures.append(
+                (
+                    AdvertisingData.SHORTENED_LOCAL_NAME,
+                    bytes(self.device.name[:8], 'utf-8'),
+                )
+            )
+        elif dt.shortened_local_name:
+            ad_structures.append(
+                (
+                    AdvertisingData.SHORTENED_LOCAL_NAME,
+                    bytes(dt.shortened_local_name, 'utf-8'),
+                )
+            )
+        if dt.HasField('include_complete_local_name'):
+            ad_structures.append(
+                (AdvertisingData.COMPLETE_LOCAL_NAME, bytes(self.device.name, 'utf-8'))
+            )
+        elif dt.complete_local_name:
+            ad_structures.append(
+                (
+                    AdvertisingData.COMPLETE_LOCAL_NAME,
+                    bytes(dt.complete_local_name, 'utf-8'),
+                )
+            )
+        if dt.HasField('include_tx_power_level'):
+            raise ValueError('unsupported data type')
+        elif dt.tx_power_level:
+            ad_structures.append(
+                (
+                    AdvertisingData.TX_POWER_LEVEL,
+                    bytes(struct.pack('<I', dt.tx_power_level)[:1]),
+                )
+            )
+        if dt.HasField('include_class_of_device'):
+            ad_structures.append(
+                (
+                    AdvertisingData.CLASS_OF_DEVICE,
+                    bytes(struct.pack('<I', self.device.class_of_device)[:-1]),
+                )
+            )
+        elif dt.class_of_device:
+            ad_structures.append(
+                (
+                    AdvertisingData.CLASS_OF_DEVICE,
+                    bytes(struct.pack('<I', dt.class_of_device)[:-1]),
+                )
+            )
+        if dt.peripheral_connection_interval_min:
+            ad_structures.append(
+                (
+                    AdvertisingData.PERIPHERAL_CONNECTION_INTERVAL_RANGE,
+                    bytes(
+                        [
+                            *struct.pack('<H', dt.peripheral_connection_interval_min),
+                            *struct.pack(
+                                '<H',
+                                dt.peripheral_connection_interval_max
+                                if dt.peripheral_connection_interval_max
+                                else dt.peripheral_connection_interval_min,
+                            ),
+                        ]
+                    ),
+                )
+            )
+        if uuids := dt.service_solicitation_uuids16:
+            ad_structures.append(
+                (
+                    AdvertisingData.LIST_OF_16_BIT_SERVICE_SOLICITATION_UUIDS,
+                    b''.join([uuid16_from_str(uuid) for uuid in uuids]),
+                )
+            )
+        if uuids := dt.service_solicitation_uuids32:
+            ad_structures.append(
+                (
+                    AdvertisingData.LIST_OF_32_BIT_SERVICE_SOLICITATION_UUIDS,
+                    b''.join([uuid32_from_str(uuid) for uuid in uuids]),
+                )
+            )
+        if uuids := dt.service_solicitation_uuids128:
+            ad_structures.append(
+                (
+                    AdvertisingData.LIST_OF_128_BIT_SERVICE_SOLICITATION_UUIDS,
+                    b''.join([uuid128_from_str(uuid) for uuid in uuids]),
+                )
+            )
+        if datas := dt.service_data_uuid16:
+            ad_structures.extend(
+                [
+                    (
+                        AdvertisingData.SERVICE_DATA_16_BIT_UUID,
+                        uuid16_from_str(uuid) + data,
+                    )
+                    for uuid, data in datas.items()
+                ]
+            )
+        if datas := dt.service_data_uuid32:
+            ad_structures.extend(
+                [
+                    (
+                        AdvertisingData.SERVICE_DATA_32_BIT_UUID,
+                        uuid32_from_str(uuid) + data,
+                    )
+                    for uuid, data in datas.items()
+                ]
+            )
+        if datas := dt.service_data_uuid128:
+            ad_structures.extend(
+                [
+                    (
+                        AdvertisingData.SERVICE_DATA_128_BIT_UUID,
+                        uuid128_from_str(uuid) + data,
+                    )
+                    for uuid, data in datas.items()
+                ]
+            )
+        if dt.appearance:
+            ad_structures.append(
+                (AdvertisingData.APPEARANCE, struct.pack('<H', dt.appearance))
+            )
+        if dt.advertising_interval:
+            ad_structures.append(
+                (
+                    AdvertisingData.ADVERTISING_INTERVAL,
+                    struct.pack('<H', dt.advertising_interval),
+                )
+            )
+        if dt.uri:
+            ad_structures.append((AdvertisingData.URI, bytes(dt.uri, 'utf-8')))
+        if dt.le_supported_features:
+            ad_structures.append(
+                (AdvertisingData.LE_SUPPORTED_FEATURES, dt.le_supported_features)
+            )
+        if dt.manufacturer_specific_data:
+            ad_structures.append(
+                (
+                    AdvertisingData.MANUFACTURER_SPECIFIC_DATA,
+                    dt.manufacturer_specific_data,
+                )
+            )
+
+        return AdvertisingData(ad_structures)
+
+    def pack_data_types(self, ad: AdvertisingData) -> DataTypes:
+        dt = DataTypes()
+        uuids: List[UUID]
+        s: str
+        i: int
+        ij: Tuple[int, int]
+        uuid_data: Tuple[UUID, bytes]
+        data: bytes
+
+        if uuids := cast(
+            List[UUID],
+            ad.get(AdvertisingData.INCOMPLETE_LIST_OF_16_BIT_SERVICE_CLASS_UUIDS),
+        ):
+            dt.incomplete_service_class_uuids16.extend(
+                list(map(lambda x: x.to_hex_str('-'), uuids))
+            )
+        if uuids := cast(
+            List[UUID],
+            ad.get(AdvertisingData.COMPLETE_LIST_OF_16_BIT_SERVICE_CLASS_UUIDS),
+        ):
+            dt.complete_service_class_uuids16.extend(
+                list(map(lambda x: x.to_hex_str('-'), uuids))
+            )
+        if uuids := cast(
+            List[UUID],
+            ad.get(AdvertisingData.INCOMPLETE_LIST_OF_32_BIT_SERVICE_CLASS_UUIDS),
+        ):
+            dt.incomplete_service_class_uuids32.extend(
+                list(map(lambda x: x.to_hex_str('-'), uuids))
+            )
+        if uuids := cast(
+            List[UUID],
+            ad.get(AdvertisingData.COMPLETE_LIST_OF_32_BIT_SERVICE_CLASS_UUIDS),
+        ):
+            dt.complete_service_class_uuids32.extend(
+                list(map(lambda x: x.to_hex_str('-'), uuids))
+            )
+        if uuids := cast(
+            List[UUID],
+            ad.get(AdvertisingData.INCOMPLETE_LIST_OF_128_BIT_SERVICE_CLASS_UUIDS),
+        ):
+            dt.incomplete_service_class_uuids128.extend(
+                list(map(lambda x: x.to_hex_str('-'), uuids))
+            )
+        if uuids := cast(
+            List[UUID],
+            ad.get(AdvertisingData.COMPLETE_LIST_OF_128_BIT_SERVICE_CLASS_UUIDS),
+        ):
+            dt.complete_service_class_uuids128.extend(
+                list(map(lambda x: x.to_hex_str('-'), uuids))
+            )
+        if s := cast(str, ad.get(AdvertisingData.SHORTENED_LOCAL_NAME)):
+            dt.shortened_local_name = s
+        if s := cast(str, ad.get(AdvertisingData.COMPLETE_LOCAL_NAME)):
+            dt.complete_local_name = s
+        if i := cast(int, ad.get(AdvertisingData.TX_POWER_LEVEL)):
+            dt.tx_power_level = i
+        if i := cast(int, ad.get(AdvertisingData.CLASS_OF_DEVICE)):
+            dt.class_of_device = i
+        if ij := cast(
+            Tuple[int, int],
+            ad.get(AdvertisingData.PERIPHERAL_CONNECTION_INTERVAL_RANGE),
+        ):
+            dt.peripheral_connection_interval_min = ij[0]
+            dt.peripheral_connection_interval_max = ij[1]
+        if uuids := cast(
+            List[UUID],
+            ad.get(AdvertisingData.LIST_OF_16_BIT_SERVICE_SOLICITATION_UUIDS),
+        ):
+            dt.service_solicitation_uuids16.extend(
+                list(map(lambda x: x.to_hex_str('-'), uuids))
+            )
+        if uuids := cast(
+            List[UUID],
+            ad.get(AdvertisingData.LIST_OF_32_BIT_SERVICE_SOLICITATION_UUIDS),
+        ):
+            dt.service_solicitation_uuids32.extend(
+                list(map(lambda x: x.to_hex_str('-'), uuids))
+            )
+        if uuids := cast(
+            List[UUID],
+            ad.get(AdvertisingData.LIST_OF_128_BIT_SERVICE_SOLICITATION_UUIDS),
+        ):
+            dt.service_solicitation_uuids128.extend(
+                list(map(lambda x: x.to_hex_str('-'), uuids))
+            )
+        if uuid_data := cast(
+            Tuple[UUID, bytes], ad.get(AdvertisingData.SERVICE_DATA_16_BIT_UUID)
+        ):
+            dt.service_data_uuid16[uuid_data[0].to_hex_str('-')] = uuid_data[1]
+        if uuid_data := cast(
+            Tuple[UUID, bytes], ad.get(AdvertisingData.SERVICE_DATA_32_BIT_UUID)
+        ):
+            dt.service_data_uuid32[uuid_data[0].to_hex_str('-')] = uuid_data[1]
+        if uuid_data := cast(
+            Tuple[UUID, bytes], ad.get(AdvertisingData.SERVICE_DATA_128_BIT_UUID)
+        ):
+            dt.service_data_uuid128[uuid_data[0].to_hex_str('-')] = uuid_data[1]
+        if data := cast(bytes, ad.get(AdvertisingData.PUBLIC_TARGET_ADDRESS, raw=True)):
+            dt.public_target_addresses.extend(
+                [data[i * 6 :: i * 6 + 6] for i in range(int(len(data) / 6))]
+            )
+        if data := cast(bytes, ad.get(AdvertisingData.RANDOM_TARGET_ADDRESS, raw=True)):
+            dt.random_target_addresses.extend(
+                [data[i * 6 :: i * 6 + 6] for i in range(int(len(data) / 6))]
+            )
+        if i := cast(int, ad.get(AdvertisingData.APPEARANCE)):
+            dt.appearance = i
+        if i := cast(int, ad.get(AdvertisingData.ADVERTISING_INTERVAL)):
+            dt.advertising_interval = i
+        if s := cast(str, ad.get(AdvertisingData.URI)):
+            dt.uri = s
+        if data := cast(bytes, ad.get(AdvertisingData.LE_SUPPORTED_FEATURES, raw=True)):
+            dt.le_supported_features = data
+        if data := cast(
+            bytes, ad.get(AdvertisingData.MANUFACTURER_SPECIFIC_DATA, raw=True)
+        ):
+            dt.manufacturer_specific_data = data
+
+        return dt

bumble/pandora/security.py

@@ -0,0 +1,529 @@
+# 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.
+
+import asyncio
+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.pairing import PairingConfig, PairingDelegate as BasePairingDelegate
+from contextlib import suppress
+from google.protobuf import any_pb2  # pytype: disable=pyi-error
+from google.protobuf import empty_pb2  # pytype: disable=pyi-error
+from google.protobuf import wrappers_pb2  # pytype: disable=pyi-error
+from pandora.host_pb2 import Connection
+from pandora.security_grpc_aio import SecurityServicer, SecurityStorageServicer
+from pandora.security_pb2 import (
+    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)  # pytype: disable=name-error
+        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)  # pytype: disable=name-error
+        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)  # pytype: disable=name-error
+        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)  # pytype: disable=name-error
+        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=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...')
+
+                if (
+                    connection.transport == BT_LE_TRANSPORT
+                    and connection.role == BT_PERIPHERAL_ROLE
+                ):
+                    wait_for_security: asyncio.Future[
+                        bool
+                    ] = asyncio.get_running_loop().create_future()
+                    connection.on("pairing", lambda *_: wait_for_security.set_result(True))  # type: ignore
+                    connection.on("pairing_failure", wait_for_security.set_exception)
+
+                    connection.request_pairing()
+
+                    await wait_for_security
+                else:
+                    await connection.pair()
+
+                self.log.debug('Paired')
+            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
+
+        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())
+
+        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'),
+        }
+
+        # register event handlers
+        for event, listener in listeners.items():
+            connection.on(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()
+
+        # remove event handlers
+        for event, listener in listeners.items():
+            connection.remove_listener(event, listener)  # type: ignore
+
+        # 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')
+
+        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 suppress(KeyError):
+                await self.device.keystore.delete(str(address))
+
+        return empty_pb2.Empty()

bumble/pandora/utils.py

@@ -0,0 +1,112 @@
+# 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.
+
+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/asha_service.py

@@ -20,6 +20,7 @@ import struct
 import logging
 from typing import List
 from ..core import AdvertisingData
+from ..device import Device, Connection
 from ..gatt import (
     GATT_ASHA_SERVICE,
     GATT_ASHA_READ_ONLY_PROPERTIES_CHARACTERISTIC,
@@ -31,7 +32,7 @@ from ..gatt import (
     Characteristic,
     CharacteristicValue,
 )
-from ..device import Device
+from ..utils import AsyncRunner
 
 # -----------------------------------------------------------------------------
 # Logging
@@ -55,16 +56,16 @@ class AshaService(TemplateService):
         self.hisyncid = hisyncid
         self.capability = capability  # Device Capabilities [Left, Monaural]
         self.device = device
-        self.emitted_data_name = 'ASHA_data_' + str(self.capability)
         self.audio_out_data = b''
         self.psm = psm  # a non-zero psm is mainly for testing purpose
 
         # Handler for volume control
-        def on_volume_write(_connection, value):
+        def on_volume_write(connection, value):
             logger.info(f'--- VOLUME Write:{value[0]}')
+            self.emit('volume', connection, value[0])
 
         # Handler for audio control commands
-        def on_audio_control_point_write(_connection, value):
+        def on_audio_control_point_write(connection: Connection, value):
             logger.info(f'--- AUDIO CONTROL POINT Write:{value.hex()}')
             opcode = value[0]
             if opcode == AshaService.OPCODE_START:
@@ -76,18 +77,33 @@ class AshaService(TemplateService):
                     f'volume={value[3]}, '
                     f'otherstate={value[4]}'
                 )
+                self.emit(
+                    'start',
+                    connection,
+                    {
+                        'codec': value[1],
+                        'audiotype': value[2],
+                        'volume': value[3],
+                        'otherstate': value[4],
+                    },
+                )
             elif opcode == AshaService.OPCODE_STOP:
                 logger.info('### STOP')
+                self.emit('stop', connection)
             elif opcode == AshaService.OPCODE_STATUS:
                 logger.info(f'### STATUS: connected={value[1]}')
 
-            # TODO Respond with a status
-            # asyncio.create_task(device.notify_subscribers(audio_status_characteristic,
-            # force=True))
+            # OPCODE_STATUS does not need audio status point update
+            if opcode != AshaService.OPCODE_STATUS:
+                AsyncRunner.spawn(
+                    device.notify_subscribers(
+                        self.audio_status_characteristic, force=True
+                    )
+                )
 
         self.read_only_properties_characteristic = Characteristic(
             GATT_ASHA_READ_ONLY_PROPERTIES_CHARACTERISTIC,
-            Characteristic.READ,
+            Characteristic.Properties.READ,
             Characteristic.READABLE,
             bytes(
                 [
@@ -104,19 +120,20 @@ class AshaService(TemplateService):
 
         self.audio_control_point_characteristic = Characteristic(
             GATT_ASHA_AUDIO_CONTROL_POINT_CHARACTERISTIC,
-            Characteristic.WRITE | Characteristic.WRITE_WITHOUT_RESPONSE,
+            Characteristic.Properties.WRITE
+            | Characteristic.Properties.WRITE_WITHOUT_RESPONSE,
             Characteristic.WRITEABLE,
             CharacteristicValue(write=on_audio_control_point_write),
         )
         self.audio_status_characteristic = Characteristic(
             GATT_ASHA_AUDIO_STATUS_CHARACTERISTIC,
-            Characteristic.READ | Characteristic.NOTIFY,
+            Characteristic.Properties.READ | Characteristic.Properties.NOTIFY,
             Characteristic.READABLE,
             bytes([0]),
         )
         self.volume_characteristic = Characteristic(
             GATT_ASHA_VOLUME_CHARACTERISTIC,
-            Characteristic.WRITE_WITHOUT_RESPONSE,
+            Characteristic.Properties.WRITE_WITHOUT_RESPONSE,
             Characteristic.WRITEABLE,
             CharacteristicValue(write=on_volume_write),
         )
@@ -126,7 +143,7 @@ class AshaService(TemplateService):
             def on_data(data):
                 logging.debug(f'<<< data received:{data}')
 
-                self.emit(self.emitted_data_name, data)
+                self.emit('data', channel.connection, data)
                 self.audio_out_data += data
 
             channel.sink = on_data
@@ -135,7 +152,7 @@ class AshaService(TemplateService):
         self.psm = self.device.register_l2cap_channel_server(self.psm, on_coc, 8)
         self.le_psm_out_characteristic = Characteristic(
             GATT_ASHA_LE_PSM_OUT_CHARACTERISTIC,
-            Characteristic.READ,
+            Characteristic.Properties.READ,
             Characteristic.READABLE,
             struct.pack('<H', self.psm),
         )

bumble/profiles/battery_service.py

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

bumble/profiles/device_information_service.py

@@ -63,7 +63,9 @@ class DeviceInformationService(TemplateService):
         # TODO: pnp_id
     ):
         characteristics = [
-            Characteristic(uuid, Characteristic.READ, Characteristic.READABLE, field)
+            Characteristic(
+                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),
@@ -79,7 +81,7 @@ class DeviceInformationService(TemplateService):
             characteristics.append(
                 Characteristic(
                     GATT_SYSTEM_ID_CHARACTERISTIC,
-                    Characteristic.READ,
+                    Characteristic.Properties.READ,
                     Characteristic.READABLE,
                     self.pack_system_id(*system_id),
                 )
@@ -89,7 +91,7 @@ class DeviceInformationService(TemplateService):
             characteristics.append(
                 Characteristic(
                     GATT_REGULATORY_CERTIFICATION_DATA_LIST_CHARACTERISTIC,
-                    Characteristic.READ,
+                    Characteristic.Properties.READ,
                     Characteristic.READABLE,
                     ieee_regulatory_certification_data_list,
                 )

bumble/profiles/heart_rate_service.py

@@ -152,7 +152,7 @@ class HeartRateService(TemplateService):
         self.heart_rate_measurement_characteristic = DelegatedCharacteristicAdapter(
             Characteristic(
                 GATT_HEART_RATE_MEASUREMENT_CHARACTERISTIC,
-                Characteristic.NOTIFY,
+                Characteristic.Properties.NOTIFY,
                 0,
                 CharacteristicValue(read=read_heart_rate_measurement),
             ),
@@ -164,7 +164,7 @@ class HeartRateService(TemplateService):
         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)]),
             )
@@ -182,7 +182,7 @@ 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),
                 ),

bumble/rfcomm.py

@@ -15,14 +15,37 @@
 # -----------------------------------------------------------------------------
 # Imports
 # -----------------------------------------------------------------------------
+from __future__ import annotations
+
 import logging
 import asyncio
+import enum
+from typing import Callable, Dict, List, Optional, Tuple, Union, TYPE_CHECKING
 
 from pyee import EventEmitter
 
-from . import core
+from . import core, l2cap
 from .colors import color
-from .core import BT_BR_EDR_TRANSPORT, InvalidStateError, ProtocolError
+from .core import (
+    UUID,
+    BT_RFCOMM_PROTOCOL_ID,
+    BT_BR_EDR_TRANSPORT,
+    BT_L2CAP_PROTOCOL_ID,
+    InvalidStateError,
+    ProtocolError,
+)
+from .sdp import (
+    SDP_SERVICE_RECORD_HANDLE_ATTRIBUTE_ID,
+    SDP_BROWSE_GROUP_LIST_ATTRIBUTE_ID,
+    SDP_SERVICE_CLASS_ID_LIST_ATTRIBUTE_ID,
+    SDP_PROTOCOL_DESCRIPTOR_LIST_ATTRIBUTE_ID,
+    SDP_PUBLIC_BROWSE_ROOT,
+    DataElement,
+    ServiceAttribute,
+)
+
+if TYPE_CHECKING:
+    from bumble.device import Device, Connection
 
 # -----------------------------------------------------------------------------
 # Logging
@@ -105,7 +128,51 @@ RFCOMM_DYNAMIC_CHANNEL_NUMBER_END   = 30
 
 
 # -----------------------------------------------------------------------------
-def compute_fcs(buffer):
+def make_service_sdp_records(
+    service_record_handle: int, channel: int, uuid: Optional[UUID] = None
+) -> List[ServiceAttribute]:
+    """
+    Create SDP records for an RFComm service given a channel number and an
+    optional UUID. A Service Class Attribute is included only if the UUID is not None.
+    """
+    records = [
+        ServiceAttribute(
+            SDP_SERVICE_RECORD_HANDLE_ATTRIBUTE_ID,
+            DataElement.unsigned_integer_32(service_record_handle),
+        ),
+        ServiceAttribute(
+            SDP_BROWSE_GROUP_LIST_ATTRIBUTE_ID,
+            DataElement.sequence([DataElement.uuid(SDP_PUBLIC_BROWSE_ROOT)]),
+        ),
+        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(channel),
+                        ]
+                    ),
+                ]
+            ),
+        ),
+    ]
+
+    if uuid:
+        records.append(
+            ServiceAttribute(
+                SDP_SERVICE_CLASS_ID_LIST_ATTRIBUTE_ID,
+                DataElement.sequence([DataElement.uuid(uuid)]),
+            )
+        )
+
+    return records
+
+
+# -----------------------------------------------------------------------------
+def compute_fcs(buffer: bytes) -> int:
     result = 0xFF
     for byte in buffer:
         result = CRC_TABLE[result ^ byte]
@@ -114,7 +181,15 @@ def compute_fcs(buffer):
 
 # -----------------------------------------------------------------------------
 class RFCOMM_Frame:
-    def __init__(self, frame_type, c_r, dlci, p_f, information=b'', with_credits=False):
+    def __init__(
+        self,
+        frame_type: int,
+        c_r: int,
+        dlci: int,
+        p_f: int,
+        information: bytes = b'',
+        with_credits: bool = False,
+    ) -> None:
         self.type = frame_type
         self.c_r = c_r
         self.dlci = dlci
@@ -136,13 +211,13 @@ class RFCOMM_Frame:
         else:
             self.fcs = compute_fcs(bytes([self.address, self.control]) + self.length)
 
-    def type_name(self):
+    def type_name(self) -> str:
         return RFCOMM_FRAME_TYPE_NAMES[self.type]
 
     @staticmethod
-    def parse_mcc(data):
+    def parse_mcc(data) -> Tuple[int, bool, bytes]:
         mcc_type = data[0] >> 2
-        c_r = (data[0] >> 1) & 1
+        c_r = bool((data[0] >> 1) & 1)
         length = data[1]
         if data[1] & 1:
             length >>= 1
@@ -154,36 +229,36 @@ class RFCOMM_Frame:
         return (mcc_type, c_r, value)
 
     @staticmethod
-    def make_mcc(mcc_type, c_r, data):
+    def make_mcc(mcc_type: int, c_r: int, data: bytes) -> bytes:
         return (
             bytes([(mcc_type << 2 | c_r << 1 | 1) & 0xFF, (len(data) & 0x7F) << 1 | 1])
             + data
         )
 
     @staticmethod
-    def sabm(c_r, dlci):
+    def sabm(c_r: int, dlci: int):
         return RFCOMM_Frame(RFCOMM_SABM_FRAME, c_r, dlci, 1)
 
     @staticmethod
-    def ua(c_r, dlci):
+    def ua(c_r: int, dlci: int):
         return RFCOMM_Frame(RFCOMM_UA_FRAME, c_r, dlci, 1)
 
     @staticmethod
-    def dm(c_r, dlci):
+    def dm(c_r: int, dlci: int):
         return RFCOMM_Frame(RFCOMM_DM_FRAME, c_r, dlci, 1)
 
     @staticmethod
-    def disc(c_r, dlci):
+    def disc(c_r: int, dlci: int):
         return RFCOMM_Frame(RFCOMM_DISC_FRAME, c_r, dlci, 1)
 
     @staticmethod
-    def uih(c_r, dlci, information, p_f=0):
+    def uih(c_r: int, dlci: int, information: bytes, p_f: int = 0):
         return RFCOMM_Frame(
             RFCOMM_UIH_FRAME, c_r, dlci, p_f, information, with_credits=(p_f == 1)
         )
 
     @staticmethod
-    def from_bytes(data):
+    def from_bytes(data: bytes) -> RFCOMM_Frame:
         # Extract fields
         dlci = (data[0] >> 2) & 0x3F
         c_r = (data[0] >> 1) & 0x01
@@ -206,7 +281,7 @@ class RFCOMM_Frame:
 
         return frame
 
-    def __bytes__(self):
+    def __bytes__(self) -> bytes:
         return (
             bytes([self.address, self.control])
             + self.length
@@ -214,7 +289,7 @@ class RFCOMM_Frame:
             + bytes([self.fcs])
         )
 
-    def __str__(self):
+    def __str__(self) -> str:
         return (
             f'{color(self.type_name(), "yellow")}'
             f'(c/r={self.c_r},'
@@ -227,16 +302,24 @@ class RFCOMM_Frame:
 
 # -----------------------------------------------------------------------------
 class RFCOMM_MCC_PN:
+    dlci: int
+    cl: int
+    priority: int
+    ack_timer: int
+    max_frame_size: int
+    max_retransmissions: int
+    window_size: int
+
     def __init__(
         self,
-        dlci,
-        cl,
-        priority,
-        ack_timer,
-        max_frame_size,
-        max_retransmissions,
-        window_size,
-    ):
+        dlci: int,
+        cl: int,
+        priority: int,
+        ack_timer: int,
+        max_frame_size: int,
+        max_retransmissions: int,
+        window_size: int,
+    ) -> None:
         self.dlci = dlci
         self.cl = cl
         self.priority = priority
@@ -246,7 +329,7 @@ class RFCOMM_MCC_PN:
         self.window_size = window_size
 
     @staticmethod
-    def from_bytes(data):
+    def from_bytes(data: bytes) -> RFCOMM_MCC_PN:
         return RFCOMM_MCC_PN(
             dlci=data[0],
             cl=data[1],
@@ -257,7 +340,7 @@ class RFCOMM_MCC_PN:
             window_size=data[7],
         )
 
-    def __bytes__(self):
+    def __bytes__(self) -> bytes:
         return bytes(
             [
                 self.dlci & 0xFF,
@@ -271,7 +354,7 @@ class RFCOMM_MCC_PN:
             ]
         )
 
-    def __str__(self):
+    def __str__(self) -> str:
         return (
             f'PN(dlci={self.dlci},'
             f'cl={self.cl},'
@@ -285,7 +368,16 @@ class RFCOMM_MCC_PN:
 
 # -----------------------------------------------------------------------------
 class RFCOMM_MCC_MSC:
-    def __init__(self, dlci, fc, rtc, rtr, ic, dv):
+    dlci: int
+    fc: int
+    rtc: int
+    rtr: int
+    ic: int
+    dv: int
+
+    def __init__(
+        self, dlci: int, fc: int, rtc: int, rtr: int, ic: int, dv: int
+    ) -> None:
         self.dlci = dlci
         self.fc = fc
         self.rtc = rtc
@@ -294,7 +386,7 @@ class RFCOMM_MCC_MSC:
         self.dv = dv
 
     @staticmethod
-    def from_bytes(data):
+    def from_bytes(data: bytes) -> RFCOMM_MCC_MSC:
         return RFCOMM_MCC_MSC(
             dlci=data[0] >> 2,
             fc=data[1] >> 1 & 1,
@@ -304,7 +396,7 @@ class RFCOMM_MCC_MSC:
             dv=data[1] >> 7 & 1,
         )
 
-    def __bytes__(self):
+    def __bytes__(self) -> bytes:
         return bytes(
             [
                 (self.dlci << 2) | 3,
@@ -317,7 +409,7 @@ class RFCOMM_MCC_MSC:
             ]
         )
 
-    def __str__(self):
+    def __str__(self) -> str:
         return (
             f'MSC(dlci={self.dlci},'
             f'fc={self.fc},'
@@ -330,24 +422,24 @@ class RFCOMM_MCC_MSC:
 
 # -----------------------------------------------------------------------------
 class DLC(EventEmitter):
-    # States
-    INIT = 0x00
-    CONNECTING = 0x01
-    CONNECTED = 0x02
-    DISCONNECTING = 0x03
-    DISCONNECTED = 0x04
-    RESET = 0x05
+    class State(enum.IntEnum):
+        INIT = 0x00
+        CONNECTING = 0x01
+        CONNECTED = 0x02
+        DISCONNECTING = 0x03
+        DISCONNECTED = 0x04
+        RESET = 0x05
 
-    STATE_NAMES = {
-        INIT: 'INIT',
-        CONNECTING: 'CONNECTING',
-        CONNECTED: 'CONNECTED',
-        DISCONNECTING: 'DISCONNECTING',
-        DISCONNECTED: 'DISCONNECTED',
-        RESET: 'RESET',
-    }
+    connection_result: Optional[asyncio.Future]
+    sink: Optional[Callable[[bytes], None]]
 
-    def __init__(self, multiplexer, dlci, max_frame_size, initial_tx_credits):
+    def __init__(
+        self,
+        multiplexer: Multiplexer,
+        dlci: int,
+        max_frame_size: int,
+        initial_tx_credits: int,
+    ) -> None:
         super().__init__()
         self.multiplexer = multiplexer
         self.dlci = dlci
@@ -355,9 +447,9 @@ class DLC(EventEmitter):
         self.rx_threshold = self.rx_credits // 2
         self.tx_credits = initial_tx_credits
         self.tx_buffer = b''
-        self.state = DLC.INIT
+        self.state = DLC.State.INIT
         self.role = multiplexer.role
-        self.c_r = 1 if self.role == Multiplexer.INITIATOR else 0
+        self.c_r = 1 if self.role == Multiplexer.Role.INITIATOR else 0
         self.sink = None
         self.connection_result = None
 
@@ -367,25 +459,19 @@ class DLC(EventEmitter):
             max_frame_size, self.multiplexer.l2cap_channel.mtu - max_overhead
         )
 
-    @staticmethod
-    def state_name(state):
-        return DLC.STATE_NAMES[state]
-
-    def change_state(self, new_state):
-        logger.debug(
-            f'{self} state change -> {color(self.state_name(new_state), "magenta")}'
-        )
+    def change_state(self, new_state: State) -> None:
+        logger.debug(f'{self} state change -> {color(new_state.name, "magenta")}')
         self.state = new_state
 
-    def send_frame(self, frame):
+    def send_frame(self, frame: RFCOMM_Frame) -> None:
         self.multiplexer.send_frame(frame)
 
-    def on_frame(self, frame):
+    def on_frame(self, frame: RFCOMM_Frame) -> None:
         handler = getattr(self, f'on_{frame.type_name()}_frame'.lower())
         handler(frame)
 
-    def on_sabm_frame(self, _frame):
-        if self.state != DLC.CONNECTING:
+    def on_sabm_frame(self, _frame: RFCOMM_Frame) -> None:
+        if self.state != DLC.State.CONNECTING:
             logger.warning(
                 color('!!! received SABM when not in CONNECTING state', 'red')
             )
@@ -401,11 +487,11 @@ class DLC(EventEmitter):
         logger.debug(f'>>> MCC MSC Command: {msc}')
         self.send_frame(RFCOMM_Frame.uih(c_r=self.c_r, dlci=0, information=mcc))
 
-        self.change_state(DLC.CONNECTED)
+        self.change_state(DLC.State.CONNECTED)
         self.emit('open')
 
-    def on_ua_frame(self, _frame):
-        if self.state != DLC.CONNECTING:
+    def on_ua_frame(self, _frame: RFCOMM_Frame) -> None:
+        if self.state != DLC.State.CONNECTING:
             logger.warning(
                 color('!!! received SABM when not in CONNECTING state', 'red')
             )
@@ -419,18 +505,18 @@ class DLC(EventEmitter):
         logger.debug(f'>>> MCC MSC Command: {msc}')
         self.send_frame(RFCOMM_Frame.uih(c_r=self.c_r, dlci=0, information=mcc))
 
-        self.change_state(DLC.CONNECTED)
+        self.change_state(DLC.State.CONNECTED)
         self.multiplexer.on_dlc_open_complete(self)
 
-    def on_dm_frame(self, frame):
+    def on_dm_frame(self, frame: RFCOMM_Frame) -> None:
         # TODO: handle all states
         pass
 
-    def on_disc_frame(self, _frame):
+    def on_disc_frame(self, _frame: RFCOMM_Frame) -> None:
         # TODO: handle all states
         self.send_frame(RFCOMM_Frame.ua(c_r=1 - self.c_r, dlci=self.dlci))
 
-    def on_uih_frame(self, frame):
+    def on_uih_frame(self, frame: RFCOMM_Frame) -> None:
         data = frame.information
         if frame.p_f == 1:
             # With credits
@@ -439,7 +525,7 @@ class DLC(EventEmitter):
 
             logger.debug(
                 f'<<< Credits [{self.dlci}]: '
-                f'received {credits}, total={self.tx_credits}'
+                f'received {received_credits}, total={self.tx_credits}'
             )
             data = data[1:]
 
@@ -460,10 +546,10 @@ class DLC(EventEmitter):
         # Check if there's anything to send (including credits)
         self.process_tx()
 
-    def on_ui_frame(self, frame):
+    def on_ui_frame(self, frame: RFCOMM_Frame) -> None:
         pass
 
-    def on_mcc_msc(self, c_r, msc):
+    def on_mcc_msc(self, c_r: bool, msc: RFCOMM_MCC_MSC) -> None:
         if c_r:
             # Command
             logger.debug(f'<<< MCC MSC Command: {msc}')
@@ -477,16 +563,16 @@ class DLC(EventEmitter):
             # Response
             logger.debug(f'<<< MCC MSC Response: {msc}')
 
-    def connect(self):
-        if self.state != DLC.INIT:
+    def connect(self) -> None:
+        if self.state != DLC.State.INIT:
             raise InvalidStateError('invalid state')
 
-        self.change_state(DLC.CONNECTING)
+        self.change_state(DLC.State.CONNECTING)
         self.connection_result = asyncio.get_running_loop().create_future()
         self.send_frame(RFCOMM_Frame.sabm(c_r=self.c_r, dlci=self.dlci))
 
-    def accept(self):
-        if self.state != DLC.INIT:
+    def accept(self) -> None:
+        if self.state != DLC.State.INIT:
             raise InvalidStateError('invalid state')
 
         pn = RFCOMM_MCC_PN(
@@ -501,15 +587,15 @@ class DLC(EventEmitter):
         mcc = RFCOMM_Frame.make_mcc(mcc_type=RFCOMM_MCC_PN_TYPE, c_r=0, data=bytes(pn))
         logger.debug(f'>>> PN Response: {pn}')
         self.send_frame(RFCOMM_Frame.uih(c_r=self.c_r, dlci=0, information=mcc))
-        self.change_state(DLC.CONNECTING)
+        self.change_state(DLC.State.CONNECTING)
 
-    def rx_credits_needed(self):
+    def rx_credits_needed(self) -> int:
         if self.rx_credits <= self.rx_threshold:
             return RFCOMM_DEFAULT_INITIAL_RX_CREDITS - self.rx_credits
 
         return 0
 
-    def process_tx(self):
+    def process_tx(self) -> None:
         # Send anything we can (or an empty frame if we need to send rx credits)
         rx_credits_needed = self.rx_credits_needed()
         while (self.tx_buffer and self.tx_credits > 0) or rx_credits_needed > 0:
@@ -547,7 +633,7 @@ class DLC(EventEmitter):
             rx_credits_needed = 0
 
     # Stream protocol
-    def write(self, data):
+    def write(self, data: Union[bytes, str]) -> None:
         # We can only send bytes
         if not isinstance(data, bytes):
             if isinstance(data, str):
@@ -559,44 +645,40 @@ class DLC(EventEmitter):
         self.tx_buffer += data
         self.process_tx()
 
-    def drain(self):
+    def drain(self) -> None:
         # TODO
         pass
 
-    def __str__(self):
-        return f'DLC(dlci={self.dlci},state={self.state_name(self.state)})'
+    def __str__(self) -> str:
+        return f'DLC(dlci={self.dlci},state={self.state.name})'
 
 
 # -----------------------------------------------------------------------------
 class Multiplexer(EventEmitter):
-    # Roles
-    INITIATOR = 0x00
-    RESPONDER = 0x01
+    class Role(enum.IntEnum):
+        INITIATOR = 0x00
+        RESPONDER = 0x01
 
-    # States
-    INIT = 0x00
-    CONNECTING = 0x01
-    CONNECTED = 0x02
-    OPENING = 0x03
-    DISCONNECTING = 0x04
-    DISCONNECTED = 0x05
-    RESET = 0x06
+    class State(enum.IntEnum):
+        INIT = 0x00
+        CONNECTING = 0x01
+        CONNECTED = 0x02
+        OPENING = 0x03
+        DISCONNECTING = 0x04
+        DISCONNECTED = 0x05
+        RESET = 0x06
 
-    STATE_NAMES = {
-        INIT: 'INIT',
-        CONNECTING: 'CONNECTING',
-        CONNECTED: 'CONNECTED',
-        OPENING: 'OPENING',
-        DISCONNECTING: 'DISCONNECTING',
-        DISCONNECTED: 'DISCONNECTED',
-        RESET: 'RESET',
-    }
+    connection_result: Optional[asyncio.Future]
+    disconnection_result: Optional[asyncio.Future]
+    open_result: Optional[asyncio.Future]
+    acceptor: Optional[Callable[[int], bool]]
+    dlcs: Dict[int, DLC]
 
-    def __init__(self, l2cap_channel, role):
+    def __init__(self, l2cap_channel: l2cap.Channel, role: Role) -> None:
         super().__init__()
         self.role = role
         self.l2cap_channel = l2cap_channel
-        self.state = Multiplexer.INIT
+        self.state = Multiplexer.State.INIT
         self.dlcs = {}  # DLCs, by DLCI
         self.connection_result = None
         self.disconnection_result = None
@@ -606,21 +688,15 @@ class Multiplexer(EventEmitter):
         # Become a sink for the L2CAP channel
         l2cap_channel.sink = self.on_pdu
 
-    @staticmethod
-    def state_name(state):
-        return Multiplexer.STATE_NAMES[state]
-
-    def change_state(self, new_state):
-        logger.debug(
-            f'{self} state change -> {color(self.state_name(new_state), "cyan")}'
-        )
+    def change_state(self, new_state: State) -> None:
+        logger.debug(f'{self} state change -> {color(new_state.name, "cyan")}')
         self.state = new_state
 
-    def send_frame(self, frame):
+    def send_frame(self, frame: RFCOMM_Frame) -> None:
         logger.debug(f'>>> Multiplexer sending {frame}')
         self.l2cap_channel.send_pdu(frame)
 
-    def on_pdu(self, pdu):
+    def on_pdu(self, pdu: bytes) -> None:
         frame = RFCOMM_Frame.from_bytes(pdu)
         logger.debug(f'<<< Multiplexer received {frame}')
 
@@ -640,32 +716,32 @@ class Multiplexer(EventEmitter):
                     return
                 dlc.on_frame(frame)
 
-    def on_frame(self, frame):
+    def on_frame(self, frame: RFCOMM_Frame) -> None:
         handler = getattr(self, f'on_{frame.type_name()}_frame'.lower())
         handler(frame)
 
-    def on_sabm_frame(self, _frame):
-        if self.state != Multiplexer.INIT:
+    def on_sabm_frame(self, _frame: RFCOMM_Frame) -> None:
+        if self.state != Multiplexer.State.INIT:
             logger.debug('not in INIT state, ignoring SABM')
             return
-        self.change_state(Multiplexer.CONNECTED)
+        self.change_state(Multiplexer.State.CONNECTED)
         self.send_frame(RFCOMM_Frame.ua(c_r=1, dlci=0))
 
-    def on_ua_frame(self, _frame):
-        if self.state == Multiplexer.CONNECTING:
-            self.change_state(Multiplexer.CONNECTED)
+    def on_ua_frame(self, _frame: RFCOMM_Frame) -> None:
+        if self.state == Multiplexer.State.CONNECTING:
+            self.change_state(Multiplexer.State.CONNECTED)
             if self.connection_result:
                 self.connection_result.set_result(0)
                 self.connection_result = None
-        elif self.state == Multiplexer.DISCONNECTING:
-            self.change_state(Multiplexer.DISCONNECTED)
+        elif self.state == Multiplexer.State.DISCONNECTING:
+            self.change_state(Multiplexer.State.DISCONNECTED)
             if self.disconnection_result:
                 self.disconnection_result.set_result(None)
                 self.disconnection_result = None
 
-    def on_dm_frame(self, _frame):
-        if self.state == Multiplexer.OPENING:
-            self.change_state(Multiplexer.CONNECTED)
+    def on_dm_frame(self, _frame: RFCOMM_Frame) -> None:
+        if self.state == Multiplexer.State.OPENING:
+            self.change_state(Multiplexer.State.CONNECTED)
             if self.open_result:
                 self.open_result.set_exception(
                     core.ConnectionError(
@@ -678,13 +754,15 @@ class Multiplexer(EventEmitter):
         else:
             logger.warning(f'unexpected state for DM: {self}')
 
-    def on_disc_frame(self, _frame):
-        self.change_state(Multiplexer.DISCONNECTED)
+    def on_disc_frame(self, _frame: RFCOMM_Frame) -> None:
+        self.change_state(Multiplexer.State.DISCONNECTED)
         self.send_frame(
-            RFCOMM_Frame.ua(c_r=0 if self.role == Multiplexer.INITIATOR else 1, dlci=0)
+            RFCOMM_Frame.ua(
+                c_r=0 if self.role == Multiplexer.Role.INITIATOR else 1, dlci=0
+            )
         )
 
-    def on_uih_frame(self, frame):
+    def on_uih_frame(self, frame: RFCOMM_Frame) -> None:
         (mcc_type, c_r, value) = RFCOMM_Frame.parse_mcc(frame.information)
 
         if mcc_type == RFCOMM_MCC_PN_TYPE:
@@ -694,11 +772,11 @@ class Multiplexer(EventEmitter):
             mcs = RFCOMM_MCC_MSC.from_bytes(value)
             self.on_mcc_msc(c_r, mcs)
 
-    def on_ui_frame(self, frame):
+    def on_ui_frame(self, frame: RFCOMM_Frame) -> None:
         pass
 
-    def on_mcc_pn(self, c_r, pn):
-        if c_r == 1:
+    def on_mcc_pn(self, c_r: bool, pn: RFCOMM_MCC_PN) -> None:
+        if c_r:
             # Command
             logger.debug(f'<<< PN Command: {pn}')
 
@@ -729,45 +807,45 @@ class Multiplexer(EventEmitter):
         else:
             # Response
             logger.debug(f'>>> PN Response: {pn}')
-            if self.state == Multiplexer.OPENING:
+            if self.state == Multiplexer.State.OPENING:
                 dlc = DLC(self, pn.dlci, pn.max_frame_size, pn.window_size)
                 self.dlcs[pn.dlci] = dlc
                 dlc.connect()
             else:
                 logger.warning('ignoring PN response')
 
-    def on_mcc_msc(self, c_r, msc):
+    def on_mcc_msc(self, c_r: bool, msc: RFCOMM_MCC_MSC) -> None:
         dlc = self.dlcs.get(msc.dlci)
         if dlc is None:
             logger.warning(f'no dlc for DLCI {msc.dlci}')
             return
         dlc.on_mcc_msc(c_r, msc)
 
-    async def connect(self):
-        if self.state != Multiplexer.INIT:
+    async def connect(self) -> None:
+        if self.state != Multiplexer.State.INIT:
             raise InvalidStateError('invalid state')
 
-        self.change_state(Multiplexer.CONNECTING)
+        self.change_state(Multiplexer.State.CONNECTING)
         self.connection_result = asyncio.get_running_loop().create_future()
         self.send_frame(RFCOMM_Frame.sabm(c_r=1, dlci=0))
         return await self.connection_result
 
-    async def disconnect(self):
-        if self.state != Multiplexer.CONNECTED:
+    async def disconnect(self) -> None:
+        if self.state != Multiplexer.State.CONNECTED:
             return
 
         self.disconnection_result = asyncio.get_running_loop().create_future()
-        self.change_state(Multiplexer.DISCONNECTING)
+        self.change_state(Multiplexer.State.DISCONNECTING)
         self.send_frame(
             RFCOMM_Frame.disc(
-                c_r=1 if self.role == Multiplexer.INITIATOR else 0, dlci=0
+                c_r=1 if self.role == Multiplexer.Role.INITIATOR else 0, dlci=0
             )
         )
         await self.disconnection_result
 
-    async def open_dlc(self, channel):
-        if self.state != Multiplexer.CONNECTED:
-            if self.state == Multiplexer.OPENING:
+    async def open_dlc(self, channel: int) -> DLC:
+        if self.state != Multiplexer.State.CONNECTED:
+            if self.state == Multiplexer.State.OPENING:
                 raise InvalidStateError('open already in progress')
 
             raise InvalidStateError('not connected')
@@ -784,10 +862,10 @@ class Multiplexer(EventEmitter):
         mcc = RFCOMM_Frame.make_mcc(mcc_type=RFCOMM_MCC_PN_TYPE, c_r=1, data=bytes(pn))
         logger.debug(f'>>> Sending MCC: {pn}')
         self.open_result = asyncio.get_running_loop().create_future()
-        self.change_state(Multiplexer.OPENING)
+        self.change_state(Multiplexer.State.OPENING)
         self.send_frame(
             RFCOMM_Frame.uih(
-                c_r=1 if self.role == Multiplexer.INITIATOR else 0,
+                c_r=1 if self.role == Multiplexer.Role.INITIATOR else 0,
                 dlci=0,
                 information=mcc,
             )
@@ -796,25 +874,28 @@ class Multiplexer(EventEmitter):
         self.open_result = None
         return result
 
-    def on_dlc_open_complete(self, dlc):
+    def on_dlc_open_complete(self, dlc: DLC) -> None:
         logger.debug(f'DLC [{dlc.dlci}] open complete')
-        self.change_state(Multiplexer.CONNECTED)
+        self.change_state(Multiplexer.State.CONNECTED)
         if self.open_result:
             self.open_result.set_result(dlc)
 
-    def __str__(self):
-        return f'Multiplexer(state={self.state_name(self.state)})'
+    def __str__(self) -> str:
+        return f'Multiplexer(state={self.state.name})'
 
 
 # -----------------------------------------------------------------------------
 class Client:
-    def __init__(self, device, connection):
+    multiplexer: Optional[Multiplexer]
+    l2cap_channel: Optional[l2cap.Channel]
+
+    def __init__(self, device: Device, connection: Connection) -> None:
         self.device = device
         self.connection = connection
         self.l2cap_channel = None
         self.multiplexer = None
 
-    async def start(self):
+    async def start(self) -> Multiplexer:
         # Create a new L2CAP connection
         try:
             self.l2cap_channel = await self.device.l2cap_channel_manager.connect(
@@ -824,15 +905,18 @@ class Client:
             logger.warning(f'L2CAP connection failed: {error}')
             raise
 
+        assert self.l2cap_channel is not None
         # Create a mutliplexer to manage DLCs with the server
-        self.multiplexer = Multiplexer(self.l2cap_channel, Multiplexer.INITIATOR)
+        self.multiplexer = Multiplexer(self.l2cap_channel, Multiplexer.Role.INITIATOR)
 
         # Connect the multiplexer
         await self.multiplexer.connect()
 
         return self.multiplexer
 
-    async def shutdown(self):
+    async def shutdown(self) -> None:
+        if self.multiplexer is None:
+            return
         # Disconnect the multiplexer
         await self.multiplexer.disconnect()
         self.multiplexer = None
@@ -843,7 +927,9 @@ class Client:
 
 # -----------------------------------------------------------------------------
 class Server(EventEmitter):
-    def __init__(self, device):
+    acceptors: Dict[int, Callable[[DLC], None]]
+
+    def __init__(self, device: Device) -> None:
         super().__init__()
         self.device = device
         self.multiplexer = None
@@ -852,37 +938,47 @@ class Server(EventEmitter):
         # Register ourselves with the L2CAP channel manager
         device.register_l2cap_server(RFCOMM_PSM, self.on_connection)
 
-    def listen(self, acceptor):
-        # Find a free channel number
-        for channel in range(
-            RFCOMM_DYNAMIC_CHANNEL_NUMBER_START, RFCOMM_DYNAMIC_CHANNEL_NUMBER_END + 1
-        ):
-            if channel not in self.acceptors:
-                self.acceptors[channel] = acceptor
-                return channel
+    def listen(self, acceptor: Callable[[DLC], None], channel: int = 0) -> int:
+        if channel:
+            if channel in self.acceptors:
+                # Busy
+                return 0
+        else:
+            # Find a free channel number
+            for candidate in range(
+                RFCOMM_DYNAMIC_CHANNEL_NUMBER_START,
+                RFCOMM_DYNAMIC_CHANNEL_NUMBER_END + 1,
+            ):
+                if candidate not in self.acceptors:
+                    channel = candidate
+                    break
 
-        # All channels used...
-        return 0
+            if channel == 0:
+                # All channels used...
+                return 0
 
-    def on_connection(self, l2cap_channel):
+        self.acceptors[channel] = acceptor
+        return channel
+
+    def on_connection(self, l2cap_channel: l2cap.Channel) -> None:
         logger.debug(f'+++ new L2CAP connection: {l2cap_channel}')
         l2cap_channel.on('open', lambda: self.on_l2cap_channel_open(l2cap_channel))
 
-    def on_l2cap_channel_open(self, l2cap_channel):
+    def on_l2cap_channel_open(self, l2cap_channel: l2cap.Channel) -> None:
         logger.debug(f'$$$ L2CAP channel open: {l2cap_channel}')
 
         # Create a new multiplexer for the channel
-        multiplexer = Multiplexer(l2cap_channel, Multiplexer.RESPONDER)
+        multiplexer = Multiplexer(l2cap_channel, Multiplexer.Role.RESPONDER)
         multiplexer.acceptor = self.accept_dlc
         multiplexer.on('dlc', self.on_dlc)
 
         # Notify
         self.emit('start', multiplexer)
 
-    def accept_dlc(self, channel_number):
+    def accept_dlc(self, channel_number: int) -> bool:
         return channel_number in self.acceptors
 
-    def on_dlc(self, dlc):
+    def on_dlc(self, dlc: DLC) -> None:
         logger.debug(f'@@@ new DLC connected: {dlc}')
 
         # Let the acceptor know

bumble/sdp.py

@@ -18,13 +18,16 @@
 from __future__ import annotations
 import logging
 import struct
-from typing import Dict, List, Type
+from typing import Dict, List, Type, Optional, Tuple, Union, NewType, TYPE_CHECKING
 
-from . import core
+from . import core, l2cap
 from .colors import color
 from .core import InvalidStateError
 from .hci import HCI_Object, name_or_number, key_with_value
 
+if TYPE_CHECKING:
+    from .device import Device, Connection
+
 # -----------------------------------------------------------------------------
 # Logging
 # -----------------------------------------------------------------------------
@@ -94,6 +97,10 @@ SDP_CLIENT_EXECUTABLE_URL_ATTRIBUTE_ID               = 0X000B
 SDP_ICON_URL_ATTRIBUTE_ID                            = 0X000C
 SDP_ADDITIONAL_PROTOCOL_DESCRIPTOR_LIST_ATTRIBUTE_ID = 0X000D
 
+# Attribute Identifier (cf. Assigned Numbers for Service Discovery)
+# used by AVRCP, HFP and A2DP
+SDP_SUPPORTED_FEATURES_ATTRIBUTE_ID = 0x0311
+
 SDP_ATTRIBUTE_ID_NAMES = {
     SDP_SERVICE_RECORD_HANDLE_ATTRIBUTE_ID:               'SDP_SERVICE_RECORD_HANDLE_ATTRIBUTE_ID',
     SDP_SERVICE_CLASS_ID_LIST_ATTRIBUTE_ID:               'SDP_SERVICE_CLASS_ID_LIST_ATTRIBUTE_ID',
@@ -462,7 +469,7 @@ class ServiceAttribute:
         self.value = value
 
     @staticmethod
-    def list_from_data_elements(elements):
+    def list_from_data_elements(elements: List[DataElement]) -> List[ServiceAttribute]:
         attribute_list = []
         for i in range(0, len(elements) // 2):
             attribute_id, attribute_value = elements[2 * i : 2 * (i + 1)]
@@ -474,7 +481,9 @@ class ServiceAttribute:
         return attribute_list
 
     @staticmethod
-    def find_attribute_in_list(attribute_list, attribute_id):
+    def find_attribute_in_list(
+        attribute_list: List[ServiceAttribute], attribute_id: int
+    ) -> Optional[DataElement]:
         return next(
             (
                 attribute.value
@@ -489,7 +498,7 @@ class ServiceAttribute:
         return name_or_number(SDP_ATTRIBUTE_ID_NAMES, id_code)
 
     @staticmethod
-    def is_uuid_in_value(uuid, value):
+    def is_uuid_in_value(uuid: core.UUID, value: DataElement) -> bool:
         # Find if a uuid matches a value, either directly or recursing into sequences
         if value.type == DataElement.UUID:
             return value.value == uuid
@@ -543,7 +552,9 @@ class SDP_PDU:
         return self
 
     @staticmethod
-    def parse_service_record_handle_list_preceded_by_count(data, offset):
+    def parse_service_record_handle_list_preceded_by_count(
+        data: bytes, offset: int
+    ) -> Tuple[int, List[int]]:
         count = struct.unpack_from('>H', data, offset - 2)[0]
         handle_list = [
             struct.unpack_from('>I', data, offset + x * 4)[0] for x in range(count)
@@ -641,6 +652,10 @@ class SDP_ServiceSearchRequest(SDP_PDU):
     See Bluetooth spec @ Vol 3, Part B - 4.5.1 SDP_ServiceSearchRequest PDU
     '''
 
+    service_search_pattern: DataElement
+    maximum_service_record_count: int
+    continuation_state: bytes
+
 
 # -----------------------------------------------------------------------------
 @SDP_PDU.subclass(
@@ -659,6 +674,11 @@ class SDP_ServiceSearchResponse(SDP_PDU):
     See Bluetooth spec @ Vol 3, Part B - 4.5.2 SDP_ServiceSearchResponse PDU
     '''
 
+    service_record_handle_list: List[int]
+    total_service_record_count: int
+    current_service_record_count: int
+    continuation_state: bytes
+
 
 # -----------------------------------------------------------------------------
 @SDP_PDU.subclass(
@@ -674,6 +694,11 @@ class SDP_ServiceAttributeRequest(SDP_PDU):
     See Bluetooth spec @ Vol 3, Part B - 4.6.1 SDP_ServiceAttributeRequest PDU
     '''
 
+    service_record_handle: int
+    maximum_attribute_byte_count: int
+    attribute_id_list: DataElement
+    continuation_state: bytes
+
 
 # -----------------------------------------------------------------------------
 @SDP_PDU.subclass(
@@ -688,6 +713,10 @@ class SDP_ServiceAttributeResponse(SDP_PDU):
     See Bluetooth spec @ Vol 3, Part B - 4.6.2 SDP_ServiceAttributeResponse PDU
     '''
 
+    attribute_list_byte_count: int
+    attribute_list: bytes
+    continuation_state: bytes
+
 
 # -----------------------------------------------------------------------------
 @SDP_PDU.subclass(
@@ -703,6 +732,11 @@ class SDP_ServiceSearchAttributeRequest(SDP_PDU):
     See Bluetooth spec @ Vol 3, Part B - 4.7.1 SDP_ServiceSearchAttributeRequest PDU
     '''
 
+    service_search_pattern: DataElement
+    maximum_attribute_byte_count: int
+    attribute_id_list: DataElement
+    continuation_state: bytes
+
 
 # -----------------------------------------------------------------------------
 @SDP_PDU.subclass(
@@ -717,26 +751,34 @@ class SDP_ServiceSearchAttributeResponse(SDP_PDU):
     See Bluetooth spec @ Vol 3, Part B - 4.7.2 SDP_ServiceSearchAttributeResponse PDU
     '''
 
+    attribute_list_byte_count: int
+    attribute_list: bytes
+    continuation_state: bytes
+
 
 # -----------------------------------------------------------------------------
 class Client:
-    def __init__(self, device):
+    channel: Optional[l2cap.Channel]
+
+    def __init__(self, device: Device) -> None:
         self.device = device
         self.pending_request = None
         self.channel = None
 
-    async def connect(self, connection):
+    async def connect(self, connection: Connection) -> None:
         result = await self.device.l2cap_channel_manager.connect(connection, SDP_PSM)
         self.channel = result
 
-    async def disconnect(self):
+    async def disconnect(self) -> None:
         if self.channel:
             await self.channel.disconnect()
             self.channel = None
 
-    async def search_services(self, uuids):
+    async def search_services(self, uuids: List[core.UUID]) -> List[int]:
         if self.pending_request is not None:
             raise InvalidStateError('request already pending')
+        if self.channel is None:
+            raise InvalidStateError('L2CAP not connected')
 
         service_search_pattern = DataElement.sequence(
             [DataElement.uuid(uuid) for uuid in uuids]
@@ -766,9 +808,13 @@ class Client:
 
         return service_record_handle_list
 
-    async def search_attributes(self, uuids, attribute_ids):
+    async def search_attributes(
+        self, uuids: List[core.UUID], attribute_ids: List[Union[int, Tuple[int, int]]]
+    ) -> List[List[ServiceAttribute]]:
         if self.pending_request is not None:
             raise InvalidStateError('request already pending')
+        if self.channel is None:
+            raise InvalidStateError('L2CAP not connected')
 
         service_search_pattern = DataElement.sequence(
             [DataElement.uuid(uuid) for uuid in uuids]
@@ -819,9 +865,15 @@ class Client:
             if sequence.type == DataElement.SEQUENCE
         ]
 
-    async def get_attributes(self, service_record_handle, attribute_ids):
+    async def get_attributes(
+        self,
+        service_record_handle: int,
+        attribute_ids: List[Union[int, Tuple[int, int]]],
+    ) -> List[ServiceAttribute]:
         if self.pending_request is not None:
             raise InvalidStateError('request already pending')
+        if self.channel is None:
+            raise InvalidStateError('L2CAP not connected')
 
         attribute_id_list = DataElement.sequence(
             [
@@ -869,21 +921,25 @@ class Client:
 # -----------------------------------------------------------------------------
 class Server:
     CONTINUATION_STATE = bytes([0x01, 0x43])
+    channel: Optional[l2cap.Channel]
+    Service = NewType('Service', List[ServiceAttribute])
+    service_records: Dict[int, Service]
+    current_response: Union[None, bytes, Tuple[int, List[int]]]
 
-    def __init__(self, device):
+    def __init__(self, device: Device) -> None:
         self.device = device
         self.service_records = {}  # Service records maps, by record handle
         self.channel = None
         self.current_response = None
 
-    def register(self, l2cap_channel_manager):
+    def register(self, l2cap_channel_manager: l2cap.ChannelManager) -> None:
         l2cap_channel_manager.register_server(SDP_PSM, self.on_connection)
 
     def send_response(self, response):
         logger.debug(f'{color(">>> Sending SDP Response", "blue")}: {response}')
         self.channel.send_pdu(response)
 
-    def match_services(self, search_pattern):
+    def match_services(self, search_pattern: DataElement) -> Dict[int, Service]:
         # Find the services for which the attributes in the pattern is a subset of the
         # service's attribute values (NOTE: the value search recurses into sequences)
         matching_services = {}
@@ -953,7 +1009,9 @@ class Server:
         return (payload, continuation_state)
 
     @staticmethod
-    def get_service_attributes(service, attribute_ids):
+    def get_service_attributes(
+        service: Service, attribute_ids: List[DataElement]
+    ) -> DataElement:
         attributes = []
         for attribute_id in attribute_ids:
             if attribute_id.value_size == 4:
@@ -978,10 +1036,10 @@ class Server:
 
         return attribute_list
 
-    def on_sdp_service_search_request(self, request):
+    def on_sdp_service_search_request(self, request: SDP_ServiceSearchRequest) -> None:
         # Check if this is a continuation
         if len(request.continuation_state) > 1:
-            if not self.current_response:
+            if self.current_response is None:
                 self.send_response(
                     SDP_ErrorResponse(
                         transaction_id=request.transaction_id,
@@ -1010,6 +1068,7 @@ class Server:
             )
 
         # Respond, keeping any unsent handles for later
+        assert isinstance(self.current_response, tuple)
         service_record_handles = self.current_response[1][
             : request.maximum_service_record_count
         ]
@@ -1033,10 +1092,12 @@ class Server:
             )
         )
 
-    def on_sdp_service_attribute_request(self, request):
+    def on_sdp_service_attribute_request(
+        self, request: SDP_ServiceAttributeRequest
+    ) -> None:
         # Check if this is a continuation
         if len(request.continuation_state) > 1:
-            if not self.current_response:
+            if self.current_response is None:
                 self.send_response(
                     SDP_ErrorResponse(
                         transaction_id=request.transaction_id,
@@ -1069,22 +1130,24 @@ class Server:
             self.current_response = bytes(attribute_list)
 
         # Respond, keeping any pending chunks for later
-        attribute_list, continuation_state = self.get_next_response_payload(
+        attribute_list_response, continuation_state = self.get_next_response_payload(
             request.maximum_attribute_byte_count
         )
         self.send_response(
             SDP_ServiceAttributeResponse(
                 transaction_id=request.transaction_id,
-                attribute_list_byte_count=len(attribute_list),
+                attribute_list_byte_count=len(attribute_list_response),
                 attribute_list=attribute_list,
                 continuation_state=continuation_state,
             )
         )
 
-    def on_sdp_service_search_attribute_request(self, request):
+    def on_sdp_service_search_attribute_request(
+        self, request: SDP_ServiceSearchAttributeRequest
+    ) -> None:
         # Check if this is a continuation
         if len(request.continuation_state) > 1:
-            if not self.current_response:
+            if self.current_response is None:
                 self.send_response(
                     SDP_ErrorResponse(
                         transaction_id=request.transaction_id,
@@ -1114,13 +1177,13 @@ class Server:
             self.current_response = bytes(attribute_lists)
 
         # Respond, keeping any pending chunks for later
-        attribute_lists, continuation_state = self.get_next_response_payload(
+        attribute_lists_response, continuation_state = self.get_next_response_payload(
             request.maximum_attribute_byte_count
         )
         self.send_response(
             SDP_ServiceSearchAttributeResponse(
                 transaction_id=request.transaction_id,
-                attribute_lists_byte_count=len(attribute_lists),
+                attribute_lists_byte_count=len(attribute_lists_response),
                 attribute_lists=attribute_lists,
                 continuation_state=continuation_state,
             )

bumble/snoop.py

@@ -15,12 +15,21 @@
 # -----------------------------------------------------------------------------
 # Imports
 # -----------------------------------------------------------------------------
+from contextlib import contextmanager
 from enum import IntEnum
+import logging
 import struct
 import datetime
-from typing import BinaryIO
+from typing import BinaryIO, Generator
+import os
 
-from bumble.hci import HCI_Packet, HCI_COMMAND_PACKET, HCI_EVENT_PACKET
+from bumble.hci import HCI_COMMAND_PACKET, HCI_EVENT_PACKET
+
+
+# -----------------------------------------------------------------------------
+# Logging
+# -----------------------------------------------------------------------------
+logger = logging.getLogger(__name__)
 
 
 # -----------------------------------------------------------------------------
@@ -44,7 +53,7 @@ class Snooper:
         HCI_BSCP = 1003
         H5 = 1004
 
-    def snoop(self, hci_packet: HCI_Packet, direction: Direction) -> None:
+    def snoop(self, hci_packet: bytes, direction: Direction) -> None:
         """Snoop on an HCI packet."""
 
 
@@ -67,9 +76,10 @@ class BtSnooper(Snooper):
             self.IDENTIFICATION_PATTERN + struct.pack('>LL', 1, self.DataLinkType.H4)
         )
 
-    def snoop(self, hci_packet: HCI_Packet, direction: Snooper.Direction) -> None:
+    def snoop(self, hci_packet: bytes, direction: Snooper.Direction) -> None:
         flags = int(direction)
-        if hci_packet.hci_packet_type in (HCI_EVENT_PACKET, HCI_COMMAND_PACKET):
+        packet_type = hci_packet[0]
+        if packet_type in (HCI_EVENT_PACKET, HCI_COMMAND_PACKET):
             flags |= 0x10
 
         # Compute the current timestamp
@@ -79,15 +89,82 @@ class BtSnooper(Snooper):
         )
 
         # Emit the record
-        packet_data = bytes(hci_packet)
         self.output.write(
             struct.pack(
                 '>IIIIQ',
-                len(packet_data),  # Original Length
-                len(packet_data),  # Included Length
+                len(hci_packet),  # Original Length
+                len(hci_packet),  # Included Length
                 flags,  # Packet Flags
                 0,  # Cumulative Drops
                 timestamp,  # Timestamp
             )
-            + packet_data
+            + hci_packet
         )
+
+
+# -----------------------------------------------------------------------------
+_SNOOPER_INSTANCE_COUNT = 0
+
+
+@contextmanager
+def create_snooper(spec: str) -> Generator[Snooper, None, None]:
+    """
+    Create a snooper given a specification string.
+
+    The general syntax for the specification string is:
+      <snooper-type>:<type-specific-arguments>
+
+    Supported snooper types are:
+
+      btsnoop
+        The syntax for the type-specific arguments for this type is:
+        <io-type>:<io-type-specific-arguments>
+
+        Supported I/O types are:
+
+        file
+          The type-specific arguments for this I/O type is a string that is converted
+          to a file path using the python `str.format()` string formatting. The log
+          records will be written to that file if it can be opened/created.
+          The keyword args that may be referenced by the string pattern are:
+            now: the value of `datetime.now()`
+            utcnow: the value of `datetime.utcnow()`
+            pid: the current process ID.
+            instance: the instance ID in the current process.
+
+    Examples:
+      btsnoop:file:my_btsnoop.log
+      btsnoop:file:/tmp/bumble_{now:%Y-%m-%d-%H:%M:%S}_{pid}.log
+
+    """
+    if ':' not in spec:
+        raise ValueError('snooper type prefix missing')
+
+    snooper_type, snooper_args = spec.split(':', maxsplit=1)
+
+    if snooper_type == 'btsnoop':
+        if ':' not in snooper_args:
+            raise ValueError('I/O type for btsnoop snooper type missing')
+
+        io_type, io_name = snooper_args.split(':', maxsplit=1)
+        if io_type == 'file':
+            # Process the file name string pattern.
+            global _SNOOPER_INSTANCE_COUNT
+            file_path = io_name.format(
+                now=datetime.datetime.now(),
+                utcnow=datetime.datetime.utcnow(),
+                pid=os.getpid(),
+                instance=_SNOOPER_INSTANCE_COUNT,
+            )
+
+            # Open the file
+            logger.debug(f'Snoop file: {file_path}')
+            with open(file_path, 'wb') as snoop_file:
+                _SNOOPER_INSTANCE_COUNT += 1
+                yield BtSnooper(snoop_file)
+                _SNOOPER_INSTANCE_COUNT -= 1
+                return
+
+        raise ValueError(f'I/O type {io_type} not supported')
+
+    raise ValueError(f'snooper type {snooper_type} not found')

bumble/transport/__init__.py

@@ -1,4 +1,4 @@
-# Copyright 2021-2022 Google LLC
+# 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.
@@ -15,10 +15,12 @@
 # -----------------------------------------------------------------------------
 # Imports
 # -----------------------------------------------------------------------------
+from contextlib import asynccontextmanager
 import logging
+import os
 
-from .common import Transport, AsyncPipeSink
-from ..controller import Controller
+from .common import Transport, AsyncPipeSink, SnoopingTransport
+from ..snoop import create_snooper
 
 # -----------------------------------------------------------------------------
 # Logging
@@ -26,14 +28,54 @@ from ..controller import Controller
 logger = logging.getLogger(__name__)
 
 
+# -----------------------------------------------------------------------------
+def _wrap_transport(transport: Transport) -> Transport:
+    """
+    Automatically wrap a Transport instance when a wrapping class can be inferred
+    from the environment.
+    If no wrapping class is applicable, the transport argument is returned as-is.
+    """
+
+    # If BUMBLE_SNOOPER is set, try to automatically create a snooper.
+    if snooper_spec := os.getenv('BUMBLE_SNOOPER'):
+        try:
+            return SnoopingTransport.create_with(
+                transport, create_snooper(snooper_spec)
+            )
+        except Exception as exc:
+            logger.warning(f'Exception while creating snooper: {exc}')
+
+    return transport
+
+
 # -----------------------------------------------------------------------------
 async def open_transport(name: str) -> Transport:
-    '''
+    """
     Open a transport by name.
     The name must be <type>:<parameters>
     Where <parameters> depend on the type (and may be empty for some types).
-    The supported types are: serial,udp,tcp,pty,usb
-    '''
+    The supported types are:
+      * serial
+      * udp
+      * tcp-client
+      * tcp-server
+      * ws-client
+      * ws-server
+      * pty
+      * file
+      * vhci
+      * hci-socket
+      * usb
+      * pyusb
+      * android-emulator
+      * android-netsim
+    """
+
+    return _wrap_transport(await _open_transport(name))
+
+
+# -----------------------------------------------------------------------------
+async def _open_transport(name: str) -> Transport:
     # pylint: disable=import-outside-toplevel
     # pylint: disable=too-many-return-statements
 
@@ -76,7 +118,8 @@ async def open_transport(name: str) -> Transport:
     if scheme == 'file':
         from .file import open_file_transport
 
-        return await open_file_transport(spec[0] if spec else None)
+        assert spec is not None
+        return await open_file_transport(spec[0])
 
     if scheme == 'vhci':
         from .vhci import open_vhci_transport
@@ -91,24 +134,43 @@ async def open_transport(name: str) -> Transport:
     if scheme == 'usb':
         from .usb import open_usb_transport
 
-        return await open_usb_transport(spec[0] if spec else None)
+        assert spec is not None
+        return await open_usb_transport(spec[0])
 
     if scheme == 'pyusb':
         from .pyusb import open_pyusb_transport
 
-        return await open_pyusb_transport(spec[0] if spec else None)
+        assert spec is not None
+        return await open_pyusb_transport(spec[0])
 
     if scheme == 'android-emulator':
         from .android_emulator import open_android_emulator_transport
 
         return await open_android_emulator_transport(spec[0] if spec else None)
 
+    if scheme == 'android-netsim':
+        from .android_netsim import open_android_netsim_transport
+
+        return await open_android_netsim_transport(spec[0] if spec else None)
+
     raise ValueError('unknown transport scheme')
 
 
 # -----------------------------------------------------------------------------
-async def open_transport_or_link(name):
+async def open_transport_or_link(name: str) -> Transport:
+    """
+    Open a transport or a link relay.
+
+    Args:
+      name:
+        Name of the transport or link relay to open.
+        When the name starts with "link-relay:", open a link relay (see RemoteLink
+        for details on what the arguments are).
+        For other namespaces, see `open_transport`.
+
+    """
     if name.startswith('link-relay:'):
+        from ..controller import Controller
         from ..link import RemoteLink  # lazy import
 
         link = RemoteLink(name[11:])
@@ -119,6 +181,6 @@ async def open_transport_or_link(name):
             async def close(self):
                 link.close()
 
-        return LinkTransport(controller, AsyncPipeSink(controller))
+        return _wrap_transport(LinkTransport(controller, AsyncPipeSink(controller)))
 
     return await open_transport(name)

bumble/transport/android_emulator.py

@@ -16,14 +16,16 @@
 # Imports
 # -----------------------------------------------------------------------------
 import logging
-import grpc
+import grpc.aio
 
-from .common import PumpedTransport, PumpedPacketSource, PumpedPacketSink
-from .emulated_bluetooth_pb2_grpc import EmulatedBluetoothServiceStub
-from .emulated_bluetooth_vhci_pb2_grpc import VhciForwardingServiceStub
+from typing import Optional, Union
 
-# pylint: disable-next=no-name-in-module
-from .emulated_bluetooth_packets_pb2 import HCIPacket
+from .common import PumpedTransport, PumpedPacketSource, PumpedPacketSink, Transport
+
+# pylint: disable=no-name-in-module
+from .grpc_protobuf.emulated_bluetooth_pb2_grpc import EmulatedBluetoothServiceStub
+from .grpc_protobuf.emulated_bluetooth_packets_pb2 import HCIPacket
+from .grpc_protobuf.emulated_bluetooth_vhci_pb2_grpc import VhciForwardingServiceStub
 
 
 # -----------------------------------------------------------------------------
@@ -33,7 +35,7 @@ logger = logging.getLogger(__name__)
 
 
 # -----------------------------------------------------------------------------
-async def open_android_emulator_transport(spec):
+async def open_android_emulator_transport(spec: Optional[str]) -> Transport:
     '''
     Open a transport connection to an Android emulator via its gRPC interface.
     The parameter string has this syntax:
@@ -66,7 +68,7 @@ async def open_android_emulator_transport(spec):
     # Parse the parameters
     mode = 'host'
     server_host = 'localhost'
-    server_port = 8554
+    server_port = '8554'
     if spec is not None:
         params = spec.split(',')
         for param in params:
@@ -82,6 +84,7 @@ async def open_android_emulator_transport(spec):
     logger.debug(f'connecting to gRPC server at {server_address}')
     channel = grpc.aio.insecure_channel(server_address)
 
+    service: Union[EmulatedBluetoothServiceStub, VhciForwardingServiceStub]
     if mode == 'host':
         # Connect as a host
         service = EmulatedBluetoothServiceStub(channel)

bumble/transport/android_netsim.py

@@ -0,0 +1,412 @@
+# 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
+# -----------------------------------------------------------------------------
+import asyncio
+import atexit
+import logging
+import grpc.aio
+import os
+import pathlib
+import sys
+from typing import Optional
+
+from .common import (
+    ParserSource,
+    PumpedTransport,
+    PumpedPacketSource,
+    PumpedPacketSink,
+    Transport,
+)
+
+# pylint: disable=no-name-in-module
+from .grpc_protobuf.packet_streamer_pb2_grpc import PacketStreamerStub
+from .grpc_protobuf.packet_streamer_pb2_grpc import (
+    PacketStreamerServicer,
+    add_PacketStreamerServicer_to_server,
+)
+from .grpc_protobuf.packet_streamer_pb2 import PacketRequest, PacketResponse
+from .grpc_protobuf.hci_packet_pb2 import HCIPacket
+from .grpc_protobuf.startup_pb2 import Chip, ChipInfo
+from .grpc_protobuf.common_pb2 import ChipKind
+
+# -----------------------------------------------------------------------------
+# Logging
+# -----------------------------------------------------------------------------
+logger = logging.getLogger(__name__)
+
+
+# -----------------------------------------------------------------------------
+# Constants
+# -----------------------------------------------------------------------------
+DEFAULT_NAME = 'bumble0'
+DEFAULT_MANUFACTURER = 'Bumble'
+
+
+# -----------------------------------------------------------------------------
+def get_ini_dir() -> Optional[pathlib.Path]:
+    if sys.platform == 'darwin':
+        if tmpdir := os.getenv('TMPDIR', None):
+            return pathlib.Path(tmpdir)
+        if home := os.getenv('HOME', None):
+            return pathlib.Path(home) / 'Library/Caches/TemporaryItems'
+    elif sys.platform == 'linux':
+        if xdg_runtime_dir := os.environ.get('XDG_RUNTIME_DIR', None):
+            return pathlib.Path(xdg_runtime_dir)
+    elif sys.platform == 'win32':
+        if local_app_data_dir := os.environ.get('LOCALAPPDATA', None):
+            return pathlib.Path(local_app_data_dir) / 'Temp'
+
+    return None
+
+
+# -----------------------------------------------------------------------------
+def find_grpc_port() -> int:
+    if not (ini_dir := get_ini_dir()):
+        logger.debug('no known directory for .ini file')
+        return 0
+
+    ini_file = ini_dir / 'netsim.ini'
+    if ini_file.is_file():
+        logger.debug(f'Found .ini file at {ini_file}')
+        with open(ini_file, 'r') as ini_file_data:
+            for line in ini_file_data.readlines():
+                if '=' in line:
+                    key, value = line.split('=')
+                    if key == 'grpc.port':
+                        logger.debug(f'gRPC port = {value}')
+                        return int(value)
+
+    # Not found
+    return 0
+
+
+# -----------------------------------------------------------------------------
+def publish_grpc_port(grpc_port) -> bool:
+    if not (ini_dir := get_ini_dir()):
+        logger.debug('no known directory for .ini file')
+        return False
+
+    if not ini_dir.is_dir():
+        logger.debug('ini directory does not exist')
+        return False
+
+    ini_file = ini_dir / 'netsim.ini'
+    try:
+        ini_file.write_text(f'grpc.port={grpc_port}\n')
+        logger.debug(f"published gRPC port at {ini_file}")
+
+        def cleanup():
+            logger.debug("removing .ini file")
+            ini_file.unlink()
+
+        atexit.register(cleanup)
+        return True
+    except OSError:
+        logger.debug('failed to write to .ini file')
+        return False
+
+
+# -----------------------------------------------------------------------------
+async def open_android_netsim_controller_transport(
+    server_host: Optional[str], server_port: int
+) -> Transport:
+    if not server_port:
+        raise ValueError('invalid port')
+    if server_host == '_' or not server_host:
+        server_host = 'localhost'
+
+    if not publish_grpc_port(server_port):
+        logger.warning("unable to publish gRPC port")
+
+    class HciDevice:
+        def __init__(self, context, on_data_received):
+            self.context = context
+            self.on_data_received = on_data_received
+            self.name = None
+            self.loop = asyncio.get_running_loop()
+            self.done = self.loop.create_future()
+            self.task = self.loop.create_task(self.pump())
+
+        async def pump(self):
+            try:
+                await self.pump_loop()
+            except asyncio.CancelledError:
+                logger.debug('Pump task canceled')
+                self.done.set_result(None)
+
+        async def pump_loop(self):
+            while True:
+                request = await self.context.read()
+                if request == grpc.aio.EOF:
+                    logger.debug('End of request stream')
+                    self.done.set_result(None)
+                    return
+
+                # If we're not initialized yet, wait for a init packet.
+                if self.name is None:
+                    if request.WhichOneof('request_type') == 'initial_info':
+                        logger.debug(f'Received initial info: {request}')
+
+                        # We only accept BLUETOOTH
+                        if request.initial_info.chip.kind != ChipKind.BLUETOOTH:
+                            logger.warning('Unsupported chip type')
+                            error = PacketResponse(error='Unsupported chip type')
+                            await self.context.write(error)
+                            return
+
+                    self.name = request.initial_info.name
+                    continue
+
+                # Expect a data packet
+                request_type = request.WhichOneof('request_type')
+                if request_type != 'hci_packet':
+                    logger.warning(f'Unexpected request type: {request_type}')
+                    error = PacketResponse(error='Unexpected request type')
+                    await self.context.write(error)
+                    continue
+
+                # Process the packet
+                data = (
+                    bytes([request.hci_packet.packet_type]) + request.hci_packet.packet
+                )
+                logger.debug(f'<<< PACKET: {data.hex()}')
+                self.on_data_received(data)
+
+        def send_packet(self, data):
+            async def send():
+                await self.context.write(
+                    PacketResponse(
+                        hci_packet=HCIPacket(packet_type=data[0], packet=data[1:])
+                    )
+                )
+
+            self.loop.create_task(send())
+
+        def terminate(self):
+            self.task.cancel()
+
+        async def wait_for_termination(self):
+            await self.done
+
+    class Server(PacketStreamerServicer, ParserSource):
+        def __init__(self):
+            PacketStreamerServicer.__init__(self)
+            ParserSource.__init__(self)
+            self.device = None
+
+            # Create a gRPC server with `so_reuseport=0` so that if there's already
+            # a server listening on that port, we get an exception.
+            self.grpc_server = grpc.aio.server(options=(('grpc.so_reuseport', 0),))
+            add_PacketStreamerServicer_to_server(self, self.grpc_server)
+            self.grpc_server.add_insecure_port(f'{server_host}:{server_port}')
+            logger.debug(f'gRPC server listening on {server_host}:{server_port}')
+
+        async def start(self):
+            logger.debug('Starting gRPC server')
+            await self.grpc_server.start()
+
+        async def serve(self):
+            # Keep serving until terminated.
+            try:
+                await self.grpc_server.wait_for_termination()
+                logger.debug('gRPC server terminated')
+            except asyncio.CancelledError:
+                logger.debug('gRPC server cancelled')
+                await self.grpc_server.stop(None)
+
+        def on_packet(self, packet):
+            if not self.device:
+                logger.debug('no device, dropping packet')
+                return
+
+            self.device.send_packet(packet)
+
+        async def StreamPackets(self, _request_iterator, context):
+            logger.debug('StreamPackets request')
+
+            # Check that we won't already have a device
+            if self.device:
+                logger.debug('busy, already serving a device')
+                return PacketResponse(error='Busy')
+
+            # Instantiate a new device
+            self.device = HciDevice(context, self.parser.feed_data)
+
+            # Wait for the device to terminate
+            logger.debug('Waiting for device to terminate')
+            try:
+                await self.device.wait_for_termination()
+            except asyncio.CancelledError:
+                logger.debug('Request canceled')
+                self.device.terminate()
+
+            logger.debug('Device terminated')
+            self.device = None
+
+    server = Server()
+    await server.start()
+    asyncio.get_running_loop().create_task(server.serve())
+
+    class GrpcServerTransport(Transport):
+        async def close(self):
+            await super().close()
+
+    return GrpcServerTransport(server, server)
+
+
+# -----------------------------------------------------------------------------
+async def open_android_netsim_host_transport(server_host, server_port, options):
+    # Wrapper for I/O operations
+    class HciDevice:
+        def __init__(self, name, manufacturer, hci_device):
+            self.name = name
+            self.manufacturer = manufacturer
+            self.hci_device = hci_device
+
+        async def start(self):  # Send the startup info
+            chip_info = ChipInfo(
+                name=self.name,
+                chip=Chip(kind=ChipKind.BLUETOOTH, manufacturer=self.manufacturer),
+            )
+            logger.debug(f'Sending chip info to netsim: {chip_info}')
+            await self.hci_device.write(PacketRequest(initial_info=chip_info))
+
+        async def read(self):
+            response = await self.hci_device.read()
+            response_type = response.WhichOneof('response_type')
+            if response_type == 'error':
+                logger.warning(f'received error: {response.error}')
+                raise RuntimeError(response.error)
+            elif response_type == 'hci_packet':
+                return (
+                    bytes([response.hci_packet.packet_type])
+                    + response.hci_packet.packet
+                )
+
+            raise ValueError('unsupported response type')
+
+        async def write(self, packet):
+            await self.hci_device.write(
+                PacketRequest(
+                    hci_packet=HCIPacket(packet_type=packet[0], packet=packet[1:])
+                )
+            )
+
+    name = options.get('name', DEFAULT_NAME)
+    manufacturer = DEFAULT_MANUFACTURER
+
+    if server_host == '_' or not server_host:
+        server_host = 'localhost'
+
+    if not server_port:
+        # Look for the gRPC config in a .ini file
+        server_host = 'localhost'
+        server_port = find_grpc_port()
+        if not server_port:
+            raise RuntimeError('gRPC server port not found')
+
+    # Connect to the gRPC server
+    server_address = f'{server_host}:{server_port}'
+    logger.debug(f'Connecting to gRPC server at {server_address}')
+    channel = grpc.aio.insecure_channel(server_address)
+
+    # Connect as a host
+    service = PacketStreamerStub(channel)
+    hci_device = HciDevice(
+        name=name,
+        manufacturer=manufacturer,
+        hci_device=service.StreamPackets(),
+    )
+    await hci_device.start()
+
+    # Create the transport object
+    transport = PumpedTransport(
+        PumpedPacketSource(hci_device.read),
+        PumpedPacketSink(hci_device.write),
+        channel.close,
+    )
+    transport.start()
+
+    return transport
+
+
+# -----------------------------------------------------------------------------
+async def open_android_netsim_transport(spec):
+    '''
+    Open a transport connection as a client or server, implementing Android's `netsim`
+    simulator protocol over gRPC.
+    The parameter string has this syntax:
+    [<host>:<port>][<options>]
+    Where <options> is a ','-separated list of <name>=<value> pairs.
+
+    General options:
+      mode=host|controller (default: host)
+        Specifies whether the transport is used
+        to connect *to* a netsim server (netsim is the controller), or accept
+        connections *as* a netsim-compatible server.
+
+    In `host` mode:
+      The <host>:<port> part is optional. When not specified, the transport
+      looks for a netsim .ini file, from which it will read the `grpc.backend.port`
+      property.
+      Options for this mode are:
+        name=<name>
+          The "chip" name, used to identify the "chip" instance. This
+          may be useful when several clients are connected, since each needs to use a
+          different name.
+
+    In `controller` mode:
+      The <host>:<port> part is required. <host> may be the address of a local network
+      interface, or '_' to accept connections on all local network interfaces.
+
+    Examples:
+    (empty string) --> connect to netsim on the port specified in the .ini file
+    localhost:8555 --> connect to netsim on localhost:8555
+    name=bumble1 --> connect to netsim, using `bumble1` as the "chip" name.
+    localhost:8555,name=bumble1 --> connect to netsim on localhost:8555, using
+    `bumble1` as the "chip" name.
+    _:8877,mode=controller --> accept connections as a controller on any interface
+    on port 8877.
+    '''
+
+    # Parse the parameters
+    params = spec.split(',') if spec else []
+    if params and ':' in params[0]:
+        # Explicit <host>:<port>
+        host, port = params[0].split(':')
+        params_offset = 1
+    else:
+        host = None
+        port = 0
+        params_offset = 0
+
+    options = {}
+    for param in params[params_offset:]:
+        if '=' not in param:
+            raise ValueError('invalid parameter, expected <name>=<value>')
+        option_name, option_value = param.split('=')
+        options[option_name] = option_value
+
+    mode = options.get('mode', 'host')
+    if mode == 'host':
+        return await open_android_netsim_host_transport(host, port, options)
+    if mode == 'controller':
+        if host is None:
+            raise ValueError('<host>:<port> missing')
+        return await open_android_netsim_controller_transport(host, port)
+
+    raise ValueError('invalid mode option')

bumble/transport/common.py

@@ -15,12 +15,17 @@
 # -----------------------------------------------------------------------------
 # Imports
 # -----------------------------------------------------------------------------
+from __future__ import annotations
+import contextlib
 import struct
 import asyncio
 import logging
+import io
+from typing import ContextManager, Tuple, Optional, Protocol, Dict
 
-from .. import hci
-from ..colors import color
+from bumble import hci
+from bumble.colors import color
+from bumble.snoop import Snooper
 
 
 # -----------------------------------------------------------------------------
@@ -32,7 +37,7 @@ logger = logging.getLogger(__name__)
 # Information needed to parse HCI packets with a generic parser:
 # For each packet type, the info represents:
 # (length-size, length-offset, unpack-type)
-HCI_PACKET_INFO = {
+HCI_PACKET_INFO: Dict[int, Tuple[int, int, str]] = {
     hci.HCI_COMMAND_PACKET: (1, 2, 'B'),
     hci.HCI_ACL_DATA_PACKET: (2, 2, 'H'),
     hci.HCI_SYNCHRONOUS_DATA_PACKET: (1, 2, 'B'),
@@ -41,33 +46,54 @@ HCI_PACKET_INFO = {
 
 
 # -----------------------------------------------------------------------------
-class PacketPump:
-    '''
-    Pump HCI packets from a reader to a sink
-    '''
+# Errors
+# -----------------------------------------------------------------------------
+class TransportLostError(Exception):
+    """
+    The Transport has been lost/disconnected.
+    """
 
-    def __init__(self, reader, sink):
+
+# -----------------------------------------------------------------------------
+# Typing Protocols
+# -----------------------------------------------------------------------------
+class TransportSink(Protocol):
+    def on_packet(self, packet: bytes) -> None:
+        ...
+
+
+class TransportSource(Protocol):
+    terminated: asyncio.Future[None]
+
+    def set_packet_sink(self, sink: TransportSink) -> None:
+        ...
+
+
+# -----------------------------------------------------------------------------
+class PacketPump:
+    """
+    Pump HCI packets from a reader to a sink.
+    """
+
+    def __init__(self, reader: AsyncPacketReader, sink: TransportSink) -> None:
         self.reader = reader
         self.sink = sink
 
-    async def run(self):
+    async def run(self) -> None:
         while True:
             try:
-                # Get a packet from the source
-                packet = hci.HCI_Packet.from_bytes(await self.reader.next_packet())
-
                 # Deliver the packet to the sink
-                self.sink.on_packet(packet)
+                self.sink.on_packet(await self.reader.next_packet())
             except Exception as error:
                 logger.warning(f'!!! {error}')
 
 
 # -----------------------------------------------------------------------------
 class PacketParser:
-    '''
+    """
     In-line parser that accepts data and emits 'on_packet' when a full packet has been
-    parsed
-    '''
+    parsed.
+    """
 
     # pylint: disable=attribute-defined-outside-init
 
@@ -75,18 +101,22 @@ class PacketParser:
     NEED_LENGTH = 1
     NEED_BODY = 2
 
-    def __init__(self, sink=None):
+    sink: Optional[TransportSink]
+    extended_packet_info: Dict[int, Tuple[int, int, str]]
+    packet_info: Optional[Tuple[int, int, str]] = None
+
+    def __init__(self, sink: Optional[TransportSink] = None) -> None:
         self.sink = sink
         self.extended_packet_info = {}
         self.reset()
 
-    def reset(self):
+    def reset(self) -> None:
         self.state = PacketParser.NEED_TYPE
         self.bytes_needed = 1
         self.packet = bytearray()
         self.packet_info = None
 
-    def feed_data(self, data):
+    def feed_data(self, data: bytes) -> None:
         data_offset = 0
         data_left = len(data)
         while data_left and self.bytes_needed:
@@ -107,6 +137,7 @@ class PacketParser:
                     self.state = PacketParser.NEED_LENGTH
                     self.bytes_needed = self.packet_info[0] + self.packet_info[1]
                 elif self.state == PacketParser.NEED_LENGTH:
+                    assert self.packet_info is not None
                     body_length = struct.unpack_from(
                         self.packet_info[2], self.packet, 1 + self.packet_info[1]
                     )[0]
@@ -124,20 +155,20 @@ class PacketParser:
                             )
                     self.reset()
 
-    def set_packet_sink(self, sink):
+    def set_packet_sink(self, sink: TransportSink) -> None:
         self.sink = sink
 
 
 # -----------------------------------------------------------------------------
 class PacketReader:
-    '''
-    Reader that reads HCI packets from a sync source
-    '''
+    """
+    Reader that reads HCI packets from a sync source.
+    """
 
-    def __init__(self, source):
+    def __init__(self, source: io.BufferedReader) -> None:
         self.source = source
 
-    def next_packet(self):
+    def next_packet(self) -> Optional[bytes]:
         # Get the packet type
         packet_type = self.source.read(1)
         if len(packet_type) != 1:
@@ -146,7 +177,7 @@ class PacketReader:
         # Get the packet info based on its type
         packet_info = HCI_PACKET_INFO.get(packet_type[0])
         if packet_info is None:
-            raise ValueError(f'invalid packet type {packet_type} found')
+            raise ValueError(f'invalid packet type {packet_type[0]} found')
 
         # Read the header (that includes the length)
         header_size = packet_info[0] + packet_info[1]
@@ -165,21 +196,21 @@ class PacketReader:
 
 # -----------------------------------------------------------------------------
 class AsyncPacketReader:
-    '''
-    Reader that reads HCI packets from an async source
-    '''
+    """
+    Reader that reads HCI packets from an async source.
+    """
 
-    def __init__(self, source):
+    def __init__(self, source: asyncio.StreamReader) -> None:
         self.source = source
 
-    async def next_packet(self):
+    async def next_packet(self) -> bytes:
         # Get the packet type
         packet_type = await self.source.readexactly(1)
 
         # Get the packet info based on its type
         packet_info = HCI_PACKET_INFO.get(packet_type[0])
         if packet_info is None:
-            raise ValueError(f'invalid packet type {packet_type} found')
+            raise ValueError(f'invalid packet type {packet_type[0]} found')
 
         # Read the header (that includes the length)
         header_size = packet_info[0] + packet_info[1]
@@ -194,15 +225,15 @@ class AsyncPacketReader:
 
 # -----------------------------------------------------------------------------
 class AsyncPipeSink:
-    '''
-    Sink that forwards packets asynchronously to another sink
-    '''
+    """
+    Sink that forwards packets asynchronously to another sink.
+    """
 
-    def __init__(self, sink):
+    def __init__(self, sink: TransportSink) -> None:
         self.sink = sink
         self.loop = asyncio.get_running_loop()
 
-    def on_packet(self, packet):
+    def on_packet(self, packet: bytes) -> None:
         self.loop.call_soon(self.sink.on_packet, packet)
 
 
@@ -212,41 +243,68 @@ class ParserSource:
     Base class designed to be subclassed by transport-specific source classes
     """
 
-    def __init__(self):
+    terminated: asyncio.Future[None]
+    parser: PacketParser
+
+    def __init__(self) -> None:
         self.parser = PacketParser()
         self.terminated = asyncio.get_running_loop().create_future()
 
-    def set_packet_sink(self, sink):
+    def set_packet_sink(self, sink: TransportSink) -> None:
         self.parser.set_packet_sink(sink)
 
-    async def wait_for_termination(self):
+    def on_transport_lost(self) -> None:
+        self.terminated.set_result(None)
+        if self.parser.sink:
+            if hasattr(self.parser.sink, 'on_transport_lost'):
+                self.parser.sink.on_transport_lost()
+
+    async def wait_for_termination(self) -> None:
+        """
+        Convenience method for backward compatibility. Prefer using the `terminated`
+        attribute instead.
+        """
         return await self.terminated
 
-    def close(self):
+    def close(self) -> None:
         pass
 
 
 # -----------------------------------------------------------------------------
 class StreamPacketSource(asyncio.Protocol, ParserSource):
-    def data_received(self, data):
+    def data_received(self, data: bytes) -> None:
         self.parser.feed_data(data)
 
 
 # -----------------------------------------------------------------------------
 class StreamPacketSink:
-    def __init__(self, transport):
+    def __init__(self, transport: asyncio.WriteTransport) -> None:
         self.transport = transport
 
-    def on_packet(self, packet):
+    def on_packet(self, packet: bytes) -> None:
         self.transport.write(packet)
 
-    def close(self):
+    def close(self) -> None:
         self.transport.close()
 
 
 # -----------------------------------------------------------------------------
 class Transport:
-    def __init__(self, source, sink):
+    """
+    Base class for all transports.
+
+    A Transport represents a source and a sink together.
+    An instance must be closed by calling close() when no longer used. Instances
+    implement the ContextManager protocol so that they may be used in a `async with`
+    statement.
+    An instance is iterable. The iterator yields, in order, its source and sink, so
+    that it may be used with a convenient call syntax like:
+
+    async with create_transport() as (source, sink):
+        ...
+    """
+
+    def __init__(self, source: TransportSource, sink: TransportSink) -> None:
         self.source = source
         self.sink = sink
 
@@ -260,19 +318,23 @@ class Transport:
         return iter((self.source, self.sink))
 
     async def close(self) -> None:
-        self.source.close()
-        self.sink.close()
+        if hasattr(self.source, 'close'):
+            self.source.close()
+        if hasattr(self.sink, 'close'):
+            self.sink.close()
 
 
 # -----------------------------------------------------------------------------
 class PumpedPacketSource(ParserSource):
-    def __init__(self, receive):
+    pump_task: Optional[asyncio.Task[None]]
+
+    def __init__(self, receive) -> None:
         super().__init__()
         self.receive_function = receive
         self.pump_task = None
 
-    def start(self):
-        async def pump_packets():
+    def start(self) -> None:
+        async def pump_packets() -> None:
             while True:
                 try:
                     packet = await self.receive_function()
@@ -282,12 +344,12 @@ class PumpedPacketSource(ParserSource):
                     break
                 except Exception as error:
                     logger.warning(f'exception while waiting for packet: {error}')
-                    self.terminated.set_result(error)
+                    self.terminated.set_exception(error)
                     break
 
         self.pump_task = asyncio.create_task(pump_packets())
 
-    def close(self):
+    def close(self) -> None:
         if self.pump_task:
             self.pump_task.cancel()
 
@@ -299,7 +361,7 @@ class PumpedPacketSink:
         self.packet_queue = asyncio.Queue()
         self.pump_task = None
 
-    def on_packet(self, packet):
+    def on_packet(self, packet: bytes) -> None:
         self.packet_queue.put_nowait(packet)
 
     def start(self):
@@ -324,14 +386,86 @@ class PumpedPacketSink:
 
 # -----------------------------------------------------------------------------
 class PumpedTransport(Transport):
-    def __init__(self, source, sink, close_function):
+    source: PumpedPacketSource
+    sink: PumpedPacketSink
+
+    def __init__(
+        self,
+        source: PumpedPacketSource,
+        sink: PumpedPacketSink,
+        close_function,
+    ) -> None:
         super().__init__(source, sink)
         self.close_function = close_function
 
-    def start(self):
+    def start(self) -> None:
         self.source.start()
         self.sink.start()
 
-    async def close(self):
+    async def close(self) -> None:
         await super().close()
         await self.close_function()
+
+
+# -----------------------------------------------------------------------------
+class SnoopingTransport(Transport):
+    """Transport wrapper that snoops on packets to/from a wrapped transport."""
+
+    @staticmethod
+    def create_with(
+        transport: Transport, snooper: ContextManager[Snooper]
+    ) -> SnoopingTransport:
+        """
+        Create an instance given a snooper that works as as context manager.
+
+        The returned instance will exit the snooper context when it is closed.
+        """
+        with contextlib.ExitStack() as exit_stack:
+            return SnoopingTransport(
+                transport, exit_stack.enter_context(snooper), exit_stack.pop_all().close
+            )
+        raise RuntimeError('unexpected code path')  # Satisfy the type checker
+
+    class Source:
+        sink: TransportSink
+
+        def __init__(self, source: TransportSource, snooper: Snooper):
+            self.source = source
+            self.snooper = snooper
+            self.terminated = source.terminated
+
+        def set_packet_sink(self, sink: TransportSink) -> None:
+            self.sink = sink
+            self.source.set_packet_sink(self)
+
+        def on_packet(self, packet: bytes) -> None:
+            self.snooper.snoop(packet, Snooper.Direction.CONTROLLER_TO_HOST)
+            if self.sink:
+                self.sink.on_packet(packet)
+
+    class Sink:
+        def __init__(self, sink: TransportSink, snooper: Snooper) -> None:
+            self.sink = sink
+            self.snooper = snooper
+
+        def on_packet(self, packet: bytes) -> None:
+            self.snooper.snoop(packet, Snooper.Direction.HOST_TO_CONTROLLER)
+            if self.sink:
+                self.sink.on_packet(packet)
+
+    def __init__(
+        self,
+        transport: Transport,
+        snooper: Snooper,
+        close_snooper=None,
+    ) -> None:
+        super().__init__(
+            self.Source(transport.source, snooper), self.Sink(transport.sink, snooper)
+        )
+        self.transport = transport
+        self.close_snooper = close_snooper
+
+    async def close(self):
+        await self.transport.close()
+        if self.close_snooper:
+            self.close_snooper()

bumble/transport/emulated_bluetooth_packets_pb2.py

@@ -1,45 +0,0 @@
-# Copyright 2021-2023 Google LLC
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#      https://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-
-# -*- coding: utf-8 -*-
-# Generated by the protocol buffer compiler.  DO NOT EDIT!
-# source: emulated_bluetooth_packets.proto
-"""Generated protocol buffer code."""
-from google.protobuf.internal import builder as _builder
-from google.protobuf import descriptor as _descriptor
-from google.protobuf import descriptor_pool as _descriptor_pool
-from google.protobuf import symbol_database as _symbol_database
-
-# @@protoc_insertion_point(imports)
-
-_sym_db = _symbol_database.Default()
-
-
-DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(
-    b'\n emulated_bluetooth_packets.proto\x12\x1b\x61ndroid.emulation.bluetooth\"\xfb\x01\n\tHCIPacket\x12?\n\x04type\x18\x01 \x01(\x0e\x32\x31.android.emulation.bluetooth.HCIPacket.PacketType\x12\x0e\n\x06packet\x18\x02 \x01(\x0c\"\x9c\x01\n\nPacketType\x12\x1b\n\x17PACKET_TYPE_UNSPECIFIED\x10\x00\x12\x1b\n\x17PACKET_TYPE_HCI_COMMAND\x10\x01\x12\x13\n\x0fPACKET_TYPE_ACL\x10\x02\x12\x13\n\x0fPACKET_TYPE_SCO\x10\x03\x12\x15\n\x11PACKET_TYPE_EVENT\x10\x04\x12\x13\n\x0fPACKET_TYPE_ISO\x10\x05\x42J\n\x1f\x63om.android.emulation.bluetoothP\x01\xf8\x01\x01\xa2\x02\x03\x41\x45\x42\xaa\x02\x1b\x41ndroid.Emulation.Bluetoothb\x06proto3'
-)
-
-_builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, globals())
-_builder.BuildTopDescriptorsAndMessages(
-    DESCRIPTOR, 'emulated_bluetooth_packets_pb2', globals()
-)
-if _descriptor._USE_C_DESCRIPTORS == False:
-
-    DESCRIPTOR._options = None
-    DESCRIPTOR._serialized_options = b'\n\037com.android.emulation.bluetoothP\001\370\001\001\242\002\003AEB\252\002\033Android.Emulation.Bluetooth'
-    _HCIPACKET._serialized_start = 66
-    _HCIPACKET._serialized_end = 317
-    _HCIPACKET_PACKETTYPE._serialized_start = 161
-    _HCIPACKET_PACKETTYPE._serialized_end = 317
-# @@protoc_insertion_point(module_scope)

bumble/transport/emulated_bluetooth_pb2.py

@@ -1,46 +0,0 @@
-# Copyright 2021-2023 Google LLC
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#      https://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-
-# -*- coding: utf-8 -*-
-# Generated by the protocol buffer compiler.  DO NOT EDIT!
-# source: emulated_bluetooth.proto
-"""Generated protocol buffer code."""
-from google.protobuf.internal import builder as _builder
-from google.protobuf import descriptor as _descriptor
-from google.protobuf import descriptor_pool as _descriptor_pool
-from google.protobuf import symbol_database as _symbol_database
-
-# @@protoc_insertion_point(imports)
-
-_sym_db = _symbol_database.Default()
-
-
-from . import emulated_bluetooth_packets_pb2 as emulated__bluetooth__packets__pb2
-
-
-DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(
-    b'\n\x18\x65mulated_bluetooth.proto\x12\x1b\x61ndroid.emulation.bluetooth\x1a emulated_bluetooth_packets.proto\"\x19\n\x07RawData\x12\x0e\n\x06packet\x18\x01 \x01(\x0c\x32\xcb\x02\n\x18\x45mulatedBluetoothService\x12\x64\n\x12registerClassicPhy\x12$.android.emulation.bluetooth.RawData\x1a$.android.emulation.bluetooth.RawData(\x01\x30\x01\x12`\n\x0eregisterBlePhy\x12$.android.emulation.bluetooth.RawData\x1a$.android.emulation.bluetooth.RawData(\x01\x30\x01\x12g\n\x11registerHCIDevice\x12&.android.emulation.bluetooth.HCIPacket\x1a&.android.emulation.bluetooth.HCIPacket(\x01\x30\x01\x42\"\n\x1e\x63om.android.emulator.bluetoothP\x01\x62\x06proto3'
-)
-
-_builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, globals())
-_builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, 'emulated_bluetooth_pb2', globals())
-if _descriptor._USE_C_DESCRIPTORS == False:
-
-    DESCRIPTOR._options = None
-    DESCRIPTOR._serialized_options = b'\n\036com.android.emulator.bluetoothP\001'
-    _RAWDATA._serialized_start = 91
-    _RAWDATA._serialized_end = 116
-    _EMULATEDBLUETOOTHSERVICE._serialized_start = 119
-    _EMULATEDBLUETOOTHSERVICE._serialized_end = 450
-# @@protoc_insertion_point(module_scope)

bumble/transport/emulated_bluetooth_pb2.pyi

@@ -1,26 +0,0 @@
-# Copyright 2021-2023 Google LLC
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#      https://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-
-import emulated_bluetooth_packets_pb2 as _emulated_bluetooth_packets_pb2
-from google.protobuf import descriptor as _descriptor
-from google.protobuf import message as _message
-from typing import ClassVar as _ClassVar, Optional as _Optional
-
-DESCRIPTOR: _descriptor.FileDescriptor
-
-class RawData(_message.Message):
-    __slots__ = ["packet"]
-    PACKET_FIELD_NUMBER: _ClassVar[int]
-    packet: bytes
-    def __init__(self, packet: _Optional[bytes] = ...) -> None: ...

bumble/transport/emulated_bluetooth_pb2_grpc.py

@@ -1,244 +0,0 @@
-# Copyright 2021-2023 Google LLC
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#      https://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-
-# Generated by the gRPC Python protocol compiler plugin. DO NOT EDIT!
-"""Client and server classes corresponding to protobuf-defined services."""
-import grpc
-
-from . import emulated_bluetooth_packets_pb2 as emulated__bluetooth__packets__pb2
-from . import emulated_bluetooth_pb2 as emulated__bluetooth__pb2
-
-
-class EmulatedBluetoothServiceStub(object):
-    """An Emulated Bluetooth Service exposes the emulated bluetooth chip from the
-    android emulator. It allows you to register emulated bluetooth devices and
-    control the packets that are exchanged between the device and the world.
-
-    This service enables you to establish a "virtual network" of emulated
-    bluetooth devices that can interact with each other.
-
-    Note: This is not yet finalized, it is likely that these definitions will
-    evolve.
-    """
-
-    def __init__(self, channel):
-        """Constructor.
-
-        Args:
-            channel: A grpc.Channel.
-        """
-        self.registerClassicPhy = channel.stream_stream(
-            '/android.emulation.bluetooth.EmulatedBluetoothService/registerClassicPhy',
-            request_serializer=emulated__bluetooth__pb2.RawData.SerializeToString,
-            response_deserializer=emulated__bluetooth__pb2.RawData.FromString,
-        )
-        self.registerBlePhy = channel.stream_stream(
-            '/android.emulation.bluetooth.EmulatedBluetoothService/registerBlePhy',
-            request_serializer=emulated__bluetooth__pb2.RawData.SerializeToString,
-            response_deserializer=emulated__bluetooth__pb2.RawData.FromString,
-        )
-        self.registerHCIDevice = channel.stream_stream(
-            '/android.emulation.bluetooth.EmulatedBluetoothService/registerHCIDevice',
-            request_serializer=emulated__bluetooth__packets__pb2.HCIPacket.SerializeToString,
-            response_deserializer=emulated__bluetooth__packets__pb2.HCIPacket.FromString,
-        )
-
-
-class EmulatedBluetoothServiceServicer(object):
-    """An Emulated Bluetooth Service exposes the emulated bluetooth chip from the
-    android emulator. It allows you to register emulated bluetooth devices and
-    control the packets that are exchanged between the device and the world.
-
-    This service enables you to establish a "virtual network" of emulated
-    bluetooth devices that can interact with each other.
-
-    Note: This is not yet finalized, it is likely that these definitions will
-    evolve.
-    """
-
-    def registerClassicPhy(self, request_iterator, context):
-        """Connect device to link layer. This will establish a direct connection
-        to the emulated bluetooth chip and configure the following:
-
-        - Each connection creates a new device and attaches it to the link layer
-        - Link Layer packets are transmitted directly to the phy
-
-        This should be used for classic connections.
-
-        This is used to directly connect various android emulators together.
-        For example a wear device can connect to an android emulator through
-        this.
-        """
-        context.set_code(grpc.StatusCode.UNIMPLEMENTED)
-        context.set_details('Method not implemented!')
-        raise NotImplementedError('Method not implemented!')
-
-    def registerBlePhy(self, request_iterator, context):
-        """Connect device to link layer. This will establish a direct connection
-        to root canal and execute the following:
-
-        - Each connection creates a new device and attaches it to the link layer
-        - Link Layer packets are transmitted directly to the phy
-
-        This should be used for BLE connections.
-
-        This is used to directly connect various android emulators together.
-        For example a wear device can connect to an android emulator through
-        this.
-        """
-        context.set_code(grpc.StatusCode.UNIMPLEMENTED)
-        context.set_details('Method not implemented!')
-        raise NotImplementedError('Method not implemented!')
-
-    def registerHCIDevice(self, request_iterator, context):
-        """Connect the device to the emulated bluetooth chip. The device will
-        participate in the network. You can configure the chip to scan, advertise
-        and setup connections with other devices that are connected to the
-        network.
-
-        This is usually used when you have a need for an emulated bluetooth chip
-        and have a bluetooth stack that can interpret and handle the packets
-        correctly.
-
-        For example the apache nimble stack can use this endpoint as the
-        transport layer.
-        """
-        context.set_code(grpc.StatusCode.UNIMPLEMENTED)
-        context.set_details('Method not implemented!')
-        raise NotImplementedError('Method not implemented!')
-
-
-def add_EmulatedBluetoothServiceServicer_to_server(servicer, server):
-    rpc_method_handlers = {
-        'registerClassicPhy': grpc.stream_stream_rpc_method_handler(
-            servicer.registerClassicPhy,
-            request_deserializer=emulated__bluetooth__pb2.RawData.FromString,
-            response_serializer=emulated__bluetooth__pb2.RawData.SerializeToString,
-        ),
-        'registerBlePhy': grpc.stream_stream_rpc_method_handler(
-            servicer.registerBlePhy,
-            request_deserializer=emulated__bluetooth__pb2.RawData.FromString,
-            response_serializer=emulated__bluetooth__pb2.RawData.SerializeToString,
-        ),
-        'registerHCIDevice': grpc.stream_stream_rpc_method_handler(
-            servicer.registerHCIDevice,
-            request_deserializer=emulated__bluetooth__packets__pb2.HCIPacket.FromString,
-            response_serializer=emulated__bluetooth__packets__pb2.HCIPacket.SerializeToString,
-        ),
-    }
-    generic_handler = grpc.method_handlers_generic_handler(
-        'android.emulation.bluetooth.EmulatedBluetoothService', rpc_method_handlers
-    )
-    server.add_generic_rpc_handlers((generic_handler,))
-
-
-# This class is part of an EXPERIMENTAL API.
-class EmulatedBluetoothService(object):
-    """An Emulated Bluetooth Service exposes the emulated bluetooth chip from the
-    android emulator. It allows you to register emulated bluetooth devices and
-    control the packets that are exchanged between the device and the world.
-
-    This service enables you to establish a "virtual network" of emulated
-    bluetooth devices that can interact with each other.
-
-    Note: This is not yet finalized, it is likely that these definitions will
-    evolve.
-    """
-
-    @staticmethod
-    def registerClassicPhy(
-        request_iterator,
-        target,
-        options=(),
-        channel_credentials=None,
-        call_credentials=None,
-        insecure=False,
-        compression=None,
-        wait_for_ready=None,
-        timeout=None,
-        metadata=None,
-    ):
-        return grpc.experimental.stream_stream(
-            request_iterator,
-            target,
-            '/android.emulation.bluetooth.EmulatedBluetoothService/registerClassicPhy',
-            emulated__bluetooth__pb2.RawData.SerializeToString,
-            emulated__bluetooth__pb2.RawData.FromString,
-            options,
-            channel_credentials,
-            insecure,
-            call_credentials,
-            compression,
-            wait_for_ready,
-            timeout,
-            metadata,
-        )
-
-    @staticmethod
-    def registerBlePhy(
-        request_iterator,
-        target,
-        options=(),
-        channel_credentials=None,
-        call_credentials=None,
-        insecure=False,
-        compression=None,
-        wait_for_ready=None,
-        timeout=None,
-        metadata=None,
-    ):
-        return grpc.experimental.stream_stream(
-            request_iterator,
-            target,
-            '/android.emulation.bluetooth.EmulatedBluetoothService/registerBlePhy',
-            emulated__bluetooth__pb2.RawData.SerializeToString,
-            emulated__bluetooth__pb2.RawData.FromString,
-            options,
-            channel_credentials,
-            insecure,
-            call_credentials,
-            compression,
-            wait_for_ready,
-            timeout,
-            metadata,
-        )
-
-    @staticmethod
-    def registerHCIDevice(
-        request_iterator,
-        target,
-        options=(),
-        channel_credentials=None,
-        call_credentials=None,
-        insecure=False,
-        compression=None,
-        wait_for_ready=None,
-        timeout=None,
-        metadata=None,
-    ):
-        return grpc.experimental.stream_stream(
-            request_iterator,
-            target,
-            '/android.emulation.bluetooth.EmulatedBluetoothService/registerHCIDevice',
-            emulated__bluetooth__packets__pb2.HCIPacket.SerializeToString,
-            emulated__bluetooth__packets__pb2.HCIPacket.FromString,
-            options,
-            channel_credentials,
-            insecure,
-            call_credentials,
-            compression,
-            wait_for_ready,
-            timeout,
-            metadata,
-        )

bumble/transport/emulated_bluetooth_vhci_pb2.py

@@ -1,46 +0,0 @@
-# Copyright 2021-2023 Google LLC
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#      https://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-
-# -*- coding: utf-8 -*-
-# Generated by the protocol buffer compiler.  DO NOT EDIT!
-# source: emulated_bluetooth_vhci.proto
-"""Generated protocol buffer code."""
-from google.protobuf.internal import builder as _builder
-from google.protobuf import descriptor as _descriptor
-from google.protobuf import descriptor_pool as _descriptor_pool
-from google.protobuf import symbol_database as _symbol_database
-
-# @@protoc_insertion_point(imports)
-
-_sym_db = _symbol_database.Default()
-
-
-from . import emulated_bluetooth_packets_pb2 as emulated__bluetooth__packets__pb2
-
-
-DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(
-    b'\n\x1d\x65mulated_bluetooth_vhci.proto\x12\x1b\x61ndroid.emulation.bluetooth\x1a emulated_bluetooth_packets.proto2y\n\x15VhciForwardingService\x12`\n\nattachVhci\x12&.android.emulation.bluetooth.HCIPacket\x1a&.android.emulation.bluetooth.HCIPacket(\x01\x30\x01\x42J\n\x1f\x63om.android.emulation.bluetoothP\x01\xf8\x01\x01\xa2\x02\x03\x41\x45\x42\xaa\x02\x1b\x41ndroid.Emulation.Bluetoothb\x06proto3'
-)
-
-_builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, globals())
-_builder.BuildTopDescriptorsAndMessages(
-    DESCRIPTOR, 'emulated_bluetooth_vhci_pb2', globals()
-)
-if _descriptor._USE_C_DESCRIPTORS == False:
-
-    DESCRIPTOR._options = None
-    DESCRIPTOR._serialized_options = b'\n\037com.android.emulation.bluetoothP\001\370\001\001\242\002\003AEB\252\002\033Android.Emulation.Bluetooth'
-    _VHCIFORWARDINGSERVICE._serialized_start = 96
-    _VHCIFORWARDINGSERVICE._serialized_end = 217
-# @@protoc_insertion_point(module_scope)

bumble/transport/emulated_bluetooth_vhci_pb2.pyi

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

bumble/transport/file.py

@@ -28,7 +28,7 @@ logger = logging.getLogger(__name__)
 
 
 # -----------------------------------------------------------------------------
-async def open_file_transport(spec):
+async def open_file_transport(spec: str) -> Transport:
     '''
     Open a File transport (typically not for a real file, but for a PTY or other unix
     virtual files).

bumble/transport/grpc_protobuf/common_pb2.py

@@ -0,0 +1,25 @@
+# -*- coding: utf-8 -*-
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# source: common.proto
+"""Generated protocol buffer code."""
+from google.protobuf.internal import builder as _builder
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import descriptor_pool as _descriptor_pool
+from google.protobuf import symbol_database as _symbol_database
+# @@protoc_insertion_point(imports)
+
+_sym_db = _symbol_database.Default()
+
+
+
+
+DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n\x0c\x63ommon.proto\x12\rnetsim.common*=\n\x08\x43hipKind\x12\x0f\n\x0bUNSPECIFIED\x10\x00\x12\r\n\tBLUETOOTH\x10\x01\x12\x08\n\x04WIFI\x10\x02\x12\x07\n\x03UWB\x10\x03\x62\x06proto3')
+
+_builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, globals())
+_builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, 'common_pb2', globals())
+if _descriptor._USE_C_DESCRIPTORS == False:
+
+  DESCRIPTOR._options = None
+  _CHIPKIND._serialized_start=31
+  _CHIPKIND._serialized_end=92
+# @@protoc_insertion_point(module_scope)

bumble/transport/grpc_protobuf/common_pb2.pyi

@@ -0,0 +1,12 @@
+from google.protobuf.internal import enum_type_wrapper as _enum_type_wrapper
+from google.protobuf import descriptor as _descriptor
+from typing import ClassVar as _ClassVar
+
+BLUETOOTH: ChipKind
+DESCRIPTOR: _descriptor.FileDescriptor
+UNSPECIFIED: ChipKind
+UWB: ChipKind
+WIFI: ChipKind
+
+class ChipKind(int, metaclass=_enum_type_wrapper.EnumTypeWrapper):
+    __slots__ = []

bumble/transport/grpc_protobuf/common_pb2_grpc.py

@@ -0,0 +1,4 @@
+# Generated by the gRPC Python protocol compiler plugin. DO NOT EDIT!
+"""Client and server classes corresponding to protobuf-defined services."""
+import grpc
+

bumble/transport/grpc_protobuf/emulated_bluetooth_device_pb2.pyi

@@ -0,0 +1,158 @@
+from . import grpc_endpoint_description_pb2 as _grpc_endpoint_description_pb2
+from google.protobuf import empty_pb2 as _empty_pb2
+from google.protobuf.internal import containers as _containers
+from google.protobuf.internal import enum_type_wrapper as _enum_type_wrapper
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import message as _message
+from typing import ClassVar as _ClassVar, Iterable as _Iterable, Mapping as _Mapping, Optional as _Optional, Union as _Union
+
+DESCRIPTOR: _descriptor.FileDescriptor
+
+class Advertisement(_message.Message):
+    __slots__ = ["connection_mode", "device_name", "discovery_mode"]
+    class ConnectionMode(int, metaclass=_enum_type_wrapper.EnumTypeWrapper):
+        __slots__ = []
+    class DiscoveryMode(int, metaclass=_enum_type_wrapper.EnumTypeWrapper):
+        __slots__ = []
+    CONNECTION_MODE_DIRECTED: Advertisement.ConnectionMode
+    CONNECTION_MODE_FIELD_NUMBER: _ClassVar[int]
+    CONNECTION_MODE_NON_CONNECTABLE: Advertisement.ConnectionMode
+    CONNECTION_MODE_UNDIRECTED: Advertisement.ConnectionMode
+    CONNECTION_MODE_UNSPECIFIED: Advertisement.ConnectionMode
+    DEVICE_NAME_FIELD_NUMBER: _ClassVar[int]
+    DISCOVERY_MODE_FIELD_NUMBER: _ClassVar[int]
+    DISCOVERY_MODE_GENERAL: Advertisement.DiscoveryMode
+    DISCOVERY_MODE_LIMITED: Advertisement.DiscoveryMode
+    DISCOVERY_MODE_NON_DISCOVERABLE: Advertisement.DiscoveryMode
+    DISCOVERY_MODE_UNSPECIFIED: Advertisement.DiscoveryMode
+    connection_mode: Advertisement.ConnectionMode
+    device_name: str
+    discovery_mode: Advertisement.DiscoveryMode
+    def __init__(self, device_name: _Optional[str] = ..., connection_mode: _Optional[_Union[Advertisement.ConnectionMode, str]] = ..., discovery_mode: _Optional[_Union[Advertisement.DiscoveryMode, str]] = ...) -> None: ...
+
+class CallbackIdentifier(_message.Message):
+    __slots__ = ["identity"]
+    IDENTITY_FIELD_NUMBER: _ClassVar[int]
+    identity: str
+    def __init__(self, identity: _Optional[str] = ...) -> None: ...
+
+class CharacteristicValueRequest(_message.Message):
+    __slots__ = ["callback_device_id", "callback_id", "data", "from_device"]
+    CALLBACK_DEVICE_ID_FIELD_NUMBER: _ClassVar[int]
+    CALLBACK_ID_FIELD_NUMBER: _ClassVar[int]
+    DATA_FIELD_NUMBER: _ClassVar[int]
+    FROM_DEVICE_FIELD_NUMBER: _ClassVar[int]
+    callback_device_id: CallbackIdentifier
+    callback_id: Uuid
+    data: bytes
+    from_device: DeviceIdentifier
+    def __init__(self, callback_device_id: _Optional[_Union[CallbackIdentifier, _Mapping]] = ..., from_device: _Optional[_Union[DeviceIdentifier, _Mapping]] = ..., callback_id: _Optional[_Union[Uuid, _Mapping]] = ..., data: _Optional[bytes] = ...) -> None: ...
+
+class CharacteristicValueResponse(_message.Message):
+    __slots__ = ["data", "status"]
+    class GattStatus(int, metaclass=_enum_type_wrapper.EnumTypeWrapper):
+        __slots__ = []
+    DATA_FIELD_NUMBER: _ClassVar[int]
+    GATT_STATUS_FAILURE: CharacteristicValueResponse.GattStatus
+    GATT_STATUS_SUCCESS: CharacteristicValueResponse.GattStatus
+    GATT_STATUS_UNSPECIFIED: CharacteristicValueResponse.GattStatus
+    STATUS_FIELD_NUMBER: _ClassVar[int]
+    data: bytes
+    status: CharacteristicValueResponse.GattStatus
+    def __init__(self, status: _Optional[_Union[CharacteristicValueResponse.GattStatus, str]] = ..., data: _Optional[bytes] = ...) -> None: ...
+
+class ConnectionStateChange(_message.Message):
+    __slots__ = ["callback_device_id", "from_device", "new_state"]
+    class ConnectionState(int, metaclass=_enum_type_wrapper.EnumTypeWrapper):
+        __slots__ = []
+    CALLBACK_DEVICE_ID_FIELD_NUMBER: _ClassVar[int]
+    CONNECTION_STATE_CONNECTED: ConnectionStateChange.ConnectionState
+    CONNECTION_STATE_DISCONNECTED: ConnectionStateChange.ConnectionState
+    CONNECTION_STATE_UNDEFINED: ConnectionStateChange.ConnectionState
+    FROM_DEVICE_FIELD_NUMBER: _ClassVar[int]
+    NEW_STATE_FIELD_NUMBER: _ClassVar[int]
+    callback_device_id: CallbackIdentifier
+    from_device: DeviceIdentifier
+    new_state: ConnectionStateChange.ConnectionState
+    def __init__(self, callback_device_id: _Optional[_Union[CallbackIdentifier, _Mapping]] = ..., from_device: _Optional[_Union[DeviceIdentifier, _Mapping]] = ..., new_state: _Optional[_Union[ConnectionStateChange.ConnectionState, str]] = ...) -> None: ...
+
+class DeviceIdentifier(_message.Message):
+    __slots__ = ["address"]
+    ADDRESS_FIELD_NUMBER: _ClassVar[int]
+    address: str
+    def __init__(self, address: _Optional[str] = ...) -> None: ...
+
+class GattCharacteristic(_message.Message):
+    __slots__ = ["callback_id", "permissions", "properties", "uuid"]
+    class Permissions(int, metaclass=_enum_type_wrapper.EnumTypeWrapper):
+        __slots__ = []
+    class Properties(int, metaclass=_enum_type_wrapper.EnumTypeWrapper):
+        __slots__ = []
+    CALLBACK_ID_FIELD_NUMBER: _ClassVar[int]
+    PERMISSIONS_FIELD_NUMBER: _ClassVar[int]
+    PERMISSION_READ: GattCharacteristic.Permissions
+    PERMISSION_READ_ENCRYPTED: GattCharacteristic.Permissions
+    PERMISSION_READ_ENCRYPTED_MITM: GattCharacteristic.Permissions
+    PERMISSION_UNSPECIFIED: GattCharacteristic.Permissions
+    PERMISSION_WRITE: GattCharacteristic.Permissions
+    PERMISSION_WRITE_ENCRYPTED: GattCharacteristic.Permissions
+    PERMISSION_WRITE_ENCRYPTED_MITM: GattCharacteristic.Permissions
+    PERMISSION_WRITE_SIGNED: GattCharacteristic.Permissions
+    PERMISSION_WRITE_SIGNED_MITM: GattCharacteristic.Permissions
+    PROPERTIES_FIELD_NUMBER: _ClassVar[int]
+    PROPERTY_BROADCAST: GattCharacteristic.Properties
+    PROPERTY_EXTENDED_PROPS: GattCharacteristic.Properties
+    PROPERTY_INDICATE: GattCharacteristic.Properties
+    PROPERTY_NOTIFY: GattCharacteristic.Properties
+    PROPERTY_READ: GattCharacteristic.Properties
+    PROPERTY_SIGNED_WRITE: GattCharacteristic.Properties
+    PROPERTY_UNSPECIFIED: GattCharacteristic.Properties
+    PROPERTY_WRITE: GattCharacteristic.Properties
+    PROPERTY_WRITE_NO_RESPONSE: GattCharacteristic.Properties
+    UUID_FIELD_NUMBER: _ClassVar[int]
+    callback_id: Uuid
+    permissions: int
+    properties: int
+    uuid: Uuid
+    def __init__(self, uuid: _Optional[_Union[Uuid, _Mapping]] = ..., properties: _Optional[int] = ..., permissions: _Optional[int] = ..., callback_id: _Optional[_Union[Uuid, _Mapping]] = ...) -> None: ...
+
+class GattDevice(_message.Message):
+    __slots__ = ["advertisement", "endpoint", "profile"]
+    ADVERTISEMENT_FIELD_NUMBER: _ClassVar[int]
+    ENDPOINT_FIELD_NUMBER: _ClassVar[int]
+    PROFILE_FIELD_NUMBER: _ClassVar[int]
+    advertisement: Advertisement
+    endpoint: _grpc_endpoint_description_pb2.Endpoint
+    profile: GattProfile
+    def __init__(self, endpoint: _Optional[_Union[_grpc_endpoint_description_pb2.Endpoint, _Mapping]] = ..., advertisement: _Optional[_Union[Advertisement, _Mapping]] = ..., profile: _Optional[_Union[GattProfile, _Mapping]] = ...) -> None: ...
+
+class GattProfile(_message.Message):
+    __slots__ = ["services"]
+    SERVICES_FIELD_NUMBER: _ClassVar[int]
+    services: _containers.RepeatedCompositeFieldContainer[GattService]
+    def __init__(self, services: _Optional[_Iterable[_Union[GattService, _Mapping]]] = ...) -> None: ...
+
+class GattService(_message.Message):
+    __slots__ = ["characteristics", "service_type", "uuid"]
+    class ServiceType(int, metaclass=_enum_type_wrapper.EnumTypeWrapper):
+        __slots__ = []
+    CHARACTERISTICS_FIELD_NUMBER: _ClassVar[int]
+    SERVICE_TYPE_FIELD_NUMBER: _ClassVar[int]
+    SERVICE_TYPE_PRIMARY: GattService.ServiceType
+    SERVICE_TYPE_SECONDARY: GattService.ServiceType
+    SERVICE_TYPE_UNSPECIFIED: GattService.ServiceType
+    UUID_FIELD_NUMBER: _ClassVar[int]
+    characteristics: _containers.RepeatedCompositeFieldContainer[GattCharacteristic]
+    service_type: GattService.ServiceType
+    uuid: Uuid
+    def __init__(self, uuid: _Optional[_Union[Uuid, _Mapping]] = ..., service_type: _Optional[_Union[GattService.ServiceType, str]] = ..., characteristics: _Optional[_Iterable[_Union[GattCharacteristic, _Mapping]]] = ...) -> None: ...
+
+class Uuid(_message.Message):
+    __slots__ = ["id", "lsb", "msb"]
+    ID_FIELD_NUMBER: _ClassVar[int]
+    LSB_FIELD_NUMBER: _ClassVar[int]
+    MSB_FIELD_NUMBER: _ClassVar[int]
+    id: int
+    lsb: int
+    msb: int
+    def __init__(self, id: _Optional[int] = ..., lsb: _Optional[int] = ..., msb: _Optional[int] = ...) -> None: ...

bumble/transport/grpc_protobuf/emulated_bluetooth_device_pb2_grpc.py

@@ -0,0 +1,193 @@
+# Generated by the gRPC Python protocol compiler plugin. DO NOT EDIT!
+"""Client and server classes corresponding to protobuf-defined services."""
+import grpc
+
+from . import emulated_bluetooth_device_pb2 as emulated__bluetooth__device__pb2
+from google.protobuf import empty_pb2 as google_dot_protobuf_dot_empty__pb2
+
+
+class GattDeviceServiceStub(object):
+    """You can provide your own GattDevice by implementing this service
+    and registering it with the android emulator.
+
+    The device will appear as a real bluetooth device, and you will
+    receive callbacks when the bluetooth system wants to
+    read, write or observe a characteristic.
+    """
+
+    def __init__(self, channel):
+        """Constructor.
+
+        Args:
+            channel: A grpc.Channel.
+        """
+        self.OnCharacteristicReadRequest = channel.unary_unary(
+                '/android.emulation.bluetooth.GattDeviceService/OnCharacteristicReadRequest',
+                request_serializer=emulated__bluetooth__device__pb2.CharacteristicValueRequest.SerializeToString,
+                response_deserializer=emulated__bluetooth__device__pb2.CharacteristicValueResponse.FromString,
+                )
+        self.OnCharacteristicWriteRequest = channel.unary_unary(
+                '/android.emulation.bluetooth.GattDeviceService/OnCharacteristicWriteRequest',
+                request_serializer=emulated__bluetooth__device__pb2.CharacteristicValueRequest.SerializeToString,
+                response_deserializer=emulated__bluetooth__device__pb2.CharacteristicValueResponse.FromString,
+                )
+        self.OnCharacteristicObserveRequest = channel.unary_stream(
+                '/android.emulation.bluetooth.GattDeviceService/OnCharacteristicObserveRequest',
+                request_serializer=emulated__bluetooth__device__pb2.CharacteristicValueRequest.SerializeToString,
+                response_deserializer=emulated__bluetooth__device__pb2.CharacteristicValueResponse.FromString,
+                )
+        self.OnConnectionStateChange = channel.unary_unary(
+                '/android.emulation.bluetooth.GattDeviceService/OnConnectionStateChange',
+                request_serializer=emulated__bluetooth__device__pb2.ConnectionStateChange.SerializeToString,
+                response_deserializer=google_dot_protobuf_dot_empty__pb2.Empty.FromString,
+                )
+
+
+class GattDeviceServiceServicer(object):
+    """You can provide your own GattDevice by implementing this service
+    and registering it with the android emulator.
+
+    The device will appear as a real bluetooth device, and you will
+    receive callbacks when the bluetooth system wants to
+    read, write or observe a characteristic.
+    """
+
+    def OnCharacteristicReadRequest(self, request, context):
+        """A remote client has requested to read a local characteristic.
+
+        Return the current observed value.
+        """
+        context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+        context.set_details('Method not implemented!')
+        raise NotImplementedError('Method not implemented!')
+
+    def OnCharacteristicWriteRequest(self, request, context):
+        """A remote client has requested to write to a local characteristic.
+
+        Return the current observed value.
+        """
+        context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+        context.set_details('Method not implemented!')
+        raise NotImplementedError('Method not implemented!')
+
+    def OnCharacteristicObserveRequest(self, request, context):
+        """Listens for notifications from the emulated device, the device should
+        write to the stream with a response when a change has occurred.
+        """
+        context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+        context.set_details('Method not implemented!')
+        raise NotImplementedError('Method not implemented!')
+
+    def OnConnectionStateChange(self, request, context):
+        """A remote device has been connected or disconnected.
+        """
+        context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+        context.set_details('Method not implemented!')
+        raise NotImplementedError('Method not implemented!')
+
+
+def add_GattDeviceServiceServicer_to_server(servicer, server):
+    rpc_method_handlers = {
+            'OnCharacteristicReadRequest': grpc.unary_unary_rpc_method_handler(
+                    servicer.OnCharacteristicReadRequest,
+                    request_deserializer=emulated__bluetooth__device__pb2.CharacteristicValueRequest.FromString,
+                    response_serializer=emulated__bluetooth__device__pb2.CharacteristicValueResponse.SerializeToString,
+            ),
+            'OnCharacteristicWriteRequest': grpc.unary_unary_rpc_method_handler(
+                    servicer.OnCharacteristicWriteRequest,
+                    request_deserializer=emulated__bluetooth__device__pb2.CharacteristicValueRequest.FromString,
+                    response_serializer=emulated__bluetooth__device__pb2.CharacteristicValueResponse.SerializeToString,
+            ),
+            'OnCharacteristicObserveRequest': grpc.unary_stream_rpc_method_handler(
+                    servicer.OnCharacteristicObserveRequest,
+                    request_deserializer=emulated__bluetooth__device__pb2.CharacteristicValueRequest.FromString,
+                    response_serializer=emulated__bluetooth__device__pb2.CharacteristicValueResponse.SerializeToString,
+            ),
+            'OnConnectionStateChange': grpc.unary_unary_rpc_method_handler(
+                    servicer.OnConnectionStateChange,
+                    request_deserializer=emulated__bluetooth__device__pb2.ConnectionStateChange.FromString,
+                    response_serializer=google_dot_protobuf_dot_empty__pb2.Empty.SerializeToString,
+            ),
+    }
+    generic_handler = grpc.method_handlers_generic_handler(
+            'android.emulation.bluetooth.GattDeviceService', rpc_method_handlers)
+    server.add_generic_rpc_handlers((generic_handler,))
+
+
+ # This class is part of an EXPERIMENTAL API.
+class GattDeviceService(object):
+    """You can provide your own GattDevice by implementing this service
+    and registering it with the android emulator.
+
+    The device will appear as a real bluetooth device, and you will
+    receive callbacks when the bluetooth system wants to
+    read, write or observe a characteristic.
+    """
+
+    @staticmethod
+    def OnCharacteristicReadRequest(request,
+            target,
+            options=(),
+            channel_credentials=None,
+            call_credentials=None,
+            insecure=False,
+            compression=None,
+            wait_for_ready=None,
+            timeout=None,
+            metadata=None):
+        return grpc.experimental.unary_unary(request, target, '/android.emulation.bluetooth.GattDeviceService/OnCharacteristicReadRequest',
+            emulated__bluetooth__device__pb2.CharacteristicValueRequest.SerializeToString,
+            emulated__bluetooth__device__pb2.CharacteristicValueResponse.FromString,
+            options, channel_credentials,
+            insecure, call_credentials, compression, wait_for_ready, timeout, metadata)
+
+    @staticmethod
+    def OnCharacteristicWriteRequest(request,
+            target,
+            options=(),
+            channel_credentials=None,
+            call_credentials=None,
+            insecure=False,
+            compression=None,
+            wait_for_ready=None,
+            timeout=None,
+            metadata=None):
+        return grpc.experimental.unary_unary(request, target, '/android.emulation.bluetooth.GattDeviceService/OnCharacteristicWriteRequest',
+            emulated__bluetooth__device__pb2.CharacteristicValueRequest.SerializeToString,
+            emulated__bluetooth__device__pb2.CharacteristicValueResponse.FromString,
+            options, channel_credentials,
+            insecure, call_credentials, compression, wait_for_ready, timeout, metadata)
+
+    @staticmethod
+    def OnCharacteristicObserveRequest(request,
+            target,
+            options=(),
+            channel_credentials=None,
+            call_credentials=None,
+            insecure=False,
+            compression=None,
+            wait_for_ready=None,
+            timeout=None,
+            metadata=None):
+        return grpc.experimental.unary_stream(request, target, '/android.emulation.bluetooth.GattDeviceService/OnCharacteristicObserveRequest',
+            emulated__bluetooth__device__pb2.CharacteristicValueRequest.SerializeToString,
+            emulated__bluetooth__device__pb2.CharacteristicValueResponse.FromString,
+            options, channel_credentials,
+            insecure, call_credentials, compression, wait_for_ready, timeout, metadata)
+
+    @staticmethod
+    def OnConnectionStateChange(request,
+            target,
+            options=(),
+            channel_credentials=None,
+            call_credentials=None,
+            insecure=False,
+            compression=None,
+            wait_for_ready=None,
+            timeout=None,
+            metadata=None):
+        return grpc.experimental.unary_unary(request, target, '/android.emulation.bluetooth.GattDeviceService/OnConnectionStateChange',
+            emulated__bluetooth__device__pb2.ConnectionStateChange.SerializeToString,
+            google_dot_protobuf_dot_empty__pb2.Empty.FromString,
+            options, channel_credentials,
+            insecure, call_credentials, compression, wait_for_ready, timeout, metadata)

bumble/transport/grpc_protobuf/emulated_bluetooth_packets_pb2.py

@@ -0,0 +1,28 @@
+# -*- coding: utf-8 -*-
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# source: emulated_bluetooth_packets.proto
+"""Generated protocol buffer code."""
+from google.protobuf.internal import builder as _builder
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import descriptor_pool as _descriptor_pool
+from google.protobuf import symbol_database as _symbol_database
+# @@protoc_insertion_point(imports)
+
+_sym_db = _symbol_database.Default()
+
+
+
+
+DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n emulated_bluetooth_packets.proto\x12\x1b\x61ndroid.emulation.bluetooth\"\xfb\x01\n\tHCIPacket\x12?\n\x04type\x18\x01 \x01(\x0e\x32\x31.android.emulation.bluetooth.HCIPacket.PacketType\x12\x0e\n\x06packet\x18\x02 \x01(\x0c\"\x9c\x01\n\nPacketType\x12\x1b\n\x17PACKET_TYPE_UNSPECIFIED\x10\x00\x12\x1b\n\x17PACKET_TYPE_HCI_COMMAND\x10\x01\x12\x13\n\x0fPACKET_TYPE_ACL\x10\x02\x12\x13\n\x0fPACKET_TYPE_SCO\x10\x03\x12\x15\n\x11PACKET_TYPE_EVENT\x10\x04\x12\x13\n\x0fPACKET_TYPE_ISO\x10\x05\x42J\n\x1f\x63om.android.emulation.bluetoothP\x01\xf8\x01\x01\xa2\x02\x03\x41\x45\x42\xaa\x02\x1b\x41ndroid.Emulation.Bluetoothb\x06proto3')
+
+_builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, globals())
+_builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, 'emulated_bluetooth_packets_pb2', globals())
+if _descriptor._USE_C_DESCRIPTORS == False:
+
+  DESCRIPTOR._options = None
+  DESCRIPTOR._serialized_options = b'\n\037com.android.emulation.bluetoothP\001\370\001\001\242\002\003AEB\252\002\033Android.Emulation.Bluetooth'
+  _HCIPACKET._serialized_start=66
+  _HCIPACKET._serialized_end=317
+  _HCIPACKET_PACKETTYPE._serialized_start=161
+  _HCIPACKET_PACKETTYPE._serialized_end=317
+# @@protoc_insertion_point(module_scope)

bumble/transport/grpc_protobuf/emulated_bluetooth_packets_pb2.pyi

@@ -1,17 +1,3 @@
-# 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.
-
 from google.protobuf.internal import enum_type_wrapper as _enum_type_wrapper
 from google.protobuf import descriptor as _descriptor
 from google.protobuf import message as _message
@@ -21,7 +7,6 @@ DESCRIPTOR: _descriptor.FileDescriptor
 
 class HCIPacket(_message.Message):
     __slots__ = ["packet", "type"]
-
     class PacketType(int, metaclass=_enum_type_wrapper.EnumTypeWrapper):
         __slots__ = []
     PACKET_FIELD_NUMBER: _ClassVar[int]
@@ -34,8 +19,4 @@ class HCIPacket(_message.Message):
     TYPE_FIELD_NUMBER: _ClassVar[int]
     packet: bytes
     type: HCIPacket.PacketType
-    def __init__(
-        self,
-        type: _Optional[_Union[HCIPacket.PacketType, str]] = ...,
-        packet: _Optional[bytes] = ...,
-    ) -> None: ...
+    def __init__(self, type: _Optional[_Union[HCIPacket.PacketType, str]] = ..., packet: _Optional[bytes] = ...) -> None: ...

bumble/transport/grpc_protobuf/emulated_bluetooth_packets_pb2_grpc.py

@@ -0,0 +1,4 @@
+# Generated by the gRPC Python protocol compiler plugin. DO NOT EDIT!
+"""Client and server classes corresponding to protobuf-defined services."""
+import grpc
+

bumble/transport/grpc_protobuf/emulated_bluetooth_pb2.py

@@ -0,0 +1,32 @@
+# -*- coding: utf-8 -*-
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# source: emulated_bluetooth.proto
+"""Generated protocol buffer code."""
+from google.protobuf.internal import builder as _builder
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import descriptor_pool as _descriptor_pool
+from google.protobuf import symbol_database as _symbol_database
+# @@protoc_insertion_point(imports)
+
+_sym_db = _symbol_database.Default()
+
+
+from . import emulated_bluetooth_packets_pb2 as emulated__bluetooth__packets__pb2
+from . import emulated_bluetooth_device_pb2 as emulated__bluetooth__device__pb2
+
+
+DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n\x18\x65mulated_bluetooth.proto\x12\x1b\x61ndroid.emulation.bluetooth\x1a emulated_bluetooth_packets.proto\x1a\x1f\x65mulated_bluetooth_device.proto\"\x19\n\x07RawData\x12\x0e\n\x06packet\x18\x01 \x01(\x0c\"a\n\x12RegistrationStatus\x12K\n\x12\x63\x61llback_device_id\x18\x01 \x01(\x0b\x32/.android.emulation.bluetooth.CallbackIdentifier2\xbb\x03\n\x18\x45mulatedBluetoothService\x12\x64\n\x12registerClassicPhy\x12$.android.emulation.bluetooth.RawData\x1a$.android.emulation.bluetooth.RawData(\x01\x30\x01\x12`\n\x0eregisterBlePhy\x12$.android.emulation.bluetooth.RawData\x1a$.android.emulation.bluetooth.RawData(\x01\x30\x01\x12g\n\x11registerHCIDevice\x12&.android.emulation.bluetooth.HCIPacket\x1a&.android.emulation.bluetooth.HCIPacket(\x01\x30\x01\x12n\n\x12registerGattDevice\x12\'.android.emulation.bluetooth.GattDevice\x1a/.android.emulation.bluetooth.RegistrationStatusB\"\n\x1e\x63om.android.emulator.bluetoothP\x01\x62\x06proto3')
+
+_builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, globals())
+_builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, 'emulated_bluetooth_pb2', globals())
+if _descriptor._USE_C_DESCRIPTORS == False:
+
+  DESCRIPTOR._options = None
+  DESCRIPTOR._serialized_options = b'\n\036com.android.emulator.bluetoothP\001'
+  _RAWDATA._serialized_start=124
+  _RAWDATA._serialized_end=149
+  _REGISTRATIONSTATUS._serialized_start=151
+  _REGISTRATIONSTATUS._serialized_end=248
+  _EMULATEDBLUETOOTHSERVICE._serialized_start=251
+  _EMULATEDBLUETOOTHSERVICE._serialized_end=694
+# @@protoc_insertion_point(module_scope)

bumble/transport/grpc_protobuf/emulated_bluetooth_pb2.pyi

@@ -0,0 +1,19 @@
+from . import emulated_bluetooth_packets_pb2 as _emulated_bluetooth_packets_pb2
+from . import emulated_bluetooth_device_pb2 as _emulated_bluetooth_device_pb2
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import message as _message
+from typing import ClassVar as _ClassVar, Mapping as _Mapping, Optional as _Optional, Union as _Union
+
+DESCRIPTOR: _descriptor.FileDescriptor
+
+class RawData(_message.Message):
+    __slots__ = ["packet"]
+    PACKET_FIELD_NUMBER: _ClassVar[int]
+    packet: bytes
+    def __init__(self, packet: _Optional[bytes] = ...) -> None: ...
+
+class RegistrationStatus(_message.Message):
+    __slots__ = ["callback_device_id"]
+    CALLBACK_DEVICE_ID_FIELD_NUMBER: _ClassVar[int]
+    callback_device_id: _emulated_bluetooth_device_pb2.CallbackIdentifier
+    def __init__(self, callback_device_id: _Optional[_Union[_emulated_bluetooth_device_pb2.CallbackIdentifier, _Mapping]] = ...) -> None: ...

bumble/transport/grpc_protobuf/emulated_bluetooth_pb2_grpc.py

@@ -0,0 +1,237 @@
+# Generated by the gRPC Python protocol compiler plugin. DO NOT EDIT!
+"""Client and server classes corresponding to protobuf-defined services."""
+import grpc
+
+from . import emulated_bluetooth_device_pb2 as emulated__bluetooth__device__pb2
+from . import emulated_bluetooth_packets_pb2 as emulated__bluetooth__packets__pb2
+from . import emulated_bluetooth_pb2 as emulated__bluetooth__pb2
+
+
+class EmulatedBluetoothServiceStub(object):
+    """An Emulated Bluetooth Service exposes the emulated bluetooth chip from the
+    android emulator. It allows you to register emulated bluetooth devices and
+    control the packets that are exchanged between the device and the world.
+
+    This service enables you to establish a "virtual network" of emulated
+    bluetooth devices that can interact with each other.
+
+    Note: This is not yet finalized, it is likely that these definitions will
+    evolve.
+    """
+
+    def __init__(self, channel):
+        """Constructor.
+
+        Args:
+            channel: A grpc.Channel.
+        """
+        self.registerClassicPhy = channel.stream_stream(
+                '/android.emulation.bluetooth.EmulatedBluetoothService/registerClassicPhy',
+                request_serializer=emulated__bluetooth__pb2.RawData.SerializeToString,
+                response_deserializer=emulated__bluetooth__pb2.RawData.FromString,
+                )
+        self.registerBlePhy = channel.stream_stream(
+                '/android.emulation.bluetooth.EmulatedBluetoothService/registerBlePhy',
+                request_serializer=emulated__bluetooth__pb2.RawData.SerializeToString,
+                response_deserializer=emulated__bluetooth__pb2.RawData.FromString,
+                )
+        self.registerHCIDevice = channel.stream_stream(
+                '/android.emulation.bluetooth.EmulatedBluetoothService/registerHCIDevice',
+                request_serializer=emulated__bluetooth__packets__pb2.HCIPacket.SerializeToString,
+                response_deserializer=emulated__bluetooth__packets__pb2.HCIPacket.FromString,
+                )
+        self.registerGattDevice = channel.unary_unary(
+                '/android.emulation.bluetooth.EmulatedBluetoothService/registerGattDevice',
+                request_serializer=emulated__bluetooth__device__pb2.GattDevice.SerializeToString,
+                response_deserializer=emulated__bluetooth__pb2.RegistrationStatus.FromString,
+                )
+
+
+class EmulatedBluetoothServiceServicer(object):
+    """An Emulated Bluetooth Service exposes the emulated bluetooth chip from the
+    android emulator. It allows you to register emulated bluetooth devices and
+    control the packets that are exchanged between the device and the world.
+
+    This service enables you to establish a "virtual network" of emulated
+    bluetooth devices that can interact with each other.
+
+    Note: This is not yet finalized, it is likely that these definitions will
+    evolve.
+    """
+
+    def registerClassicPhy(self, request_iterator, context):
+        """Connect device to link layer. This will establish a direct connection
+        to the emulated bluetooth chip and configure the following:
+
+        - Each connection creates a new device and attaches it to the link layer
+        - Link Layer packets are transmitted directly to the phy
+
+        This should be used for classic connections.
+
+        This is used to directly connect various android emulators together.
+        For example a wear device can connect to an android emulator through
+        this.
+        """
+        context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+        context.set_details('Method not implemented!')
+        raise NotImplementedError('Method not implemented!')
+
+    def registerBlePhy(self, request_iterator, context):
+        """Connect device to link layer. This will establish a direct connection
+        to root canal and execute the following:
+
+        - Each connection creates a new device and attaches it to the link layer
+        - Link Layer packets are transmitted directly to the phy
+
+        This should be used for BLE connections.
+
+        This is used to directly connect various android emulators together.
+        For example a wear device can connect to an android emulator through
+        this.
+        """
+        context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+        context.set_details('Method not implemented!')
+        raise NotImplementedError('Method not implemented!')
+
+    def registerHCIDevice(self, request_iterator, context):
+        """Connect the device to the emulated bluetooth chip. The device will
+        participate in the network. You can configure the chip to scan, advertise
+        and setup connections with other devices that are connected to the
+        network.
+
+        This is usually used when you have a need for an emulated bluetooth chip
+        and have a bluetooth stack that can interpret and handle the packets
+        correctly.
+
+        For example the apache nimble stack can use this endpoint as the
+        transport layer.
+        """
+        context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+        context.set_details('Method not implemented!')
+        raise NotImplementedError('Method not implemented!')
+
+    def registerGattDevice(self, request, context):
+        """Registers an emulated bluetooth device. The emulator will reach out to
+        the emulated device to read/write and subscribe to properties.
+
+        The following gRPC error codes can be returned:
+        -  FAILED_PRECONDITION (code 9):
+        - root canal is not available on this device
+        - unable to reach the endpoint for the GattDevice
+        -  INTERNAL (code 13) if there was an internal emulator failure.
+
+        The device will not be discoverable in case of an error.
+        """
+        context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+        context.set_details('Method not implemented!')
+        raise NotImplementedError('Method not implemented!')
+
+
+def add_EmulatedBluetoothServiceServicer_to_server(servicer, server):
+    rpc_method_handlers = {
+            'registerClassicPhy': grpc.stream_stream_rpc_method_handler(
+                    servicer.registerClassicPhy,
+                    request_deserializer=emulated__bluetooth__pb2.RawData.FromString,
+                    response_serializer=emulated__bluetooth__pb2.RawData.SerializeToString,
+            ),
+            'registerBlePhy': grpc.stream_stream_rpc_method_handler(
+                    servicer.registerBlePhy,
+                    request_deserializer=emulated__bluetooth__pb2.RawData.FromString,
+                    response_serializer=emulated__bluetooth__pb2.RawData.SerializeToString,
+            ),
+            'registerHCIDevice': grpc.stream_stream_rpc_method_handler(
+                    servicer.registerHCIDevice,
+                    request_deserializer=emulated__bluetooth__packets__pb2.HCIPacket.FromString,
+                    response_serializer=emulated__bluetooth__packets__pb2.HCIPacket.SerializeToString,
+            ),
+            'registerGattDevice': grpc.unary_unary_rpc_method_handler(
+                    servicer.registerGattDevice,
+                    request_deserializer=emulated__bluetooth__device__pb2.GattDevice.FromString,
+                    response_serializer=emulated__bluetooth__pb2.RegistrationStatus.SerializeToString,
+            ),
+    }
+    generic_handler = grpc.method_handlers_generic_handler(
+            'android.emulation.bluetooth.EmulatedBluetoothService', rpc_method_handlers)
+    server.add_generic_rpc_handlers((generic_handler,))
+
+
+ # This class is part of an EXPERIMENTAL API.
+class EmulatedBluetoothService(object):
+    """An Emulated Bluetooth Service exposes the emulated bluetooth chip from the
+    android emulator. It allows you to register emulated bluetooth devices and
+    control the packets that are exchanged between the device and the world.
+
+    This service enables you to establish a "virtual network" of emulated
+    bluetooth devices that can interact with each other.
+
+    Note: This is not yet finalized, it is likely that these definitions will
+    evolve.
+    """
+
+    @staticmethod
+    def registerClassicPhy(request_iterator,
+            target,
+            options=(),
+            channel_credentials=None,
+            call_credentials=None,
+            insecure=False,
+            compression=None,
+            wait_for_ready=None,
+            timeout=None,
+            metadata=None):
+        return grpc.experimental.stream_stream(request_iterator, target, '/android.emulation.bluetooth.EmulatedBluetoothService/registerClassicPhy',
+            emulated__bluetooth__pb2.RawData.SerializeToString,
+            emulated__bluetooth__pb2.RawData.FromString,
+            options, channel_credentials,
+            insecure, call_credentials, compression, wait_for_ready, timeout, metadata)
+
+    @staticmethod
+    def registerBlePhy(request_iterator,
+            target,
+            options=(),
+            channel_credentials=None,
+            call_credentials=None,
+            insecure=False,
+            compression=None,
+            wait_for_ready=None,
+            timeout=None,
+            metadata=None):
+        return grpc.experimental.stream_stream(request_iterator, target, '/android.emulation.bluetooth.EmulatedBluetoothService/registerBlePhy',
+            emulated__bluetooth__pb2.RawData.SerializeToString,
+            emulated__bluetooth__pb2.RawData.FromString,
+            options, channel_credentials,
+            insecure, call_credentials, compression, wait_for_ready, timeout, metadata)
+
+    @staticmethod
+    def registerHCIDevice(request_iterator,
+            target,
+            options=(),
+            channel_credentials=None,
+            call_credentials=None,
+            insecure=False,
+            compression=None,
+            wait_for_ready=None,
+            timeout=None,
+            metadata=None):
+        return grpc.experimental.stream_stream(request_iterator, target, '/android.emulation.bluetooth.EmulatedBluetoothService/registerHCIDevice',
+            emulated__bluetooth__packets__pb2.HCIPacket.SerializeToString,
+            emulated__bluetooth__packets__pb2.HCIPacket.FromString,
+            options, channel_credentials,
+            insecure, call_credentials, compression, wait_for_ready, timeout, metadata)
+
+    @staticmethod
+    def registerGattDevice(request,
+            target,
+            options=(),
+            channel_credentials=None,
+            call_credentials=None,
+            insecure=False,
+            compression=None,
+            wait_for_ready=None,
+            timeout=None,
+            metadata=None):
+        return grpc.experimental.unary_unary(request, target, '/android.emulation.bluetooth.EmulatedBluetoothService/registerGattDevice',
+            emulated__bluetooth__device__pb2.GattDevice.SerializeToString,
+            emulated__bluetooth__pb2.RegistrationStatus.FromString,
+            options, channel_credentials,
+            insecure, call_credentials, compression, wait_for_ready, timeout, metadata)

bumble/transport/grpc_protobuf/emulated_bluetooth_vhci_pb2.py

@@ -0,0 +1,27 @@
+# -*- coding: utf-8 -*-
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# source: emulated_bluetooth_vhci.proto
+"""Generated protocol buffer code."""
+from google.protobuf.internal import builder as _builder
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import descriptor_pool as _descriptor_pool
+from google.protobuf import symbol_database as _symbol_database
+# @@protoc_insertion_point(imports)
+
+_sym_db = _symbol_database.Default()
+
+
+from . import emulated_bluetooth_packets_pb2 as emulated__bluetooth__packets__pb2
+
+
+DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n\x1d\x65mulated_bluetooth_vhci.proto\x12\x1b\x61ndroid.emulation.bluetooth\x1a emulated_bluetooth_packets.proto2y\n\x15VhciForwardingService\x12`\n\nattachVhci\x12&.android.emulation.bluetooth.HCIPacket\x1a&.android.emulation.bluetooth.HCIPacket(\x01\x30\x01\x42J\n\x1f\x63om.android.emulation.bluetoothP\x01\xf8\x01\x01\xa2\x02\x03\x41\x45\x42\xaa\x02\x1b\x41ndroid.Emulation.Bluetoothb\x06proto3')
+
+_builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, globals())
+_builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, 'emulated_bluetooth_vhci_pb2', globals())
+if _descriptor._USE_C_DESCRIPTORS == False:
+
+  DESCRIPTOR._options = None
+  DESCRIPTOR._serialized_options = b'\n\037com.android.emulation.bluetoothP\001\370\001\001\242\002\003AEB\252\002\033Android.Emulation.Bluetooth'
+  _VHCIFORWARDINGSERVICE._serialized_start=96
+  _VHCIFORWARDINGSERVICE._serialized_end=217
+# @@protoc_insertion_point(module_scope)

bumble/transport/grpc_protobuf/emulated_bluetooth_vhci_pb2.pyi

@@ -0,0 +1,5 @@
+import emulated_bluetooth_packets_pb2 as _emulated_bluetooth_packets_pb2
+from google.protobuf import descriptor as _descriptor
+from typing import ClassVar as _ClassVar
+
+DESCRIPTOR: _descriptor.FileDescriptor

bumble/transport/grpc_protobuf/emulated_bluetooth_vhci_pb2_grpc.py

@@ -1,17 +1,3 @@
-# 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.
-
 # Generated by the gRPC Python protocol compiler plugin. DO NOT EDIT!
 """Client and server classes corresponding to protobuf-defined services."""
 import grpc
@@ -35,10 +21,10 @@ class VhciForwardingServiceStub(object):
             channel: A grpc.Channel.
         """
         self.attachVhci = channel.stream_stream(
-            '/android.emulation.bluetooth.VhciForwardingService/attachVhci',
-            request_serializer=emulated__bluetooth__packets__pb2.HCIPacket.SerializeToString,
-            response_deserializer=emulated__bluetooth__packets__pb2.HCIPacket.FromString,
-        )
+                '/android.emulation.bluetooth.VhciForwardingService/attachVhci',
+                request_serializer=emulated__bluetooth__packets__pb2.HCIPacket.SerializeToString,
+                response_deserializer=emulated__bluetooth__packets__pb2.HCIPacket.FromString,
+                )
 
 
 class VhciForwardingServiceServicer(object):
@@ -75,19 +61,18 @@ class VhciForwardingServiceServicer(object):
 
 def add_VhciForwardingServiceServicer_to_server(servicer, server):
     rpc_method_handlers = {
-        'attachVhci': grpc.stream_stream_rpc_method_handler(
-            servicer.attachVhci,
-            request_deserializer=emulated__bluetooth__packets__pb2.HCIPacket.FromString,
-            response_serializer=emulated__bluetooth__packets__pb2.HCIPacket.SerializeToString,
-        ),
+            'attachVhci': grpc.stream_stream_rpc_method_handler(
+                    servicer.attachVhci,
+                    request_deserializer=emulated__bluetooth__packets__pb2.HCIPacket.FromString,
+                    response_serializer=emulated__bluetooth__packets__pb2.HCIPacket.SerializeToString,
+            ),
     }
     generic_handler = grpc.method_handlers_generic_handler(
-        'android.emulation.bluetooth.VhciForwardingService', rpc_method_handlers
-    )
+            'android.emulation.bluetooth.VhciForwardingService', rpc_method_handlers)
     server.add_generic_rpc_handlers((generic_handler,))
 
 
-# This class is part of an EXPERIMENTAL API.
+ # This class is part of an EXPERIMENTAL API.
 class VhciForwardingService(object):
     """This is a service which allows you to directly intercept the VHCI packets
     that are coming and going to the device before they are delivered to
@@ -98,30 +83,18 @@ class VhciForwardingService(object):
     """
 
     @staticmethod
-    def attachVhci(
-        request_iterator,
-        target,
-        options=(),
-        channel_credentials=None,
-        call_credentials=None,
-        insecure=False,
-        compression=None,
-        wait_for_ready=None,
-        timeout=None,
-        metadata=None,
-    ):
-        return grpc.experimental.stream_stream(
-            request_iterator,
+    def attachVhci(request_iterator,
             target,
-            '/android.emulation.bluetooth.VhciForwardingService/attachVhci',
+            options=(),
+            channel_credentials=None,
+            call_credentials=None,
+            insecure=False,
+            compression=None,
+            wait_for_ready=None,
+            timeout=None,
+            metadata=None):
+        return grpc.experimental.stream_stream(request_iterator, target, '/android.emulation.bluetooth.VhciForwardingService/attachVhci',
             emulated__bluetooth__packets__pb2.HCIPacket.SerializeToString,
             emulated__bluetooth__packets__pb2.HCIPacket.FromString,
-            options,
-            channel_credentials,
-            insecure,
-            call_credentials,
-            compression,
-            wait_for_ready,
-            timeout,
-            metadata,
-        )
+            options, channel_credentials,
+            insecure, call_credentials, compression, wait_for_ready, timeout, metadata)

bumble/transport/grpc_protobuf/grpc_endpoint_description_pb2.py

@@ -0,0 +1,30 @@
+# -*- coding: utf-8 -*-
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# source: grpc_endpoint_description.proto
+"""Generated protocol buffer code."""
+from google.protobuf.internal import builder as _builder
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import descriptor_pool as _descriptor_pool
+from google.protobuf import symbol_database as _symbol_database
+# @@protoc_insertion_point(imports)
+
+_sym_db = _symbol_database.Default()
+
+
+
+
+DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n\x1fgrpc_endpoint_description.proto\x12\x18\x61ndroid.emulation.remote\"V\n\x0b\x43redentials\x12\x16\n\x0epem_root_certs\x18\x01 \x01(\t\x12\x17\n\x0fpem_private_key\x18\x02 \x01(\t\x12\x16\n\x0epem_cert_chain\x18\x03 \x01(\t\"$\n\x06Header\x12\x0b\n\x03key\x18\x01 \x01(\t\x12\r\n\x05value\x18\x02 \x01(\t\"\x96\x01\n\x08\x45ndpoint\x12\x0e\n\x06target\x18\x01 \x01(\t\x12>\n\x0ftls_credentials\x18\x02 \x01(\x0b\x32%.android.emulation.remote.Credentials\x12:\n\x10required_headers\x18\x03 \x03(\x0b\x32 .android.emulation.remote.HeaderB \n\x1c\x63om.android.emulation.remoteP\x01\x62\x06proto3')
+
+_builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, globals())
+_builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, 'grpc_endpoint_description_pb2', globals())
+if _descriptor._USE_C_DESCRIPTORS == False:
+
+  DESCRIPTOR._options = None
+  DESCRIPTOR._serialized_options = b'\n\034com.android.emulation.remoteP\001'
+  _CREDENTIALS._serialized_start=61
+  _CREDENTIALS._serialized_end=147
+  _HEADER._serialized_start=149
+  _HEADER._serialized_end=185
+  _ENDPOINT._serialized_start=188
+  _ENDPOINT._serialized_end=338
+# @@protoc_insertion_point(module_scope)

bumble/transport/grpc_protobuf/grpc_endpoint_description_pb2.pyi

@@ -0,0 +1,34 @@
+from google.protobuf.internal import containers as _containers
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import message as _message
+from typing import ClassVar as _ClassVar, Iterable as _Iterable, Mapping as _Mapping, Optional as _Optional, Union as _Union
+
+DESCRIPTOR: _descriptor.FileDescriptor
+
+class Credentials(_message.Message):
+    __slots__ = ["pem_cert_chain", "pem_private_key", "pem_root_certs"]
+    PEM_CERT_CHAIN_FIELD_NUMBER: _ClassVar[int]
+    PEM_PRIVATE_KEY_FIELD_NUMBER: _ClassVar[int]
+    PEM_ROOT_CERTS_FIELD_NUMBER: _ClassVar[int]
+    pem_cert_chain: str
+    pem_private_key: str
+    pem_root_certs: str
+    def __init__(self, pem_root_certs: _Optional[str] = ..., pem_private_key: _Optional[str] = ..., pem_cert_chain: _Optional[str] = ...) -> None: ...
+
+class Endpoint(_message.Message):
+    __slots__ = ["required_headers", "target", "tls_credentials"]
+    REQUIRED_HEADERS_FIELD_NUMBER: _ClassVar[int]
+    TARGET_FIELD_NUMBER: _ClassVar[int]
+    TLS_CREDENTIALS_FIELD_NUMBER: _ClassVar[int]
+    required_headers: _containers.RepeatedCompositeFieldContainer[Header]
+    target: str
+    tls_credentials: Credentials
+    def __init__(self, target: _Optional[str] = ..., tls_credentials: _Optional[_Union[Credentials, _Mapping]] = ..., required_headers: _Optional[_Iterable[_Union[Header, _Mapping]]] = ...) -> None: ...
+
+class Header(_message.Message):
+    __slots__ = ["key", "value"]
+    KEY_FIELD_NUMBER: _ClassVar[int]
+    VALUE_FIELD_NUMBER: _ClassVar[int]
+    key: str
+    value: str
+    def __init__(self, key: _Optional[str] = ..., value: _Optional[str] = ...) -> None: ...

bumble/transport/grpc_protobuf/grpc_endpoint_description_pb2_grpc.py

@@ -0,0 +1,4 @@
+# Generated by the gRPC Python protocol compiler plugin. DO NOT EDIT!
+"""Client and server classes corresponding to protobuf-defined services."""
+import grpc
+

bumble/transport/grpc_protobuf/hci_packet_pb2.py

@@ -0,0 +1,28 @@
+# -*- coding: utf-8 -*-
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# source: hci_packet.proto
+"""Generated protocol buffer code."""
+from google.protobuf.internal import builder as _builder
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import descriptor_pool as _descriptor_pool
+from google.protobuf import symbol_database as _symbol_database
+# @@protoc_insertion_point(imports)
+
+_sym_db = _symbol_database.Default()
+
+
+
+
+DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n\x10hci_packet.proto\x12\rnetsim.packet\"\xb2\x01\n\tHCIPacket\x12\x38\n\x0bpacket_type\x18\x01 \x01(\x0e\x32#.netsim.packet.HCIPacket.PacketType\x12\x0e\n\x06packet\x18\x02 \x01(\x0c\"[\n\nPacketType\x12\x1a\n\x16HCI_PACKET_UNSPECIFIED\x10\x00\x12\x0b\n\x07\x43OMMAND\x10\x01\x12\x07\n\x03\x41\x43L\x10\x02\x12\x07\n\x03SCO\x10\x03\x12\t\n\x05\x45VENT\x10\x04\x12\x07\n\x03ISO\x10\x05\x42J\n\x1f\x63om.android.emulation.bluetoothP\x01\xf8\x01\x01\xa2\x02\x03\x41\x45\x42\xaa\x02\x1b\x41ndroid.Emulation.Bluetoothb\x06proto3')
+
+_builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, globals())
+_builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, 'hci_packet_pb2', globals())
+if _descriptor._USE_C_DESCRIPTORS == False:
+
+  DESCRIPTOR._options = None
+  DESCRIPTOR._serialized_options = b'\n\037com.android.emulation.bluetoothP\001\370\001\001\242\002\003AEB\252\002\033Android.Emulation.Bluetooth'
+  _HCIPACKET._serialized_start=36
+  _HCIPACKET._serialized_end=214
+  _HCIPACKET_PACKETTYPE._serialized_start=123
+  _HCIPACKET_PACKETTYPE._serialized_end=214
+# @@protoc_insertion_point(module_scope)

bumble/transport/grpc_protobuf/hci_packet_pb2.pyi

@@ -0,0 +1,22 @@
+from google.protobuf.internal import enum_type_wrapper as _enum_type_wrapper
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import message as _message
+from typing import ClassVar as _ClassVar, Optional as _Optional, Union as _Union
+
+DESCRIPTOR: _descriptor.FileDescriptor
+
+class HCIPacket(_message.Message):
+    __slots__ = ["packet", "packet_type"]
+    class PacketType(int, metaclass=_enum_type_wrapper.EnumTypeWrapper):
+        __slots__ = []
+    ACL: HCIPacket.PacketType
+    COMMAND: HCIPacket.PacketType
+    EVENT: HCIPacket.PacketType
+    HCI_PACKET_UNSPECIFIED: HCIPacket.PacketType
+    ISO: HCIPacket.PacketType
+    PACKET_FIELD_NUMBER: _ClassVar[int]
+    PACKET_TYPE_FIELD_NUMBER: _ClassVar[int]
+    SCO: HCIPacket.PacketType
+    packet: bytes
+    packet_type: HCIPacket.PacketType
+    def __init__(self, packet_type: _Optional[_Union[HCIPacket.PacketType, str]] = ..., packet: _Optional[bytes] = ...) -> None: ...

bumble/transport/grpc_protobuf/hci_packet_pb2_grpc.py

@@ -0,0 +1,4 @@
+# Generated by the gRPC Python protocol compiler plugin. DO NOT EDIT!
+"""Client and server classes corresponding to protobuf-defined services."""
+import grpc
+

bumble/transport/grpc_protobuf/packet_streamer_pb2.py

@@ -0,0 +1,31 @@
+# -*- coding: utf-8 -*-
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# source: packet_streamer.proto
+"""Generated protocol buffer code."""
+from google.protobuf.internal import builder as _builder
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import descriptor_pool as _descriptor_pool
+from google.protobuf import symbol_database as _symbol_database
+# @@protoc_insertion_point(imports)
+
+_sym_db = _symbol_database.Default()
+
+
+from . import hci_packet_pb2 as hci__packet__pb2
+from . import startup_pb2 as startup__pb2
+
+
+DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n\x15packet_streamer.proto\x12\rnetsim.packet\x1a\x10hci_packet.proto\x1a\rstartup.proto\"\x93\x01\n\rPacketRequest\x12\x30\n\x0cinitial_info\x18\x01 \x01(\x0b\x32\x18.netsim.startup.ChipInfoH\x00\x12.\n\nhci_packet\x18\x02 \x01(\x0b\x32\x18.netsim.packet.HCIPacketH\x00\x12\x10\n\x06packet\x18\x03 \x01(\x0cH\x00\x42\x0e\n\x0crequest_type\"t\n\x0ePacketResponse\x12\x0f\n\x05\x65rror\x18\x01 \x01(\tH\x00\x12.\n\nhci_packet\x18\x02 \x01(\x0b\x32\x18.netsim.packet.HCIPacketH\x00\x12\x10\n\x06packet\x18\x03 \x01(\x0cH\x00\x42\x0f\n\rresponse_type2b\n\x0ePacketStreamer\x12P\n\rStreamPackets\x12\x1c.netsim.packet.PacketRequest\x1a\x1d.netsim.packet.PacketResponse(\x01\x30\x01\x62\x06proto3')
+
+_builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, globals())
+_builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, 'packet_streamer_pb2', globals())
+if _descriptor._USE_C_DESCRIPTORS == False:
+
+  DESCRIPTOR._options = None
+  _PACKETREQUEST._serialized_start=74
+  _PACKETREQUEST._serialized_end=221
+  _PACKETRESPONSE._serialized_start=223
+  _PACKETRESPONSE._serialized_end=339
+  _PACKETSTREAMER._serialized_start=341
+  _PACKETSTREAMER._serialized_end=439
+# @@protoc_insertion_point(module_scope)

bumble/transport/grpc_protobuf/packet_streamer_pb2.pyi

@@ -0,0 +1,27 @@
+from . import hci_packet_pb2 as _hci_packet_pb2
+from . import startup_pb2 as _startup_pb2
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import message as _message
+from typing import ClassVar as _ClassVar, Mapping as _Mapping, Optional as _Optional, Union as _Union
+
+DESCRIPTOR: _descriptor.FileDescriptor
+
+class PacketRequest(_message.Message):
+    __slots__ = ["hci_packet", "initial_info", "packet"]
+    HCI_PACKET_FIELD_NUMBER: _ClassVar[int]
+    INITIAL_INFO_FIELD_NUMBER: _ClassVar[int]
+    PACKET_FIELD_NUMBER: _ClassVar[int]
+    hci_packet: _hci_packet_pb2.HCIPacket
+    initial_info: _startup_pb2.ChipInfo
+    packet: bytes
+    def __init__(self, initial_info: _Optional[_Union[_startup_pb2.ChipInfo, _Mapping]] = ..., hci_packet: _Optional[_Union[_hci_packet_pb2.HCIPacket, _Mapping]] = ..., packet: _Optional[bytes] = ...) -> None: ...
+
+class PacketResponse(_message.Message):
+    __slots__ = ["error", "hci_packet", "packet"]
+    ERROR_FIELD_NUMBER: _ClassVar[int]
+    HCI_PACKET_FIELD_NUMBER: _ClassVar[int]
+    PACKET_FIELD_NUMBER: _ClassVar[int]
+    error: str
+    hci_packet: _hci_packet_pb2.HCIPacket
+    packet: bytes
+    def __init__(self, error: _Optional[str] = ..., hci_packet: _Optional[_Union[_hci_packet_pb2.HCIPacket, _Mapping]] = ..., packet: _Optional[bytes] = ...) -> None: ...

bumble/transport/grpc_protobuf/packet_streamer_pb2_grpc.py

@@ -0,0 +1,109 @@
+# Generated by the gRPC Python protocol compiler plugin. DO NOT EDIT!
+"""Client and server classes corresponding to protobuf-defined services."""
+import grpc
+
+from . import packet_streamer_pb2 as packet__streamer__pb2
+
+
+class PacketStreamerStub(object):
+    """*
+    This is the packet service for the network simulator.
+
+    Android Virtual Devices (AVDs) and accessory devices use this service to
+    connect to the network simulator and pass packets back and forth.
+
+    AVDs running in a guest VM are built with virtual controllers for each radio
+    chip. These controllers route chip requests to host emulators (qemu and
+    crosvm) using virtio and from there they are forwarded to this gRpc service.
+
+    This setup provides a transparent radio environment across AVDs and
+    accessories because the network simulator contains libraries to emulate
+    Bluetooth, 80211MAC, UWB, and Rtt chips.
+
+    """
+
+    def __init__(self, channel):
+        """Constructor.
+
+        Args:
+            channel: A grpc.Channel.
+        """
+        self.StreamPackets = channel.stream_stream(
+                '/netsim.packet.PacketStreamer/StreamPackets',
+                request_serializer=packet__streamer__pb2.PacketRequest.SerializeToString,
+                response_deserializer=packet__streamer__pb2.PacketResponse.FromString,
+                )
+
+
+class PacketStreamerServicer(object):
+    """*
+    This is the packet service for the network simulator.
+
+    Android Virtual Devices (AVDs) and accessory devices use this service to
+    connect to the network simulator and pass packets back and forth.
+
+    AVDs running in a guest VM are built with virtual controllers for each radio
+    chip. These controllers route chip requests to host emulators (qemu and
+    crosvm) using virtio and from there they are forwarded to this gRpc service.
+
+    This setup provides a transparent radio environment across AVDs and
+    accessories because the network simulator contains libraries to emulate
+    Bluetooth, 80211MAC, UWB, and Rtt chips.
+
+    """
+
+    def StreamPackets(self, request_iterator, context):
+        """Attach a virtual radio controller to the network simulation.
+        """
+        context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+        context.set_details('Method not implemented!')
+        raise NotImplementedError('Method not implemented!')
+
+
+def add_PacketStreamerServicer_to_server(servicer, server):
+    rpc_method_handlers = {
+            'StreamPackets': grpc.stream_stream_rpc_method_handler(
+                    servicer.StreamPackets,
+                    request_deserializer=packet__streamer__pb2.PacketRequest.FromString,
+                    response_serializer=packet__streamer__pb2.PacketResponse.SerializeToString,
+            ),
+    }
+    generic_handler = grpc.method_handlers_generic_handler(
+            'netsim.packet.PacketStreamer', rpc_method_handlers)
+    server.add_generic_rpc_handlers((generic_handler,))
+
+
+ # This class is part of an EXPERIMENTAL API.
+class PacketStreamer(object):
+    """*
+    This is the packet service for the network simulator.
+
+    Android Virtual Devices (AVDs) and accessory devices use this service to
+    connect to the network simulator and pass packets back and forth.
+
+    AVDs running in a guest VM are built with virtual controllers for each radio
+    chip. These controllers route chip requests to host emulators (qemu and
+    crosvm) using virtio and from there they are forwarded to this gRpc service.
+
+    This setup provides a transparent radio environment across AVDs and
+    accessories because the network simulator contains libraries to emulate
+    Bluetooth, 80211MAC, UWB, and Rtt chips.
+
+    """
+
+    @staticmethod
+    def StreamPackets(request_iterator,
+            target,
+            options=(),
+            channel_credentials=None,
+            call_credentials=None,
+            insecure=False,
+            compression=None,
+            wait_for_ready=None,
+            timeout=None,
+            metadata=None):
+        return grpc.experimental.stream_stream(request_iterator, target, '/netsim.packet.PacketStreamer/StreamPackets',
+            packet__streamer__pb2.PacketRequest.SerializeToString,
+            packet__streamer__pb2.PacketResponse.FromString,
+            options, channel_credentials,
+            insecure, call_credentials, compression, wait_for_ready, timeout, metadata)

bumble/transport/grpc_protobuf/startup_pb2.py

@@ -0,0 +1,32 @@
+# -*- coding: utf-8 -*-
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# source: startup.proto
+"""Generated protocol buffer code."""
+from google.protobuf.internal import builder as _builder
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import descriptor_pool as _descriptor_pool
+from google.protobuf import symbol_database as _symbol_database
+# @@protoc_insertion_point(imports)
+
+_sym_db = _symbol_database.Default()
+
+
+from . import common_pb2 as common__pb2
+
+
+DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n\rstartup.proto\x12\x0enetsim.startup\x1a\x0c\x63ommon.proto\"\x7f\n\x0bStartupInfo\x12\x33\n\x07\x64\x65vices\x18\x01 \x03(\x0b\x32\".netsim.startup.StartupInfo.Device\x1a;\n\x06\x44\x65vice\x12\x0c\n\x04name\x18\x01 \x01(\t\x12#\n\x05\x63hips\x18\x02 \x03(\x0b\x32\x14.netsim.startup.Chip\"<\n\x08\x43hipInfo\x12\x0c\n\x04name\x18\x01 \x01(\t\x12\"\n\x04\x63hip\x18\x02 \x01(\x0b\x32\x14.netsim.startup.Chip\"\x96\x01\n\x04\x43hip\x12%\n\x04kind\x18\x01 \x01(\x0e\x32\x17.netsim.common.ChipKind\x12\n\n\x02id\x18\x02 \x01(\t\x12\x14\n\x0cmanufacturer\x18\x03 \x01(\t\x12\x14\n\x0cproduct_name\x18\x04 \x01(\t\x12\r\n\x05\x66\x64_in\x18\x05 \x01(\x05\x12\x0e\n\x06\x66\x64_out\x18\x06 \x01(\x05\x12\x10\n\x08loopback\x18\x07 \x01(\x08\x62\x06proto3')
+
+_builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, globals())
+_builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, 'startup_pb2', globals())
+if _descriptor._USE_C_DESCRIPTORS == False:
+
+  DESCRIPTOR._options = None
+  _STARTUPINFO._serialized_start=47
+  _STARTUPINFO._serialized_end=174
+  _STARTUPINFO_DEVICE._serialized_start=115
+  _STARTUPINFO_DEVICE._serialized_end=174
+  _CHIPINFO._serialized_start=176
+  _CHIPINFO._serialized_end=236
+  _CHIP._serialized_start=239
+  _CHIP._serialized_end=389
+# @@protoc_insertion_point(module_scope)

bumble/transport/grpc_protobuf/startup_pb2.pyi

@@ -0,0 +1,46 @@
+from . import common_pb2 as _common_pb2
+from google.protobuf.internal import containers as _containers
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import message as _message
+from typing import ClassVar as _ClassVar, Iterable as _Iterable, Mapping as _Mapping, Optional as _Optional, Union as _Union
+
+DESCRIPTOR: _descriptor.FileDescriptor
+
+class Chip(_message.Message):
+    __slots__ = ["fd_in", "fd_out", "id", "kind", "loopback", "manufacturer", "product_name"]
+    FD_IN_FIELD_NUMBER: _ClassVar[int]
+    FD_OUT_FIELD_NUMBER: _ClassVar[int]
+    ID_FIELD_NUMBER: _ClassVar[int]
+    KIND_FIELD_NUMBER: _ClassVar[int]
+    LOOPBACK_FIELD_NUMBER: _ClassVar[int]
+    MANUFACTURER_FIELD_NUMBER: _ClassVar[int]
+    PRODUCT_NAME_FIELD_NUMBER: _ClassVar[int]
+    fd_in: int
+    fd_out: int
+    id: str
+    kind: _common_pb2.ChipKind
+    loopback: bool
+    manufacturer: str
+    product_name: str
+    def __init__(self, kind: _Optional[_Union[_common_pb2.ChipKind, str]] = ..., id: _Optional[str] = ..., manufacturer: _Optional[str] = ..., product_name: _Optional[str] = ..., fd_in: _Optional[int] = ..., fd_out: _Optional[int] = ..., loopback: bool = ...) -> None: ...
+
+class ChipInfo(_message.Message):
+    __slots__ = ["chip", "name"]
+    CHIP_FIELD_NUMBER: _ClassVar[int]
+    NAME_FIELD_NUMBER: _ClassVar[int]
+    chip: Chip
+    name: str
+    def __init__(self, name: _Optional[str] = ..., chip: _Optional[_Union[Chip, _Mapping]] = ...) -> None: ...
+
+class StartupInfo(_message.Message):
+    __slots__ = ["devices"]
+    class Device(_message.Message):
+        __slots__ = ["chips", "name"]
+        CHIPS_FIELD_NUMBER: _ClassVar[int]
+        NAME_FIELD_NUMBER: _ClassVar[int]
+        chips: _containers.RepeatedCompositeFieldContainer[Chip]
+        name: str
+        def __init__(self, name: _Optional[str] = ..., chips: _Optional[_Iterable[_Union[Chip, _Mapping]]] = ...) -> None: ...
+    DEVICES_FIELD_NUMBER: _ClassVar[int]
+    devices: _containers.RepeatedCompositeFieldContainer[StartupInfo.Device]
+    def __init__(self, devices: _Optional[_Iterable[_Union[StartupInfo.Device, _Mapping]]] = ...) -> None: ...

bumble/transport/grpc_protobuf/startup_pb2_grpc.py

@@ -0,0 +1,4 @@
+# Generated by the gRPC Python protocol compiler plugin. DO NOT EDIT!
+"""Client and server classes corresponding to protobuf-defined services."""
+import grpc
+

bumble/transport/hci_socket.py

@@ -23,6 +23,8 @@ import socket
 import ctypes
 import collections
 
+from typing import Optional
+
 from .common import Transport, ParserSource
 
 
@@ -33,7 +35,7 @@ logger = logging.getLogger(__name__)
 
 
 # -----------------------------------------------------------------------------
-async def open_hci_socket_transport(spec):
+async def open_hci_socket_transport(spec: Optional[str]) -> Transport:
     '''
     Open an HCI Socket (only available on some platforms).
     The parameter string is either empty (to use the first/default Bluetooth adapter)
@@ -47,7 +49,7 @@ async def open_hci_socket_transport(spec):
         hci_socket = socket.socket(
             socket.AF_BLUETOOTH,
             socket.SOCK_RAW | socket.SOCK_NONBLOCK,
-            socket.BTPROTO_HCI,
+            socket.BTPROTO_HCI,  # type: ignore
         )
     except AttributeError as error:
         # Not supported on this platform

bumble/transport/pty.py

@@ -23,6 +23,8 @@ import atexit
 import os
 import logging
 
+from typing import Optional
+
 from .common import Transport, StreamPacketSource, StreamPacketSink
 
 # -----------------------------------------------------------------------------
@@ -32,7 +34,7 @@ logger = logging.getLogger(__name__)
 
 
 # -----------------------------------------------------------------------------
-async def open_pty_transport(spec):
+async def open_pty_transport(spec: Optional[str]) -> Transport:
     '''
     Open a PTY transport.
     The parameter string may be empty, or a path name where a symbolic link

bumble/transport/pyusb.py

@@ -35,7 +35,7 @@ logger = logging.getLogger(__name__)
 
 
 # -----------------------------------------------------------------------------
-async def open_pyusb_transport(spec):
+async def open_pyusb_transport(spec: str) -> Transport:
     '''
     Open a USB transport. [Implementation based on PyUSB]
     The parameter string has this syntax: