use list comprehension

Make pairing and link mode configurable

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

@@ -24,11 +24,11 @@ jobs:
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
-        python -m pip install build
-        pip install ".[test]"
-    - name: Build package
-      run: |
-        python -m build
+        python -m pip install ".[test,development,documentation]"
     - name: Test with pytest
       run: |
         pytest
+    - name: Build
+      run: |
+        inv build
+        inv mkdocs

README.md

@@ -11,6 +11,8 @@ Bluetooth Stack for Apps, Emulation, Test and Experimentation
 
 <img src="docs/mkdocs/src/images/logo_framed.png" alt="drawing" width="200" height="200"/>
 
+Bumble is a full-featured Bluetooth stack written entirely in Python. It supports most of the common Bluetooth Low Energy (BLE) and Bluetooth Classic (BR/EDR) protocols and profiles, including GAP, L2CAP, ATT, GATT, SMP, SDP, RFCOMM, HFP, HID and A2DP. The stack can be used with physical radios via HCI over USB, UART, or the Linux VHCI, as well as virtual radios, including the virtual Bluetooth support of the Android emulator.
+
 ## Documentation
 
 Browse the pre-built [Online Documentation](https://google.github.io/bumble/), 

apps/controller_info.py

@@ -0,0 +1,105 @@
+# Copyright 2021-2022 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# -----------------------------------------------------------------------------
+# Imports
+# -----------------------------------------------------------------------------
+import asyncio
+import os
+import logging
+import click
+from colors import color
+from bumble.company_ids import COMPANY_IDENTIFIERS
+
+from bumble.core import name_or_number
+from bumble.hci import (
+    map_null_terminated_utf8_string,
+    HCI_LE_SUPPORTED_FEATURES_NAMES,
+    HCI_SUCCESS,
+    HCI_VERSION_NAMES,
+    LMP_VERSION_NAMES,
+    HCI_Command,
+    HCI_Read_BD_ADDR_Command,
+    HCI_READ_BD_ADDR_COMMAND,
+    HCI_Read_Local_Name_Command,
+    HCI_READ_LOCAL_NAME_COMMAND
+)
+from bumble.host import Host
+from bumble.transport import open_transport_or_link
+
+
+# -----------------------------------------------------------------------------
+async def get_classic_info(host):
+    if host.supports_command(HCI_READ_BD_ADDR_COMMAND):
+        response = await host.send_command(HCI_Read_BD_ADDR_Command())
+        if response.return_parameters.status == HCI_SUCCESS:
+            print()
+            print(color('Classic Address:', 'yellow'), response.return_parameters.bd_addr)
+
+    if host.supports_command(HCI_READ_LOCAL_NAME_COMMAND):
+        response = await host.send_command(HCI_Read_Local_Name_Command())
+        if response.return_parameters.status == HCI_SUCCESS:
+            print()
+            print(color('Local Name:', 'yellow'), map_null_terminated_utf8_string(response.return_parameters.local_name))
+
+
+# -----------------------------------------------------------------------------
+async def get_le_info(host):
+    print()
+    print(color('LE Features:', 'yellow'))
+    for feature in host.supported_le_features:
+        print('  ', name_or_number(HCI_LE_SUPPORTED_FEATURES_NAMES, feature))
+
+
+# -----------------------------------------------------------------------------
+async def async_main(transport):
+    print('<<< connecting to HCI...')
+    async with await open_transport_or_link(transport) as (hci_source, hci_sink):
+        print('<<< connected')
+
+        host = Host(hci_source, hci_sink)
+        await host.reset()
+
+        # Print version
+        print(color('Version:', 'yellow'))
+        print(color('  Manufacturer:  ', 'green'), name_or_number(COMPANY_IDENTIFIERS, host.local_version.company_identifier))
+        print(color('  HCI Version:   ', 'green'), name_or_number(HCI_VERSION_NAMES, host.local_version.hci_version))
+        print(color('  HCI Subversion:', 'green'), host.local_version.hci_subversion)
+        print(color('  LMP Version:   ', 'green'), name_or_number(LMP_VERSION_NAMES, host.local_version.lmp_version))
+        print(color('  LMP Subversion:', 'green'), host.local_version.lmp_subversion)
+
+        # Get the Classic info
+        await get_classic_info(host)
+
+        # Get the LE info
+        await get_le_info(host)
+
+        # Print the list of commands supported by the controller
+        print()
+        print(color('Supported Commands:', 'yellow'))
+        for command in host.supported_commands:
+            print('  ', HCI_Command.command_name(command))
+
+
+# -----------------------------------------------------------------------------
+@click.command()
+@click.argument('transport')
+def main(transport):
+    logging.basicConfig(level = os.environ.get('BUMBLE_LOGLEVEL', 'WARNING').upper())
+    asyncio.run(async_main(transport))
+
+
+# -----------------------------------------------------------------------------
+if __name__ == '__main__':
+    main()

apps/pair.py

@@ -44,7 +44,7 @@ from bumble.att import (
 
 # -----------------------------------------------------------------------------
 class Delegate(PairingDelegate):
-    def __init__(self, connection, capability_string, prompt):
+    def __init__(self, mode, connection, capability_string, prompt):
         super().__init__({
             'keyboard':         PairingDelegate.KEYBOARD_INPUT_ONLY,
             'display':          PairingDelegate.DISPLAY_OUTPUT_ONLY,
@@ -53,6 +53,7 @@ class Delegate(PairingDelegate):
             'none':             PairingDelegate.NO_OUTPUT_NO_INPUT
         }[capability_string.lower()])
 
+        self.mode      = mode
         self.peer      = Peer(connection)
         self.peer_name = None
         self.prompt    = prompt
@@ -64,7 +65,7 @@ class Delegate(PairingDelegate):
 
         # Try to get the peer's name
         if self.peer:
-            peer_name = await get_peer_name(self.peer)
+            peer_name = await get_peer_name(self.peer, self.mode)
             self.peer_name = f'{peer_name or ""} [{self.peer.connection.peer_address}]'
         else:
             self.peer_name = '[?]'
@@ -91,7 +92,7 @@ class Delegate(PairingDelegate):
             # Accept silently
             return True
 
-    async def compare_numbers(self, number):
+    async def compare_numbers(self, number, digits):
         await self.update_peer_name()
 
         # Wait a bit to allow some of the log lines to print before we prompt
@@ -102,7 +103,7 @@ class Delegate(PairingDelegate):
         print(color(f'### Pairing with {self.peer_name}', 'yellow'))
         print(color('###-----------------------------------', 'yellow'))
         while True:
-            response = await aioconsole.ainput(color(f'>>> Does the other device display {number:06}? ', 'yellow'))
+            response = await aioconsole.ainput(color(f'>>> Does the other device display {number:0{digits}}? ', 'yellow'))
             response = response.lower().strip()
             if response == 'yes':
                 return True
@@ -125,7 +126,7 @@ class Delegate(PairingDelegate):
             except ValueError:
                 pass
 
-    async def display_number(self, number):
+    async def display_number(self, number, digits):
         await self.update_peer_name()
 
         # Wait a bit to allow some of the log lines to print before we prompt
@@ -134,19 +135,23 @@ class Delegate(PairingDelegate):
         # Display a PIN code
         print(color('###-----------------------------------', 'yellow'))
         print(color(f'### Pairing with {self.peer_name}', 'yellow'))
-        print(color(f'### PIN: {number:06}', 'yellow'))
+        print(color(f'### PIN: {number:0{digits}}', 'yellow'))
         print(color('###-----------------------------------', 'yellow'))
 
 
 # -----------------------------------------------------------------------------
-async def get_peer_name(peer):
-    services = await peer.discover_service(GATT_GENERIC_ACCESS_SERVICE)
-    if not services:
-        return None
+async def get_peer_name(peer, mode):
+    if mode == 'classic':
+        return await peer.request_name()
+    else:
+        # Try to get the peer name from GATT
+        services = await peer.discover_service(GATT_GENERIC_ACCESS_SERVICE)
+        if not services:
+            return None
 
-    values = await peer.read_characteristics_by_uuid(GATT_DEVICE_NAME_CHARACTERISTIC, services[0])
-    if values:
-        return values[0].decode('utf-8')
+        values = await peer.read_characteristics_by_uuid(GATT_DEVICE_NAME_CHARACTERISTIC, services[0])
+        if values:
+            return values[0].decode('utf-8')
 
 
 # -----------------------------------------------------------------------------
@@ -224,9 +229,22 @@ def on_pairing_failure(reason):
 
 
 # -----------------------------------------------------------------------------
-async def pair(sc, mitm, bond, io, prompt, request, print_keys, keystore_file, device_config, transport, address_or_name):
+async def pair(
+    mode,
+    sc,
+    mitm,
+    bond,
+    io,
+    prompt,
+    request,
+    print_keys,
+    keystore_file,
+    device_config,
+    hci_transport,
+    address_or_name
+):
     print('<<< connecting to HCI...')
-    async with await open_transport_or_link(transport) as (hci_source, hci_sink):
+    async with await open_transport_or_link(hci_transport) as (hci_source, hci_sink):
         print('<<< connected')
 
         # Create a device to manage the host
@@ -245,19 +263,25 @@ async def pair(sc, mitm, bond, io, prompt, request, print_keys, keystore_file, d
 
         # Expose a GATT characteristic that can be used to trigger pairing by
         # responding with an authentication error when read
-        device.add_service(
-            Service(
-                '50DB505C-8AC4-4738-8448-3B1D9CC09CC5',
-                [
-                    Characteristic(
-                        '552957FB-CF1F-4A31-9535-E78847E1A714',
-                        Characteristic.READ | Characteristic.WRITE,
-                        Characteristic.READABLE | Characteristic.WRITEABLE,
-                        CharacteristicValue(read=read_with_error, write=write_with_error)
-                    )
-                ]
+        if mode == 'le':
+            device.add_service(
+                Service(
+                    '50DB505C-8AC4-4738-8448-3B1D9CC09CC5',
+                    [
+                        Characteristic(
+                            '552957FB-CF1F-4A31-9535-E78847E1A714',
+                            Characteristic.READ | Characteristic.WRITE,
+                            Characteristic.READABLE | Characteristic.WRITEABLE,
+                            CharacteristicValue(read=read_with_error, write=write_with_error)
+                        )
+                    ]
+                )
             )
-        )
+
+        # Select LE or Classic
+        if mode == 'classic':
+            device.classic_enabled = True
+            device.le_enabled = False
 
         # Get things going
         await device.power_on()
@@ -267,7 +291,7 @@ async def pair(sc, mitm, bond, io, prompt, request, print_keys, keystore_file, d
             sc,
             mitm,
             bond,
-            Delegate(connection, io, prompt)
+            Delegate(mode, connection, io, prompt)
         )
 
         # Connect to a peer or wait for a connection
@@ -278,10 +302,14 @@ async def pair(sc, mitm, bond, io, prompt, request, print_keys, keystore_file, d
 
             if not request:
                 try:
-                    await connection.pair()
+                    if mode == 'le':
+                        await connection.pair()
+                    else:
+                        await connection.authenticate()
+                    return
+                except ProtocolError as error:
+                    print(color(f'Pairing failed: {error}', 'red'))
                     return
-                except ProtocolError:
-                    pass
         else:
             # Advertise so that peers can find us and connect
             await device.start_advertising(auto_restart=True)
@@ -291,6 +319,7 @@ async def pair(sc, mitm, bond, io, prompt, request, print_keys, keystore_file, d
 
 # -----------------------------------------------------------------------------
 @click.command()
+@click.option('--mode', type=click.Choice(['le', 'classic']), default='le', show_default=True)
 @click.option('--sc', type=bool, default=True, help='Use the Secure Connections protocol', show_default=True)
 @click.option('--mitm', type=bool, default=True, help='Request MITM protection', show_default=True)
 @click.option('--bond', type=bool, default=True, help='Enable bonding', show_default=True)
@@ -300,11 +329,11 @@ async def pair(sc, mitm, bond, io, prompt, request, print_keys, keystore_file, d
 @click.option('--print-keys', is_flag=True, help='Print the bond keys before pairing')
 @click.option('--keystore-file', help='File in which to store the pairing keys')
 @click.argument('device-config')
-@click.argument('transport')
+@click.argument('hci_transport')
 @click.argument('address-or-name', required=False)
-def main(sc, mitm, bond, io, prompt, request, print_keys, keystore_file, device_config, transport, address_or_name):
+def main(mode, sc, mitm, bond, io, prompt, request, print_keys, keystore_file, device_config, hci_transport, address_or_name):
     logging.basicConfig(level = os.environ.get('BUMBLE_LOGLEVEL', 'INFO').upper())
-    asyncio.run(pair(sc, mitm, bond, io, prompt, request, print_keys, keystore_file, device_config, transport, address_or_name))
+    asyncio.run(pair(mode, sc, mitm, bond, io, prompt, request, print_keys, keystore_file, device_config, hci_transport, address_or_name))
 
 
 # -----------------------------------------------------------------------------

apps/show.py

@@ -20,7 +20,7 @@ import click
 from colors import color
 
 from bumble import hci
-from bumble.transport import PacketReader
+from bumble.transport.common import PacketReader
 from bumble.helpers import PacketTracer
 
 

bumble/controller.py

@@ -77,7 +77,7 @@ class Controller:
         self.le_features                  = bytes.fromhex('ff49010000000000')
         self.le_states                    = bytes.fromhex('ffff3fffff030000')
         self.avertising_channel_tx_power  = 0
-        self.white_list_size              = 8
+        self.filter_accept_list_size      = 8
         self.resolving_list_size          = 8
         self.supported_max_tx_octets      = 27
         self.supported_max_tx_time        = 10000  # microseconds
@@ -731,27 +731,27 @@ class Controller:
         '''
         return bytes([HCI_SUCCESS])
 
-    def on_hci_le_read_white_list_size_command(self, command):
+    def on_hci_le_read_filter_accept_list_size_command(self, command):
         '''
-        See Bluetooth spec Vol 2, Part E - 7.8.14 LE Read White List Size Command
+        See Bluetooth spec Vol 2, Part E - 7.8.14 LE Read Filter Accept List Size Command
         '''
-        return bytes([HCI_SUCCESS, self.white_list_size])
+        return bytes([HCI_SUCCESS, self.filter_accept_list_size])
 
-    def on_hci_le_clear_white_list_command(self, command):
+    def on_hci_le_clear_filter_accept_list_command(self, command):
         '''
-        See Bluetooth spec Vol 2, Part E - 7.8.15 LE Clear White List Command
+        See Bluetooth spec Vol 2, Part E - 7.8.15 LE Clear Filter Accept List Command
         '''
         return bytes([HCI_SUCCESS])
 
-    def on_hci_le_add_device_to_white_list_command(self, command):
+    def on_hci_le_add_device_to_filter_accept_list_command(self, command):
         '''
-        See Bluetooth spec Vol 2, Part E - 7.8.16 LE Add Device To White List Command
+        See Bluetooth spec Vol 2, Part E - 7.8.16 LE Add Device To Filter Accept List Command
         '''
         return bytes([HCI_SUCCESS])
 
-    def on_hci_le_remove_device_from_white_list_command(self, command):
+    def on_hci_le_remove_device_from_filter_accept_list_command(self, command):
         '''
-        See Bluetooth spec Vol 2, Part E - 7.8.17 LE Remove Device From White List Command
+        See Bluetooth spec Vol 2, Part E - 7.8.17 LE Remove Device From Filter Accept List Command
         '''
         return bytes([HCI_SUCCESS])
 
@@ -780,9 +780,9 @@ class Controller:
         '''
         return bytes([HCI_SUCCESS]) + struct.pack('Q', random.randint(0, 1 << 64))
 
-    def on_hci_le_start_encryption_command(self, command):
+    def on_hci_le_enable_encryption_command(self, command):
         '''
-        See Bluetooth spec Vol 2, Part E - 7.8.24 LE Start Encryption Command
+        See Bluetooth spec Vol 2, Part E - 7.8.24 LE Enable Encryption Command
         '''
 
         # Check the parameters

bumble/device.py

@@ -137,6 +137,10 @@ class Peer:
     def get_characteristics_by_uuid(self, uuid, service = None):
         return self.gatt_client.get_characteristics_by_uuid(uuid, service)
 
+    # [Classic only]
+    async def request_name(self):
+        return await self.connection.request_remote_name()
+
     def __str__(self):
         return f'{self.connection.peer_address} as {self.connection.role_name}'
 
@@ -176,6 +180,7 @@ class Connection(CompositeEventEmitter):
         self.transport               = transport
         self.peer_address            = peer_address
         self.peer_resolvable_address = peer_resolvable_address
+        self.peer_name               = None  # Classic only
         self.role                    = role
         self.parameters              = parameters
         self.encryption              = 0
@@ -231,6 +236,10 @@ class Connection(CompositeEventEmitter):
             supervision_timeout
         )
 
+    # [Classic only]
+    async def request_remote_name(self):
+        return await self.device.request_remote_name(self)
+
     def __str__(self):
         return f'Connection(handle=0x{self.handle:04X}, role={self.role_name}, address={self.peer_address})'
 
@@ -245,39 +254,48 @@ class DeviceConfiguration:
         self.scan_response_data       = DEVICE_DEFAULT_SCAN_RESPONSE_DATA
         self.advertising_interval_min = DEVICE_DEFAULT_ADVERTISING_INTERVAL
         self.advertising_interval_max = DEVICE_DEFAULT_ADVERTISING_INTERVAL
+        self.le_enabled               = True
+        # LE host enable 2nd parameter
+        self.le_simultaneous_enabled  = True
+        self.classic_sc_enabled       = True
+        self.classic_ssp_enabled      = True
         self.advertising_data = bytes(
             AdvertisingData([(AdvertisingData.COMPLETE_LOCAL_NAME, bytes(self.name, 'utf-8'))])
         )
         self.irk      = bytes(16)  # This really must be changed for any level of security
         self.keystore = None
 
+    def load_from_dict(self, config):
+        # Load simple properties
+        self.name = config.get('name', self.name)
+        self.address = Address(config.get('address', self.address))
+        self.class_of_device = config.get('class_of_device', self.class_of_device)
+        self.advertising_interval_min = config.get('advertising_interval', self.advertising_interval_min)
+        self.advertising_interval_max = self.advertising_interval_min
+        self.keystore                 = config.get('keystore')
+        self.le_enabled               = config.get('le_enabled', self.le_enabled)
+        self.le_simultaneous_enabled  = config.get('le_simultaneous_enabled', self.le_simultaneous_enabled)
+        self.classic_sc_enabled       = config.get('classic_sc_enabled', self.classic_sc_enabled)
+        self.classic_ssp_enabled      = config.get('classic_ssp_enabled', self.classic_ssp_enabled)
+
+        # Load or synthesize an IRK
+        irk = config.get('irk')
+        if irk:
+            self.irk = bytes.fromhex(irk)
+        else:
+            # Construct an IRK from the address bytes
+            # NOTE: this is not secure, but will always give the same IRK for the same address
+            address_bytes = bytes(self.address)
+            self.irk = (address_bytes * 3)[:16]
+
+        # Load advertising data
+        advertising_data = config.get('advertising_data')
+        if advertising_data:
+            self.advertising_data = bytes.fromhex(advertising_data)
+
     def load_from_file(self, filename):
         with open(filename, 'r') as file:
-            config = json.load(file)
-
-            # Load simple properties
-            self.name = config.get('name', self.name)
-            self.address = Address(config.get('address', self.address))
-            self.class_of_device = config.get('class_of_device', self.class_of_device)
-            self.advertising_interval_min = config.get('advertising_interval', self.advertising_interval_min)
-            self.advertising_interval_max = self.advertising_interval_min
-            self.keystore = config.get('keystore')
-
-            # Load or synthesize an IRK
-            irk = config.get('irk')
-            if irk:
-                self.irk = bytes.fromhex(irk)
-            else:
-                # Construct an IRK from the address bytes
-                # NOTE: this is not secure, but will always give the same IRK for the same address
-                address_bytes = bytes(self.address)
-                self.irk = (address_bytes * 3)[:16]
-
-            # Load advertising data
-            advertising_data = config.get('advertising_data')
-            if advertising_data:
-                self.advertising_data = bytes.fromhex(advertising_data)
-
+            self.load_from_dict(json.load(file))
 
 # -----------------------------------------------------------------------------
 # Decorators used with the following Device class
@@ -285,14 +303,25 @@ class DeviceConfiguration:
 #  within a class requires unnecessarily complicated acrobatics)
 # -----------------------------------------------------------------------------
 
+
 # Decorator that converts the first argument from a connection handle to a connection
 def with_connection_from_handle(function):
     @functools.wraps(function)
     def wrapper(self, connection_handle, *args, **kwargs):
         if (connection := self.lookup_connection(connection_handle)) is None:
-            logger.warn(f'no connection found for handle 0x{connection_handle:04X}')
-            return
-        function(self, connection, *args, **kwargs)
+            raise ValueError('no connection for handle')
+        return function(self, connection, *args, **kwargs)
+    return wrapper
+
+
+# Decorator that converts the first argument from a bluetooth address to a connection
+def with_connection_from_address(function):
+    @functools.wraps(function)
+    def wrapper(self, address, *args, **kwargs):
+        for connection in self.connections.values():
+            if connection.peer_address == address:
+                return function(self, connection, *args, **kwargs)
+        raise ValueError('no connection for address')
     return wrapper
 
 
@@ -368,7 +397,6 @@ class Device(CompositeEventEmitter):
         self.connecting               = False
         self.disconnecting            = False
         self.connections              = {}  # Connections, by connection handle
-        self.le_enabled               = True
         self.classic_enabled          = False
         self.discoverable             = False
         self.connectable              = False
@@ -388,6 +416,10 @@ class Device(CompositeEventEmitter):
         self.advertising_interval_max = config.advertising_interval_max
         self.keystore                 = keys.KeyStore.create_for_device(config)
         self.irk                      = config.irk
+        self.le_enabled               = config.le_enabled
+        self.le_simultaneous_enabled  = config.le_simultaneous_enabled
+        self.classic_ssp_enabled      = config.classic_ssp_enabled
+        self.classic_sc_enabled       = config.classic_sc_enabled
 
         # If a name is passed, override the name from the config
         if name:
@@ -453,6 +485,11 @@ class Device(CompositeEventEmitter):
         if connection := self.connections.get(connection_handle):
             return connection
 
+    def find_connection_by_bd_addr(self, bd_addr):
+        for connection in self.connections.values():
+            if connection.peer_address == bd_addr:
+                return connection
+
     def register_l2cap_server(self, psm, server):
         self.l2cap_channel_manager.register_server(psm, server)
 
@@ -480,6 +517,11 @@ class Device(CompositeEventEmitter):
             logger.debug(color(f'BD_ADDR: {response.return_parameters.bd_addr}', 'yellow'))
             self.public_address = response.return_parameters.bd_addr
 
+
+        await self.send_command(HCI_Write_LE_Host_Support_Command(
+            le_supported_host = int(self.le_enabled),
+            simultaneous_le_host = int(self.le_simultaneous_enabled),
+        ))
         if self.le_enabled:
             # Set the controller address
             await self.send_command(HCI_LE_Set_Random_Address_Command(
@@ -517,7 +559,12 @@ class Device(CompositeEventEmitter):
                 HCI_Write_Class_Of_Device_Command(class_of_device = self.class_of_device)
             )
             await self.send_command(
-                HCI_Write_Simple_Pairing_Mode_Command(simple_pairing_mode = 0x01)
+                HCI_Write_Simple_Pairing_Mode_Command(
+                    simple_pairing_mode=int(self.classic_ssp_enabled))
+            )
+            await self.send_command(
+                HCI_Write_Secure_Connections_Host_Support_Command(
+                    secure_connections_host_support=int(self.classic_sc_enabled))
             )
 
         # Let the SMP manager know about the address
@@ -727,7 +774,7 @@ class Device(CompositeEventEmitter):
             try:
                 peer_address = Address(peer_address)
             except ValueError:
-                # If the address is not parssable, assume it is a name instead
+                # If the address is not parsable, assume it is a name instead
                 logger.debug('looking for peer by name')
                 peer_address = await self.find_peer_by_name(peer_address, transport)
 
@@ -792,8 +839,8 @@ class Device(CompositeEventEmitter):
     async def disconnect(self, connection, reason):
         # Create a future so that we can wait for the disconnection's result
         pending_disconnection = asyncio.get_running_loop().create_future()
-        self.on('disconnection', pending_disconnection.set_result)
-        self.on('disconnection_failure', pending_disconnection.set_exception)
+        connection.on('disconnection', pending_disconnection.set_result)
+        connection.on('disconnection_failure', pending_disconnection.set_exception)
 
         # Request a disconnection
         result = await self.send_command(HCI_Disconnect_Command(connection_handle = connection.handle, reason = reason))
@@ -806,8 +853,8 @@ class Device(CompositeEventEmitter):
             self.disconnecting = True
             return await pending_disconnection
         finally:
-            self.remove_listener('disconnection', pending_disconnection.set_result)
-            self.remove_listener('disconnection_failure', pending_disconnection.set_exception)
+            connection.remove_listener('disconnection', pending_disconnection.set_result)
+            connection.remove_listener('disconnection_failure', pending_disconnection.set_exception)
             self.disconnecting = False
 
     async def update_connection_parameters(
@@ -936,13 +983,13 @@ class Device(CompositeEventEmitter):
         # Set up event handlers
         pending_authentication = asyncio.get_running_loop().create_future()
 
-        def on_authentication_complete():
+        def on_authentication():
             pending_authentication.set_result(None)
 
-        def on_authentication_failure(error):
-            pending_authentication.set_exception(error)
+        def on_authentication_failure(error_code):
+            pending_authentication.set_exception(HCI_Error(error_code))
 
-        connection.on('connection_authentication_complete', on_authentication_complete)
+        connection.on('connection_authentication', on_authentication)
         connection.on('connection_authentication_failure',  on_authentication_failure)
 
         # Request the authentication
@@ -957,7 +1004,7 @@ class Device(CompositeEventEmitter):
             # Wait for the authentication to complete
             await pending_authentication
         finally:
-            connection.remove_listener('connection_authentication_complete', on_authentication_complete)
+            connection.remove_listener('connection_authentication', on_authentication)
             connection.remove_listener('connection_authentication_failure',  on_authentication_failure)
 
     async def encrypt(self, connection):
@@ -999,7 +1046,7 @@ class Device(CompositeEventEmitter):
                     raise InvalidStateError('only centrals can start encryption')
 
                 result = await self.send_command(
-                    HCI_LE_Start_Encryption_Command(
+                    HCI_LE_Enable_Encryption_Command(
                         connection_handle     = connection.handle,
                         random_number         = rand,
                         encrypted_diversifier = ediv,
@@ -1008,7 +1055,7 @@ class Device(CompositeEventEmitter):
                 )
 
                 if result.status != HCI_COMMAND_STATUS_PENDING:
-                    logger.warn(f'HCI_LE_Start_Encryption_Command failed: {HCI_Constant.error_name(result.status)}')
+                    logger.warn(f'HCI_LE_Enable_Encryption_Command failed: {HCI_Constant.error_name(result.status)}')
                     raise HCI_Error(result.status)
             else:
                 result = await self.send_command(
@@ -1028,6 +1075,40 @@ class Device(CompositeEventEmitter):
             connection.remove_listener('connection_encryption_change',  on_encryption_change)
             connection.remove_listener('connection_encryption_failure', on_encryption_failure)
 
+    # [Classic only]
+    async def request_remote_name(self, connection):
+        # Set up event handlers
+        pending_name = asyncio.get_running_loop().create_future()
+
+        def on_remote_name():
+            pending_name.set_result(connection.peer_name)
+
+        def on_remote_name_failure(error_code):
+            pending_name.set_exception(HCI_Error(error_code))
+
+        connection.on('remote_name', on_remote_name)
+        connection.on('remote_name_failure', on_remote_name_failure)
+
+        try:
+            result = await self.send_command(
+                HCI_Remote_Name_Request_Command(
+                    bd_addr                   = connection.peer_address,
+                    page_scan_repetition_mode = HCI_Remote_Name_Request_Command.R0,  # TODO investigate other options
+                    reserved                  = 0,
+                    clock_offset              = 0  # TODO investigate non-0 values
+                )
+            )
+
+            if result.status != HCI_COMMAND_STATUS_PENDING:
+                logger.warn(f'HCI_Set_Connection_Encryption_Command failed: {HCI_Constant.error_name(result.status)}')
+                raise HCI_Error(result.status)
+
+            # Wait for the result
+            return await pending_name
+        finally:
+            connection.remove_listener('remote_name', on_remote_name)
+            connection.remove_listener('remote_name_failure', on_remote_name_failure)
+
     # [Classic only]
     @host_event_handler
     def on_link_key(self, bd_addr, link_key, key_type):
@@ -1123,14 +1204,15 @@ class Device(CompositeEventEmitter):
             asyncio.create_task(self.start_advertising(auto_restart=self.auto_restart_advertising))
 
     @host_event_handler
-    def on_disconnection_failure(self, error_code):
+    @with_connection_from_handle
+    def on_disconnection_failure(self, connection, error_code):
         logger.debug(f'*** Disconnection failed: {error_code}')
         error = ConnectionError(
             error_code,
             'hci',
             HCI_Constant.error_name(error_code)
         )
-        self.emit('disconnection_failure', error)
+        connection.emit('disconnection_failure', error)
 
     @host_event_handler
     @AsyncRunner.run_in_task()
@@ -1141,10 +1223,10 @@ class Device(CompositeEventEmitter):
 
     @host_event_handler
     @with_connection_from_handle
-    def on_connection_authentication_complete(self, connection):
-        logger.debug(f'*** Connection Authentication Complete: [0x{connection.handle:04X}] {connection.peer_address} as {connection.role_name}')
+    def on_connection_authentication(self, connection):
+        logger.debug(f'*** Connection Authentication: [0x{connection.handle:04X}] {connection.peer_address} as {connection.role_name}')
         connection.authenticated = True
-        connection.emit('connection_authentication_complete')
+        connection.emit('connection_authentication')
 
     @host_event_handler
     @with_connection_from_handle
@@ -1152,6 +1234,132 @@ class Device(CompositeEventEmitter):
         logger.debug(f'*** Connection Authentication Failure: [0x{connection.handle:04X}] {connection.peer_address} as {connection.role_name}, error={error}')
         connection.emit('connection_authentication_failure', error)
 
+    # [Classic only]
+    @host_event_handler
+    @with_connection_from_address
+    def on_authentication_io_capability_request(self, connection):
+        # Ask what the pairing config should be for this connection
+        pairing_config = self.pairing_config_factory(connection)
+
+        # Map the SMP IO capability to a Classic IO capability
+        io_capability = {
+            smp.SMP_DISPLAY_ONLY_IO_CAPABILITY:       HCI_DISPLAY_ONLY_IO_CAPABILITY,
+            smp.SMP_DISPLAY_YES_NO_IO_CAPABILITY:     HCI_DISPLAY_YES_NO_IO_CAPABILITY,
+            smp.SMP_KEYBOARD_ONLY_IO_CAPABILITY:      HCI_KEYBOARD_ONLY_IO_CAPABILITY,
+            smp.SMP_NO_INPUT_NO_OUTPUT_IO_CAPABILITY: HCI_NO_INPUT_NO_OUTPUT_IO_CAPABILITY,
+            smp.SMP_KEYBOARD_DISPLAY_IO_CAPABILITY:   HCI_DISPLAY_YES_NO_IO_CAPABILITY
+        }.get(pairing_config.delegate.io_capability)
+
+        if io_capability is None:
+            logger.warning(f'cannot map IO capability ({pairing_config.delegate.io_capability}')
+            io_capability = HCI_NO_INPUT_NO_OUTPUT_IO_CAPABILITY
+
+        # Compute the authentication requirements
+        authentication_requirements = (
+            # No Bonding
+            (
+                HCI_MITM_NOT_REQUIRED_NO_BONDING_AUTHENTICATION_REQUIREMENTS,
+                HCI_MITM_REQUIRED_NO_BONDING_AUTHENTICATION_REQUIREMENTS
+            ),
+            # General Bonding
+            (
+                HCI_MITM_NOT_REQUIRED_GENERAL_BONDING_AUTHENTICATION_REQUIREMENTS,
+                HCI_MITM_REQUIRED_GENERAL_BONDING_AUTHENTICATION_REQUIREMENTS
+            )
+        )[1 if pairing_config.bonding else 0][1 if pairing_config.mitm else 0]
+
+        # Respond
+        self.host.send_command_sync(
+            HCI_IO_Capability_Request_Reply_Command(
+                bd_addr                     = connection.peer_address,
+                io_capability               = io_capability,
+                oob_data_present            = 0x00,  # Not present
+                authentication_requirements = authentication_requirements
+            )
+        )
+
+    # [Classic only]
+    @host_event_handler
+    @with_connection_from_address
+    def on_authentication_user_confirmation_request(self, connection, code):
+        # Ask what the pairing config should be for this connection
+        pairing_config = self.pairing_config_factory(connection)
+
+        can_confirm = pairing_config.delegate.io_capability not in {
+            smp.SMP_NO_INPUT_NO_OUTPUT_IO_CAPABILITY,
+            smp.SMP_DISPLAY_ONLY_IO_CAPABILITY
+        }
+
+        # Respond
+        if can_confirm and pairing_config.delegate:
+            async def compare_numbers():
+                numbers_match = await pairing_config.delegate.compare_numbers(code, digits=6)
+                if numbers_match:
+                    self.host.send_command_sync(
+                        HCI_User_Confirmation_Request_Reply_Command(bd_addr=connection.peer_address)
+                    )
+                else:
+                    self.host.send_command_sync(
+                        HCI_User_Confirmation_Request_Negative_Reply_Command(bd_addr=connection.peer_address)
+                    )
+
+            asyncio.create_task(compare_numbers())
+        else:
+            self.host.send_command_sync(
+                HCI_User_Confirmation_Request_Reply_Command(bd_addr=connection.peer_address)
+            )
+
+    # [Classic only]
+    @host_event_handler
+    @with_connection_from_address
+    def on_authentication_user_passkey_request(self, connection):
+        # Ask what the pairing config should be for this connection
+        pairing_config = self.pairing_config_factory(connection)
+
+        can_input = pairing_config.delegate.io_capability in {
+            smp.SMP_KEYBOARD_ONLY_IO_CAPABILITY,
+            smp.SMP_KEYBOARD_DISPLAY_IO_CAPABILITY
+        }
+
+        # Respond
+        if can_input and pairing_config.delegate:
+            async def get_number():
+                number = await pairing_config.delegate.get_number()
+                if number is not None:
+                    self.host.send_command_sync(
+                        HCI_User_Passkey_Request_Reply_Command(
+                            bd_addr       = connection.peer_address,
+                            numeric_value = number)
+                    )
+                else:
+                    self.host.send_command_sync(
+                        HCI_User_Passkey_Request_Negative_Reply_Command(bd_addr=connection.peer_address)
+                    )
+
+            asyncio.create_task(get_number())
+        else:
+            self.host.send_command_sync(
+                HCI_User_Passkey_Request_Negative_Reply_Command(bd_addr=connection.peer_address)
+            )
+
+    # [Classic only]
+    @host_event_handler
+    @with_connection_from_address
+    def on_remote_name(self, connection, remote_name):
+        # Try to decode the name
+        try:
+            connection.peer_name = remote_name.decode('utf-8')
+            connection.emit('remote_name')
+        except UnicodeDecodeError as error:
+            logger.warning('peer name is not valid UTF-8')
+            connection.emit('remote_name_failure', error)
+
+    # [Classic only]
+    @host_event_handler
+    @with_connection_from_address
+    def on_remote_name_failure(self, connection, error):
+        connection.emit('remote_name_failure', error)
+
     @host_event_handler
     @with_connection_from_handle
     def on_connection_encryption_change(self, connection, encryption):

bumble/host.py

@@ -81,10 +81,13 @@ class Host(EventEmitter):
         self.hc_total_num_acl_data_packets    = HOST_HC_TOTAL_NUM_ACL_DATA_PACKETS
         self.acl_packet_queue                 = collections.deque()
         self.acl_packets_in_flight            = 0
+        self.local_version                    = None
         self.local_supported_commands         = bytes(64)
+        self.local_le_features                = 0
         self.command_semaphore                = asyncio.Semaphore(1)
         self.long_term_key_provider           = None
         self.link_key_provider                = None
+        self.pairing_io_capability_provider   = None  # Classic only
 
         # Connect to the source and sink if specified
         if controller_source:
@@ -96,34 +99,51 @@ class Host(EventEmitter):
         await self.send_command(HCI_Reset_Command())
         self.ready = True
 
-        response = await self.send_command(HCI_Read_Local_Supported_Commands_Command())
-        if response.return_parameters.status != HCI_SUCCESS:
-            raise ProtocolError(response.return_parameters.status, 'hci')
-        self.local_supported_commands = response.return_parameters.supported_commands
-
         await self.send_command(HCI_Set_Event_Mask_Command(event_mask = bytes.fromhex('FFFFFFFFFFFFFFFF')))
         await self.send_command(HCI_LE_Set_Event_Mask_Command(le_event_mask = bytes.fromhex('FFFFF00000000000')))
-        await self.send_command(HCI_Read_Local_Version_Information_Command())
-        await self.send_command(HCI_Write_LE_Host_Support_Command(le_supported_host = 1, simultaneous_le_host = 0))
 
-        response = await self.send_command(HCI_LE_Read_Buffer_Size_Command())
+        response = await self.send_command(HCI_Read_Local_Supported_Commands_Command())
         if response.return_parameters.status == HCI_SUCCESS:
-            self.hc_le_acl_data_packet_length = response.return_parameters.hc_le_acl_data_packet_length
-            self.hc_total_num_le_acl_data_packets = response.return_parameters.hc_total_num_le_acl_data_packets
-            logger.debug(f'HCI LE ACL flow control: hc_le_acl_data_packet_length={response.return_parameters.hc_le_acl_data_packet_length}, hc_total_num_le_acl_data_packets={response.return_parameters.hc_total_num_le_acl_data_packets}')
+            self.local_supported_commands = response.return_parameters.supported_commands
         else:
-            logger.warn(f'HCI_LE_Read_Buffer_Size_Command failed: {response.return_parameters.status}')
-        if response.return_parameters.hc_le_acl_data_packet_length == 0 or response.return_parameters.hc_total_num_le_acl_data_packets == 0:
-            # Read the non-LE-specific values
-            response = await self.send_command(HCI_Read_Buffer_Size_Command())
+            logger.warn(f'HCI_Read_Local_Supported_Commands_Command failed: {response.return_parameters.status}')
+
+        if self.supports_command(HCI_WRITE_LE_HOST_SUPPORT_COMMAND):
+            await self.send_command(HCI_Write_LE_Host_Support_Command(le_supported_host = 1, simultaneous_le_host = 0))
+
+        if self.supports_command(HCI_READ_LOCAL_VERSION_INFORMATION_COMMAND):
+            response = await self.send_command(HCI_Read_Local_Version_Information_Command())
             if response.return_parameters.status == HCI_SUCCESS:
-                self.hc_acl_data_packet_length        = response.return_parameters.hc_le_acl_data_packet_length
-                self.hc_le_acl_data_packet_length     = self.hc_le_acl_data_packet_length or self.hc_acl_data_packet_length
-                self.hc_total_num_acl_data_packets    = response.return_parameters.hc_total_num_le_acl_data_packets
-                self.hc_total_num_le_acl_data_packets = self.hc_total_num_le_acl_data_packets or self.hc_total_num_acl_data_packets
-                logger.debug(f'HCI LE ACL flow control: hc_le_acl_data_packet_length={self.hc_le_acl_data_packet_length}, hc_total_num_le_acl_data_packets={self.hc_total_num_le_acl_data_packets}')
+                self.local_version = response.return_parameters
             else:
-                logger.warn(f'HCI_Read_Buffer_Size_Command failed: {response.return_parameters.status}')
+                logger.warn(f'HCI_Read_Local_Version_Information_Command failed: {response.return_parameters.status}')
+
+        if self.supports_command(HCI_LE_READ_BUFFER_SIZE_COMMAND):
+            response = await self.send_command(HCI_LE_Read_Buffer_Size_Command())
+            if response.return_parameters.status == HCI_SUCCESS:
+                self.hc_le_acl_data_packet_length = response.return_parameters.hc_le_acl_data_packet_length
+                self.hc_total_num_le_acl_data_packets = response.return_parameters.hc_total_num_le_acl_data_packets
+                logger.debug(f'HCI LE ACL flow control: hc_le_acl_data_packet_length={response.return_parameters.hc_le_acl_data_packet_length}, hc_total_num_le_acl_data_packets={response.return_parameters.hc_total_num_le_acl_data_packets}')
+            else:
+                logger.warn(f'HCI_LE_Read_Buffer_Size_Command failed: {response.return_parameters.status}')
+            if response.return_parameters.hc_le_acl_data_packet_length == 0 or response.return_parameters.hc_total_num_le_acl_data_packets == 0:
+                # Read the non-LE-specific values
+                response = await self.send_command(HCI_Read_Buffer_Size_Command())
+                if response.return_parameters.status == HCI_SUCCESS:
+                    self.hc_acl_data_packet_length        = response.return_parameters.hc_le_acl_data_packet_length
+                    self.hc_le_acl_data_packet_length     = self.hc_le_acl_data_packet_length or self.hc_acl_data_packet_length
+                    self.hc_total_num_acl_data_packets    = response.return_parameters.hc_total_num_le_acl_data_packets
+                    self.hc_total_num_le_acl_data_packets = self.hc_total_num_le_acl_data_packets or self.hc_total_num_acl_data_packets
+                    logger.debug(f'HCI LE ACL flow control: hc_le_acl_data_packet_length={self.hc_le_acl_data_packet_length}, hc_total_num_le_acl_data_packets={self.hc_total_num_le_acl_data_packets}')
+                else:
+                    logger.warn(f'HCI_Read_Buffer_Size_Command failed: {response.return_parameters.status}')
+
+        if self.supports_command(HCI_LE_READ_LOCAL_SUPPORTED_FEATURES_COMMAND):
+            response = await self.send_command(HCI_LE_Read_Local_Supported_Features_Command())
+            if response.return_parameters.status == HCI_SUCCESS:
+                self.local_le_features = struct.unpack('<Q', response.return_parameters.le_features)[0]
+            else:
+                logger.warn(f'HCI_LE_Read_Supported_Features_Command failed: {response.return_parameters.status}')
 
         self.reset_done = True
 
@@ -210,6 +230,37 @@ class Host(EventEmitter):
             self.send_hci_packet(packet)
             self.acl_packets_in_flight += 1
 
+    def supports_command(self, command):
+        # Find the support flag position for this command
+        for (octet, flags) in enumerate(HCI_SUPPORTED_COMMANDS_FLAGS):
+            for (flag_position, value) in enumerate(flags):
+                if value == command:
+                    # Check if the flag is set
+                    if octet < len(self.local_supported_commands) and flag_position < 8:
+                        return (self.local_supported_commands[octet] & (1 << flag_position)) != 0
+
+        return False
+
+    @property
+    def supported_commands(self):
+        commands = []
+        for (octet, flags) in enumerate(self.local_supported_commands):
+            if octet < len(HCI_SUPPORTED_COMMANDS_FLAGS):
+                for flag in range(8):
+                    if flags & (1 << flag) != 0:
+                        command = HCI_SUPPORTED_COMMANDS_FLAGS[octet][flag]
+                        if command is not None:
+                            commands.append(command)
+
+        return commands
+
+    def supports_le_feature(self, feature):
+        return (self.local_le_features & (1 << feature)) != 0
+
+    @property
+    def supported_le_features(self):
+        return [feature for feature in range(64) if self.local_le_features & (1 << feature)]
+
     # Packet Sink protocol (packets coming from the controller via HCI)
     def on_packet(self, packet):
         hci_packet = HCI_Packet.from_bytes(packet)
@@ -363,7 +414,7 @@ class Host(EventEmitter):
             logger.debug(f'### BR/EDR CONNECTION FAILED: {event.status}')
 
             # Notify the client
-            self.emit('connection_failure', event.status)
+            self.emit('connection_failure', event.connection_handle, event.status)
 
     def on_hci_disconnection_complete_event(self, event):
         # Find the connection
@@ -495,7 +546,7 @@ class Host(EventEmitter):
     def on_hci_authentication_complete_event(self, event):
         # Notify the client
         if event.status == HCI_SUCCESS:
-            self.emit('connection_authentication_complete', event.connection_handle)
+            self.emit('connection_authentication', event.connection_handle)
         else:
             self.emit('connection_authentication_failure', event.connection_handle, event.status)
 
@@ -560,26 +611,16 @@ class Host(EventEmitter):
         asyncio.create_task(send_link_key())
 
     def on_hci_io_capability_request_event(self, event):
-        # For now, just return NoInputNoOutput and no MITM
-        # TODO: delegate the decision
-        self.send_command_sync(
-            HCI_IO_Capability_Request_Reply_Command(
-                bd_addr                     = event.bd_addr,
-                io_capability               = HCI_NO_INPUT_NO_OUTPUT_IO_CAPABILITY,
-                oob_data_present            = 0x00,
-                authentication_requirements = 0x00  # 0x02  # FIXME: testing only
-            )
-        )
+        self.emit('authentication_io_capability_request', event.bd_addr)
 
     def on_hci_io_capability_response_event(self, event):
         pass
 
     def on_hci_user_confirmation_request_event(self, event):
-        # For now, just confirm everything
-        # TODO: delegate the decision
-        self.send_command_sync(
-            HCI_User_Confirmation_Request_Reply_Command(bd_addr = event.bd_addr)
-        )
+        self.emit('authentication_user_confirmation_request', event.bd_addr, event.numeric_value)
+
+    def on_hci_user_passkey_request_event(self, event):
+        self.emit('authentication_user_passkey_request', event.bd_addr)
 
     def on_hci_inquiry_complete_event(self, event):
         self.emit('inquiry_complete')
@@ -602,3 +643,9 @@ class Host(EventEmitter):
             event.extended_inquiry_response,
             event.rssi
         )
+
+    def on_hci_remote_name_request_complete_event(self, event):
+        if event.status != HCI_SUCCESS:
+            self.emit('remote_name_failure', event.bd_addr, event.status)
+        else:
+            self.emit('remote_name', event.bd_addr, event.remote_name)

bumble/l2cap.py

@@ -243,7 +243,7 @@ class L2CAP_Control_Frame:
 
 # -----------------------------------------------------------------------------
 @L2CAP_Control_Frame.subclass([
-    ('reason', {'size': 2, 'mapper': lambda x: L2CAP_Command_Reject.map_reason(x)}),
+    ('reason', {'size': 2, 'mapper': lambda x: L2CAP_Command_Reject.reason_name(x)}),
     ('data',   '*')
 ])
 class L2CAP_Command_Reject(L2CAP_Control_Frame):
@@ -262,7 +262,7 @@ class L2CAP_Command_Reject(L2CAP_Control_Frame):
     }
 
     @staticmethod
-    def map_reason(reason):
+    def reason_name(reason):
         return name_or_number(L2CAP_Command_Reject.REASON_NAMES, reason)
 
 
@@ -330,7 +330,7 @@ class L2CAP_Configure_Request(L2CAP_Control_Frame):
 @L2CAP_Control_Frame.subclass([
     ('source_cid', 2),
     ('flags',      2),
-    ('result',     {'size': 2, 'mapper': lambda x: L2CAP_Configure_Response.map_result(x)}),
+    ('result',     {'size': 2, 'mapper': lambda x: L2CAP_Configure_Response.result_name(x)}),
     ('options',    '*')
 ])
 class L2CAP_Configure_Response(L2CAP_Control_Frame):
@@ -355,7 +355,7 @@ class L2CAP_Configure_Response(L2CAP_Control_Frame):
     }
 
     @staticmethod
-    def map_result(result):
+    def result_name(result):
         return name_or_number(L2CAP_Configure_Response.RESULT_NAMES, result)
 
 
@@ -403,31 +403,49 @@ class L2CAP_Echo_Response(L2CAP_Control_Frame):
 
 # -----------------------------------------------------------------------------
 @L2CAP_Control_Frame.subclass([
-    ('info_type', 2)
+    ('info_type', {'size': 2, 'mapper': lambda x: L2CAP_Information_Request.info_type_name(x)})
 ])
 class L2CAP_Information_Request(L2CAP_Control_Frame):
     '''
     See Bluetooth spec @ Vol 3, Part A - 4.10 INFORMATION REQUEST
     '''
 
-    SUCCESS       = 0x00
-    NOT_SUPPORTED = 0x01
-
     CONNECTIONLESS_MTU          = 0x0001
     EXTENDED_FEATURES_SUPPORTED = 0x0002
     FIXED_CHANNELS_SUPPORTED    = 0x0003
 
+    INFO_TYPE_NAMES = {
+        CONNECTIONLESS_MTU:          'CONNECTIONLESS_MTU',
+        EXTENDED_FEATURES_SUPPORTED: 'EXTENDED_FEATURES_SUPPORTED',
+        FIXED_CHANNELS_SUPPORTED:    'FIXED_CHANNELS_SUPPORTED'
+    }
+
+    @staticmethod
+    def info_type_name(info_type):
+        return name_or_number(L2CAP_Information_Request.INFO_TYPE_NAMES, info_type)
+
 
 # -----------------------------------------------------------------------------
 @L2CAP_Control_Frame.subclass([
-    ('info_type', 2),
-    ('result',    2),
+    ('info_type', {'size': 2, 'mapper': L2CAP_Information_Request.info_type_name}),
+    ('result',    {'size': 2, 'mapper': lambda x: L2CAP_Information_Response.result_name(x)}),
     ('data',     '*')
 ])
 class L2CAP_Information_Response(L2CAP_Control_Frame):
     '''
     See Bluetooth spec @ Vol 3, Part A - 4.11 INFORMATION RESPONSE
     '''
+    SUCCESS       = 0x00
+    NOT_SUPPORTED = 0x01
+
+    RESULT_NAMES = {
+        SUCCESS:       'SUCCESS',
+        NOT_SUPPORTED: 'NOT_SUPPORTED'
+    }
+
+    @staticmethod
+    def result_name(result):
+        return name_or_number(L2CAP_Information_Response.RESULT_NAMES, result)
 
 
 # -----------------------------------------------------------------------------
@@ -473,7 +491,7 @@ class L2CAP_LE_Credit_Based_Connection_Request(L2CAP_Control_Frame):
     ('mtu',             2),
     ('mps',             2),
     ('initial_credits', 2),
-    ('result',          {'size': 2, 'mapper': lambda x: L2CAP_LE_Credit_Based_Connection_Response.map_result(x)})
+    ('result',          {'size': 2, 'mapper': lambda x: L2CAP_LE_Credit_Based_Connection_Response.result_name(x)})
 ])
 class L2CAP_LE_Credit_Based_Connection_Response(L2CAP_Control_Frame):
     '''
@@ -505,7 +523,7 @@ class L2CAP_LE_Credit_Based_Connection_Response(L2CAP_Control_Frame):
     }
 
     @staticmethod
-    def map_result(result):
+    def result_name(result):
         return name_or_number(L2CAP_LE_Credit_Based_Connection_Response.CONNECTION_RESULT_NAMES, result)
 
 
@@ -980,13 +998,13 @@ class ChannelManager:
 
     def on_l2cap_information_request(self, connection, cid, request):
         if request.info_type == L2CAP_Information_Request.CONNECTIONLESS_MTU:
-            result = L2CAP_Information_Request.SUCCESS
+            result = L2CAP_Information_Response.SUCCESS
             data = struct.pack('<H', 1024)  # TODO: don't use a fixed value
         elif request.info_type == L2CAP_Information_Request.EXTENDED_FEATURES_SUPPORTED:
-            result = L2CAP_Information_Request.SUCCESS
+            result = L2CAP_Information_Response.SUCCESS
             data = bytes.fromhex('00000000')  # TODO: don't use a fixed value
         elif request.info_type == L2CAP_Information_Request.FIXED_CHANNELS_SUPPORTED:
-            result = L2CAP_Information_Request.SUCCESS
+            result = L2CAP_Information_Response.SUCCESS
             data = bytes.fromhex('FFFFFFFFFFFFFFFF')  # TODO: don't use a fixed value
         else:
             result = L2CAP_Information_Request.NO_SUPPORTED

bumble/smp.py

@@ -464,13 +464,13 @@ class PairingDelegate:
     async def accept(self):
         return True
 
-    async def compare_numbers(self, number):
+    async def compare_numbers(self, number, digits=6):
         return True
 
     async def get_number(self):
         return 0
 
-    async def display_number(self, number):
+    async def display_number(self, number, digits=6):
         pass
 
 
@@ -699,7 +699,7 @@ class Session:
         async def prompt():
             logger.debug(f'verification code: {code}')
             try:
-                response = await self.pairing_config.delegate.compare_numbers(code)
+                response = await self.pairing_config.delegate.compare_numbers(code, digits=6)
                 if response:
                     next_steps()
                     return
@@ -733,7 +733,7 @@ class Session:
             self.tk = self.passkey.to_bytes(16, byteorder='little')
             logger.debug(f'TK from passkey = {self.tk.hex()}')
 
-        asyncio.create_task(self.pairing_config.delegate.display_number(self.passkey))
+        asyncio.create_task(self.pairing_config.delegate.display_number(self.passkey, digits=6))
 
     def input_passkey(self, next_steps=None):
         # Prompt the user for the passkey displayed on the peer
@@ -852,7 +852,7 @@ class Session:
         # distribute the long term and/or other keys over an encrypted connection
         asyncio.create_task(
             self.manager.device.host.send_command(
-                HCI_LE_Start_Encryption_Command(
+                HCI_LE_Enable_Encryption_Command(
                     connection_handle     = self.connection.handle,
                     random_number         = bytes(8),
                     encrypted_diversifier = 0,

bumble/transport/usb.py

@@ -37,14 +37,17 @@ async def open_usb_transport(spec):
     '''
     Open a USB transport.
     The parameter string has this syntax:
-    either <index> or <vendor>:<product>
+    either <index> or <vendor>:<product>[/<serial-number>]
     With <index> as the 0-based index to select amongst all the devices that appear
     to be supporting Bluetooth HCI (0 being the first one), or
-    Where <vendor> and <product> are the vendor ID and product ID in hexadecimal.
+    Where <vendor> and <product> are the vendor ID and product ID in hexadecimal. The
+    /<serial-number> suffix max be specified when more than one device with the same
+    vendor and product identifiers are present.
 
     Examples:
     0 --> the first BT USB dongle
     04b4:f901 --> the BT USB dongle with vendor=04b4 and product=f901
+    04b4:f901/00E04C239987 --> the BT USB dongle with vendor=04b4 and product=f901 and serial number 00E04C239987
     '''
 
     USB_RECIPIENT_DEVICE                             = 0x00
@@ -218,7 +221,7 @@ async def open_usb_transport(spec):
                     pass
 
             logger.debug('USB event loop done')
-            self.event_loop_done.set_result(None)
+            self.loop.call_soon_threadsafe(self.event_loop_done.set_result, None)
 
         async def close(self):
             self.closed = True
@@ -268,22 +271,32 @@ async def open_usb_transport(spec):
         found = None
         if ':' in spec:
             vendor_id, product_id = spec.split(':')
-            found = context.getByVendorIDAndProductID(int(vendor_id, 16), int(product_id, 16), skip_on_error=True)
+            if '/' in product_id:
+                product_id, serial_number = product_id.split('/')
+                for device in context.getDeviceIterator(skip_on_error=True):
+                    if (
+                        device.getVendorID() == int(vendor_id, 16) and
+                        device.getProductID() == int(product_id, 16) and
+                        device.getSerialNumber() == serial_number
+                    ):
+                        found = device
+                        break
+                    device.close()
+            else:
+                found = context.getByVendorIDAndProductID(int(vendor_id, 16), int(product_id, 16), skip_on_error=True)
         else:
             device_index = int(spec)
-            device_iterator = context.getDeviceIterator(skip_on_error=True)
-            try:
-                for device in device_iterator:
-                    if device.getDeviceClass()    == USB_DEVICE_CLASS_WIRELESS_CONTROLLER and \
-                       device.getDeviceSubClass() == USB_DEVICE_SUBCLASS_RF_CONTROLLER and \
-                       device.getDeviceProtocol() == USB_DEVICE_PROTOCOL_BLUETOOTH_PRIMARY_CONTROLLER:
-                        if device_index == 0:
-                            found = device
-                            break
-                        device_index -= 1
-                    device.close()
-            finally:
-                device_iterator.close()
+            for device in context.getDeviceIterator(skip_on_error=True):
+                if (
+                    device.getDeviceClass()    == USB_DEVICE_CLASS_WIRELESS_CONTROLLER and
+                    device.getDeviceSubClass() == USB_DEVICE_SUBCLASS_RF_CONTROLLER and
+                    device.getDeviceProtocol() == USB_DEVICE_PROTOCOL_BLUETOOTH_PRIMARY_CONTROLLER
+                ):
+                    if device_index == 0:
+                        found = device
+                        break
+                    device_index -= 1
+                device.close()
 
         if found is None:
             context.close()

docs/mkdocs/mkdocs.yml

@@ -5,6 +5,8 @@ use_directory_urls: false
 nav:
   - Introduction: index.md
   - Getting Started: getting_started.md
+  - Development:
+    - Python Environments: development/python_environments.md
   - Use Cases:
     - Overview: use_cases/index.md
     - Use Case 1: use_cases/use_case_1.md
@@ -63,7 +65,10 @@ theme:
   custom_dir: 'theme'
 
 plugins:
-  - mkdocstrings
+  - mkdocstrings:
+      handlers:
+        python:
+          paths: [../..]
 
 docs_dir: 'src'
 

docs/mkdocs/src/apps_and_tools/gatt_dump.md

@@ -0,0 +1,2 @@
+GATT DUMP TOOL
+==============

docs/mkdocs/src/apps_and_tools/index.md

@@ -5,8 +5,10 @@ Included in the project are a few apps and tools, built on top of the core libra
 These include:
 
   * [Console](console.md) - an interactive text-based console
+  * [Pair](pair.md) - Pair/bond two devices (LE and Classic)
+  * [Unbond](unbond.md) - Remove a previously established bond
   * [HCI Bridge](hci_bridge.md) - a HCI transport bridge to connect two HCI transports and filter/snoop the HCI packets
   * [Golden Gate Bridge](gg_bridge.md) - a bridge between GATT and UDP to use with the Golden Gate "stack tool"
-  * [`Show`](show.md) - Parse a file with HCI packets and print the details of each packet in a human readable form
-  * [`Link Relay`](link_relay.md) - WebSocket relay for virtual RemoteLink instances to communicate with each other.
+  * [Show](show.md) - Parse a file with HCI packets and print the details of each packet in a human readable form
+  * [Link Relay](link_relay.md) - WebSocket relay for virtual RemoteLink instances to communicate with each other.
 

docs/mkdocs/src/apps_and_tools/pair.md

@@ -0,0 +1,2 @@
+PAIR TOOL
+=========

docs/mkdocs/src/apps_and_tools/show.md

@@ -0,0 +1,2 @@
+SHOW TOOL
+=========

docs/mkdocs/src/apps_and_tools/unbond.md

@@ -0,0 +1,2 @@
+UNBOND TOOL
+===========

docs/mkdocs/src/development/python_environments.md

@@ -0,0 +1,45 @@
+PYTHON ENVIRONMENTS
+===================
+
+When you don't want to install Bumble in your main/default python environment, 
+using a virtual environment, where the package and its dependencies can be
+installed, isolated from the rest, may be useful.
+
+There are many flavors of python environments and dependency managers. 
+This page describes a few of the most common ones.
+
+
+## venv
+
+`venv` is a standard module that is included with python.
+Visit the [`venv` documentation](https://docs.python.org/3/library/venv.html) page for details.
+
+## Pyenv
+
+`pyenv` lets you easily switch between multiple versions of Python. It's simple, unobtrusive, and follows the UNIX tradition of single-purpose tools that do one thing well.  
+Visit the [`pyenv` site](https://github.com/pyenv/pyenv) for instructions on how to install
+and use `pyenv`
+
+## Conda
+
+Conda is a convenient package manager and virtual environment.
+The file `environment.yml` is a Conda environment file that you can use to create
+a new Conda environment. Once created, you can simply activate this environment when
+working with Bumble.  
+Visit the [Conda site](https://docs.conda.io/en/latest/) for instructions on how to install
+and use Conda.
+A few useful commands:  
+
+### Create a new `bumble` Conda environment
+```
+$ conda env create -f environment.yml
+```
+This will create a new environment, named `bumble`, which you can then activate with:
+```
+$ conda activate bumble
+```
+
+### Update an existing `bumble` environment
+```
+$ conda env update -f environment.yml
+```

docs/mkdocs/src/getting_started.md

@@ -20,7 +20,7 @@ You may be simply using Bumble as a module for your own application or as a depe
 module, or you may be working on modifying or contributing to the Bumble module or example code
 itself.
 
-# Working With Bumble As A Module
+# Using Bumble As A Python Module
 
 ## Installing
 
@@ -29,52 +29,40 @@ manager, or from source.
 
 !!! tip "Python Virtual Environments"
     When you install Bumble, you have the option to install it as part of your default
-    python environment, or in a virtual environment, such as a `venv`, `pyenv` or `conda` environment
-
-### venv
-
-`venv` is a standard module that is included with python.
-Visit the [`venv` documentation](https://docs.python.org/3/library/venv.html) page for details.
-
-### Pyenv
-
-`pyenv` lets you easily switch between multiple versions of Python. It's simple, unobtrusive, and follows the UNIX tradition of single-purpose tools that do one thing well.  
-Visit the [`pyenv` site](https://github.com/pyenv/pyenv) for instructions on how to install
-and use `pyenv`
-
-### Conda
-
-Conda is a convenient package manager and virtual environment.
-The file `environment.yml` is a Conda environment file that you can use to create
-a new Conda environment. Once created, you can simply activate this environment when
-working with Bumble.  
-Visit the [Conda side](https://docs.conda.io/en/latest/) for instructions on how to install
-and use Conda.
-A few useful commands:  
-
-#### Create a new `bumble` Conda environment
-```
-$ conda env create -f environment.yml
-```
-This will create a new environment, named `bumble`, which you can then activate with:
-```
-$ conda activate bumble
-```
-
-#### Update an existing `bumble` environment
-```
-$ conda env update -f environment.yml
-```
+    python environment, or in a virtual environment, such as a `venv`, `pyenv` or `conda` environment.
+    See the [Python Environments page](development/python_environments.md) page for details.
 
 ### Install From Source
 
-The instructions for working with virtual Python environments above also apply in this case.
-
-Install with `pip`
+Install with `pip`. Run in a command shell in the directory where you downloaded the source
+distribution
 ```
 $ python -m pip install -e .
 ```
 
+### Install from GitHub
+
+You can install directly from GitHub without first downloading the repo.
+
+Install the latest commit from the main branch with `pip`:
+```
+$ python -m pip install git+https://github.com/google/bumble.git
+```
+
+You can specify a specific tag.
+
+Install tag `v0.0.1` with `pip`:
+```
+$ python -m pip install git+https://github.com/google/bumble.git@v0.0.1
+```
+
+You can also specify a specific commit.
+
+Install commit `27c0551` with `pip`:
+```
+$ python -m pip install git+https://github.com/google/bumble.git@27c0551
+```
+
 # Working On The Bumble Code
 When you work on the Bumble code itself, and run some of the tests or example apps, or import the
 module in your own code, you typically either install the package from source in "development mode" as described above, or you may choose to skip the install phase. 
@@ -106,3 +94,13 @@ Setting `PYTHONPATH` locally with each command would look something like:
 ```
 $ PYTHONPATH=. python examples/run_advertiser.py examples/device1.json serial:/dev/tty.usbmodem0006839912171
 ```
+
+# Where To Go Next
+Once you've installed or downloaded Bumble, you can either start using some of the 
+[Bundled apps and tools](apps_and_tools/index.md), or look at the [examples](examples/index.md)
+to get a feel for how to use the APIs, and start writing your own applications.
+
+Depending on the use case you're interested in exploring, you may need to use a physical Bluetooth
+controller, like a USB dongle or a board with a Bluetooth radio. Visit the [Hardware page](hardware/index.md)
+for more information on using a physical radio, and/or the [Transports page](transports/index.md) for more 
+details on interfacing with either hardware modules or virtual controllers over various transports.

docs/mkdocs/src/platforms/android.md

@@ -46,7 +46,7 @@ through it with Android applications as well as system-managed profiles.
 To connect a Bumble host stack to a Root Canal virtual controller instance, use 
 the bumble `android-emulator` transport in `host` mode (the default).
 
-!!! example "Running the example GATT server connected to the emulator"
+!!! example "Run the example GATT server connected to the emulator"
     ``` shell
     $ python run_gatt_server.py device1.json android-emulator
     ```
@@ -57,7 +57,7 @@ This is an advanced use case, which may not be officially supported, but should
 versions of the emulator.
 You will likely need to start the emulator from the command line, in order to specify the `-forward-vhci` option (unless the emulator offers a way to control that feature from a user/ui menu).
 
-!!! example "Launching the emulator with VHCI forwarding"
+!!! example "Launch the emulator with VHCI forwarding"
     In this example, we launch an emulator AVD named "Tiramisu"
     ```shell
     $ emulator -forward-vhci -avd Tiramisu
@@ -70,10 +70,20 @@ You will likely need to start the emulator from the command line, in order to sp
 
 To connect a virtual controller to the Android Bluetooth stack, use the bumble `android-emulator` transport in `controller` mode. For example, using the default gRPC port, the transport name would be: `android-emulator:mode=controller`.
 
-!!! example "connecting the Android emulator to the first USB Bluetooth dongle, using the `hci_bridge` application"
+!!! example "Connect the Android emulator to the first USB Bluetooth dongle, using the `hci_bridge` application"
     ```shell
     $ bumble-hci-bridge android-emulator:mode=controller usb:0
     ```
 
+## Other Tools
 
+The `show` application that's included with Bumble can be used to parse and pretty-print the HCI packets
+from an Android HCI "snoop log" (see [this page](https://source.android.com/devices/bluetooth/verifying_debugging) 
+for details on how to obtain HCI snoop logs from an Android device).
+Use the `--format snoop` option to specify that the file is in that specific format.
+
+!!! example "Analyze an Android HCI snoop log file"
+    ```shell
+    $ bumble-show --format snoop btsnoop_hci.log
+    ```
 

setup.cfg

@@ -26,7 +26,6 @@ packages = bumble, bumble.transport, bumble.apps, bumble.apps.link_relay
 package_dir =
     bumble = bumble
     bumble.apps = apps
-    bumble.apps.link_relay = apps/link_relay
 install_requires =
     aioconsole >= 0.4.1
     ansicolors >= 1.1
@@ -66,4 +65,4 @@ development =
 documentation =
     mkdocs >= 1.2.3
     mkdocs-material >= 8.1.9
-    mkdocstrings >= 0.17.0
+    mkdocstrings[python] >= 0.19.0

tests/hci_test.py

@@ -294,8 +294,8 @@ def test_HCI_LE_Create_Connection_Command():
 
 
 # -----------------------------------------------------------------------------
-def test_HCI_LE_Add_Device_To_White_List_Command():
-    command = HCI_LE_Add_Device_To_White_List_Command(
+def test_HCI_LE_Add_Device_To_Filter_Accept_List_Command():
+    command = HCI_LE_Add_Device_To_Filter_Accept_List_Command(
         address_type = 1,
         address      = Address('00:11:22:33:44:55')
     )
@@ -303,8 +303,8 @@ def test_HCI_LE_Add_Device_To_White_List_Command():
 
 
 # -----------------------------------------------------------------------------
-def test_HCI_LE_Remove_Device_From_White_List_Command():
-    command = HCI_LE_Remove_Device_From_White_List_Command(
+def test_HCI_LE_Remove_Device_From_Filter_Accept_List_Command():
+    command = HCI_LE_Remove_Device_From_Filter_Accept_List_Command(
         address_type = 1,
         address      = Address('00:11:22:33:44:55')
     )
@@ -343,6 +343,23 @@ def test_HCI_LE_Set_Default_PHY_Command():
     basic_check(command)
 
 
+# -----------------------------------------------------------------------------
+def test_HCI_LE_Set_Extended_Scan_Parameters_Command():
+    command = HCI_LE_Set_Extended_Scan_Parameters_Command(
+        own_address_type=Address.RANDOM_DEVICE_ADDRESS,
+        scanning_filter_policy=HCI_LE_Set_Extended_Scan_Parameters_Command.BASIC_FILTERED_POLICY,
+        scanning_phys=(1 << HCI_LE_Set_Extended_Scan_Parameters_Command.LE_1M_PHY | 1 << HCI_LE_Set_Extended_Scan_Parameters_Command.LE_CODED_PHY | 1 << 4),
+        scan_types=[
+            HCI_LE_Set_Extended_Scan_Parameters_Command.ACTIVE_SCANNING,
+            HCI_LE_Set_Extended_Scan_Parameters_Command.ACTIVE_SCANNING,
+            HCI_LE_Set_Extended_Scan_Parameters_Command.PASSIVE_SCANNING
+        ],
+        scan_intervals=[1, 2, 3],
+        scan_windows=[4, 5, 6]
+    )
+    basic_check(command)
+
+
 # -----------------------------------------------------------------------------
 def test_address():
     a = Address('C4:F2:17:1A:1D:BB')
@@ -391,11 +408,12 @@ def run_test_commands():
     test_HCI_LE_Set_Scan_Parameters_Command()
     test_HCI_LE_Set_Scan_Enable_Command()
     test_HCI_LE_Create_Connection_Command()
-    test_HCI_LE_Add_Device_To_White_List_Command()
-    test_HCI_LE_Remove_Device_From_White_List_Command()
+    test_HCI_LE_Add_Device_To_Filter_Accept_List_Command()
+    test_HCI_LE_Remove_Device_From_Filter_Accept_List_Command()
     test_HCI_LE_Connection_Update_Command()
     test_HCI_LE_Read_Remote_Features_Command()
     test_HCI_LE_Set_Default_PHY_Command()
+    test_HCI_LE_Set_Extended_Scan_Parameters_Command()
 
 
 # -----------------------------------------------------------------------------

tests/pytest.ini

@@ -1,2 +1,3 @@
 [pytest]
 junit_logging = all
+asyncio_mode = auto

tests/self_test.py

@@ -208,11 +208,11 @@ async def test_self_smp():
             self.peer_delegate = None
             self.number = asyncio.get_running_loop().create_future()
 
-        async def compare_numbers(self, number):
+        async def compare_numbers(self, number, digits):
             if self.peer_delegate is None:
                 logger.warn(f'[{self.name}] no peer delegate')
                 return False
-            await self.display_number(number)
+            await self.display_number(number, digits=6)
             logger.debug(f'[{self.name}] waiting for peer number')
             peer_number = await self.peer_delegate.number
             logger.debug(f'[{self.name}] comparing numbers: {number} and {peer_number}')
@@ -231,7 +231,7 @@ async def test_self_smp():
                 logger.debug(f'[{self.name}] returning number: {peer_number}')
                 return peer_number
 
-        async def display_number(self, number):
+        async def display_number(self, number, digits):
             logger.debug(f'[{self.name}] displaying number: {number}')
             self.number.set_result(number)
 
@@ -293,7 +293,7 @@ async def test_self_smp_wrong_pin():
         def __init__(self):
             super().__init__(PairingDelegate.DISPLAY_OUTPUT_AND_KEYBOARD_INPUT)
 
-        async def compare_numbers(self, number):
+        async def compare_numbers(self, number, digits):
             return False
 
     wrong_pin_pairing_config = PairingConfig(delegate = WrongPinDelegate())