use r0 by default

realtek driver

apps/pair.py

@@ -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()
@@ -283,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':
@@ -323,6 +332,17 @@ async def pair(
         # 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)

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/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/device.py

@@ -58,7 +58,7 @@ from .hci import (
     HCI_MITM_REQUIRED_GENERAL_BONDING_AUTHENTICATION_REQUIREMENTS,
     HCI_MITM_REQUIRED_NO_BONDING_AUTHENTICATION_REQUIREMENTS,
     HCI_NO_INPUT_NO_OUTPUT_IO_CAPABILITY,
-    HCI_R2_PAGE_SCAN_REPETITION_MODE,
+    HCI_R0_PAGE_SCAN_REPETITION_MODE,
     HCI_REMOTE_USER_TERMINATED_CONNECTION_ERROR,
     HCI_SUCCESS,
     HCI_WRITE_LE_HOST_SUPPORT_COMMAND,
@@ -1842,7 +1842,7 @@ class Device(CompositeEventEmitter):
                     HCI_Create_Connection_Command(
                         bd_addr=peer_address,
                         packet_type=0xCC18,  # FIXME: change
-                        page_scan_repetition_mode=HCI_R2_PAGE_SCAN_REPETITION_MODE,
+                        page_scan_repetition_mode=HCI_R0_PAGE_SCAN_REPETITION_MODE,
                         clock_offset=0x0000,
                         allow_role_switch=0x01,
                         reserved=0,
@@ -3098,7 +3098,16 @@ class Device(CompositeEventEmitter):
     def on_pairing_start(self, connection: Connection) -> None:
         connection.emit('pairing_start')
 
-    def on_pairing(self, connection: Connection, keys: PairingKeys, sc: bool) -> None:
+    def on_pairing(
+        self,
+        connection: Connection,
+        identity_address: Optional[Address],
+        keys: PairingKeys,
+        sc: bool,
+    ) -> None:
+        if identity_address is not None:
+            connection.peer_resolvable_address = connection.peer_address
+            connection.peer_address = identity_address
         connection.sc = sc
         connection.authenticated = True
         connection.emit('pairing', keys)

bumble/drivers/__init__.py

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

bumble/drivers/rtk.py

@@ -0,0 +1,647 @@
+# 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_command_op_code,
+    STATUS_SPEC,
+    HCI_SUCCESS,
+    HCI_COMMAND_NAMES,
+    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),
+    # 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_command_op_code(0x3F, 0x6D)
+HCI_COMMAND_NAMES[HCI_RTK_READ_ROM_VERSION_COMMAND] = "HCI_RTK_READ_ROM_VERSION_COMMAND"
+
+
+@HCI_Command.command(return_parameters_fields=[("status", STATUS_SPEC), ("version", 1)])
+class HCI_RTK_Read_ROM_Version_Command(HCI_Command):
+    pass
+
+
+HCI_RTK_DOWNLOAD_COMMAND = hci_command_op_code(0x3F, 0x20)
+HCI_COMMAND_NAMES[HCI_RTK_DOWNLOAD_COMMAND] = "HCI_RTK_DOWNLOAD_COMMAND"
+
+
+@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_RTK_DROP_FIRMWARE_COMMAND = hci_command_op_code(0x3F, 0x66)
+HCI_COMMAND_NAMES[HCI_RTK_DROP_FIRMWARE_COMMAND] = "HCI_RTK_DROP_FIRMWARE_COMMAND"
+
+
+@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 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}")

bumble/hci.py

@@ -185,7 +185,7 @@ HCI_IO_CAPABILITY_REQUEST_EVENT                                  = 0x31
 HCI_IO_CAPABILITY_RESPONSE_EVENT                                 = 0x32
 HCI_USER_CONFIRMATION_REQUEST_EVENT                              = 0x33
 HCI_USER_PASSKEY_REQUEST_EVENT                                   = 0x34
-HCI_REMOTE_OOB_DATA_REQUEST                                      = 0x35
+HCI_REMOTE_OOB_DATA_REQUEST_EVENT                                = 0x35
 HCI_SIMPLE_PAIRING_COMPLETE_EVENT                                = 0x36
 HCI_LINK_SUPERVISION_TIMEOUT_CHANGED_EVENT                       = 0x38
 HCI_ENHANCED_FLUSH_COMPLETE_EVENT                                = 0x39
@@ -1641,9 +1641,11 @@ class HCI_Object:
             # Get the value for the field
             value = hci_object[key]
 
-            # Map the value if needed
+            # Check if there's a matching mapper passed
             if value_mappers:
                 value_mapper = value_mappers.get(key, value_mapper)
+
+            # Map the value if we have a mapper
             if value_mapper is not None:
                 value = value_mapper(value)
 
@@ -2286,6 +2288,55 @@ class HCI_User_Passkey_Request_Negative_Reply_Command(HCI_Command):
     '''
 
 
+# -----------------------------------------------------------------------------
+@HCI_Command.command(
+    fields=[
+        ('bd_addr', Address.parse_address),
+        ('c', 16),
+        ('r', 16),
+    ],
+    return_parameters_fields=[
+        ('status', STATUS_SPEC),
+        ('bd_addr', Address.parse_address),
+    ],
+)
+class HCI_Remote_OOB_Data_Request_Reply_Command(HCI_Command):
+    '''
+    See Bluetooth spec @ 7.1.34 Remote OOB Data Request Reply Command
+    '''
+
+
+# -----------------------------------------------------------------------------
+@HCI_Command.command(
+    fields=[('bd_addr', Address.parse_address)],
+    return_parameters_fields=[
+        ('status', STATUS_SPEC),
+        ('bd_addr', Address.parse_address),
+    ],
+)
+class HCI_Remote_OOB_Data_Request_Negative_Reply_Command(HCI_Command):
+    '''
+    See Bluetooth spec @ 7.1.35 Remote OOB Data Request Negative Reply Command
+    '''
+
+
+# -----------------------------------------------------------------------------
+@HCI_Command.command(
+    fields=[
+        ('bd_addr', Address.parse_address),
+        ('reason', 1),
+    ],
+    return_parameters_fields=[
+        ('status', STATUS_SPEC),
+        ('bd_addr', Address.parse_address),
+    ],
+)
+class HCI_IO_Capability_Request_Negative_Reply_Command(HCI_Command):
+    '''
+    See Bluetooth spec @ 7.1.36 IO Capability Request Negative Reply Command
+    '''
+
+
 # -----------------------------------------------------------------------------
 @HCI_Command.command(
     [
@@ -2321,6 +2372,161 @@ class HCI_Enhanced_Setup_Synchronous_Connection_Command(HCI_Command):
     '''
 
 
+# -----------------------------------------------------------------------------
+@HCI_Command.command(
+    [
+        ('bd_addr', Address.parse_address),
+        ('transmit_bandwidth', 4),
+        ('receive_bandwidth', 4),
+        ('transmit_coding_format', 5),
+        ('receive_coding_format', 5),
+        ('transmit_codec_frame_size', 2),
+        ('receive_codec_frame_size', 2),
+        ('input_bandwidth', 4),
+        ('output_bandwidth', 4),
+        ('input_coding_format', 5),
+        ('output_coding_format', 5),
+        ('input_coded_data_size', 2),
+        ('output_coded_data_size', 2),
+        ('input_pcm_data_format', 1),
+        ('output_pcm_data_format', 1),
+        ('input_pcm_sample_payload_msb_position', 1),
+        ('output_pcm_sample_payload_msb_position', 1),
+        ('input_data_path', 1),
+        ('output_data_path', 1),
+        ('input_transport_unit_size', 1),
+        ('output_transport_unit_size', 1),
+        ('max_latency', 2),
+        ('packet_type', 2),
+        ('retransmission_effort', 1),
+    ]
+)
+class HCI_Enhanced_Accept_Synchronous_Connection_Request_Command(HCI_Command):
+    '''
+    See Bluetooth spec @ 7.1.46 Enhanced Accept Synchronous Connection Request Command
+    '''
+
+
+# -----------------------------------------------------------------------------
+@HCI_Command.command(
+    fields=[
+        ('bd_addr', Address.parse_address),
+        ('page_scan_repetition_mode', 1),
+        ('clock_offset', 2),
+    ]
+)
+class HCI_Truncated_Page_Command(HCI_Command):
+    '''
+    See Bluetooth spec @ 7.1.47 Truncated Page Command
+    '''
+
+
+# -----------------------------------------------------------------------------
+@HCI_Command.command(
+    fields=[('bd_addr', Address.parse_address)],
+    return_parameters_fields=[
+        ('status', STATUS_SPEC),
+        ('bd_addr', Address.parse_address),
+    ],
+)
+class HCI_Truncated_Page_Cancel_Command(HCI_Command):
+    '''
+    See Bluetooth spec @ 7.1.48 Truncated Page Cancel Command
+    '''
+
+
+# -----------------------------------------------------------------------------
+@HCI_Command.command(
+    fields=[
+        ('enable', 1),
+        ('lt_addr', 1),
+        ('lpo_allowed', 1),
+        ('packet_type', 2),
+        ('interval_min', 2),
+        ('interval_max', 2),
+        ('supervision_timeout', 2),
+    ],
+    return_parameters_fields=[
+        ('status', STATUS_SPEC),
+        ('lt_addr', 1),
+        ('interval', 2),
+    ],
+)
+class HCI_Set_Connectionless_Peripheral_Broadcast_Command(HCI_Command):
+    '''
+    See Bluetooth spec @ 7.1.49 Set Connectionless Peripheral Broadcast Command
+    '''
+
+
+# -----------------------------------------------------------------------------
+@HCI_Command.command(
+    fields=[
+        ('enable', 1),
+        ('bd_addr', Address.parse_address),
+        ('lt_addr', 1),
+        ('interval', 2),
+        ('clock_offset', 4),
+        ('next_connectionless_peripheral_broadcast_clock', 4),
+        ('supervision_timeout', 2),
+        ('remote_timing_accuracy', 1),
+        ('skip', 1),
+        ('packet_type', 2),
+        ('afh_channel_map', 10),
+    ],
+    return_parameters_fields=[
+        ('status', STATUS_SPEC),
+        ('bd_addr', Address.parse_address),
+        ('lt_addr', 1),
+    ],
+)
+class HCI_Set_Connectionless_Peripheral_Broadcast_Receive_Command(HCI_Command):
+    '''
+    See Bluetooth spec @ 7.1.50 Set Connectionless Peripheral Broadcast Receive Command
+    '''
+
+
+# -----------------------------------------------------------------------------
+class HCI_Start_Synchronization_Train_Command(HCI_Command):
+    '''
+    See Bluetooth spec @ 7.1.51 Start Synchronization Train Command
+    '''
+
+
+# -----------------------------------------------------------------------------
+@HCI_Command.command(
+    fields=[
+        ('bd_addr', Address.parse_address),
+        ('sync_scan_timeout', 2),
+        ('sync_scan_window', 2),
+        ('sync_scan_interval', 2),
+    ],
+)
+class HCI_Receive_Synchronization_Train_Command(HCI_Command):
+    '''
+    See Bluetooth spec @ 7.1.52 Receive Synchronization Train Command
+    '''
+
+
+# -----------------------------------------------------------------------------
+@HCI_Command.command(
+    fields=[
+        ('bd_addr', Address.parse_address),
+        ('c_192', 16),
+        ('r_192', 16),
+        ('c_256', 16),
+        ('r_256', 16),
+    ],
+    return_parameters_fields=[
+        ('status', STATUS_SPEC),
+        ('bd_addr', Address.parse_address),
+    ],
+)
+class HCI_Remote_OOB_Extended_Data_Request_Reply_Command(HCI_Command):
+    '''
+    See Bluetooth spec @ 7.1.53 Remote OOB Extended Data Request Reply Command
+    '''
+
+
 # -----------------------------------------------------------------------------
 @HCI_Command.command(
     [
@@ -2687,6 +2893,20 @@ class HCI_Write_Simple_Pairing_Mode_Command(HCI_Command):
     '''
 
 
+# -----------------------------------------------------------------------------
+@HCI_Command.command(
+    return_parameters_fields=[
+        ('status', STATUS_SPEC),
+        ('c', 16),
+        ('r', 16),
+    ]
+)
+class HCI_Read_Local_OOB_Data_Command(HCI_Command):
+    '''
+    See Bluetooth spec @ 7.3.60 Read Local OOB Data Command
+    '''
+
+
 # -----------------------------------------------------------------------------
 @HCI_Command.command(
     return_parameters_fields=[('status', STATUS_SPEC), ('tx_power', -1)]
@@ -2747,6 +2967,22 @@ class HCI_Write_Authenticated_Payload_Timeout_Command(HCI_Command):
     '''
 
 
+# -----------------------------------------------------------------------------
+@HCI_Command.command(
+    return_parameters_fields=[
+        ('status', STATUS_SPEC),
+        ('c_192', 16),
+        ('r_192', 16),
+        ('c_256', 16),
+        ('r_256', 16),
+    ]
+)
+class HCI_Read_Local_OOB_Extended_Data_Command(HCI_Command):
+    '''
+    See Bluetooth spec @ 7.3.95 Read Local OOB Extended Data Command
+    '''
+
+
 # -----------------------------------------------------------------------------
 @HCI_Command.command(
     return_parameters_fields=[
@@ -5303,6 +5539,14 @@ class HCI_User_Passkey_Request_Event(HCI_Event):
     '''
 
 
+# -----------------------------------------------------------------------------
+@HCI_Event.event([('bd_addr', Address.parse_address)])
+class HCI_Remote_OOB_Data_Request_Event(HCI_Event):
+    '''
+    See Bluetooth spec @ 7.7.44 Remote OOB Data Request Event
+    '''
+
+
 # -----------------------------------------------------------------------------
 @HCI_Event.event([('status', STATUS_SPEC), ('bd_addr', Address.parse_address)])
 class HCI_Simple_Pairing_Complete_Event(HCI_Event):
@@ -5319,6 +5563,14 @@ class HCI_Link_Supervision_Timeout_Changed_Event(HCI_Event):
     '''
 
 
+# -----------------------------------------------------------------------------
+@HCI_Event.event([('handle', 2)])
+class HCI_Enhanced_Flush_Complete_Event(HCI_Event):
+    '''
+    See Bluetooth spec @ 7.7.47 Enhanced Flush Complete Event
+    '''
+
+
 # -----------------------------------------------------------------------------
 @HCI_Event.event([('bd_addr', Address.parse_address), ('passkey', 4)])
 class HCI_User_Passkey_Notification_Event(HCI_Event):
@@ -5327,6 +5579,14 @@ class HCI_User_Passkey_Notification_Event(HCI_Event):
     '''
 
 
+# -----------------------------------------------------------------------------
+@HCI_Event.event([('bd_addr', Address.parse_address), ('notification_type', 1)])
+class HCI_Keypress_Notification_Event(HCI_Event):
+    '''
+    See Bluetooth spec @ 7.7.49 Keypress Notification Event
+    '''
+
+
 # -----------------------------------------------------------------------------
 @HCI_Event.event([('bd_addr', Address.parse_address), ('host_supported_features', 8)])
 class HCI_Remote_Host_Supported_Features_Notification_Event(HCI_Event):

bumble/hfp.py

@@ -18,10 +18,11 @@
 import logging
 import asyncio
 import collections
+from typing import Union
 
+from . import rfcomm
 from .colors import color
 
-
 # -----------------------------------------------------------------------------
 # Logging
 # -----------------------------------------------------------------------------
@@ -34,7 +35,12 @@ 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:
         self.dlc = dlc
         self.buffer = ''
         self.lines = collections.deque()
@@ -42,7 +48,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 +63,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,7 +83,7 @@ class HfpProtocol:
         logger.debug(color(f'<<< {line}', 'green'))
         return line
 
-    async def initialize_service(self):
+    async def initialize_service(self) -> None:
         # Perform Service Level Connection Initialization
         self.send_command_line('AT+BRSF=2072')  # Retrieve Supported Features
         await (self.next_line())

bumble/host.py

@@ -23,6 +23,7 @@ import struct
 from bumble.colors import color
 from bumble.l2cap import L2CAP_PDU
 from bumble.snoop import Snooper
+from bumble import drivers
 
 from typing import Optional
 
@@ -116,6 +117,7 @@ class Host(AbortableEventEmitter):
         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
@@ -141,6 +143,9 @@ 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)
 
@@ -170,7 +175,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()
@@ -178,6 +183,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
         )
@@ -298,7 +312,7 @@ class Host(AbortableEventEmitter):
         if self.snooper:
             self.snooper.snoop(bytes(packet), Snooper.Direction.HOST_TO_CONTROLLER)
 
-        self.hci_sink.on_packet(packet.to_bytes())
+        self.hci_sink.on_packet(bytes(packet))
 
     async def send_command(self, command, check_result=False):
         logger.debug(f'{color("### HOST -> CONTROLLER", "blue")}: {command}')
@@ -350,7 +364,7 @@ class Host(AbortableEventEmitter):
         asyncio.create_task(send_command(command))
 
     def send_l2cap_pdu(self, connection_handle, cid, pdu):
-        l2cap_pdu = L2CAP_PDU(cid, pdu).to_bytes()
+        l2cap_pdu = bytes(L2CAP_PDU(cid, pdu))
 
         # Send the data to the controller via ACL packets
         bytes_remaining = len(l2cap_pdu)

bumble/keys.py

@@ -190,10 +190,44 @@ class KeyStore:
 
 # -----------------------------------------------------------------------------
 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
@@ -208,8 +242,9 @@ class JsonKeyStore(KeyStore):
             self.directory_name = os.path.join(
                 appdirs.user_data_dir(self.APP_NAME, self.APP_AUTHOR), self.KEYS_DIR
             )
+            base_name = self.DEFAULT_BASE_NAME if namespace is None else self.namespace
             json_filename = (
-                f'{self.namespace}.json'.lower().replace(':', '-').replace('/p', '-p')
+                f'{base_name}.json'.lower().replace(':', '-').replace('/p', '-p')
             )
             self.filename = os.path.join(self.directory_name, json_filename)
         else:
@@ -219,11 +254,13 @@ class JsonKeyStore(KeyStore):
         logger.debug(f'JSON keystore: {self.filename}')
 
     @staticmethod
-    def from_device(device: Device) -> Optional[JsonKeyStore]:
-        if not device.config.keystore:
-            return None
-
-        params = device.config.keystore.split(':', 1)[1:]
+    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):
@@ -232,19 +269,31 @@ class JsonKeyStore(KeyStore):
             namespace = str(device.random_address)
         else:
             namespace = JsonKeyStore.DEFAULT_NAMESPACE
-        if params:
-            filename = params[0]
-        else:
-            filename = None
 
         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
@@ -260,53 +309,30 @@ class JsonKeyStore(KeyStore):
         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.setdefault(name, {}).update(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(keys)
+        return PairingKeys.from_dict(key_map[name])
 
 
 # -----------------------------------------------------------------------------

bumble/pandora/host.py

@@ -43,7 +43,8 @@ from bumble.hci import (
     HCI_REMOTE_USER_TERMINATED_CONNECTION_ERROR,
     Address,
 )
-from google.protobuf import any_pb2, empty_pb2  # pytype: disable=pyi-error
+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,

bumble/pandora/security.py

@@ -29,12 +29,9 @@ 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,
-    empty_pb2,
-    wrappers_pb2,
-)  # pytype: disable=pyi-error
-from google.protobuf.wrappers_pb2 import BoolValue  # pytype: disable=pyi-error
+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 (
@@ -513,7 +510,7 @@ class SecurityStorageService(SecurityStorageServicer):
         else:
             is_bonded = False
 
-        return BoolValue(value=is_bonded)
+        return wrappers_pb2.BoolValue(value=is_bonded)
 
     @utils.rpc
     async def DeleteBond(

bumble/rfcomm.py

@@ -19,8 +19,9 @@ import logging
 import asyncio
 
 from pyee import EventEmitter
+from typing import Optional, Tuple, Callable, Dict, Union
 
-from . import core
+from . import core, l2cap
 from .colors import color
 from .core import BT_BR_EDR_TRANSPORT, InvalidStateError, ProtocolError
 
@@ -105,7 +106,7 @@ RFCOMM_DYNAMIC_CHANNEL_NUMBER_END   = 30
 
 
 # -----------------------------------------------------------------------------
-def compute_fcs(buffer):
+def compute_fcs(buffer: bytes) -> int:
     result = 0xFF
     for byte in buffer:
         result = CRC_TABLE[result ^ byte]
@@ -114,7 +115,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,11 +145,11 @@ 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, int, bytes]:
         mcc_type = data[0] >> 2
         c_r = (data[0] >> 1) & 1
         length = data[1]
@@ -154,36 +163,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):
         # Extract fields
         dlci = (data[0] >> 2) & 0x3F
         c_r = (data[0] >> 1) & 0x01
@@ -227,15 +236,23 @@ 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,
     ):
         self.dlci = dlci
         self.cl = cl
@@ -246,7 +263,7 @@ class RFCOMM_MCC_PN:
         self.window_size = window_size
 
     @staticmethod
-    def from_bytes(data):
+    def from_bytes(data: bytes):
         return RFCOMM_MCC_PN(
             dlci=data[0],
             cl=data[1],
@@ -285,7 +302,14 @@ 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):
         self.dlci = dlci
         self.fc = fc
         self.rtc = rtc
@@ -294,7 +318,7 @@ class RFCOMM_MCC_MSC:
         self.dv = dv
 
     @staticmethod
-    def from_bytes(data):
+    def from_bytes(data: bytes):
         return RFCOMM_MCC_MSC(
             dlci=data[0] >> 2,
             fc=data[1] >> 1 & 1,
@@ -347,7 +371,12 @@ class DLC(EventEmitter):
         RESET: 'RESET',
     }
 
-    def __init__(self, multiplexer, dlci, max_frame_size, initial_tx_credits):
+    connection_result: Optional[asyncio.Future]
+    sink: Optional[Callable[[bytes], None]]
+
+    def __init__(
+        self, multiplexer, dlci: int, max_frame_size: int, initial_tx_credits: int
+    ):
         super().__init__()
         self.multiplexer = multiplexer
         self.dlci = dlci
@@ -368,23 +397,23 @@ class DLC(EventEmitter):
         )
 
     @staticmethod
-    def state_name(state):
+    def state_name(state: int) -> str:
         return DLC.STATE_NAMES[state]
 
-    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), "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):
+    def on_sabm_frame(self, _frame) -> None:
         if self.state != DLC.CONNECTING:
             logger.warning(
                 color('!!! received SABM when not in CONNECTING state', 'red')
@@ -404,7 +433,7 @@ class DLC(EventEmitter):
         self.change_state(DLC.CONNECTED)
         self.emit('open')
 
-    def on_ua_frame(self, _frame):
+    def on_ua_frame(self, _frame) -> None:
         if self.state != DLC.CONNECTING:
             logger.warning(
                 color('!!! received SABM when not in CONNECTING state', 'red')
@@ -422,15 +451,15 @@ class DLC(EventEmitter):
         self.change_state(DLC.CONNECTED)
         self.multiplexer.on_dlc_open_complete(self)
 
-    def on_dm_frame(self, frame):
+    def on_dm_frame(self, frame) -> None:
         # TODO: handle all states
         pass
 
-    def on_disc_frame(self, _frame):
+    def on_disc_frame(self, _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
@@ -460,10 +489,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) -> None:
         pass
 
-    def on_mcc_msc(self, c_r, msc):
+    def on_mcc_msc(self, c_r, msc) -> None:
         if c_r:
             # Command
             logger.debug(f'<<< MCC MSC Command: {msc}')
@@ -477,7 +506,7 @@ class DLC(EventEmitter):
             # Response
             logger.debug(f'<<< MCC MSC Response: {msc}')
 
-    def connect(self):
+    def connect(self) -> None:
         if self.state != DLC.INIT:
             raise InvalidStateError('invalid state')
 
@@ -485,7 +514,7 @@ class DLC(EventEmitter):
         self.connection_result = asyncio.get_running_loop().create_future()
         self.send_frame(RFCOMM_Frame.sabm(c_r=self.c_r, dlci=self.dlci))
 
-    def accept(self):
+    def accept(self) -> None:
         if self.state != DLC.INIT:
             raise InvalidStateError('invalid state')
 
@@ -503,13 +532,13 @@ class DLC(EventEmitter):
         self.send_frame(RFCOMM_Frame.uih(c_r=self.c_r, dlci=0, information=mcc))
         self.change_state(DLC.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 +576,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,7 +588,7 @@ class DLC(EventEmitter):
         self.tx_buffer += data
         self.process_tx()
 
-    def drain(self):
+    def drain(self) -> None:
         # TODO
         pass
 
@@ -592,7 +621,13 @@ class Multiplexer(EventEmitter):
         RESET: 'RESET',
     }
 
-    def __init__(self, l2cap_channel, role):
+    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: l2cap.Channel, role: int) -> None:
         super().__init__()
         self.role = role
         self.l2cap_channel = l2cap_channel
@@ -607,20 +642,20 @@ class Multiplexer(EventEmitter):
         l2cap_channel.sink = self.on_pdu
 
     @staticmethod
-    def state_name(state):
+    def state_name(state: int):
         return Multiplexer.STATE_NAMES[state]
 
-    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")}'
         )
         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,18 +675,18 @@ 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):
+    def on_sabm_frame(self, _frame) -> None:
         if self.state != Multiplexer.INIT:
             logger.debug('not in INIT state, ignoring SABM')
             return
         self.change_state(Multiplexer.CONNECTED)
         self.send_frame(RFCOMM_Frame.ua(c_r=1, dlci=0))
 
-    def on_ua_frame(self, _frame):
+    def on_ua_frame(self, _frame) -> None:
         if self.state == Multiplexer.CONNECTING:
             self.change_state(Multiplexer.CONNECTED)
             if self.connection_result:
@@ -663,7 +698,7 @@ class Multiplexer(EventEmitter):
                 self.disconnection_result.set_result(None)
                 self.disconnection_result = None
 
-    def on_dm_frame(self, _frame):
+    def on_dm_frame(self, _frame) -> None:
         if self.state == Multiplexer.OPENING:
             self.change_state(Multiplexer.CONNECTED)
             if self.open_result:
@@ -678,13 +713,13 @@ class Multiplexer(EventEmitter):
         else:
             logger.warning(f'unexpected state for DM: {self}')
 
-    def on_disc_frame(self, _frame):
+    def on_disc_frame(self, _frame) -> None:
         self.change_state(Multiplexer.DISCONNECTED)
         self.send_frame(
             RFCOMM_Frame.ua(c_r=0 if self.role == Multiplexer.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,10 +729,10 @@ 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) -> None:
         pass
 
-    def on_mcc_pn(self, c_r, pn):
+    def on_mcc_pn(self, c_r, pn) -> None:
         if c_r == 1:
             # Command
             logger.debug(f'<<< PN Command: {pn}')
@@ -736,14 +771,14 @@ class Multiplexer(EventEmitter):
             else:
                 logger.warning('ignoring PN response')
 
-    def on_mcc_msc(self, c_r, msc):
+    def on_mcc_msc(self, c_r, 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):
+    async def connect(self) -> None:
         if self.state != Multiplexer.INIT:
             raise InvalidStateError('invalid state')
 
@@ -752,7 +787,7 @@ class Multiplexer(EventEmitter):
         self.send_frame(RFCOMM_Frame.sabm(c_r=1, dlci=0))
         return await self.connection_result
 
-    async def disconnect(self):
+    async def disconnect(self) -> None:
         if self.state != Multiplexer.CONNECTED:
             return
 
@@ -765,7 +800,7 @@ class Multiplexer(EventEmitter):
         )
         await self.disconnection_result
 
-    async def open_dlc(self, channel):
+    async def open_dlc(self, channel: int) -> DLC:
         if self.state != Multiplexer.CONNECTED:
             if self.state == Multiplexer.OPENING:
                 raise InvalidStateError('open already in progress')
@@ -796,7 +831,7 @@ class Multiplexer(EventEmitter):
         self.open_result = None
         return result
 
-    def on_dlc_open_complete(self, dlc):
+    def on_dlc_open_complete(self, dlc: DLC):
         logger.debug(f'DLC [{dlc.dlci}] open complete')
         self.change_state(Multiplexer.CONNECTED)
         if self.open_result:
@@ -808,13 +843,16 @@ class Multiplexer(EventEmitter):
 
 # -----------------------------------------------------------------------------
 class Client:
-    def __init__(self, device, connection):
+    multiplexer: Optional[Multiplexer]
+    l2cap_channel: Optional[l2cap.Channel]
+
+    def __init__(self, device, 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,6 +862,7 @@ 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)
 
@@ -832,7 +871,9 @@ class Client:
 
         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 +884,9 @@ class Client:
 
 # -----------------------------------------------------------------------------
 class Server(EventEmitter):
-    def __init__(self, device):
+    acceptors: Dict[int, Callable[[DLC], None]]
+
+    def __init__(self, device) -> None:
         super().__init__()
         self.device = device
         self.multiplexer = None
@@ -852,7 +895,7 @@ class Server(EventEmitter):
         # Register ourselves with the L2CAP channel manager
         device.register_l2cap_server(RFCOMM_PSM, self.on_connection)
 
-    def listen(self, acceptor, channel=0):
+    def listen(self, acceptor: Callable[[DLC], None], channel: int = 0) -> int:
         if channel:
             if channel in self.acceptors:
                 # Busy
@@ -874,11 +917,11 @@ class Server(EventEmitter):
         self.acceptors[channel] = acceptor
         return channel
 
-    def on_connection(self, l2cap_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
@@ -889,10 +932,10 @@ class Server(EventEmitter):
         # 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/smp.py

@@ -1805,7 +1805,7 @@ class Manager(EventEmitter):
             self.device.abort_on('flush', store_keys())
 
         # Notify the device
-        self.device.on_pairing(session.connection, keys, session.sc)
+        self.device.on_pairing(session.connection, identity_address, keys, session.sc)
 
     def on_pairing_failure(self, session: Session, reason: int) -> None:
         self.device.on_pairing_failure(session.connection, reason)

bumble/transport/usb.py

@@ -206,10 +206,11 @@ async def open_usb_transport(spec):
                     logger.debug('OUT transfer likely already completed')
 
     class UsbPacketSource(asyncio.Protocol, ParserSource):
-        def __init__(self, context, device, acl_in, events_in):
+        def __init__(self, context, device, metadata, acl_in, events_in):
             super().__init__()
             self.context = context
             self.device = device
+            self.metadata = metadata
             self.acl_in = acl_in
             self.events_in = events_in
             self.loop = asyncio.get_running_loop()
@@ -510,6 +511,10 @@ async def open_usb_transport(spec):
             f'events_in=0x{events_in:02X}, '
         )
 
+        device_metadata = {
+            'vendor_id': found.getVendorID(),
+            'product_id': found.getProductID(),
+        }
         device = found.open()
 
         # Auto-detach the kernel driver if supported
@@ -535,7 +540,7 @@ async def open_usb_transport(spec):
             except usb1.USBError:
                 logger.warning('failed to set configuration')
 
-        source = UsbPacketSource(context, device, acl_in, events_in)
+        source = UsbPacketSource(context, device, device_metadata, acl_in, events_in)
         sink = UsbPacketSink(device, acl_out)
         return UsbTransport(context, device, interface, setting, source, sink)
     except usb1.USBError as error:

docs/mkdocs/mkdocs.yml

@@ -36,6 +36,9 @@ nav:
     - HCI Socket: transports/hci_socket.md
     - Android Emulator: transports/android_emulator.md
     - File: transports/file.md
+  - Drivers:
+    - Overview: drivers/index.md
+    - Realtek: drivers/realtek.md
   - API:
     - Guide: api/guide.md
     - Examples: api/examples.md

docs/mkdocs/src/drivers/index.md

@@ -0,0 +1,10 @@
+DRIVERS
+=======
+
+Some Bluetooth controllers require a driver to function properly.
+This may include, for instance, loading a Firmware image or patch,
+loading a configuration.
+
+Drivers included in the module are:
+
+  * [Realtek](realtek.md): Loading of Firmware and Config for Realtek USB dongles.

docs/mkdocs/src/drivers/realtek.md

@@ -0,0 +1,62 @@
+REALTEK DRIVER
+==============
+
+This driver supports loading firmware images and optional config data to 
+USB dongles with a Realtek chipset.
+A number of USB dongles are supported, but likely not all.
+When using a USB dongle, the USB product ID and manufacturer ID are used
+to find whether a matching set of firmware image and config data
+is needed for that specific model. If a match exists, the driver will try
+load the firmware image and, if needed, config data.
+The driver will look for those files by name, in order, in:
+
+  * The directory specified by the environment variable `BUMBLE_RTK_FIRMWARE_DIR`
+    if set.
+  * The directory `<package-dir>/drivers/rtk_fw` where `<package-dir>` is the directory
+    where the `bumble` package is installed.
+  * The current directory.
+
+
+Obtaining Firmware Images and Config Data
+-----------------------------------------
+
+Firmware images and config data may be obtained from a variety of online
+sources.
+To facilitate finding a downloading the, the utility program `bumble-rtk-fw-download`
+may be used.
+
+```
+Usage: bumble-rtk-fw-download [OPTIONS]
+
+  Download RTK firmware images and configs.
+
+Options:
+  --output-dir TEXT               Output directory where the files will be
+                                  saved  [default: .]
+  --source [linux-kernel|realtek-opensource|linux-from-scratch]
+                                  [default: linux-kernel]
+  --single TEXT                   Only download a single image set, by its
+                                  base name
+  --force                         Overwrite files if they already exist
+  --parse                         Parse the FW image after saving
+  --help                          Show this message and exit.
+```
+
+Utility
+-------
+
+The `bumble-rtk-util` utility may be used to interact with a Realtek USB dongle
+and/or firmware images.
+
+```
+Usage: bumble-rtk-util [OPTIONS] COMMAND [ARGS]...
+
+Options:
+  --help  Show this message and exit.
+
+Commands:
+  drop   Drop a firmware image from the USB dongle.
+  info   Get the firmware info from a USB dongle.
+  load   Load a firmware image into the USB dongle.
+  parse  Parse a firmware image.
+```

setup.cfg

@@ -24,16 +24,17 @@ url = https://github.com/google/bumble
 
 [options]
 python_requires = >=3.8
-packages = bumble, bumble.transport, bumble.profiles, bumble.apps, bumble.apps.link_relay, bumble.pandora
+packages = bumble, bumble.transport, bumble.drivers, bumble.profiles, bumble.apps, bumble.apps.link_relay, bumble.pandora, bumble.tools
 package_dir =
     bumble = bumble
     bumble.apps = apps
-include-package-data = True
+    bumble.tools = tools
+include_package_data = True
 install_requires =
-    aiohttp >= 3.8.4; platform_system!='Emscripten'
+    aiohttp ~= 3.8; platform_system!='Emscripten'
     appdirs >= 1.4
     bt-test-interfaces >= 0.0.2
-    click >= 7.1.2; platform_system!='Emscripten'
+    click == 8.1.3; platform_system!='Emscripten'
     cryptography == 35; platform_system!='Emscripten'
     grpcio == 1.51.1; platform_system!='Emscripten'
     humanize >= 4.6.0
@@ -64,6 +65,8 @@ console_scripts =
     bumble-bench = bumble.apps.bench:main
     bumble-speaker = bumble.apps.speaker.speaker:main
     bumble-pandora-server = bumble.apps.pandora_server:main
+    bumble-rtk-util = bumble.tools.rtk_util:main
+    bumble-rtk-fw-download = bumble.tools.rtk_fw_download:main
 
 [options.package_data]
 * = py.typed, *.pyi

tests/keystore_test.py

@@ -0,0 +1,179 @@
+# Copyright 2021-2022 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# -----------------------------------------------------------------------------
+# Imports
+# -----------------------------------------------------------------------------
+import asyncio
+import json
+import logging
+import tempfile
+import os
+
+from bumble.keys import JsonKeyStore, PairingKeys
+
+
+# -----------------------------------------------------------------------------
+# Logging
+# -----------------------------------------------------------------------------
+logger = logging.getLogger(__name__)
+
+
+# -----------------------------------------------------------------------------
+# Tests
+# -----------------------------------------------------------------------------
+
+JSON1 = """
+        {
+            "my_namespace": {
+                "14:7D:DA:4E:53:A8/P": {
+                    "address_type": 0,
+                    "irk": {
+                        "authenticated": false,
+                        "value": "e7b2543b206e4e46b44f9e51dad22bd1"
+                    },
+                    "link_key": {
+                        "authenticated": false,
+                        "value": "0745dd9691e693d9dca740f7d8dfea75"
+                    },
+                    "ltk": {
+                        "authenticated": false,
+                        "value": "d1897ee10016eb1a08e4e037fd54c683"
+                    }
+                }
+            }
+        }
+        """
+
+JSON2 = """
+        {
+            "my_namespace1": {
+            },
+            "my_namespace2": {
+            }
+        }
+        """
+
+JSON3 = """
+        {
+            "my_namespace1": {
+            },
+            "__DEFAULT__": {
+                "14:7D:DA:4E:53:A8/P": {
+                    "address_type": 0,
+                    "irk": {
+                        "authenticated": false,
+                        "value": "e7b2543b206e4e46b44f9e51dad22bd1"
+                    }
+                }
+            }
+        }
+        """
+
+
+# -----------------------------------------------------------------------------
+async def test_basic():
+    with tempfile.NamedTemporaryFile(mode="r+", encoding='utf-8') as file:
+        keystore = JsonKeyStore('my_namespace', file.name)
+        file.write("{}")
+        file.flush()
+
+        keys = await keystore.get_all()
+        assert len(keys) == 0
+
+        keys = PairingKeys()
+        await keystore.update('foo', keys)
+        foo = await keystore.get('foo')
+        assert foo is not None
+        assert foo.ltk is None
+        ltk = bytes([0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15])
+        keys.ltk = PairingKeys.Key(ltk)
+        await keystore.update('foo', keys)
+        foo = await keystore.get('foo')
+        assert foo is not None
+        assert foo.ltk is not None
+        assert foo.ltk.value == ltk
+
+        file.flush()
+        with open(file.name, "r", encoding="utf-8") as json_file:
+            json_data = json.load(json_file)
+            assert 'my_namespace' in json_data
+            assert 'foo' in json_data['my_namespace']
+            assert 'ltk' in json_data['my_namespace']['foo']
+
+
+# -----------------------------------------------------------------------------
+async def test_parsing():
+    with tempfile.NamedTemporaryFile(mode="w", encoding='utf-8') as file:
+        keystore = JsonKeyStore('my_namespace', file.name)
+        file.write(JSON1)
+        file.flush()
+
+        foo = await keystore.get('14:7D:DA:4E:53:A8/P')
+        assert foo is not None
+        assert foo.ltk.value == bytes.fromhex('d1897ee10016eb1a08e4e037fd54c683')
+
+
+# -----------------------------------------------------------------------------
+async def test_default_namespace():
+    with tempfile.NamedTemporaryFile(mode="w", encoding='utf-8') as file:
+        keystore = JsonKeyStore(None, file.name)
+        file.write(JSON1)
+        file.flush()
+
+        all_keys = await keystore.get_all()
+        assert len(all_keys) == 1
+        name, keys = all_keys[0]
+        assert name == '14:7D:DA:4E:53:A8/P'
+        assert keys.irk.value == bytes.fromhex('e7b2543b206e4e46b44f9e51dad22bd1')
+
+    with tempfile.NamedTemporaryFile(mode="w", encoding='utf-8') as file:
+        keystore = JsonKeyStore(None, file.name)
+        file.write(JSON2)
+        file.flush()
+
+        keys = PairingKeys()
+        ltk = bytes([0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15])
+        keys.ltk = PairingKeys.Key(ltk)
+        await keystore.update('foo', keys)
+        file.flush()
+        with open(file.name, "r", encoding="utf-8") as json_file:
+            json_data = json.load(json_file)
+            assert '__DEFAULT__' in json_data
+            assert 'foo' in json_data['__DEFAULT__']
+            assert 'ltk' in json_data['__DEFAULT__']['foo']
+
+    with tempfile.NamedTemporaryFile(mode="w", encoding='utf-8') as file:
+        keystore = JsonKeyStore(None, file.name)
+        file.write(JSON3)
+        file.flush()
+
+        all_keys = await keystore.get_all()
+        assert len(all_keys) == 1
+        name, keys = all_keys[0]
+        assert name == '14:7D:DA:4E:53:A8/P'
+        assert keys.irk.value == bytes.fromhex('e7b2543b206e4e46b44f9e51dad22bd1')
+
+
+# -----------------------------------------------------------------------------
+async def run_tests():
+    await test_basic()
+    await test_parsing()
+    await test_default_namespace()
+
+
+# -----------------------------------------------------------------------------
+if __name__ == '__main__':
+    logging.basicConfig(level=os.environ.get('BUMBLE_LOGLEVEL', 'INFO').upper())
+    asyncio.run(run_tests())

tools/rtk_fw_download.py

@@ -0,0 +1,149 @@
+# 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 logging
+import pathlib
+import urllib.request
+import urllib.error
+
+import click
+
+from bumble.colors import color
+from bumble.drivers import rtk
+from bumble.tools import rtk_util
+
+
+# -----------------------------------------------------------------------------
+# Logging
+# -----------------------------------------------------------------------------
+logger = logging.getLogger(__name__)
+
+
+# -----------------------------------------------------------------------------
+# Constants
+# -----------------------------------------------------------------------------
+LINUX_KERNEL_GIT_SOURCE = (
+    "https://git.kernel.org/pub/scm/linux/kernel/git/firmware/linux-firmware.git/plain/rtl_bt",
+    False,
+)
+REALTEK_OPENSOURCE_SOURCE = (
+    "https://github.com/Realtek-OpenSource/android_hardware_realtek/raw/rtk1395/bt/rtkbt/Firmware/BT",
+    True,
+)
+LINUX_FROM_SCRATCH_SOURCE = (
+    "https://anduin.linuxfromscratch.org/sources/linux-firmware/rtl_bt",
+    False,
+)
+
+# -----------------------------------------------------------------------------
+# Functions
+# -----------------------------------------------------------------------------
+def download_file(base_url, name, remove_suffix):
+    if remove_suffix:
+        name = name.replace(".bin", "")
+
+    url = f"{base_url}/{name}"
+    with urllib.request.urlopen(url) as file:
+        data = file.read()
+        print(f"Downloaded {name}: {len(data)} bytes")
+        return data
+
+
+# -----------------------------------------------------------------------------
+@click.command
+@click.option(
+    "--output-dir",
+    default=".",
+    help="Output directory where the files will be saved",
+    show_default=True,
+)
+@click.option(
+    "--source",
+    type=click.Choice(["linux-kernel", "realtek-opensource", "linux-from-scratch"]),
+    default="linux-kernel",
+    show_default=True,
+)
+@click.option("--single", help="Only download a single image set, by its base name")
+@click.option("--force", is_flag=True, help="Overwrite files if they already exist")
+@click.option("--parse", is_flag=True, help="Parse the FW image after saving")
+def main(output_dir, source, single, force, parse):
+    """Download RTK firmware images and configs."""
+
+    # Check that the output dir exists
+    output_dir = pathlib.Path(output_dir)
+    if not output_dir.is_dir():
+        print("Output dir does not exist or is not a directory")
+        return
+
+    base_url, remove_suffix = {
+        "linux-kernel": LINUX_KERNEL_GIT_SOURCE,
+        "realtek-opensource": REALTEK_OPENSOURCE_SOURCE,
+        "linux-from-scratch": LINUX_FROM_SCRATCH_SOURCE,
+    }[source]
+
+    print("Downloading")
+    print(color("FROM:", "green"), base_url)
+    print(color("TO:", "green"), output_dir)
+
+    if single:
+        images = [(f"{single}_fw.bin", f"{single}_config.bin", True)]
+    else:
+        images = [
+            (driver_info.fw_name, driver_info.config_name, driver_info.config_needed)
+            for driver_info in rtk.Driver.DRIVER_INFOS
+        ]
+
+    for (fw_name, config_name, config_needed) in images:
+        print(color("---", "yellow"))
+        fw_image_out = output_dir / fw_name
+        if not force and fw_image_out.exists():
+            print(color(f"{fw_image_out} already exists, skipping", "red"))
+            continue
+        if config_name:
+            config_image_out = output_dir / config_name
+            if not force and config_image_out.exists():
+                print(color("f{config_out} already exists, skipping", "red"))
+                continue
+
+        try:
+            fw_image = download_file(base_url, fw_name, remove_suffix)
+        except urllib.error.HTTPError as error:
+            print(f"Failed to download {fw_name}: {error}")
+            continue
+
+        config_image = None
+        if config_name:
+            try:
+                config_image = download_file(base_url, config_name, remove_suffix)
+            except urllib.error.HTTPError as error:
+                if config_needed:
+                    print(f"Failed to download {config_name}: {error}")
+                    continue
+                else:
+                    print(f"No config available as {config_name}")
+
+        fw_image_out.write_bytes(fw_image)
+        if parse and config_name:
+            print(color("Parsing:", "cyan"), fw_name)
+            rtk_util.do_parse(fw_image_out)
+        if config_image:
+            config_image_out.write_bytes(config_image)
+
+
+# -----------------------------------------------------------------------------
+if __name__ == '__main__':
+    main()

tools/rtk_util.py

@@ -0,0 +1,161 @@
+# 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 logging
+import asyncio
+import os
+
+import click
+
+from bumble import transport
+from bumble.host import Host
+from bumble.drivers import rtk
+
+# -----------------------------------------------------------------------------
+# Logging
+# -----------------------------------------------------------------------------
+logger = logging.getLogger(__name__)
+
+
+# -----------------------------------------------------------------------------
+def do_parse(firmware_path):
+    with open(firmware_path, 'rb') as firmware_file:
+        firmware_data = firmware_file.read()
+        firmware = rtk.Firmware(firmware_data)
+        print(
+            f"Firmware: version=0x{firmware.version:08X} "
+            f"project_id=0x{firmware.project_id:04X}"
+        )
+        for patch in firmware.patches:
+            print(
+                f"  Patch: chip_id=0x{patch[0]:04X}, "
+                f"{len(patch[1])} bytes, "
+                f"SVN Version={patch[2]:08X}"
+            )
+
+
+# -----------------------------------------------------------------------------
+async def do_load(usb_transport, force):
+    async with await transport.open_transport_or_link(usb_transport) as (
+        hci_source,
+        hci_sink,
+    ):
+        # Create a host to communicate with the device
+        host = Host(hci_source, hci_sink)
+        await host.reset(driver_factory=None)
+
+        # Get the driver.
+        driver = await rtk.Driver.for_host(host, force)
+        if driver is None:
+            if not force:
+                print("Firmware already loaded or no supported driver for this device.")
+                return
+
+        await driver.download_firmware()
+
+
+# -----------------------------------------------------------------------------
+async def do_drop(usb_transport):
+    async with await transport.open_transport_or_link(usb_transport) as (
+        hci_source,
+        hci_sink,
+    ):
+        # Create a host to communicate with the device
+        host = Host(hci_source, hci_sink)
+        await host.reset(driver_factory=None)
+
+        # Tell the device to reset/drop any loaded patch
+        await rtk.Driver.drop_firmware(host)
+
+
+# -----------------------------------------------------------------------------
+async def do_info(usb_transport, force):
+    async with await transport.open_transport(usb_transport) as (
+        hci_source,
+        hci_sink,
+    ):
+        # Create a host to communicate with the device
+        host = Host(hci_source, hci_sink)
+        await host.reset(driver_factory=None)
+
+        # Check if this is a supported device.
+        if not force and not rtk.Driver.check(host):
+            print("USB device not supported by this RTK driver")
+            return
+
+        # Get the driver info.
+        driver_info = await rtk.Driver.driver_info_for_host(host)
+        if driver_info:
+            print(
+                "Driver:\n"
+                f"  ROM:      {driver_info.rom:04X}\n"
+                f"  Firmware: {driver_info.fw_name}\n"
+                f"  Config:   {driver_info.config_name}\n"
+            )
+        else:
+            print("Firmware already loaded or no supported driver for this device.")
+
+
+# -----------------------------------------------------------------------------
+@click.group()
+def main():
+    logging.basicConfig(level=os.environ.get('BUMBLE_LOGLEVEL', 'INFO').upper())
+
+
+@main.command
+@click.argument("firmware_path")
+def parse(firmware_path):
+    """Parse a firmware image."""
+    do_parse(firmware_path)
+
+
+@main.command
+@click.argument("usb_transport")
+@click.option(
+    "--force",
+    is_flag=True,
+    default=False,
+    help="Load even if the USB info doesn't match",
+)
+def load(usb_transport, force):
+    """Load a firmware image into the USB dongle."""
+    asyncio.run(do_load(usb_transport, force))
+
+
+@main.command
+@click.argument("usb_transport")
+def drop(usb_transport):
+    """Drop a firmware image from the USB dongle."""
+    asyncio.run(do_drop(usb_transport))
+
+
+@main.command
+@click.argument("usb_transport")
+@click.option(
+    "--force",
+    is_flag=True,
+    default=False,
+    help="Try to get the device info even if the USB info doesn't match",
+)
+def info(usb_transport, force):
+    """Get the firmware info from a USB dongle."""
+    asyncio.run(do_info(usb_transport, force))
+
+
+# -----------------------------------------------------------------------------
+if __name__ == '__main__':
+    main()