a few more constants from the spec

Remove # type: ignore[call-arg] in HCI_Command builders

.github/workflows/code-check.yml

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

.github/workflows/python-avatar.yml

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

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

@@ -12,10 +12,10 @@ permissions:
 
 jobs:
   build:
-
-    runs-on: ubuntu-latest
+    runs-on: ${{ matrix.os }}
     strategy:
       matrix:
+        os: ['ubuntu-latest', 'macos-latest', 'windows-latest']
         python-version: ["3.8", "3.9", "3.10", "3.11"]
       fail-fast: false
 
@@ -41,6 +41,7 @@ jobs:
       run: |
         inv build
         inv build.mkdocs
+
   build-rust:
     runs-on: ubuntu-latest
     strategy:
@@ -55,7 +56,7 @@ jobs:
         uses: actions/setup-python@v4
         with:
           python-version: ${{ matrix.python-version }}
-      - name: Install dependencies
+      - name: Install Python dependencies
         run: |
           python -m pip install --upgrade pip
           python -m pip install ".[build,test,development,documentation]"
@@ -64,13 +65,17 @@ jobs:
         with:
           components: clippy,rustfmt
           toolchain: ${{ matrix.rust-version }}
+      - name: Install Rust dependencies
+        run: cargo install cargo-all-features # allows building/testing combinations of features
+      - name: Check License Headers
+        run: cd rust && cargo run --features dev-tools --bin file-header check-all
       - name: Rust Build
-        run: cd rust && cargo build --all-targets && cargo build --all-features --all-targets
+        run: cd rust && cargo build --all-targets && cargo build-all-features --all-targets
       # Lints after build so what clippy needs is already built
       - name: Rust Lints
         run: cd rust && cargo fmt --check && cargo clippy --all-targets -- --deny warnings && cargo clippy --all-features --all-targets -- --deny warnings
       - name: Rust Tests
-        run: cd rust && cargo test
+        run: cd rust && cargo test-all-features
       # At some point, hook up publishing the binary. For now, just make sure it builds.
       # Once we're ready to publish binaries, this should be built with `--release`.
       - name: Build Bumble CLI

.vscode/settings.json

@@ -21,7 +21,9 @@
         "cccds",
         "cmac",
         "CONNECTIONLESS",
+        "csip",
         "csrcs",
+        "CVSD",
         "datagram",
         "DATALINK",
         "delayreport",
@@ -29,6 +31,7 @@
         "deregistration",
         "dhkey",
         "diversifier",
+        "endianness",
         "Fitbit",
         "GATTLINK",
         "HANDSFREE",
@@ -38,13 +41,18 @@
         "libc",
         "libusb",
         "MITM",
+        "MSBC",
         "NDIS",
+        "netsim",
         "NONBLOCK",
         "NONCONN",
         "OXIMETER",
         "popleft",
+        "PRAND",
+        "protobuf",
         "psms",
         "pyee",
+        "Pyodide",
         "pyusb",
         "rfcomm",
         "ROHC",
@@ -52,6 +60,7 @@
         "SEID",
         "seids",
         "SERV",
+        "SIRK",
         "ssrc",
         "strerror",
         "subband",

apps/bench.py

@@ -24,6 +24,7 @@ import time
 
 import click
 
+from bumble import l2cap
 from bumble.core import (
     BT_BR_EDR_TRANSPORT,
     BT_LE_TRANSPORT,
@@ -49,8 +50,10 @@ from bumble.sdp import (
     SDP_PUBLIC_BROWSE_ROOT,
     SDP_SERVICE_CLASS_ID_LIST_ATTRIBUTE_ID,
     SDP_SERVICE_RECORD_HANDLE_ATTRIBUTE_ID,
+    SDP_BLUETOOTH_PROFILE_DESCRIPTOR_LIST_ATTRIBUTE_ID,
     DataElement,
     ServiceAttribute,
+    Client as SdpClient,
 )
 from bumble.transport import open_transport_or_link
 import bumble.rfcomm
@@ -76,6 +79,7 @@ SPEED_SERVICE_UUID = '50DB505C-8AC4-4738-8448-3B1D9CC09CC5'
 SPEED_TX_UUID = 'E789C754-41A1-45F4-A948-A0A1A90DBA53'
 SPEED_RX_UUID = '016A2CC7-E14B-4819-935F-1F56EAE4098D'
 
+DEFAULT_RFCOMM_UUID = 'E6D55659-C8B4-4B85-96BB-B1143AF6D3AE'
 DEFAULT_L2CAP_PSM = 1234
 DEFAULT_L2CAP_MAX_CREDITS = 128
 DEFAULT_L2CAP_MTU = 1022
@@ -85,6 +89,7 @@ DEFAULT_LINGER_TIME = 1.0
 
 DEFAULT_RFCOMM_CHANNEL = 8
 
+
 # -----------------------------------------------------------------------------
 # Utils
 # -----------------------------------------------------------------------------
@@ -126,11 +131,16 @@ def print_connection(connection):
     if connection.transport == BT_LE_TRANSPORT:
         phy_state = (
             'PHY='
-            f'RX:{le_phy_name(connection.phy.rx_phy)}/'
-            f'TX:{le_phy_name(connection.phy.tx_phy)}'
+            f'TX:{le_phy_name(connection.phy.tx_phy)}/'
+            f'RX:{le_phy_name(connection.phy.rx_phy)}'
         )
 
-        data_length = f'DL={connection.data_length}'
+        data_length = (
+            'DL=('
+            f'TX:{connection.data_length[0]}/{connection.data_length[1]},'
+            f'RX:{connection.data_length[2]}/{connection.data_length[3]}'
+            ')'
+        )
         connection_parameters = (
             'Parameters='
             f'{connection.parameters.connection_interval * 1.25:.2f}/'
@@ -167,9 +177,7 @@ def make_sdp_records(channel):
             ),
             ServiceAttribute(
                 SDP_SERVICE_CLASS_ID_LIST_ATTRIBUTE_ID,
-                DataElement.sequence(
-                    [DataElement.uuid(UUID('E6D55659-C8B4-4B85-96BB-B1143AF6D3AE'))]
-                ),
+                DataElement.sequence([DataElement.uuid(UUID(DEFAULT_RFCOMM_UUID))]),
             ),
             ServiceAttribute(
                 SDP_PROTOCOL_DESCRIPTOR_LIST_ATTRIBUTE_ID,
@@ -189,6 +197,48 @@ def make_sdp_records(channel):
     }
 
 
+async def find_rfcomm_channel_with_uuid(connection: Connection, uuid: str) -> int:
+    # Connect to the SDP Server
+    sdp_client = SdpClient(connection)
+    await sdp_client.connect()
+
+    # Search for services with an L2CAP service attribute
+    search_result = await sdp_client.search_attributes(
+        [BT_L2CAP_PROTOCOL_ID],
+        [
+            SDP_PROTOCOL_DESCRIPTOR_LIST_ATTRIBUTE_ID,
+            SDP_BLUETOOTH_PROFILE_DESCRIPTOR_LIST_ATTRIBUTE_ID,
+            SDP_SERVICE_CLASS_ID_LIST_ATTRIBUTE_ID,
+        ],
+    )
+    for attribute_list in search_result:
+        service_uuid = None
+        service_class_id_list = ServiceAttribute.find_attribute_in_list(
+            attribute_list, SDP_SERVICE_CLASS_ID_LIST_ATTRIBUTE_ID
+        )
+        if service_class_id_list:
+            if service_class_id_list.value:
+                for service_class_id in service_class_id_list.value:
+                    service_uuid = service_class_id.value
+        if str(service_uuid) != uuid:
+            # This service doesn't have a UUID or isn't the right one.
+            continue
+
+        # Look for the RFCOMM Channel number
+        protocol_descriptor_list = ServiceAttribute.find_attribute_in_list(
+            attribute_list, SDP_PROTOCOL_DESCRIPTOR_LIST_ATTRIBUTE_ID
+        )
+        if protocol_descriptor_list:
+            for protocol_descriptor in protocol_descriptor_list.value:
+                if len(protocol_descriptor.value) >= 2:
+                    if protocol_descriptor.value[0].value == BT_RFCOMM_PROTOCOL_ID:
+                        await sdp_client.disconnect()
+                        return protocol_descriptor.value[1].value
+
+    await sdp_client.disconnect()
+    return 0
+
+
 class PacketType(enum.IntEnum):
     RESET = 0
     SEQUENCE = 1
@@ -197,6 +247,7 @@ class PacketType(enum.IntEnum):
 
 PACKET_FLAG_LAST = 1
 
+
 # -----------------------------------------------------------------------------
 # Sender
 # -----------------------------------------------------------------------------
@@ -221,7 +272,7 @@ class Sender:
 
         if self.tx_start_delay:
             print(color(f'*** Startup delay: {self.tx_start_delay}', 'blue'))
-            await asyncio.sleep(self.tx_start_delay)  # FIXME
+            await asyncio.sleep(self.tx_start_delay)
 
         print(color('=== Sending RESET', 'magenta'))
         await self.packet_io.send_packet(bytes([PacketType.RESET]))
@@ -361,7 +412,7 @@ class Ping:
 
         if self.tx_start_delay:
             print(color(f'*** Startup delay: {self.tx_start_delay}', 'blue'))
-            await asyncio.sleep(self.tx_start_delay)  # FIXME
+            await asyncio.sleep(self.tx_start_delay)
 
         print(color('=== Sending RESET', 'magenta'))
         await self.packet_io.send_packet(bytes([PacketType.RESET]))
@@ -659,17 +710,19 @@ class L2capClient(StreamedPacketIO):
         self.mps = mps
         self.ready = asyncio.Event()
 
-    async def on_connection(self, connection):
+    async def on_connection(self, connection: Connection) -> None:
         connection.on('disconnection', self.on_disconnection)
 
         # Connect a new L2CAP channel
         print(color(f'>>> Opening L2CAP channel on PSM = {self.psm}', 'yellow'))
         try:
-            l2cap_channel = await connection.open_l2cap_channel(
-                psm=self.psm,
-                max_credits=self.max_credits,
-                mtu=self.mtu,
-                mps=self.mps,
+            l2cap_channel = await connection.create_l2cap_channel(
+                spec=l2cap.LeCreditBasedChannelSpec(
+                    psm=self.psm,
+                    max_credits=self.max_credits,
+                    mtu=self.mtu,
+                    mps=self.mps,
+                )
             )
             print(color('*** L2CAP channel:', 'cyan'), l2cap_channel)
         except Exception as error:
@@ -695,7 +748,7 @@ class L2capClient(StreamedPacketIO):
 class L2capServer(StreamedPacketIO):
     def __init__(
         self,
-        device,
+        device: Device,
         psm=DEFAULT_L2CAP_PSM,
         max_credits=DEFAULT_L2CAP_MAX_CREDITS,
         mtu=DEFAULT_L2CAP_MTU,
@@ -705,15 +758,14 @@ class L2capServer(StreamedPacketIO):
         self.l2cap_channel = None
         self.ready = asyncio.Event()
 
-        # Listen for incoming L2CAP CoC connections
-        device.register_l2cap_channel_server(
-            psm=psm,
-            server=self.on_l2cap_channel,
-            max_credits=max_credits,
-            mtu=mtu,
-            mps=mps,
+        # Listen for incoming L2CAP connections
+        device.create_l2cap_server(
+            spec=l2cap.LeCreditBasedChannelSpec(
+                psm=psm, mtu=mtu, mps=mps, max_credits=max_credits
+            ),
+            handler=self.on_l2cap_channel,
         )
-        print(color(f'### Listening for CoC connection on PSM {psm}', 'yellow'))
+        print(color(f'### Listening for L2CAP connection on PSM {psm}', 'yellow'))
 
     async def on_connection(self, connection):
         connection.on('disconnection', self.on_disconnection)
@@ -739,21 +791,35 @@ class L2capServer(StreamedPacketIO):
 # RfcommClient
 # -----------------------------------------------------------------------------
 class RfcommClient(StreamedPacketIO):
-    def __init__(self, device):
+    def __init__(self, device, channel, uuid):
         super().__init__()
         self.device = device
+        self.channel = channel
+        self.uuid = uuid
         self.ready = asyncio.Event()
 
     async def on_connection(self, connection):
         connection.on('disconnection', self.on_disconnection)
 
+        # Find the channel number if not specified
+        channel = self.channel
+        if channel == 0:
+            print(
+                color(f'@@@ Discovering channel number from UUID {self.uuid}', 'cyan')
+            )
+            channel = await find_rfcomm_channel_with_uuid(connection, self.uuid)
+            print(color(f'@@@ Channel number = {channel}', 'cyan'))
+            if channel == 0:
+                print(color('!!! No RFComm service with this UUID found', 'red'))
+                await connection.disconnect()
+                return
+
         # Create a client and start it
         print(color('*** Starting RFCOMM client...', 'blue'))
-        rfcomm_client = bumble.rfcomm.Client(self.device, connection)
+        rfcomm_client = bumble.rfcomm.Client(connection)
         rfcomm_mux = await rfcomm_client.start()
         print(color('*** Started', 'blue'))
 
-        channel = DEFAULT_RFCOMM_CHANNEL
         print(color(f'### Opening session for channel {channel}...', 'yellow'))
         try:
             rfcomm_session = await rfcomm_mux.open_dlc(channel)
@@ -776,7 +842,7 @@ class RfcommClient(StreamedPacketIO):
 # RfcommServer
 # -----------------------------------------------------------------------------
 class RfcommServer(StreamedPacketIO):
-    def __init__(self, device):
+    def __init__(self, device, channel):
         super().__init__()
         self.ready = asyncio.Event()
 
@@ -784,7 +850,7 @@ class RfcommServer(StreamedPacketIO):
         rfcomm_server = bumble.rfcomm.Server(device)
 
         # Listen for incoming DLC connections
-        channel_number = rfcomm_server.listen(self.on_dlc, DEFAULT_RFCOMM_CHANNEL)
+        channel_number = rfcomm_server.listen(self.on_dlc, channel)
 
         # Setup the SDP to advertise this channel
         device.sdp_service_records = make_sdp_records(channel_number)
@@ -821,6 +887,9 @@ class Central(Connection.Listener):
         mode_factory,
         connection_interval,
         phy,
+        authenticate,
+        encrypt,
+        extended_data_length,
     ):
         super().__init__()
         self.transport = transport
@@ -828,6 +897,9 @@ class Central(Connection.Listener):
         self.classic = classic
         self.role_factory = role_factory
         self.mode_factory = mode_factory
+        self.authenticate = authenticate
+        self.encrypt = encrypt or authenticate
+        self.extended_data_length = extended_data_length
         self.device = None
         self.connection = None
 
@@ -900,7 +972,26 @@ class Central(Connection.Listener):
             self.connection.listener = self
             print_connection(self.connection)
 
-            await mode.on_connection(self.connection)
+            # Request a new data length if requested
+            if self.extended_data_length:
+                print(color('+++ Requesting extended data length', 'cyan'))
+                await self.connection.set_data_length(
+                    self.extended_data_length[0], self.extended_data_length[1]
+                )
+
+            # Authenticate if requested
+            if self.authenticate:
+                # Request authentication
+                print(color('*** Authenticating...', 'cyan'))
+                await self.connection.authenticate()
+                print(color('*** Authenticated', 'cyan'))
+
+            # Encrypt if requested
+            if self.encrypt:
+                # Enable encryption
+                print(color('*** Enabling encryption...', 'cyan'))
+                await self.connection.encrypt()
+                print(color('*** Encryption on', 'cyan'))
 
             # Set the PHY if requested
             if self.phy is not None:
@@ -915,6 +1006,8 @@ class Central(Connection.Listener):
                         )
                     )
 
+            await mode.on_connection(self.connection)
+
             await role.run()
             await asyncio.sleep(DEFAULT_LINGER_TIME)
 
@@ -939,9 +1032,12 @@ class Central(Connection.Listener):
 # Peripheral
 # -----------------------------------------------------------------------------
 class Peripheral(Device.Listener, Connection.Listener):
-    def __init__(self, transport, classic, role_factory, mode_factory):
+    def __init__(
+        self, transport, classic, extended_data_length, role_factory, mode_factory
+    ):
         self.transport = transport
         self.classic = classic
+        self.extended_data_length = extended_data_length
         self.role_factory = role_factory
         self.role = None
         self.mode_factory = mode_factory
@@ -1002,6 +1098,15 @@ class Peripheral(Device.Listener, Connection.Listener):
         self.connection = connection
         self.connected.set()
 
+        # Request a new data length if needed
+        if self.extended_data_length:
+            print("+++ Requesting extended data length")
+            AsyncRunner.spawn(
+                connection.set_data_length(
+                    self.extended_data_length[0], self.extended_data_length[1]
+                )
+            )
+
     def on_disconnection(self, reason):
         print(color(f'!!! Disconnection: reason={reason}', 'red'))
         self.connection = None
@@ -1034,16 +1139,18 @@ def create_mode_factory(ctx, default_mode):
             return GattServer(device)
 
         if mode == 'l2cap-client':
-            return L2capClient(device)
+            return L2capClient(device, psm=ctx.obj['l2cap_psm'])
 
         if mode == 'l2cap-server':
-            return L2capServer(device)
+            return L2capServer(device, psm=ctx.obj['l2cap_psm'])
 
         if mode == 'rfcomm-client':
-            return RfcommClient(device)
+            return RfcommClient(
+                device, channel=ctx.obj['rfcomm_channel'], uuid=ctx.obj['rfcomm_uuid']
+            )
 
         if mode == 'rfcomm-server':
-            return RfcommServer(device)
+            return RfcommServer(device, channel=ctx.obj['rfcomm_channel'])
 
         raise ValueError('invalid mode')
 
@@ -1109,6 +1216,27 @@ def create_role_factory(ctx, default_role):
     type=click.IntRange(23, 517),
     help='GATT MTU (gatt-client mode)',
 )
+@click.option(
+    '--extended-data-length',
+    help='Request a data length upon connection, specified as tx_octets/tx_time',
+)
+@click.option(
+    '--rfcomm-channel',
+    type=int,
+    default=DEFAULT_RFCOMM_CHANNEL,
+    help='RFComm channel to use',
+)
+@click.option(
+    '--rfcomm-uuid',
+    default=DEFAULT_RFCOMM_UUID,
+    help='RFComm service UUID to use (ignored is --rfcomm-channel is not 0)',
+)
+@click.option(
+    '--l2cap-psm',
+    type=int,
+    default=DEFAULT_L2CAP_PSM,
+    help='L2CAP PSM to use',
+)
 @click.option(
     '--packet-size',
     '-s',
@@ -1135,17 +1263,36 @@ def create_role_factory(ctx, default_role):
 )
 @click.pass_context
 def bench(
-    ctx, device_config, role, mode, att_mtu, packet_size, packet_count, start_delay
+    ctx,
+    device_config,
+    role,
+    mode,
+    att_mtu,
+    extended_data_length,
+    packet_size,
+    packet_count,
+    start_delay,
+    rfcomm_channel,
+    rfcomm_uuid,
+    l2cap_psm,
 ):
     ctx.ensure_object(dict)
     ctx.obj['device_config'] = device_config
     ctx.obj['role'] = role
     ctx.obj['mode'] = mode
     ctx.obj['att_mtu'] = att_mtu
+    ctx.obj['rfcomm_channel'] = rfcomm_channel
+    ctx.obj['rfcomm_uuid'] = rfcomm_uuid
+    ctx.obj['l2cap_psm'] = l2cap_psm
     ctx.obj['packet_size'] = packet_size
     ctx.obj['packet_count'] = packet_count
     ctx.obj['start_delay'] = start_delay
 
+    ctx.obj['extended_data_length'] = (
+        [int(x) for x in extended_data_length.split('/')]
+        if extended_data_length
+        else None
+    )
     ctx.obj['classic'] = mode in ('rfcomm-client', 'rfcomm-server')
 
 
@@ -1166,8 +1313,12 @@ def bench(
     help='Connection interval (in ms)',
 )
 @click.option('--phy', type=click.Choice(['1m', '2m', 'coded']), help='PHY to use')
+@click.option('--authenticate', is_flag=True, help='Authenticate (RFComm only)')
+@click.option('--encrypt', is_flag=True, help='Encrypt the connection (RFComm only)')
 @click.pass_context
-def central(ctx, transport, peripheral_address, connection_interval, phy):
+def central(
+    ctx, transport, peripheral_address, connection_interval, phy, authenticate, encrypt
+):
     """Run as a central (initiates the connection)"""
     role_factory = create_role_factory(ctx, 'sender')
     mode_factory = create_mode_factory(ctx, 'gatt-client')
@@ -1182,6 +1333,9 @@ def central(ctx, transport, peripheral_address, connection_interval, phy):
             mode_factory,
             connection_interval,
             phy,
+            authenticate,
+            encrypt or authenticate,
+            ctx.obj['extended_data_length'],
         ).run()
     )
 
@@ -1195,7 +1349,13 @@ def peripheral(ctx, transport):
     mode_factory = create_mode_factory(ctx, 'gatt-server')
 
     asyncio.run(
-        Peripheral(transport, ctx.obj['classic'], role_factory, mode_factory).run()
+        Peripheral(
+            transport,
+            ctx.obj['classic'],
+            ctx.obj['extended_data_length'],
+            role_factory,
+            mode_factory,
+        ).run()
     )
 
 

apps/console.py

@@ -1172,7 +1172,7 @@ class ScanResult:
             name = ''
 
         # Remove any '/P' qualifier suffix from the address string
-        address_str = str(self.address).replace('/P', '')
+        address_str = self.address.to_string(with_type_qualifier=False)
 
         # RSSI bar
         bar_string = rssi_bar(self.rssi)

apps/controller_info.py

@@ -42,6 +42,8 @@ from bumble.hci import (
     HCI_LE_Read_Number_Of_Supported_Advertising_Sets_Command,
     HCI_LE_READ_MAXIMUM_ADVERTISING_DATA_LENGTH_COMMAND,
     HCI_LE_Read_Maximum_Advertising_Data_Length_Command,
+    HCI_LE_READ_SUGGESTED_DEFAULT_DATA_LENGTH_COMMAND,
+    HCI_LE_Read_Suggested_Default_Data_Length_Command,
 )
 from bumble.host import Host
 from bumble.transport import open_transport_or_link
@@ -63,7 +65,8 @@ async def get_classic_info(host):
         if command_succeeded(response):
             print()
             print(
-                color('Classic Address:', 'yellow'), response.return_parameters.bd_addr
+                color('Classic Address:', 'yellow'),
+                response.return_parameters.bd_addr.to_string(False),
             )
 
     if host.supports_command(HCI_READ_LOCAL_NAME_COMMAND):
@@ -116,6 +119,18 @@ async def get_le_info(host):
                 '\n',
             )
 
+    if host.supports_command(HCI_LE_READ_SUGGESTED_DEFAULT_DATA_LENGTH_COMMAND):
+        response = await host.send_command(
+            HCI_LE_Read_Suggested_Default_Data_Length_Command()
+        )
+        if command_succeeded(response):
+            print(
+                color('Suggested Default Data Length:', 'yellow'),
+                f'{response.return_parameters.suggested_max_tx_octets}/'
+                f'{response.return_parameters.suggested_max_tx_time}',
+                '\n',
+            )
+
     print(color('LE Features:', 'yellow'))
     for feature in host.supported_le_features:
         print('  ', name_or_number(HCI_LE_SUPPORTED_FEATURES_NAMES, feature))

apps/gg_bridge.py

@@ -21,6 +21,7 @@ import struct
 import logging
 import click
 
+from bumble import l2cap
 from bumble.colors import color
 from bumble.device import Device, Peer
 from bumble.core import AdvertisingData
@@ -204,7 +205,7 @@ class GattlinkHubBridge(GattlinkL2capEndpoint, Device.Listener):
 
 # -----------------------------------------------------------------------------
 class GattlinkNodeBridge(GattlinkL2capEndpoint, Device.Listener):
-    def __init__(self, device):
+    def __init__(self, device: Device):
         super().__init__()
         self.device = device
         self.peer = None
@@ -218,7 +219,12 @@ class GattlinkNodeBridge(GattlinkL2capEndpoint, Device.Listener):
 
         # Listen for incoming L2CAP CoC connections
         psm = 0xFB
-        device.register_l2cap_channel_server(0xFB, self.on_coc)
+        device.create_l2cap_server(
+            spec=l2cap.LeCreditBasedChannelSpec(
+                psm=0xFB,
+            ),
+            handler=self.on_coc,
+        )
         print(f'### Listening for CoC connection on PSM {psm}')
 
         # Setup the Gattlink service

apps/l2cap_bridge.py

@@ -20,6 +20,7 @@ import logging
 import os
 import click
 
+from bumble import l2cap
 from bumble.colors import color
 from bumble.transport import open_transport_or_link
 from bumble.device import Device
@@ -47,14 +48,13 @@ class ServerBridge:
         self.tcp_host = tcp_host
         self.tcp_port = tcp_port
 
-    async def start(self, device):
+    async def start(self, device: Device) -> None:
         # Listen for incoming L2CAP CoC connections
-        device.register_l2cap_channel_server(
-            psm=self.psm,
-            server=self.on_coc,
-            max_credits=self.max_credits,
-            mtu=self.mtu,
-            mps=self.mps,
+        device.create_l2cap_server(
+            spec=l2cap.LeCreditBasedChannelSpec(
+                psm=self.psm, mtu=self.mtu, mps=self.mps, max_credits=self.max_credits
+            ),
+            handler=self.on_coc,
         )
         print(color(f'### Listening for CoC connection on PSM {self.psm}', 'yellow'))
 
@@ -195,11 +195,13 @@ class ClientBridge:
             # Connect a new L2CAP channel
             print(color(f'>>> Opening L2CAP channel on PSM = {self.psm}', 'yellow'))
             try:
-                l2cap_channel = await connection.open_l2cap_channel(
-                    psm=self.psm,
-                    max_credits=self.max_credits,
-                    mtu=self.mtu,
-                    mps=self.mps,
+                l2cap_channel = await connection.create_l2cap_channel(
+                    spec=l2cap.LeCreditBasedChannelSpec(
+                        psm=self.psm,
+                        max_credits=self.max_credits,
+                        mtu=self.mtu,
+                        mps=self.mps,
+                    )
                 )
                 print(color('*** L2CAP channel:', 'cyan'), l2cap_channel)
             except Exception as error:

apps/pair.py

@@ -24,10 +24,16 @@ from prompt_toolkit.shortcuts import PromptSession
 from bumble.colors import color
 from bumble.device import Device, Peer
 from bumble.transport import open_transport_or_link
-from bumble.pairing import PairingDelegate, PairingConfig
+from bumble.pairing import OobData, PairingDelegate, PairingConfig
+from bumble.smp import OobContext, OobLegacyContext
 from bumble.smp import error_name as smp_error_name
 from bumble.keys import JsonKeyStore
-from bumble.core import ProtocolError
+from bumble.core import (
+    AdvertisingData,
+    ProtocolError,
+    BT_LE_TRANSPORT,
+    BT_BR_EDR_TRANSPORT,
+)
 from bumble.gatt import (
     GATT_DEVICE_NAME_CHARACTERISTIC,
     GATT_GENERIC_ACCESS_SERVICE,
@@ -60,7 +66,7 @@ class Waiter:
 class Delegate(PairingDelegate):
     def __init__(self, mode, connection, capability_string, do_prompt):
         super().__init__(
-            {
+            io_capability={
                 'keyboard': PairingDelegate.KEYBOARD_INPUT_ONLY,
                 'display': PairingDelegate.DISPLAY_OUTPUT_ONLY,
                 'display+keyboard': PairingDelegate.DISPLAY_OUTPUT_AND_KEYBOARD_INPUT,
@@ -285,7 +291,9 @@ async def pair(
     mitm,
     bond,
     ctkd,
+    linger,
     io,
+    oob,
     prompt,
     request,
     print_keys,
@@ -306,6 +314,7 @@ async def pair(
         # Expose a GATT characteristic that can be used to trigger pairing by
         # responding with an authentication error when read
         if mode == 'le':
+            device.le_enabled = True
             device.add_service(
                 Service(
                     '50DB505C-8AC4-4738-8448-3B1D9CC09CC5',
@@ -326,7 +335,6 @@ async def pair(
         # Select LE or Classic
         if mode == 'classic':
             device.classic_enabled = True
-            device.le_enabled = False
             device.classic_smp_enabled = ctkd
 
         # Get things going
@@ -343,16 +351,52 @@ async def pair(
             await device.keystore.print(prefix=color('@@@ ', 'blue'))
             print(color('@@@-----------------------------------', 'blue'))
 
+        # Create an OOB context if needed
+        if oob:
+            our_oob_context = OobContext()
+            shared_data = (
+                None
+                if oob == '-'
+                else OobData.from_ad(AdvertisingData.from_bytes(bytes.fromhex(oob)))
+            )
+            legacy_context = OobLegacyContext()
+            oob_contexts = PairingConfig.OobConfig(
+                our_context=our_oob_context,
+                peer_data=shared_data,
+                legacy_context=legacy_context,
+            )
+            oob_data = OobData(
+                address=device.random_address,
+                shared_data=shared_data,
+                legacy_context=legacy_context,
+            )
+            print(color('@@@-----------------------------------', 'yellow'))
+            print(color('@@@ OOB Data:', 'yellow'))
+            print(color(f'@@@   {our_oob_context.share()}', 'yellow'))
+            print(color(f'@@@   TK={legacy_context.tk.hex()}', 'yellow'))
+            print(color(f'@@@   HEX: ({bytes(oob_data.to_ad()).hex()})', 'yellow'))
+            print(color('@@@-----------------------------------', 'yellow'))
+        else:
+            oob_contexts = None
+
         # Set up a pairing config factory
         device.pairing_config_factory = lambda connection: PairingConfig(
-            sc, mitm, bond, Delegate(mode, connection, io, prompt)
+            sc=sc,
+            mitm=mitm,
+            bonding=bond,
+            oob=oob_contexts,
+            delegate=Delegate(mode, connection, io, prompt),
         )
 
         # Connect to a peer or wait for a connection
         device.on('connection', lambda connection: on_connection(connection, request))
         if address_or_name is not None:
             print(color(f'=== Connecting to {address_or_name}...', 'green'))
-            connection = await device.connect(address_or_name)
+            connection = await device.connect(
+                address_or_name,
+                transport=BT_LE_TRANSPORT if mode == 'le' else BT_BR_EDR_TRANSPORT,
+            )
+            pairing_failure = False
 
             if not request:
                 try:
@@ -360,10 +404,12 @@ async def pair(
                         await connection.pair()
                     else:
                         await connection.authenticate()
-                    return
                 except ProtocolError as error:
+                    pairing_failure = True
                     print(color(f'Pairing failed: {error}', 'red'))
-                    return
+
+            if not linger or pairing_failure:
+                return
         else:
             if mode == 'le':
                 # Advertise so that peers can find us and connect
@@ -413,6 +459,7 @@ class LogHandler(logging.Handler):
     help='Enable CTKD',
     show_default=True,
 )
+@click.option('--linger', default=True, is_flag=True, help='Linger after pairing')
 @click.option(
     '--io',
     type=click.Choice(
@@ -421,6 +468,14 @@ class LogHandler(logging.Handler):
     default='display+keyboard',
     show_default=True,
 )
+@click.option(
+    '--oob',
+    metavar='<oob-data-hex>',
+    help=(
+        'Use OOB pairing with this data from the peer '
+        '(use "-" to enable OOB without peer data)'
+    ),
+)
 @click.option('--prompt', is_flag=True, help='Prompt to accept/reject pairing request')
 @click.option(
     '--request', is_flag=True, help='Request that the connecting peer initiate pairing'
@@ -440,7 +495,9 @@ def main(
     mitm,
     bond,
     ctkd,
+    linger,
     io,
+    oob,
     prompt,
     request,
     print_keys,
@@ -463,7 +520,9 @@ def main(
             mitm,
             bond,
             ctkd,
+            linger,
             io,
+            oob,
             prompt,
             request,
             print_keys,

apps/pandora_server.py

@@ -3,7 +3,7 @@ import click
 import logging
 import json
 
-from bumble.pandora import PandoraDevice, serve
+from bumble.pandora import PandoraDevice, Config, serve
 from typing import Dict, Any
 
 BUMBLE_SERVER_GRPC_PORT = 7999
@@ -29,12 +29,14 @@ def main(grpc_port: int, rootcanal_port: int, transport: str, config: str) -> No
         transport = transport.replace('<rootcanal-port>', str(rootcanal_port))
 
     bumble_config = retrieve_config(config)
-    if 'transport' not in bumble_config.keys():
-        bumble_config.update({'transport': transport})
+    bumble_config.setdefault('transport', transport)
     device = PandoraDevice(bumble_config)
 
+    server_config = Config()
+    server_config.load_from_dict(bumble_config.get('server', {}))
+
     logging.basicConfig(level=logging.DEBUG)
-    asyncio.run(serve(device, port=grpc_port))
+    asyncio.run(serve(device, config=server_config, port=grpc_port))
 
 
 def retrieve_config(config: str) -> Dict[str, Any]:

apps/show.py

@@ -102,9 +102,21 @@ class SnoopPacketReader:
     default='h4',
     help='Format of the input file',
 )
+@click.option(
+    '--vendors',
+    type=click.Choice(['android', 'zephyr']),
+    multiple=True,
+    help='Support vendor-specific commands (list one or more)',
+)
 @click.argument('filename')
 # pylint: disable=redefined-builtin
-def main(format, filename):
+def main(format, vendors, filename):
+    for vendor in vendors:
+        if vendor == 'android':
+            import bumble.vendor.android.hci
+        elif vendor == 'zephyr':
+            import bumble.vendor.zephyr.hci
+
     input = open(filename, 'rb')
     if format == 'h4':
         packet_reader = PacketReader(input)
@@ -124,7 +136,6 @@ def main(format, filename):
             if packet is None:
                 break
             tracer.trace(hci.HCI_Packet.from_bytes(packet), direction)
-
         except Exception as error:
             print(color(f'!!! {error}', 'red'))
 

apps/speaker/speaker.css

@@ -56,7 +56,7 @@ body, h1, h2, h3, h4, h5, h6 {
     border-radius: 4px;
     padding: 4px;
     margin: 6px;
-    margin-left: 0px;
+    margin-left: 0;
 }
 
 th, td {
@@ -65,7 +65,7 @@ th, td {
 }
 
 .properties td:nth-child(even) {
-    background-color: #D6EEEE;
+    background-color: #d6eeee;
     font-family: monospace;
 }
 

apps/speaker/speaker.html

@@ -2,7 +2,7 @@
 <html>
 <head>
   <title>Bumble Speaker</title>
-  <script type="text/javascript" src="speaker.js"></script>
+  <script src="speaker.js"></script>
   <link rel="stylesheet" href="speaker.css">
 </head>
 <body>

apps/speaker/speaker.py

@@ -195,7 +195,7 @@ class WebSocketOutput(QueuedOutput):
         except HCI_StatusError:
             pass
         peer_name = '' if connection.peer_name is None else connection.peer_name
-        peer_address = str(connection.peer_address).replace('/P', '')
+        peer_address = connection.peer_address.to_string(False)
         await self.send_message(
             'connection',
             peer_address=peer_address,
@@ -376,7 +376,7 @@ class UiServer:
         if connection := self.speaker().connection:
             await self.send_message(
                 'connection',
-                peer_address=str(connection.peer_address).replace('/P', ''),
+                peer_address=connection.peer_address.to_string(False),
                 peer_name=connection.peer_name,
             )
 
@@ -641,7 +641,7 @@ class Speaker:
             self.device.on('connection', self.on_bluetooth_connection)
 
             # Create a listener to wait for AVDTP connections
-            self.listener = Listener(Listener.create_registrar(self.device))
+            self.listener = Listener.for_device(self.device)
             self.listener.on('connection', self.on_avdtp_connection)
 
             print(f'Speaker ready to play, codec={color(self.codec, "cyan")}')

bumble/a2dp.py

@@ -15,9 +15,13 @@
 # -----------------------------------------------------------------------------
 # Imports
 # -----------------------------------------------------------------------------
+from __future__ import annotations
+
+import dataclasses
 import struct
 import logging
-from collections import namedtuple
+from collections.abc import AsyncGenerator
+from typing import List, Callable, Awaitable
 
 from .company_ids import COMPANY_IDENTIFIERS
 from .sdp import (
@@ -239,24 +243,20 @@ def make_audio_sink_service_sdp_records(service_record_handle, version=(1, 3)):
 
 
 # -----------------------------------------------------------------------------
-class SbcMediaCodecInformation(
-    namedtuple(
-        'SbcMediaCodecInformation',
-        [
-            'sampling_frequency',
-            'channel_mode',
-            'block_length',
-            'subbands',
-            'allocation_method',
-            'minimum_bitpool_value',
-            'maximum_bitpool_value',
-        ],
-    )
-):
+@dataclasses.dataclass
+class SbcMediaCodecInformation:
     '''
     A2DP spec - 4.3.2 Codec Specific Information Elements
     '''
 
+    sampling_frequency: int
+    channel_mode: int
+    block_length: int
+    subbands: int
+    allocation_method: int
+    minimum_bitpool_value: int
+    maximum_bitpool_value: int
+
     SAMPLING_FREQUENCY_BITS = {16000: 1 << 3, 32000: 1 << 2, 44100: 1 << 1, 48000: 1}
     CHANNEL_MODE_BITS = {
         SBC_MONO_CHANNEL_MODE: 1 << 3,
@@ -272,7 +272,7 @@ class SbcMediaCodecInformation(
     }
 
     @staticmethod
-    def from_bytes(data: bytes) -> 'SbcMediaCodecInformation':
+    def from_bytes(data: bytes) -> SbcMediaCodecInformation:
         sampling_frequency = (data[0] >> 4) & 0x0F
         channel_mode = (data[0] >> 0) & 0x0F
         block_length = (data[1] >> 4) & 0x0F
@@ -293,14 +293,14 @@ class SbcMediaCodecInformation(
     @classmethod
     def from_discrete_values(
         cls,
-        sampling_frequency,
-        channel_mode,
-        block_length,
-        subbands,
-        allocation_method,
-        minimum_bitpool_value,
-        maximum_bitpool_value,
-    ):
+        sampling_frequency: int,
+        channel_mode: int,
+        block_length: int,
+        subbands: int,
+        allocation_method: int,
+        minimum_bitpool_value: int,
+        maximum_bitpool_value: int,
+    ) -> SbcMediaCodecInformation:
         return SbcMediaCodecInformation(
             sampling_frequency=cls.SAMPLING_FREQUENCY_BITS[sampling_frequency],
             channel_mode=cls.CHANNEL_MODE_BITS[channel_mode],
@@ -314,14 +314,14 @@ class SbcMediaCodecInformation(
     @classmethod
     def from_lists(
         cls,
-        sampling_frequencies,
-        channel_modes,
-        block_lengths,
-        subbands,
-        allocation_methods,
-        minimum_bitpool_value,
-        maximum_bitpool_value,
-    ):
+        sampling_frequencies: List[int],
+        channel_modes: List[int],
+        block_lengths: List[int],
+        subbands: List[int],
+        allocation_methods: List[int],
+        minimum_bitpool_value: int,
+        maximum_bitpool_value: int,
+    ) -> SbcMediaCodecInformation:
         return SbcMediaCodecInformation(
             sampling_frequency=sum(
                 cls.SAMPLING_FREQUENCY_BITS[x] for x in sampling_frequencies
@@ -348,7 +348,7 @@ class SbcMediaCodecInformation(
             ]
         )
 
-    def __str__(self):
+    def __str__(self) -> str:
         channel_modes = ['MONO', 'DUAL_CHANNEL', 'STEREO', 'JOINT_STEREO']
         allocation_methods = ['SNR', 'Loudness']
         return '\n'.join(
@@ -367,16 +367,19 @@ class SbcMediaCodecInformation(
 
 
 # -----------------------------------------------------------------------------
-class AacMediaCodecInformation(
-    namedtuple(
-        'AacMediaCodecInformation',
-        ['object_type', 'sampling_frequency', 'channels', 'rfa', 'vbr', 'bitrate'],
-    )
-):
+@dataclasses.dataclass
+class AacMediaCodecInformation:
     '''
     A2DP spec - 4.5.2 Codec Specific Information Elements
     '''
 
+    object_type: int
+    sampling_frequency: int
+    channels: int
+    rfa: int
+    vbr: int
+    bitrate: int
+
     OBJECT_TYPE_BITS = {
         MPEG_2_AAC_LC_OBJECT_TYPE: 1 << 7,
         MPEG_4_AAC_LC_OBJECT_TYPE: 1 << 6,
@@ -400,7 +403,7 @@ class AacMediaCodecInformation(
     CHANNELS_BITS = {1: 1 << 1, 2: 1}
 
     @staticmethod
-    def from_bytes(data: bytes) -> 'AacMediaCodecInformation':
+    def from_bytes(data: bytes) -> AacMediaCodecInformation:
         object_type = data[0]
         sampling_frequency = (data[1] << 4) | ((data[2] >> 4) & 0x0F)
         channels = (data[2] >> 2) & 0x03
@@ -413,8 +416,13 @@ class AacMediaCodecInformation(
 
     @classmethod
     def from_discrete_values(
-        cls, object_type, sampling_frequency, channels, vbr, bitrate
-    ):
+        cls,
+        object_type: int,
+        sampling_frequency: int,
+        channels: int,
+        vbr: int,
+        bitrate: int,
+    ) -> AacMediaCodecInformation:
         return AacMediaCodecInformation(
             object_type=cls.OBJECT_TYPE_BITS[object_type],
             sampling_frequency=cls.SAMPLING_FREQUENCY_BITS[sampling_frequency],
@@ -425,7 +433,14 @@ class AacMediaCodecInformation(
         )
 
     @classmethod
-    def from_lists(cls, object_types, sampling_frequencies, channels, vbr, bitrate):
+    def from_lists(
+        cls,
+        object_types: List[int],
+        sampling_frequencies: List[int],
+        channels: List[int],
+        vbr: int,
+        bitrate: int,
+    ) -> AacMediaCodecInformation:
         return AacMediaCodecInformation(
             object_type=sum(cls.OBJECT_TYPE_BITS[x] for x in object_types),
             sampling_frequency=sum(
@@ -449,7 +464,7 @@ class AacMediaCodecInformation(
             ]
         )
 
-    def __str__(self):
+    def __str__(self) -> str:
         object_types = [
             'MPEG_2_AAC_LC',
             'MPEG_4_AAC_LC',
@@ -474,26 +489,26 @@ class AacMediaCodecInformation(
         )
 
 
+@dataclasses.dataclass
 # -----------------------------------------------------------------------------
 class VendorSpecificMediaCodecInformation:
     '''
     A2DP spec - 4.7.2 Codec Specific Information Elements
     '''
 
+    vendor_id: int
+    codec_id: int
+    value: bytes
+
     @staticmethod
-    def from_bytes(data):
+    def from_bytes(data: bytes) -> VendorSpecificMediaCodecInformation:
         (vendor_id, codec_id) = struct.unpack_from('<IH', data, 0)
         return VendorSpecificMediaCodecInformation(vendor_id, codec_id, data[6:])
 
-    def __init__(self, vendor_id, codec_id, value):
-        self.vendor_id = vendor_id
-        self.codec_id = codec_id
-        self.value = value
-
-    def __bytes__(self):
+    def __bytes__(self) -> bytes:
         return struct.pack('<IH', self.vendor_id, self.codec_id, self.value)
 
-    def __str__(self):
+    def __str__(self) -> str:
         # pylint: disable=line-too-long
         return '\n'.join(
             [
@@ -506,29 +521,27 @@ class VendorSpecificMediaCodecInformation:
 
 
 # -----------------------------------------------------------------------------
+@dataclasses.dataclass
 class SbcFrame:
-    def __init__(
-        self, sampling_frequency, block_count, channel_mode, subband_count, payload
-    ):
-        self.sampling_frequency = sampling_frequency
-        self.block_count = block_count
-        self.channel_mode = channel_mode
-        self.subband_count = subband_count
-        self.payload = payload
+    sampling_frequency: int
+    block_count: int
+    channel_mode: int
+    subband_count: int
+    payload: bytes
 
     @property
-    def sample_count(self):
+    def sample_count(self) -> int:
         return self.subband_count * self.block_count
 
     @property
-    def bitrate(self):
+    def bitrate(self) -> int:
         return 8 * ((len(self.payload) * self.sampling_frequency) // self.sample_count)
 
     @property
-    def duration(self):
+    def duration(self) -> float:
         return self.sample_count / self.sampling_frequency
 
-    def __str__(self):
+    def __str__(self) -> str:
         return (
             f'SBC(sf={self.sampling_frequency},'
             f'cm={self.channel_mode},'
@@ -540,12 +553,12 @@ class SbcFrame:
 
 # -----------------------------------------------------------------------------
 class SbcParser:
-    def __init__(self, read):
+    def __init__(self, read: Callable[[int], Awaitable[bytes]]) -> None:
         self.read = read
 
     @property
-    def frames(self):
-        async def generate_frames():
+    def frames(self) -> AsyncGenerator[SbcFrame, None]:
+        async def generate_frames() -> AsyncGenerator[SbcFrame, None]:
             while True:
                 # Read 4 bytes of header
                 header = await self.read(4)
@@ -589,7 +602,9 @@ class SbcParser:
 
 # -----------------------------------------------------------------------------
 class SbcPacketSource:
-    def __init__(self, read, mtu, codec_capabilities):
+    def __init__(
+        self, read: Callable[[int], Awaitable[bytes]], mtu: int, codec_capabilities
+    ) -> None:
         self.read = read
         self.mtu = mtu
         self.codec_capabilities = codec_capabilities

bumble/att.py

@@ -23,13 +23,14 @@
 # Imports
 # -----------------------------------------------------------------------------
 from __future__ import annotations
+import enum
 import functools
 import struct
 from pyee import EventEmitter
-from typing import Dict, Type, TYPE_CHECKING
+from typing import Dict, Type, List, Protocol, Union, Optional, Any, TYPE_CHECKING
 
-from bumble.core import UUID, name_or_number, get_dict_key_by_value, ProtocolError
-from bumble.hci import HCI_Object, key_with_value, HCI_Constant
+from bumble.core import UUID, name_or_number, ProtocolError
+from bumble.hci import HCI_Object, key_with_value
 from bumble.colors import color
 
 if TYPE_CHECKING:
@@ -182,6 +183,7 @@ UUID_2_FIELD_SPEC    = lambda x, y: UUID.parse_uuid_2(x, y)  # noqa: E731
 # pylint: enable=line-too-long
 # pylint: disable=invalid-name
 
+
 # -----------------------------------------------------------------------------
 # Exceptions
 # -----------------------------------------------------------------------------
@@ -209,7 +211,7 @@ class ATT_PDU:
 
     pdu_classes: Dict[int, Type[ATT_PDU]] = {}
     op_code = 0
-    name = None
+    name: str
 
     @staticmethod
     def from_bytes(pdu):
@@ -719,48 +721,68 @@ class ATT_Handle_Value_Confirmation(ATT_PDU):
     '''
 
 
+# -----------------------------------------------------------------------------
+class ConnectionValue(Protocol):
+    def read(self, connection) -> bytes:
+        ...
+
+    def write(self, connection, value: bytes) -> None:
+        ...
+
+
 # -----------------------------------------------------------------------------
 class Attribute(EventEmitter):
-    # Permission flags
-    READABLE = 0x01
-    WRITEABLE = 0x02
-    READ_REQUIRES_ENCRYPTION = 0x04
-    WRITE_REQUIRES_ENCRYPTION = 0x08
-    READ_REQUIRES_AUTHENTICATION = 0x10
-    WRITE_REQUIRES_AUTHENTICATION = 0x20
-    READ_REQUIRES_AUTHORIZATION = 0x40
-    WRITE_REQUIRES_AUTHORIZATION = 0x80
+    class Permissions(enum.IntFlag):
+        READABLE = 0x01
+        WRITEABLE = 0x02
+        READ_REQUIRES_ENCRYPTION = 0x04
+        WRITE_REQUIRES_ENCRYPTION = 0x08
+        READ_REQUIRES_AUTHENTICATION = 0x10
+        WRITE_REQUIRES_AUTHENTICATION = 0x20
+        READ_REQUIRES_AUTHORIZATION = 0x40
+        WRITE_REQUIRES_AUTHORIZATION = 0x80
 
-    PERMISSION_NAMES = {
-        READABLE: 'READABLE',
-        WRITEABLE: 'WRITEABLE',
-        READ_REQUIRES_ENCRYPTION: 'READ_REQUIRES_ENCRYPTION',
-        WRITE_REQUIRES_ENCRYPTION: 'WRITE_REQUIRES_ENCRYPTION',
-        READ_REQUIRES_AUTHENTICATION: 'READ_REQUIRES_AUTHENTICATION',
-        WRITE_REQUIRES_AUTHENTICATION: 'WRITE_REQUIRES_AUTHENTICATION',
-        READ_REQUIRES_AUTHORIZATION: 'READ_REQUIRES_AUTHORIZATION',
-        WRITE_REQUIRES_AUTHORIZATION: 'WRITE_REQUIRES_AUTHORIZATION',
-    }
+        @classmethod
+        def from_string(cls, permissions_str: str) -> Attribute.Permissions:
+            try:
+                return functools.reduce(
+                    lambda x, y: x | Attribute.Permissions[y],
+                    permissions_str.replace('|', ',').split(","),
+                    Attribute.Permissions(0),
+                )
+            except TypeError as exc:
+                # The check for `p.name is not None` here is needed because for InFlag
+                # enums, the .name property can be None, when the enum value is 0,
+                # so the type hint for .name is Optional[str].
+                enum_list: List[str] = [p.name for p in cls if p.name is not None]
+                enum_list_str = ",".join(enum_list)
+                raise TypeError(
+                    f"Attribute::permissions error:\nExpected a string containing any of the keys, separated by commas: {enum_list_str  }\nGot: {permissions_str}"
+                ) from exc
 
-    @staticmethod
-    def string_to_permissions(permissions_str: str):
-        try:
-            return functools.reduce(
-                lambda x, y: x | get_dict_key_by_value(Attribute.PERMISSION_NAMES, y),
-                permissions_str.split(","),
-                0,
-            )
-        except TypeError as exc:
-            raise TypeError(
-                f"Attribute::permissions error:\nExpected a string containing any of the keys, separated by commas: {','.join(Attribute.PERMISSION_NAMES.values())}\nGot: {permissions_str}"
-            ) from exc
+    # Permission flags(legacy-use only)
+    READABLE = Permissions.READABLE
+    WRITEABLE = Permissions.WRITEABLE
+    READ_REQUIRES_ENCRYPTION = Permissions.READ_REQUIRES_ENCRYPTION
+    WRITE_REQUIRES_ENCRYPTION = Permissions.WRITE_REQUIRES_ENCRYPTION
+    READ_REQUIRES_AUTHENTICATION = Permissions.READ_REQUIRES_AUTHENTICATION
+    WRITE_REQUIRES_AUTHENTICATION = Permissions.WRITE_REQUIRES_AUTHENTICATION
+    READ_REQUIRES_AUTHORIZATION = Permissions.READ_REQUIRES_AUTHORIZATION
+    WRITE_REQUIRES_AUTHORIZATION = Permissions.WRITE_REQUIRES_AUTHORIZATION
 
-    def __init__(self, attribute_type, permissions, value=b''):
+    value: Union[str, bytes, ConnectionValue]
+
+    def __init__(
+        self,
+        attribute_type: Union[str, bytes, UUID],
+        permissions: Union[str, Attribute.Permissions],
+        value: Union[str, bytes, ConnectionValue] = b'',
+    ) -> None:
         EventEmitter.__init__(self)
         self.handle = 0
         self.end_group_handle = 0
         if isinstance(permissions, str):
-            self.permissions = self.string_to_permissions(permissions)
+            self.permissions = Attribute.Permissions.from_string(permissions)
         else:
             self.permissions = permissions
 
@@ -778,22 +800,26 @@ class Attribute(EventEmitter):
         else:
             self.value = value
 
-    def encode_value(self, value):
+    def encode_value(self, value: Any) -> bytes:
         return value
 
-    def decode_value(self, value_bytes):
+    def decode_value(self, value_bytes: bytes) -> Any:
         return value_bytes
 
-    def read_value(self, connection: Connection):
+    def read_value(self, connection: Optional[Connection]) -> bytes:
         if (
-            self.permissions & self.READ_REQUIRES_ENCRYPTION
-        ) and not connection.encryption:
+            (self.permissions & self.READ_REQUIRES_ENCRYPTION)
+            and connection is not None
+            and not connection.encryption
+        ):
             raise ATT_Error(
                 error_code=ATT_INSUFFICIENT_ENCRYPTION_ERROR, att_handle=self.handle
             )
         if (
-            self.permissions & self.READ_REQUIRES_AUTHENTICATION
-        ) and not connection.authenticated:
+            (self.permissions & self.READ_REQUIRES_AUTHENTICATION)
+            and connection is not None
+            and not connection.authenticated
+        ):
             raise ATT_Error(
                 error_code=ATT_INSUFFICIENT_AUTHENTICATION_ERROR, att_handle=self.handle
             )
@@ -803,9 +829,9 @@ class Attribute(EventEmitter):
                 error_code=ATT_INSUFFICIENT_AUTHORIZATION_ERROR, att_handle=self.handle
             )
 
-        if read := getattr(self.value, 'read', None):
+        if hasattr(self.value, 'read'):
             try:
-                value = read(connection)  # pylint: disable=not-callable
+                value = self.value.read(connection)
             except ATT_Error as error:
                 raise ATT_Error(
                     error_code=error.error_code, att_handle=self.handle
@@ -815,7 +841,7 @@ class Attribute(EventEmitter):
 
         return self.encode_value(value)
 
-    def write_value(self, connection: Connection, value_bytes):
+    def write_value(self, connection: Connection, value_bytes: bytes) -> None:
         if (
             self.permissions & self.WRITE_REQUIRES_ENCRYPTION
         ) and not connection.encryption:
@@ -836,9 +862,9 @@ class Attribute(EventEmitter):
 
         value = self.decode_value(value_bytes)
 
-        if write := getattr(self.value, 'write', None):
+        if hasattr(self.value, 'write'):
             try:
-                write(connection, value)  # pylint: disable=not-callable
+                self.value.write(connection, value)  # pylint: disable=not-callable
             except ATT_Error as error:
                 raise ATT_Error(
                     error_code=error.error_code, att_handle=self.handle

bumble/controller.py

@@ -15,6 +15,8 @@
 # -----------------------------------------------------------------------------
 # Imports
 # -----------------------------------------------------------------------------
+from __future__ import annotations
+
 import logging
 import asyncio
 import itertools
@@ -58,8 +60,10 @@ from bumble.hci import (
     HCI_Packet,
     HCI_Role_Change_Event,
 )
-from typing import Optional, Union, Dict
+from typing import Optional, Union, Dict, TYPE_CHECKING
 
+if TYPE_CHECKING:
+    from bumble.transport.common import TransportSink, TransportSource
 
 # -----------------------------------------------------------------------------
 # Logging
@@ -104,7 +108,7 @@ class Controller:
         self,
         name,
         host_source=None,
-        host_sink=None,
+        host_sink: Optional[TransportSink] = None,
         link=None,
         public_address: Optional[Union[bytes, str, Address]] = None,
     ):
@@ -996,6 +1000,9 @@ class Controller:
         '''
         See Bluetooth spec Vol 4, Part E - 7.8.10 LE Set Scan Parameters Command
         '''
+        if self.le_scan_enable:
+            return bytes([HCI_COMMAND_DISALLOWED_ERROR])
+
         self.le_scan_type = command.le_scan_type
         self.le_scan_interval = command.le_scan_interval
         self.le_scan_window = command.le_scan_window

bumble/core.py

@@ -16,6 +16,7 @@
 # Imports
 # -----------------------------------------------------------------------------
 from __future__ import annotations
+import enum
 import struct
 from typing import List, Optional, Tuple, Union, cast, Dict
 
@@ -78,7 +79,13 @@ def get_dict_key_by_value(dictionary, value):
 class BaseError(Exception):
     """Base class for errors with an error code, error name and namespace"""
 
-    def __init__(self, error_code, error_namespace='', error_name='', details=''):
+    def __init__(
+        self,
+        error_code: Optional[int],
+        error_namespace: str = '',
+        error_name: str = '',
+        details: str = '',
+    ):
         super().__init__()
         self.error_code = error_code
         self.error_namespace = error_namespace
@@ -90,12 +97,14 @@ class BaseError(Exception):
             namespace = f'{self.error_namespace}/'
         else:
             namespace = ''
-        if self.error_name:
-            name = f'{self.error_name} [0x{self.error_code:X}]'
-        else:
-            name = f'0x{self.error_code:X}'
+        error_text = {
+            (True, True): f'{self.error_name} [0x{self.error_code:X}]',
+            (True, False): self.error_name,
+            (False, True): f'0x{self.error_code:X}',
+            (False, False): '',
+        }[(self.error_name != '', self.error_code is not None)]
 
-        return f'{type(self).__name__}({namespace}{name})'
+        return f'{type(self).__name__}({namespace}{error_text})'
 
 
 class ProtocolError(BaseError):
@@ -134,6 +143,10 @@ class ConnectionError(BaseError):  # pylint: disable=redefined-builtin
         self.peer_address = peer_address
 
 
+class ConnectionParameterUpdateError(BaseError):
+    """Connection Parameter Update Error"""
+
+
 # -----------------------------------------------------------------------------
 # UUID
 #
@@ -1039,3 +1052,13 @@ class ConnectionPHY:
 
     def __str__(self):
         return f'ConnectionPHY(tx_phy={self.tx_phy}, rx_phy={self.rx_phy})'
+
+
+# -----------------------------------------------------------------------------
+# LE Role
+# -----------------------------------------------------------------------------
+class LeRole(enum.IntEnum):
+    PERIPHERAL_ONLY = 0x00
+    CENTRAL_ONLY = 0x01
+    BOTH_PERIPHERAL_PREFERRED = 0x02
+    BOTH_CENTRAL_PREFERRED = 0x03

bumble/crypto.py

@@ -21,6 +21,8 @@
 # -----------------------------------------------------------------------------
 # Imports
 # -----------------------------------------------------------------------------
+from __future__ import annotations
+
 import logging
 import operator
 
@@ -29,11 +31,13 @@ from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
 from cryptography.hazmat.primitives.asymmetric.ec import (
     generate_private_key,
     ECDH,
+    EllipticCurvePrivateKey,
     EllipticCurvePublicNumbers,
     EllipticCurvePrivateNumbers,
     SECP256R1,
 )
 from cryptography.hazmat.primitives import cmac
+from typing import Tuple
 
 
 # -----------------------------------------------------------------------------
@@ -46,16 +50,18 @@ logger = logging.getLogger(__name__)
 # Classes
 # -----------------------------------------------------------------------------
 class EccKey:
-    def __init__(self, private_key):
+    def __init__(self, private_key: EllipticCurvePrivateKey) -> None:
         self.private_key = private_key
 
     @classmethod
-    def generate(cls):
+    def generate(cls) -> EccKey:
         private_key = generate_private_key(SECP256R1())
         return cls(private_key)
 
     @classmethod
-    def from_private_key_bytes(cls, d_bytes, x_bytes, y_bytes):
+    def from_private_key_bytes(
+        cls, d_bytes: bytes, x_bytes: bytes, y_bytes: bytes
+    ) -> EccKey:
         d = int.from_bytes(d_bytes, byteorder='big', signed=False)
         x = int.from_bytes(x_bytes, byteorder='big', signed=False)
         y = int.from_bytes(y_bytes, byteorder='big', signed=False)
@@ -65,7 +71,7 @@ class EccKey:
         return cls(private_key)
 
     @property
-    def x(self):
+    def x(self) -> bytes:
         return (
             self.private_key.public_key()
             .public_numbers()
@@ -73,14 +79,14 @@ class EccKey:
         )
 
     @property
-    def y(self):
+    def y(self) -> bytes:
         return (
             self.private_key.public_key()
             .public_numbers()
             .y.to_bytes(32, byteorder='big')
         )
 
-    def dh(self, public_key_x, public_key_y):
+    def dh(self, public_key_x: bytes, public_key_y: bytes) -> bytes:
         x = int.from_bytes(public_key_x, byteorder='big', signed=False)
         y = int.from_bytes(public_key_y, byteorder='big', signed=False)
         public_key = EllipticCurvePublicNumbers(x, y, SECP256R1()).public_key()
@@ -93,14 +99,23 @@ class EccKey:
 # Functions
 # -----------------------------------------------------------------------------
 
+
 # -----------------------------------------------------------------------------
-def xor(x, y):
+def xor(x: bytes, y: bytes) -> bytes:
     assert len(x) == len(y)
     return bytes(map(operator.xor, x, y))
 
 
 # -----------------------------------------------------------------------------
-def r():
+def reverse(input: bytes) -> bytes:
+    '''
+    Returns bytes of input in reversed endianness.
+    '''
+    return input[::-1]
+
+
+# -----------------------------------------------------------------------------
+def r() -> bytes:
     '''
     Generate 16 bytes of random data
     '''
@@ -108,20 +123,20 @@ def r():
 
 
 # -----------------------------------------------------------------------------
-def e(key, data):
+def e(key: bytes, data: bytes) -> bytes:
     '''
     AES-128 ECB, expecting byte-swapped inputs and producing a byte-swapped output.
 
     See Bluetooth spec Vol 3, Part H - 2.2.1 Security function e
     '''
 
-    cipher = Cipher(algorithms.AES(bytes(reversed(key))), modes.ECB())
+    cipher = Cipher(algorithms.AES(reverse(key)), modes.ECB())
     encryptor = cipher.encryptor()
-    return bytes(reversed(encryptor.update(bytes(reversed(data)))))
+    return reverse(encryptor.update(reverse(data)))
 
 
 # -----------------------------------------------------------------------------
-def ah(k, r):  # pylint: disable=redefined-outer-name
+def ah(k: bytes, r: bytes) -> bytes:  # pylint: disable=redefined-outer-name
     '''
     See Bluetooth spec Vol 3, Part H - 2.2.2 Random Address Hash function ah
     '''
@@ -132,7 +147,16 @@ def ah(k, r):  # pylint: disable=redefined-outer-name
 
 
 # -----------------------------------------------------------------------------
-def c1(k, r, preq, pres, iat, rat, ia, ra):  # pylint: disable=redefined-outer-name
+def c1(
+    k: bytes,
+    r: bytes,
+    preq: bytes,
+    pres: bytes,
+    iat: int,
+    rat: int,
+    ia: bytes,
+    ra: bytes,
+) -> bytes:  # pylint: disable=redefined-outer-name
     '''
     See Bluetooth spec, Vol 3, Part H - 2.2.3 Confirm value generation function c1 for
     LE Legacy Pairing
@@ -144,7 +168,7 @@ def c1(k, r, preq, pres, iat, rat, ia, ra):  # pylint: disable=redefined-outer-n
 
 
 # -----------------------------------------------------------------------------
-def s1(k, r1, r2):
+def s1(k: bytes, r1: bytes, r2: bytes) -> bytes:
     '''
     See Bluetooth spec, Vol 3, Part H - 2.2.4 Key generation function s1 for LE Legacy
     Pairing
@@ -154,7 +178,7 @@ def s1(k, r1, r2):
 
 
 # -----------------------------------------------------------------------------
-def aes_cmac(m, k):
+def aes_cmac(m: bytes, k: bytes) -> bytes:
     '''
     See Bluetooth spec, Vol 3, Part H - 2.2.5 FunctionAES-CMAC
 
@@ -166,20 +190,16 @@ def aes_cmac(m, k):
 
 
 # -----------------------------------------------------------------------------
-def f4(u, v, x, z):
+def f4(u: bytes, v: bytes, x: bytes, z: bytes) -> bytes:
     '''
     See Bluetooth spec, Vol 3, Part H - 2.2.6 LE Secure Connections Confirm Value
     Generation Function f4
     '''
-    return bytes(
-        reversed(
-            aes_cmac(bytes(reversed(u)) + bytes(reversed(v)) + z, bytes(reversed(x)))
-        )
-    )
+    return reverse(aes_cmac(reverse(u) + reverse(v) + z, reverse(x)))
 
 
 # -----------------------------------------------------------------------------
-def f5(w, n1, n2, a1, a2):
+def f5(w: bytes, n1: bytes, n2: bytes, a1: bytes, a2: bytes) -> Tuple[bytes, bytes]:
     '''
     See Bluetooth spec, Vol 3, Part H - 2.2.7 LE Secure Connections Key Generation
     Function f5
@@ -187,87 +207,83 @@ def f5(w, n1, n2, a1, a2):
     NOTE: this returns a tuple: (MacKey, LTK) in little-endian byte order
     '''
     salt = bytes.fromhex('6C888391AAF5A53860370BDB5A6083BE')
-    t = aes_cmac(bytes(reversed(w)), salt)
+    t = aes_cmac(reverse(w), salt)
     key_id = bytes([0x62, 0x74, 0x6C, 0x65])
     return (
-        bytes(
-            reversed(
-                aes_cmac(
-                    bytes([0])
-                    + key_id
-                    + bytes(reversed(n1))
-                    + bytes(reversed(n2))
-                    + bytes(reversed(a1))
-                    + bytes(reversed(a2))
-                    + bytes([1, 0]),
-                    t,
-                )
+        reverse(
+            aes_cmac(
+                bytes([0])
+                + key_id
+                + reverse(n1)
+                + reverse(n2)
+                + reverse(a1)
+                + reverse(a2)
+                + bytes([1, 0]),
+                t,
             )
         ),
-        bytes(
-            reversed(
-                aes_cmac(
-                    bytes([1])
-                    + key_id
-                    + bytes(reversed(n1))
-                    + bytes(reversed(n2))
-                    + bytes(reversed(a1))
-                    + bytes(reversed(a2))
-                    + bytes([1, 0]),
-                    t,
-                )
+        reverse(
+            aes_cmac(
+                bytes([1])
+                + key_id
+                + reverse(n1)
+                + reverse(n2)
+                + reverse(a1)
+                + reverse(a2)
+                + bytes([1, 0]),
+                t,
             )
         ),
     )
 
 
 # -----------------------------------------------------------------------------
-def f6(w, n1, n2, r, io_cap, a1, a2):  # pylint: disable=redefined-outer-name
+def f6(
+    w: bytes, n1: bytes, n2: bytes, r: bytes, io_cap: bytes, a1: bytes, a2: bytes
+) -> bytes:  # pylint: disable=redefined-outer-name
     '''
     See Bluetooth spec, Vol 3, Part H - 2.2.8 LE Secure Connections Check Value
     Generation Function f6
     '''
-    return bytes(
-        reversed(
-            aes_cmac(
-                bytes(reversed(n1))
-                + bytes(reversed(n2))
-                + bytes(reversed(r))
-                + bytes(reversed(io_cap))
-                + bytes(reversed(a1))
-                + bytes(reversed(a2)),
-                bytes(reversed(w)),
-            )
+    return reverse(
+        aes_cmac(
+            reverse(n1)
+            + reverse(n2)
+            + reverse(r)
+            + reverse(io_cap)
+            + reverse(a1)
+            + reverse(a2),
+            reverse(w),
         )
     )
 
 
 # -----------------------------------------------------------------------------
-def g2(u, v, x, y):
+def g2(u: bytes, v: bytes, x: bytes, y: bytes) -> int:
     '''
     See Bluetooth spec, Vol 3, Part H - 2.2.9 LE Secure Connections Numeric Comparison
     Value Generation Function g2
     '''
     return int.from_bytes(
         aes_cmac(
-            bytes(reversed(u)) + bytes(reversed(v)) + bytes(reversed(y)),
-            bytes(reversed(x)),
+            reverse(u) + reverse(v) + reverse(y),
+            reverse(x),
         )[-4:],
         byteorder='big',
     )
 
 
 # -----------------------------------------------------------------------------
-def h6(w, key_id):
+def h6(w: bytes, key_id: bytes) -> bytes:
     '''
     See Bluetooth spec, Vol 3, Part H - 2.2.10 Link key conversion function h6
     '''
-    return aes_cmac(key_id, w)
+    return reverse(aes_cmac(key_id, reverse(w)))
 
 
 # -----------------------------------------------------------------------------
-def h7(salt, w):
+def h7(salt: bytes, w: bytes) -> bytes:
     '''
     See Bluetooth spec, Vol 3, Part H - 2.2.11 Link key conversion function h7
     '''
-    return aes_cmac(w, salt)
+    return reverse(aes_cmac(reverse(w), salt))

bumble/drivers/__init__.py

@@ -23,7 +23,6 @@ import abc
 import logging
 import pathlib
 import platform
-import platformdirs
 from . import rtk
 
 
@@ -77,6 +76,8 @@ def project_data_dir() -> pathlib.Path:
         A path to an OS-specific directory for bumble data. The directory is created if
          it doesn't exist.
     """
+    import platformdirs
+
     if platform.system() == 'Darwin':
         # platformdirs doesn't handle macOS right: it doesn't assemble a bundle id
         # out of author & project

bumble/drivers/rtk.py

@@ -34,10 +34,9 @@ import weakref
 
 
 from bumble.hci import (
-    hci_command_op_code,
+    hci_vendor_command_op_code,
     STATUS_SPEC,
     HCI_SUCCESS,
-    HCI_COMMAND_NAMES,
     HCI_Command,
     HCI_Reset_Command,
     HCI_Read_Local_Version_Information_Command,
@@ -179,8 +178,10 @@ RTK_USB_PRODUCTS = {
 # -----------------------------------------------------------------------------
 # 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_RTK_READ_ROM_VERSION_COMMAND = hci_vendor_command_op_code(0x6D)
+HCI_RTK_DOWNLOAD_COMMAND = hci_vendor_command_op_code(0x20)
+HCI_RTK_DROP_FIRMWARE_COMMAND = hci_vendor_command_op_code(0x66)
+HCI_Command.register_commands(globals())
 
 
 @HCI_Command.command(return_parameters_fields=[("status", STATUS_SPEC), ("version", 1)])
@@ -188,10 +189,6 @@ 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)],
@@ -200,10 +197,6 @@ 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

bumble/gatt.py

@@ -28,7 +28,7 @@ import enum
 import functools
 import logging
 import struct
-from typing import Optional, Sequence, List
+from typing import Optional, Sequence, Iterable, List, Union
 
 from .colors import color
 from .core import UUID, get_dict_key_by_value
@@ -93,20 +93,35 @@ GATT_RECONNECTION_CONFIGURATION_SERVICE     = UUID.from_16_bits(0x1829, 'Reconne
 GATT_INSULIN_DELIVERY_SERVICE               = UUID.from_16_bits(0x183A, 'Insulin Delivery')
 GATT_BINARY_SENSOR_SERVICE                  = UUID.from_16_bits(0x183B, 'Binary Sensor')
 GATT_EMERGENCY_CONFIGURATION_SERVICE        = UUID.from_16_bits(0x183C, 'Emergency Configuration')
+GATT_AUTHORIZATION_CONTROL_SERVICE          = UUID.from_16_bits(0x183D, 'Authorization Control')
 GATT_PHYSICAL_ACTIVITY_MONITOR_SERVICE      = UUID.from_16_bits(0x183E, 'Physical Activity Monitor')
+GATT_ELAPSED_TIME_SERVICE                   = UUID.from_16_bits(0x183F, 'Elapsed Time')
+GATT_GENERIC_HEALTH_SENSOR_SERVICE          = UUID.from_16_bits(0x1840, 'Generic Health Sensor')
 GATT_AUDIO_INPUT_CONTROL_SERVICE            = UUID.from_16_bits(0x1843, 'Audio Input Control')
 GATT_VOLUME_CONTROL_SERVICE                 = UUID.from_16_bits(0x1844, 'Volume Control')
 GATT_VOLUME_OFFSET_CONTROL_SERVICE          = UUID.from_16_bits(0x1845, 'Volume Offset Control')
-GATT_COORDINATED_SET_IDENTIFICATION_SERVICE = UUID.from_16_bits(0x1846, 'Coordinated Set Identification Service')
+GATT_COORDINATED_SET_IDENTIFICATION_SERVICE = UUID.from_16_bits(0x1846, 'Coordinated Set Identification')
 GATT_DEVICE_TIME_SERVICE                    = UUID.from_16_bits(0x1847, 'Device Time')
-GATT_MEDIA_CONTROL_SERVICE                  = UUID.from_16_bits(0x1848, 'Media Control Service')
-GATT_GENERIC_MEDIA_CONTROL_SERVICE          = UUID.from_16_bits(0x1849, 'Generic Media Control Service')
+GATT_MEDIA_CONTROL_SERVICE                  = UUID.from_16_bits(0x1848, 'Media Control')
+GATT_GENERIC_MEDIA_CONTROL_SERVICE          = UUID.from_16_bits(0x1849, 'Generic Media Control')
 GATT_CONSTANT_TONE_EXTENSION_SERVICE        = UUID.from_16_bits(0x184A, 'Constant Tone Extension')
-GATT_TELEPHONE_BEARER_SERVICE               = UUID.from_16_bits(0x184B, 'Telephone Bearer Service')
-GATT_GENERIC_TELEPHONE_BEARER_SERVICE       = UUID.from_16_bits(0x184C, 'Generic Telephone Bearer Service')
+GATT_TELEPHONE_BEARER_SERVICE               = UUID.from_16_bits(0x184B, 'Telephone Bearer')
+GATT_GENERIC_TELEPHONE_BEARER_SERVICE       = UUID.from_16_bits(0x184C, 'Generic Telephone Bearer')
 GATT_MICROPHONE_CONTROL_SERVICE             = UUID.from_16_bits(0x184D, 'Microphone Control')
+GATT_AUDIO_STREAM_CONTROL_SERVICE           = UUID.from_16_bits(0x184E, 'Audio Stream Control')
+GATT_BROADCAST_AUDIO_SCAN_SERVICE           = UUID.from_16_bits(0x184F, 'Broadcast Audio Scan')
+GATT_PUBLISHED_AUDIO_CAPABILITIES_SERVICE   = UUID.from_16_bits(0x1850, 'Published Audio Capabilities')
+GATT_BASIC_AUDIO_ANNOUNCEMENT_SERVICE       = UUID.from_16_bits(0x1851, 'Basic Audio Announcement')
+GATT_BROADCAST_AUDIO_ANNOUNCEMENT_SERVICE   = UUID.from_16_bits(0x1852, 'Broadcast Audio Announcement')
+GATT_COMMON_AUDIO_SERVICE                   = UUID.from_16_bits(0x1853, 'Common Audio')
+GATT_HEARING_ACCESS_SERVICE                 = UUID.from_16_bits(0x1854, 'Hearing Access')
+GATT_TELEPHONY_AND_MEDIA_AUDIO_SERVICE      = UUID.from_16_bits(0x1855, 'Telephony and Media Audio')
+GATT_PUBLIC_BROADCAST_ANNOUNCEMENT_SERVICE  = UUID.from_16_bits(0x1856, 'Public Broadcast Announcement')
+GATT_ELECTRONIC_SHELF_LABEL_SERVICE         = UUID.from_16_bits(0X1857, 'Electronic Shelf Label')
+GATT_GAMING_AUDIO_SERVICE                   = UUID.from_16_bits(0x1858, 'Gaming Audio')
+GATT_MESH_PROXY_SOLICITATION_SERVICE        = UUID.from_16_bits(0x1859, 'Mesh Audio Solicitation')
 
-# Types
+# Attribute Types
 GATT_PRIMARY_SERVICE_ATTRIBUTE_TYPE   = UUID.from_16_bits(0x2800, 'Primary Service')
 GATT_SECONDARY_SERVICE_ATTRIBUTE_TYPE = UUID.from_16_bits(0x2801, 'Secondary Service')
 GATT_INCLUDE_ATTRIBUTE_TYPE           = UUID.from_16_bits(0x2802, 'Include')
@@ -129,6 +144,8 @@ GATT_ENVIRONMENTAL_SENSING_MEASUREMENT_DESCRIPTOR    = UUID.from_16_bits(0x290C,
 GATT_ENVIRONMENTAL_SENSING_TRIGGER_DESCRIPTOR        = UUID.from_16_bits(0x290D, 'Environmental Sensing Trigger Setting')
 GATT_TIME_TRIGGER_DESCRIPTOR                         = UUID.from_16_bits(0x290E, 'Time Trigger Setting')
 GATT_COMPLETE_BR_EDR_TRANSPORT_BLOCK_DATA_DESCRIPTOR = UUID.from_16_bits(0x290F, 'Complete BR-EDR Transport Block Data')
+GATT_OBSERVATION_SCHEDULE_DESCRIPTOR                 = UUID.from_16_bits(0x290F, 'Observation Schedule')
+GATT_VALID_RANGE_AND_ACCURACY_DESCRIPTOR             = UUID.from_16_bits(0x290F, 'Valid Range And Accuracy')
 
 # Device Information Service
 GATT_SYSTEM_ID_CHARACTERISTIC                          = UUID.from_16_bits(0x2A23, 'System ID')
@@ -156,6 +173,96 @@ GATT_HEART_RATE_CONTROL_POINT_CHARACTERISTIC = UUID.from_16_bits(0x2A39, 'Heart
 # Battery Service
 GATT_BATTERY_LEVEL_CHARACTERISTIC = UUID.from_16_bits(0x2A19, 'Battery Level')
 
+# Telephony And Media Audio Service (TMAS)
+GATT_TMAP_ROLE_CHARACTERISTIC = UUID.from_16_bits(0x2B51, 'TMAP Role')
+
+# Audio Input Control Service (AICS)
+GATT_AUDIO_INPUT_STATE_CHARACTERISTIC         = UUID.from_16_bits(0x2B77, 'Audio Input State')
+GATT_GAIN_SETTINGS_ATTRIBUTE_CHARACTERISTIC   = UUID.from_16_bits(0x2B78, 'Gain Settings Attribute')
+GATT_AUDIO_INPUT_TYPE_CHARACTERISTIC          = UUID.from_16_bits(0x2B79, 'Audio Input Type')
+GATT_AUDIO_INPUT_STATUS_CHARACTERISTIC        = UUID.from_16_bits(0x2B7A, 'Audio Input Status')
+GATT_AUDIO_INPUT_CONTROL_POINT_CHARACTERISTIC = UUID.from_16_bits(0x2B7B, 'Audio Input Control Point')
+GATT_AUDIO_INPUT_DESCRIPTION_CHARACTERISTIC   = UUID.from_16_bits(0x2B7C, 'Audio Input Description')
+
+# Volume Control Service (VCS)
+GATT_VOLUME_STATE_CHARACTERISTIC                = UUID.from_16_bits(0x2B7D, 'Volume State')
+GATT_VOLUME_CONTROL_POINT_CHARACTERISTIC        = UUID.from_16_bits(0x2B7E, 'Volume Control Point')
+GATT_VOLUME_FLAGS_CHARACTERISTIC                = UUID.from_16_bits(0x2B7F, 'Volume Flags')
+
+# Volume Offset Control Service (VOCS)
+GATT_VOLUME_OFFSET_STATE_CHARACTERISTIC         = UUID.from_16_bits(0x2B80, 'Volume Offset State')
+GATT_AUDIO_LOCATION_CHARACTERISTIC              = UUID.from_16_bits(0x2B81, 'Audio Location')
+GATT_VOLUME_OFFSET_CONTROL_POINT_CHARACTERISTIC = UUID.from_16_bits(0x2B82, 'Volume Offset Control Point')
+GATT_AUDIO_OUTPUT_DESCRIPTION_CHARACTERISTIC    = UUID.from_16_bits(0x2B83, 'Audio Output Description')
+
+# Coordinated Set Identification Service (CSIS)
+GATT_SET_IDENTITY_RESOLVING_KEY_CHARACTERISTIC  = UUID.from_16_bits(0x2B84, 'Set Identity Resolving Key')
+GATT_COORDINATED_SET_SIZE_CHARACTERISTIC        = UUID.from_16_bits(0x2B85, 'Coordinated Set Size')
+GATT_SET_MEMBER_LOCK_CHARACTERISTIC             = UUID.from_16_bits(0x2B86, 'Set Member Lock')
+GATT_SET_MEMBER_RANK_CHARACTERISTIC             = UUID.from_16_bits(0x2B87, 'Set Member Rank')
+
+# Media Control Service (MCS)
+GATT_MEDIA_PLAYER_NAME_CHARACTERISTIC                     = UUID.from_16_bits(0x2B93, 'Media Player Name')
+GATT_MEDIA_PLAYER_ICON_OBJECT_ID_CHARACTERISTIC           = UUID.from_16_bits(0x2B94, 'Media Player Icon Object ID')
+GATT_MEDIA_PLAYER_ICON_URL_CHARACTERISTIC                 = UUID.from_16_bits(0x2B95, 'Media Player Icon URL')
+GATT_TRACK_CHANGED_CHARACTERISTIC                         = UUID.from_16_bits(0x2B96, 'Track Changed')
+GATT_TRACK_TITLE_CHARACTERISTIC                           = UUID.from_16_bits(0x2B97, 'Track Title')
+GATT_TRACK_DURATION_CHARACTERISTIC                        = UUID.from_16_bits(0x2B98, 'Track Duration')
+GATT_TRACK_POSITION_CHARACTERISTIC                        = UUID.from_16_bits(0x2B99, 'Track Position')
+GATT_PLAYBACK_SPEED_CHARACTERISTIC                        = UUID.from_16_bits(0x2B9A, 'Playback Speed')
+GATT_SEEKING_SPEED_CHARACTERISTIC                         = UUID.from_16_bits(0x2B9B, 'Seeking Speed')
+GATT_CURRENT_TRACK_SEGMENTS_OBJECT_ID_CHARACTERISTIC      = UUID.from_16_bits(0x2B9C, 'Current Track Segments Object ID')
+GATT_CURRENT_TRACK_OBJECT_ID_CHARACTERISTIC               = UUID.from_16_bits(0x2B9D, 'Current Track Object ID')
+GATT_NEXT_TRACK_OBJECT_ID_CHARACTERISTIC                  = UUID.from_16_bits(0x2B9E, 'Next Track Object ID')
+GATT_PARENT_GROUP_OBJECT_ID_CHARACTERISTIC                = UUID.from_16_bits(0x2B9F, 'Parent Group Object ID')
+GATT_CURRENT_GROUP_OBJECT_ID_CHARACTERISTIC               = UUID.from_16_bits(0x2BA0, 'Current Group Object ID')
+GATT_PLAYING_ORDER_CHARACTERISTIC                         = UUID.from_16_bits(0x2BA1, 'Playing Order')
+GATT_PLAYING_ORDERS_SUPPORTED_CHARACTERISTIC              = UUID.from_16_bits(0x2BA2, 'Playing Orders Supported')
+GATT_MEDIA_STATE_CHARACTERISTIC                           = UUID.from_16_bits(0x2BA3, 'Media State')
+GATT_MEDIA_CONTROL_POINT_CHARACTERISTIC                   = UUID.from_16_bits(0x2BA4, 'Media Control Point')
+GATT_MEDIA_CONTROL_POINT_OPCODES_SUPPORTED_CHARACTERISTIC = UUID.from_16_bits(0x2BA5, 'Media Control Point Opcodes Supported')
+GATT_SEARCH_RESULTS_OBJECT_ID_CHARACTERISTIC              = UUID.from_16_bits(0x2BA6, 'Search Results Object ID')
+GATT_SEARCH_CONTROL_POINT_CHARACTERISTIC                  = UUID.from_16_bits(0x2BA7, 'Search Control Point')
+GATT_CONTENT_CONTROL_ID_CHARACTERISTIC                    = UUID.from_16_bits(0x2BBA, 'Content Control Id')
+
+# Telephone Bearer Service (TBS)
+GATT_BEARER_PROVIDER_NAME_CHARACTERISTIC                      = UUID.from_16_bits(0x2BB4, 'Bearer Provider Name')
+GATT_BEARER_UCI_CHARACTERISTIC                                = UUID.from_16_bits(0x2BB5, 'Bearer UCI')
+GATT_BEARER_TECHNOLOGY_CHARACTERISTIC                         = UUID.from_16_bits(0x2BB6, 'Bearer Technology')
+GATT_BEARER_URI_SCHEMES_SUPPORTED_LIST_CHARACTERISTIC         = UUID.from_16_bits(0x2BB7, 'Bearer URI Schemes Supported List')
+GATT_BEARER_SIGNAL_STRENGTH_CHARACTERISTIC                    = UUID.from_16_bits(0x2BB8, 'Bearer Signal Strength')
+GATT_BEARER_SIGNAL_STRENGTH_REPORTING_INTERVAL_CHARACTERISTIC = UUID.from_16_bits(0x2BB9, 'Bearer Signal Strength Reporting Interval')
+GATT_BEARER_LIST_CURRENT_CALLS_CHARACTERISTIC                 = UUID.from_16_bits(0x2BBA, 'Bearer List Current Calls')
+GATT_CONTENT_CONTROL_ID_CHARACTERISTIC                        = UUID.from_16_bits(0x2BBB, 'Content Control ID')
+GATT_STATUS_FLAGS_CHARACTERISTIC                              = UUID.from_16_bits(0x2BBC, 'Status Flags')
+GATT_INCOMING_CALL_TARGET_BEARER_URI_CHARACTERISTIC           = UUID.from_16_bits(0x2BBD, 'Incoming Call Target Bearer URI')
+GATT_CALL_STATE_CHARACTERISTIC                                = UUID.from_16_bits(0x2BBE, 'Call State')
+GATT_CALL_CONTROL_POINT_CHARACTERISTIC                        = UUID.from_16_bits(0x2BBF, 'Call Control Point')
+GATT_CALL_CONTROL_POINT_OPTIONAL_OPCODES_CHARACTERISTIC       = UUID.from_16_bits(0x2BC0, 'Call Control Point Optional Opcodes')
+GATT_TERMINATION_REASON_CHARACTERISTIC                        = UUID.from_16_bits(0x2BC1, 'Termination Reason')
+GATT_INCOMING_CALL_CHARACTERISTIC                             = UUID.from_16_bits(0x2BC2, 'Incoming Call')
+GATT_CALL_FRIENDLY_NAME_CHARACTERISTIC                        = UUID.from_16_bits(0x2BC3, 'Call Friendly Name')
+
+# Microphone Control Service (MICS)
+GATT_MUTE_CHARACTERISTIC = UUID.from_16_bits(0x2BC3, 'Mute')
+
+# Audio Stream Control Service (ASCS)
+GATT_SINK_ASE_CHARACTERISTIC                    = UUID.from_16_bits(0x2BC4, 'Sink ASE')
+GATT_SOURCE_ASE_CHARACTERISTIC                  = UUID.from_16_bits(0x2BC5, 'Source ASE')
+GATT_ASE_CONTROL_POINT_CHARACTERISTIC           = UUID.from_16_bits(0x2BC6, 'ASE Control Point')
+
+# Broadcast Audio Scan Service (BASS)
+GATT_BROADCAST_AUDIO_SCAN_CONTROL_POINT_CHARACTERISTIC = UUID.from_16_bits(0x2BC7, 'Broadcast Audio Scan Control Point')
+GATT_BROADCAST_RECEIVE_STATE_CHARACTERISTIC            = UUID.from_16_bits(0x2BC8, 'Broadcast Receive State')
+
+# Published Audio Capabilities Service (PACS)
+GATT_SINK_PAC_CHARACTERISTIC                    = UUID.from_16_bits(0x2BC9, 'Sink PAC')
+GATT_SINK_AUDIO_LOCATION_CHARACTERISTIC         = UUID.from_16_bits(0x2BCA, 'Sink Audio Location')
+GATT_SOURCE_PAC_CHARACTERISTIC                  = UUID.from_16_bits(0x2BCB, 'Source PAC')
+GATT_SOURCE_AUDIO_LOCATION_CHARACTERISTIC       = UUID.from_16_bits(0x2BCC, 'Source Audio Location')
+GATT_AVAILABLE_AUDIO_CONTEXTS_CHARACTERISTIC    = UUID.from_16_bits(0x2BCD, 'Available Audio Contexts')
+GATT_SUPPORTED_AUDIO_CONTEXTS_CHARACTERISTIC    = UUID.from_16_bits(0x2BCE, 'Supported Audio Contexts')
+
 # ASHA Service
 GATT_ASHA_SERVICE                             = UUID.from_16_bits(0xFDF0, 'Audio Streaming for Hearing Aid')
 GATT_ASHA_READ_ONLY_PROPERTIES_CHARACTERISTIC = UUID('6333651e-c481-4a3e-9169-7c902aad37bb', 'ReadOnlyProperties')
@@ -177,6 +284,9 @@ GATT_BOOT_KEYBOARD_INPUT_REPORT_CHARACTERISTIC                 = UUID.from_16_bi
 GATT_CURRENT_TIME_CHARACTERISTIC                               = UUID.from_16_bits(0x2A2B, 'Current Time')
 GATT_BOOT_KEYBOARD_OUTPUT_REPORT_CHARACTERISTIC                = UUID.from_16_bits(0x2A32, 'Boot Keyboard Output Report')
 GATT_CENTRAL_ADDRESS_RESOLUTION__CHARACTERISTIC                = UUID.from_16_bits(0x2AA6, 'Central Address Resolution')
+GATT_CLIENT_SUPPORTED_FEATURES_CHARACTERISTIC                  = UUID.from_16_bits(0x2B29, 'Client Supported Features')
+GATT_DATABASE_HASH_CHARACTERISTIC                              = UUID.from_16_bits(0x2B2A, 'Database Hash')
+GATT_SERVER_SUPPORTED_FEATURES_CHARACTERISTIC                  = UUID.from_16_bits(0x2B3A, 'Server Supported Features')
 
 # fmt: on
 # pylint: enable=line-too-long
@@ -187,7 +297,7 @@ GATT_CENTRAL_ADDRESS_RESOLUTION__CHARACTERISTIC                = UUID.from_16_bi
 # -----------------------------------------------------------------------------
 
 
-def show_services(services):
+def show_services(services: Iterable[Service]) -> None:
     for service in services:
         print(color(str(service), 'cyan'))
 
@@ -210,11 +320,11 @@ class Service(Attribute):
 
     def __init__(
         self,
-        uuid,
+        uuid: Union[str, UUID],
         characteristics: List[Characteristic],
         primary=True,
         included_services: List[Service] = [],
-    ):
+    ) -> None:
         # Convert the uuid to a UUID object if it isn't already
         if isinstance(uuid, str):
             uuid = UUID(uuid)
@@ -239,7 +349,7 @@ class Service(Attribute):
         """
         return None
 
-    def __str__(self):
+    def __str__(self) -> str:
         return (
             f'Service(handle=0x{self.handle:04X}, '
             f'end=0x{self.end_group_handle:04X}, '
@@ -255,9 +365,11 @@ class TemplateService(Service):
     to expose their UUID as a class property
     '''
 
-    UUID: Optional[UUID] = None
+    UUID: UUID
 
-    def __init__(self, characteristics, primary=True):
+    def __init__(
+        self, characteristics: List[Characteristic], primary: bool = True
+    ) -> None:
         super().__init__(self.UUID, characteristics, primary)
 
 
@@ -269,7 +381,7 @@ class IncludedServiceDeclaration(Attribute):
 
     service: Service
 
-    def __init__(self, service):
+    def __init__(self, service: Service) -> None:
         declaration_bytes = struct.pack(
             '<HH2s', service.handle, service.end_group_handle, service.uuid.to_bytes()
         )
@@ -278,7 +390,7 @@ class IncludedServiceDeclaration(Attribute):
         )
         self.service = service
 
-    def __str__(self):
+    def __str__(self) -> str:
         return (
             f'IncludedServiceDefinition(handle=0x{self.handle:04X}, '
             f'group_starting_handle=0x{self.service.handle:04X}, '
@@ -326,7 +438,7 @@ class Characteristic(Attribute):
                     f"Characteristic.Properties::from_string() error:\nExpected a string containing any of the keys, separated by , or |: {enum_list_str}\nGot: {properties_str}"
                 )
 
-        def __str__(self):
+        def __str__(self) -> str:
             # NOTE: we override this method to offer a consistent result between python
             # versions: the value returned by IntFlag.__str__() changed in version 11.
             return '|'.join(
@@ -348,10 +460,10 @@ class Characteristic(Attribute):
 
     def __init__(
         self,
-        uuid,
+        uuid: Union[str, bytes, UUID],
         properties: Characteristic.Properties,
-        permissions,
-        value=b'',
+        permissions: Union[str, Attribute.Permissions],
+        value: Union[str, bytes, CharacteristicValue] = b'',
         descriptors: Sequence[Descriptor] = (),
     ):
         super().__init__(uuid, permissions, value)
@@ -369,7 +481,7 @@ class Characteristic(Attribute):
     def has_properties(self, properties: Characteristic.Properties) -> bool:
         return self.properties & properties == properties
 
-    def __str__(self):
+    def __str__(self) -> str:
         return (
             f'Characteristic(handle=0x{self.handle:04X}, '
             f'end=0x{self.end_group_handle:04X}, '
@@ -386,7 +498,7 @@ class CharacteristicDeclaration(Attribute):
 
     characteristic: Characteristic
 
-    def __init__(self, characteristic, value_handle):
+    def __init__(self, characteristic: Characteristic, value_handle: int) -> None:
         declaration_bytes = (
             struct.pack('<BH', characteristic.properties, value_handle)
             + characteristic.uuid.to_pdu_bytes()
@@ -397,7 +509,7 @@ class CharacteristicDeclaration(Attribute):
         self.value_handle = value_handle
         self.characteristic = characteristic
 
-    def __str__(self):
+    def __str__(self) -> str:
         return (
             f'CharacteristicDeclaration(handle=0x{self.handle:04X}, '
             f'value_handle=0x{self.value_handle:04X}, '
@@ -520,7 +632,7 @@ class CharacteristicAdapter:
 
         return self.wrapped_characteristic.unsubscribe(subscriber)
 
-    def __str__(self):
+    def __str__(self) -> str:
         wrapped = str(self.wrapped_characteristic)
         return f'{self.__class__.__name__}({wrapped})'
 
@@ -600,10 +712,10 @@ class UTF8CharacteristicAdapter(CharacteristicAdapter):
     Adapter that converts strings to/from bytes using UTF-8 encoding
     '''
 
-    def encode_value(self, value):
+    def encode_value(self, value: str) -> bytes:
         return value.encode('utf-8')
 
-    def decode_value(self, value):
+    def decode_value(self, value: bytes) -> str:
         return value.decode('utf-8')
 
 
@@ -613,7 +725,7 @@ class Descriptor(Attribute):
     See Vol 3, Part G - 3.3.3 Characteristic Descriptor Declarations
     '''
 
-    def __str__(self):
+    def __str__(self) -> str:
         return (
             f'Descriptor(handle=0x{self.handle:04X}, '
             f'type={self.type}, '

bumble/gatt_client.py

@@ -28,7 +28,19 @@ import asyncio
 import logging
 import struct
 from datetime import datetime
-from typing import List, Optional, Dict, Tuple, Callable, Union, Any
+from typing import (
+    List,
+    Optional,
+    Dict,
+    Tuple,
+    Callable,
+    Union,
+    Any,
+    Iterable,
+    Type,
+    Set,
+    TYPE_CHECKING,
+)
 
 from pyee import EventEmitter
 
@@ -66,8 +78,12 @@ from .gatt import (
     GATT_INCLUDE_ATTRIBUTE_TYPE,
     Characteristic,
     ClientCharacteristicConfigurationBits,
+    TemplateService,
 )
 
+if TYPE_CHECKING:
+    from bumble.device import Connection
+
 # -----------------------------------------------------------------------------
 # Logging
 # -----------------------------------------------------------------------------
@@ -78,16 +94,16 @@ logger = logging.getLogger(__name__)
 # Proxies
 # -----------------------------------------------------------------------------
 class AttributeProxy(EventEmitter):
-    client: Client
-
-    def __init__(self, client, handle, end_group_handle, attribute_type):
+    def __init__(
+        self, client: Client, handle: int, end_group_handle: int, attribute_type: UUID
+    ) -> None:
         EventEmitter.__init__(self)
         self.client = client
         self.handle = handle
         self.end_group_handle = end_group_handle
         self.type = attribute_type
 
-    async def read_value(self, no_long_read=False):
+    async def read_value(self, no_long_read: bool = False) -> bytes:
         return self.decode_value(
             await self.client.read_value(self.handle, no_long_read)
         )
@@ -97,13 +113,13 @@ class AttributeProxy(EventEmitter):
             self.handle, self.encode_value(value), with_response
         )
 
-    def encode_value(self, value):
+    def encode_value(self, value: Any) -> bytes:
         return value
 
-    def decode_value(self, value_bytes):
+    def decode_value(self, value_bytes: bytes) -> Any:
         return value_bytes
 
-    def __str__(self):
+    def __str__(self) -> str:
         return f'Attribute(handle=0x{self.handle:04X}, type={self.type})'
 
 
@@ -113,7 +129,7 @@ class ServiceProxy(AttributeProxy):
     included_services: List[ServiceProxy]
 
     @staticmethod
-    def from_client(service_class, client, service_uuid):
+    def from_client(service_class, client: Client, service_uuid: UUID):
         # The service and its characteristics are considered to have already been
         # discovered
         services = client.get_services_by_uuid(service_uuid)
@@ -136,14 +152,14 @@ class ServiceProxy(AttributeProxy):
     def get_characteristics_by_uuid(self, uuid):
         return self.client.get_characteristics_by_uuid(uuid, self)
 
-    def __str__(self):
+    def __str__(self) -> str:
         return f'Service(handle=0x{self.handle:04X}, uuid={self.uuid})'
 
 
 class CharacteristicProxy(AttributeProxy):
     properties: Characteristic.Properties
     descriptors: List[DescriptorProxy]
-    subscribers: Dict[Any, Callable]
+    subscribers: Dict[Any, Callable[[bytes], Any]]
 
     def __init__(
         self,
@@ -171,7 +187,9 @@ class CharacteristicProxy(AttributeProxy):
         return await self.client.discover_descriptors(self)
 
     async def subscribe(
-        self, subscriber: Optional[Callable] = None, prefer_notify=True
+        self,
+        subscriber: Optional[Callable[[bytes], Any]] = None,
+        prefer_notify: bool = True,
     ):
         if subscriber is not None:
             if subscriber in self.subscribers:
@@ -189,13 +207,13 @@ class CharacteristicProxy(AttributeProxy):
 
         return await self.client.subscribe(self, subscriber, prefer_notify)
 
-    async def unsubscribe(self, subscriber=None):
+    async def unsubscribe(self, subscriber=None, force=False):
         if subscriber in self.subscribers:
             subscriber = self.subscribers.pop(subscriber)
 
-        return await self.client.unsubscribe(self, subscriber)
+        return await self.client.unsubscribe(self, subscriber, force)
 
-    def __str__(self):
+    def __str__(self) -> str:
         return (
             f'Characteristic(handle=0x{self.handle:04X}, '
             f'uuid={self.uuid}, '
@@ -207,7 +225,7 @@ class DescriptorProxy(AttributeProxy):
     def __init__(self, client, handle, descriptor_type):
         super().__init__(client, handle, 0, descriptor_type)
 
-    def __str__(self):
+    def __str__(self) -> str:
         return f'Descriptor(handle=0x{self.handle:04X}, type={self.type})'
 
 
@@ -216,8 +234,10 @@ class ProfileServiceProxy:
     Base class for profile-specific service proxies
     '''
 
+    SERVICE_CLASS: Type[TemplateService]
+
     @classmethod
-    def from_client(cls, client):
+    def from_client(cls, client: Client) -> ProfileServiceProxy:
         return ServiceProxy.from_client(cls, client, cls.SERVICE_CLASS.UUID)
 
 
@@ -227,30 +247,36 @@ class ProfileServiceProxy:
 class Client:
     services: List[ServiceProxy]
     cached_values: Dict[int, Tuple[datetime, bytes]]
+    notification_subscribers: Dict[
+        int, Set[Union[CharacteristicProxy, Callable[[bytes], Any]]]
+    ]
+    indication_subscribers: Dict[
+        int, Set[Union[CharacteristicProxy, Callable[[bytes], Any]]]
+    ]
+    pending_response: Optional[asyncio.futures.Future[ATT_PDU]]
+    pending_request: Optional[ATT_PDU]
 
-    def __init__(self, connection):
+    def __init__(self, connection: Connection) -> None:
         self.connection = connection
         self.mtu_exchange_done = False
         self.request_semaphore = asyncio.Semaphore(1)
         self.pending_request = None
         self.pending_response = None
-        self.notification_subscribers = (
-            {}
-        )  # Notification subscribers, by attribute handle
-        self.indication_subscribers = {}  # Indication subscribers, by attribute handle
+        self.notification_subscribers = {}  # Subscriber set, by attribute handle
+        self.indication_subscribers = {}  # Subscriber set, by attribute handle
         self.services = []
         self.cached_values = {}
 
-    def send_gatt_pdu(self, pdu):
+    def send_gatt_pdu(self, pdu: bytes) -> None:
         self.connection.send_l2cap_pdu(ATT_CID, pdu)
 
-    async def send_command(self, command):
+    async def send_command(self, command: ATT_PDU) -> None:
         logger.debug(
             f'GATT Command from client: [0x{self.connection.handle:04X}] {command}'
         )
         self.send_gatt_pdu(command.to_bytes())
 
-    async def send_request(self, request):
+    async def send_request(self, request: ATT_PDU):
         logger.debug(
             f'GATT Request from client: [0x{self.connection.handle:04X}] {request}'
         )
@@ -279,14 +305,14 @@ class Client:
 
         return response
 
-    def send_confirmation(self, confirmation):
+    def send_confirmation(self, confirmation: ATT_Handle_Value_Confirmation) -> None:
         logger.debug(
             f'GATT Confirmation from client: [0x{self.connection.handle:04X}] '
             f'{confirmation}'
         )
         self.send_gatt_pdu(confirmation.to_bytes())
 
-    async def request_mtu(self, mtu):
+    async def request_mtu(self, mtu: int) -> int:
         # Check the range
         if mtu < ATT_DEFAULT_MTU:
             raise ValueError(f'MTU must be >= {ATT_DEFAULT_MTU}')
@@ -313,10 +339,12 @@ class Client:
 
         return self.connection.att_mtu
 
-    def get_services_by_uuid(self, uuid):
+    def get_services_by_uuid(self, uuid: UUID) -> List[ServiceProxy]:
         return [service for service in self.services if service.uuid == uuid]
 
-    def get_characteristics_by_uuid(self, uuid, service=None):
+    def get_characteristics_by_uuid(
+        self, uuid: UUID, service: Optional[ServiceProxy] = None
+    ) -> List[CharacteristicProxy]:
         services = [service] if service else self.services
         return [
             c
@@ -363,7 +391,7 @@ class Client:
         if not already_known:
             self.services.append(service)
 
-    async def discover_services(self, uuids=None) -> List[ServiceProxy]:
+    async def discover_services(self, uuids: Iterable[UUID] = []) -> List[ServiceProxy]:
         '''
         See Vol 3, Part G - 4.4.1 Discover All Primary Services
         '''
@@ -435,7 +463,7 @@ class Client:
 
         return services
 
-    async def discover_service(self, uuid):
+    async def discover_service(self, uuid: Union[str, UUID]) -> List[ServiceProxy]:
         '''
         See Vol 3, Part G - 4.4.2 Discover Primary Service by Service UUID
         '''
@@ -468,7 +496,7 @@ class Client:
                         f'{HCI_Constant.error_name(response.error_code)}'
                     )
                     # TODO raise appropriate exception
-                    return
+                    return []
                 break
 
             for attribute_handle, end_group_handle in response.handles_information:
@@ -480,7 +508,7 @@ class Client:
                     logger.warning(
                         f'bogus handle values: {attribute_handle} {end_group_handle}'
                     )
-                    return
+                    return []
 
                 # Create a service proxy for this service
                 service = ServiceProxy(
@@ -657,8 +685,8 @@ class Client:
     async def discover_descriptors(
         self,
         characteristic: Optional[CharacteristicProxy] = None,
-        start_handle=None,
-        end_handle=None,
+        start_handle: Optional[int] = None,
+        end_handle: Optional[int] = None,
     ) -> List[DescriptorProxy]:
         '''
         See Vol 3, Part G - 4.7.1 Discover All Characteristic Descriptors
@@ -721,7 +749,7 @@ class Client:
 
         return descriptors
 
-    async def discover_attributes(self):
+    async def discover_attributes(self) -> List[AttributeProxy]:
         '''
         Discover all attributes, regardless of type
         '''
@@ -764,7 +792,12 @@ class Client:
 
         return attributes
 
-    async def subscribe(self, characteristic, subscriber=None, prefer_notify=True):
+    async def subscribe(
+        self,
+        characteristic: CharacteristicProxy,
+        subscriber: Optional[Callable[[bytes], Any]] = None,
+        prefer_notify: bool = True,
+    ) -> None:
         # If we haven't already discovered the descriptors for this characteristic,
         # do it now
         if not characteristic.descriptors_discovered:
@@ -801,6 +834,7 @@ class Client:
         subscriber_set = subscribers.setdefault(characteristic.handle, set())
         if subscriber is not None:
             subscriber_set.add(subscriber)
+
         # Add the characteristic as a subscriber, which will result in the
         # characteristic emitting an 'update' event when a notification or indication
         # is received
@@ -808,7 +842,18 @@ class Client:
 
         await self.write_value(cccd, struct.pack('<H', bits), with_response=True)
 
-    async def unsubscribe(self, characteristic, subscriber=None):
+    async def unsubscribe(
+        self,
+        characteristic: CharacteristicProxy,
+        subscriber: Optional[Callable[[bytes], Any]] = None,
+        force: bool = False,
+    ) -> None:
+        '''
+        Unsubscribe from a characteristic.
+
+        If `force` is True, this will write zeros to the CCCD when there are no
+        subscribers left, even if there were already no registered subscribers.
+        '''
         # If we haven't already discovered the descriptors for this characteristic,
         # do it now
         if not characteristic.descriptors_discovered:
@@ -822,29 +867,45 @@ class Client:
             logger.warning('unsubscribing from characteristic with no CCCD descriptor')
             return
 
+        # Check if the characteristic has subscribers
+        if not (
+            characteristic.handle in self.notification_subscribers
+            or characteristic.handle in self.indication_subscribers
+        ):
+            if not force:
+                return
+
+        # Remove the subscriber(s)
         if subscriber is not None:
             # Remove matching subscriber from subscriber sets
             for subscriber_set in (
                 self.notification_subscribers,
                 self.indication_subscribers,
             ):
-                subscribers = subscriber_set.get(characteristic.handle, [])
-                if subscriber in subscribers:
+                if (
+                    subscribers := subscriber_set.get(characteristic.handle)
+                ) and subscriber in subscribers:
                     subscribers.remove(subscriber)
 
                     # Cleanup if we removed the last one
                     if not subscribers:
                         del subscriber_set[characteristic.handle]
         else:
-            # Remove all subscribers for this attribute from the sets!
+            # Remove all subscribers for this attribute from the sets
             self.notification_subscribers.pop(characteristic.handle, None)
             self.indication_subscribers.pop(characteristic.handle, None)
 
-        if not self.notification_subscribers and not self.indication_subscribers:
+        # Update the CCCD
+        if not (
+            characteristic.handle in self.notification_subscribers
+            or characteristic.handle in self.indication_subscribers
+        ):
             # No more subscribers left
             await self.write_value(cccd, b'\x00\x00', with_response=True)
 
-    async def read_value(self, attribute, no_long_read=False):
+    async def read_value(
+        self, attribute: Union[int, AttributeProxy], no_long_read: bool = False
+    ) -> bytes:
         '''
         See Vol 3, Part G - 4.8.1 Read Characteristic Value
 
@@ -905,7 +966,9 @@ class Client:
         # Return the value as bytes
         return attribute_value
 
-    async def read_characteristics_by_uuid(self, uuid, service):
+    async def read_characteristics_by_uuid(
+        self, uuid: UUID, service: Optional[ServiceProxy]
+    ) -> List[bytes]:
         '''
         See Vol 3, Part G - 4.8.2 Read Using Characteristic UUID
         '''
@@ -960,7 +1023,12 @@ class Client:
 
         return characteristics_values
 
-    async def write_value(self, attribute, value, with_response=False):
+    async def write_value(
+        self,
+        attribute: Union[int, AttributeProxy],
+        value: bytes,
+        with_response: bool = False,
+    ) -> None:
         '''
         See Vol 3, Part G - 4.9.1 Write Without Response & 4.9.3 Write Characteristic
         Value
@@ -990,7 +1058,7 @@ class Client:
                 )
             )
 
-    def on_gatt_pdu(self, att_pdu):
+    def on_gatt_pdu(self, att_pdu: ATT_PDU) -> None:
         logger.debug(
             f'GATT Response to client: [0x{self.connection.handle:04X}] {att_pdu}'
         )
@@ -1013,6 +1081,7 @@ class Client:
                     return
 
             # Return the response to the coroutine that is waiting for it
+            assert self.pending_response is not None
             self.pending_response.set_result(att_pdu)
         else:
             handler_name = f'on_{att_pdu.name.lower()}'
@@ -1032,7 +1101,7 @@ class Client:
     def on_att_handle_value_notification(self, notification):
         # Call all subscribers
         subscribers = self.notification_subscribers.get(
-            notification.attribute_handle, []
+            notification.attribute_handle, set()
         )
         if not subscribers:
             logger.warning('!!! received notification with no subscriber')
@@ -1046,7 +1115,9 @@ class Client:
 
     def on_att_handle_value_indication(self, indication):
         # Call all subscribers
-        subscribers = self.indication_subscribers.get(indication.attribute_handle, [])
+        subscribers = self.indication_subscribers.get(
+            indication.attribute_handle, set()
+        )
         if not subscribers:
             logger.warning('!!! received indication with no subscriber')
 
@@ -1060,7 +1131,7 @@ class Client:
         # Confirm that we received the indication
         self.send_confirmation(ATT_Handle_Value_Confirmation())
 
-    def cache_value(self, attribute_handle: int, value: bytes):
+    def cache_value(self, attribute_handle: int, value: bytes) -> None:
         self.cached_values[attribute_handle] = (
             datetime.now(),
             value,

bumble/gatt_server.py

@@ -23,11 +23,12 @@
 # -----------------------------------------------------------------------------
 # Imports
 # -----------------------------------------------------------------------------
+from __future__ import annotations
 import asyncio
 import logging
 from collections import defaultdict
 import struct
-from typing import List, Tuple, Optional, TypeVar, Type
+from typing import List, Tuple, Optional, TypeVar, Type, Dict, Iterable, TYPE_CHECKING
 from pyee import EventEmitter
 
 from .colors import color
@@ -42,6 +43,7 @@ from .att import (
     ATT_INVALID_OFFSET_ERROR,
     ATT_REQUEST_NOT_SUPPORTED_ERROR,
     ATT_REQUESTS,
+    ATT_PDU,
     ATT_UNLIKELY_ERROR_ERROR,
     ATT_UNSUPPORTED_GROUP_TYPE_ERROR,
     ATT_Error,
@@ -73,6 +75,8 @@ from .gatt import (
     Service,
 )
 
+if TYPE_CHECKING:
+    from bumble.device import Device, Connection
 
 # -----------------------------------------------------------------------------
 # Logging
@@ -91,8 +95,13 @@ GATT_SERVER_DEFAULT_MAX_MTU = 517
 # -----------------------------------------------------------------------------
 class Server(EventEmitter):
     attributes: List[Attribute]
+    services: List[Service]
+    attributes_by_handle: Dict[int, Attribute]
+    subscribers: Dict[int, Dict[int, bytes]]
+    indication_semaphores: defaultdict[int, asyncio.Semaphore]
+    pending_confirmations: defaultdict[int, Optional[asyncio.futures.Future]]
 
-    def __init__(self, device):
+    def __init__(self, device: Device) -> None:
         super().__init__()
         self.device = device
         self.services = []
@@ -107,16 +116,16 @@ class Server(EventEmitter):
         self.indication_semaphores = defaultdict(lambda: asyncio.Semaphore(1))
         self.pending_confirmations = defaultdict(lambda: None)
 
-    def __str__(self):
+    def __str__(self) -> str:
         return "\n".join(map(str, self.attributes))
 
-    def send_gatt_pdu(self, connection_handle, pdu):
+    def send_gatt_pdu(self, connection_handle: int, pdu: bytes) -> None:
         self.device.send_l2cap_pdu(connection_handle, ATT_CID, pdu)
 
-    def next_handle(self):
+    def next_handle(self) -> int:
         return 1 + len(self.attributes)
 
-    def get_advertising_service_data(self):
+    def get_advertising_service_data(self) -> Dict[Attribute, bytes]:
         return {
             attribute: data
             for attribute in self.attributes
@@ -124,7 +133,7 @@ class Server(EventEmitter):
             and (data := attribute.get_advertising_data())
         }
 
-    def get_attribute(self, handle):
+    def get_attribute(self, handle: int) -> Optional[Attribute]:
         attribute = self.attributes_by_handle.get(handle)
         if attribute:
             return attribute
@@ -173,12 +182,17 @@ class Server(EventEmitter):
 
         return next(
             (
-                (attribute, self.get_attribute(attribute.characteristic.handle))
+                (
+                    attribute,
+                    self.get_attribute(attribute.characteristic.handle),
+                )  # type: ignore
                 for attribute in map(
                     self.get_attribute,
                     range(service_handle.handle, service_handle.end_group_handle + 1),
                 )
-                if attribute.type == GATT_CHARACTERISTIC_ATTRIBUTE_TYPE
+                if attribute is not None
+                and attribute.type == GATT_CHARACTERISTIC_ATTRIBUTE_TYPE
+                and isinstance(attribute, CharacteristicDeclaration)
                 and attribute.characteristic.uuid == characteristic_uuid
             ),
             None,
@@ -197,7 +211,7 @@ class Server(EventEmitter):
 
         return next(
             (
-                attribute
+                attribute  # type: ignore
                 for attribute in map(
                     self.get_attribute,
                     range(
@@ -205,12 +219,12 @@ class Server(EventEmitter):
                         characteristic_value.end_group_handle + 1,
                     ),
                 )
-                if attribute.type == descriptor_uuid
+                if attribute is not None and attribute.type == descriptor_uuid
             ),
             None,
         )
 
-    def add_attribute(self, attribute):
+    def add_attribute(self, attribute: Attribute) -> None:
         # Assign a handle to this attribute
         attribute.handle = self.next_handle()
         attribute.end_group_handle = (
@@ -220,7 +234,7 @@ class Server(EventEmitter):
         # Add this attribute to the list
         self.attributes.append(attribute)
 
-    def add_service(self, service: Service):
+    def add_service(self, service: Service) -> None:
         # Add the service attribute to the DB
         self.add_attribute(service)
 
@@ -285,11 +299,13 @@ class Server(EventEmitter):
         service.end_group_handle = self.attributes[-1].handle
         self.services.append(service)
 
-    def add_services(self, services):
+    def add_services(self, services: Iterable[Service]) -> None:
         for service in services:
             self.add_service(service)
 
-    def read_cccd(self, connection, characteristic):
+    def read_cccd(
+        self, connection: Optional[Connection], characteristic: Characteristic
+    ) -> bytes:
         if connection is None:
             return bytes([0, 0])
 
@@ -300,7 +316,12 @@ class Server(EventEmitter):
 
         return cccd or bytes([0, 0])
 
-    def write_cccd(self, connection, characteristic, value):
+    def write_cccd(
+        self,
+        connection: Connection,
+        characteristic: Characteristic,
+        value: bytes,
+    ) -> None:
         logger.debug(
             f'Subscription update for connection=0x{connection.handle:04X}, '
             f'handle=0x{characteristic.handle:04X}: {value.hex()}'
@@ -327,13 +348,19 @@ class Server(EventEmitter):
             indicate_enabled,
         )
 
-    def send_response(self, connection, response):
+    def send_response(self, connection: Connection, response: ATT_PDU) -> None:
         logger.debug(
             f'GATT Response from server: [0x{connection.handle:04X}] {response}'
         )
         self.send_gatt_pdu(connection.handle, response.to_bytes())
 
-    async def notify_subscriber(self, connection, attribute, value=None, force=False):
+    async def notify_subscriber(
+        self,
+        connection: Connection,
+        attribute: Attribute,
+        value: Optional[bytes] = None,
+        force: bool = False,
+    ) -> None:
         # Check if there's a subscriber
         if not force:
             subscribers = self.subscribers.get(connection.handle)
@@ -370,7 +397,13 @@ class Server(EventEmitter):
         )
         self.send_gatt_pdu(connection.handle, bytes(notification))
 
-    async def indicate_subscriber(self, connection, attribute, value=None, force=False):
+    async def indicate_subscriber(
+        self,
+        connection: Connection,
+        attribute: Attribute,
+        value: Optional[bytes] = None,
+        force: bool = False,
+    ) -> None:
         # Check if there's a subscriber
         if not force:
             subscribers = self.subscribers.get(connection.handle)
@@ -411,15 +444,13 @@ class Server(EventEmitter):
             assert self.pending_confirmations[connection.handle] is None
 
             # Create a future value to hold the eventual response
-            self.pending_confirmations[
+            pending_confirmation = self.pending_confirmations[
                 connection.handle
             ] = asyncio.get_running_loop().create_future()
 
             try:
                 self.send_gatt_pdu(connection.handle, indication.to_bytes())
-                await asyncio.wait_for(
-                    self.pending_confirmations[connection.handle], GATT_REQUEST_TIMEOUT
-                )
+                await asyncio.wait_for(pending_confirmation, GATT_REQUEST_TIMEOUT)
             except asyncio.TimeoutError as error:
                 logger.warning(color('!!! GATT Indicate timeout', 'red'))
                 raise TimeoutError(f'GATT timeout for {indication.name}') from error
@@ -427,8 +458,12 @@ class Server(EventEmitter):
                 self.pending_confirmations[connection.handle] = None
 
     async def notify_or_indicate_subscribers(
-        self, indicate, attribute, value=None, force=False
-    ):
+        self,
+        indicate: bool,
+        attribute: Attribute,
+        value: Optional[bytes] = None,
+        force: bool = False,
+    ) -> None:
         # Get all the connections for which there's at least one subscription
         connections = [
             connection
@@ -450,13 +485,23 @@ class Server(EventEmitter):
                 ]
             )
 
-    async def notify_subscribers(self, attribute, value=None, force=False):
+    async def notify_subscribers(
+        self,
+        attribute: Attribute,
+        value: Optional[bytes] = None,
+        force: bool = False,
+    ):
         return await self.notify_or_indicate_subscribers(False, attribute, value, force)
 
-    async def indicate_subscribers(self, attribute, value=None, force=False):
+    async def indicate_subscribers(
+        self,
+        attribute: Attribute,
+        value: Optional[bytes] = None,
+        force: bool = False,
+    ):
         return await self.notify_or_indicate_subscribers(True, attribute, value, force)
 
-    def on_disconnection(self, connection):
+    def on_disconnection(self, connection: Connection) -> None:
         if connection.handle in self.subscribers:
             del self.subscribers[connection.handle]
         if connection.handle in self.indication_semaphores:
@@ -464,7 +509,7 @@ class Server(EventEmitter):
         if connection.handle in self.pending_confirmations:
             del self.pending_confirmations[connection.handle]
 
-    def on_gatt_pdu(self, connection, att_pdu):
+    def on_gatt_pdu(self, connection: Connection, att_pdu: ATT_PDU) -> None:
         logger.debug(f'GATT Request to server: [0x{connection.handle:04X}] {att_pdu}')
         handler_name = f'on_{att_pdu.name.lower()}'
         handler = getattr(self, handler_name, None)
@@ -506,7 +551,7 @@ class Server(EventEmitter):
     #######################################################
     # ATT handlers
     #######################################################
-    def on_att_request(self, connection, pdu):
+    def on_att_request(self, connection: Connection, pdu: ATT_PDU) -> None:
         '''
         Handler for requests without a more specific handler
         '''
@@ -679,7 +724,6 @@ class Server(EventEmitter):
             and attribute.handle <= request.ending_handle
             and pdu_space_available
         ):
-
             try:
                 attribute_value = attribute.read_value(connection)
             except ATT_Error as error:

bumble/helpers.py

@@ -15,30 +15,39 @@
 # -----------------------------------------------------------------------------
 # Imports
 # -----------------------------------------------------------------------------
+from __future__ import annotations
+
+from collections.abc import Callable, MutableMapping
+from typing import cast, Any
 import logging
 
-from .colors import color
-from .att import ATT_CID, ATT_PDU
-from .smp import SMP_CID, SMP_Command
-from .core import name_or_number
-from .l2cap import (
+from bumble import avdtp
+from bumble.colors import color
+from bumble.att import ATT_CID, ATT_PDU
+from bumble.smp import SMP_CID, SMP_Command
+from bumble.core import name_or_number
+from bumble.l2cap import (
     L2CAP_PDU,
     L2CAP_CONNECTION_REQUEST,
     L2CAP_CONNECTION_RESPONSE,
     L2CAP_SIGNALING_CID,
     L2CAP_LE_SIGNALING_CID,
     L2CAP_Control_Frame,
+    L2CAP_Connection_Request,
     L2CAP_Connection_Response,
 )
-from .hci import (
+from bumble.hci import (
     HCI_EVENT_PACKET,
     HCI_ACL_DATA_PACKET,
     HCI_DISCONNECTION_COMPLETE_EVENT,
     HCI_AclDataPacketAssembler,
+    HCI_Packet,
+    HCI_Event,
+    HCI_AclDataPacket,
+    HCI_Disconnection_Complete_Event,
 )
-from .rfcomm import RFCOMM_Frame, RFCOMM_PSM
-from .sdp import SDP_PDU, SDP_PSM
-from .avdtp import MessageAssembler as AVDTP_MessageAssembler, AVDTP_PSM
+from bumble.rfcomm import RFCOMM_Frame, RFCOMM_PSM
+from bumble.sdp import SDP_PDU, SDP_PSM
 
 # -----------------------------------------------------------------------------
 # Logging
@@ -50,23 +59,25 @@ logger = logging.getLogger(__name__)
 PSM_NAMES = {
     RFCOMM_PSM: 'RFCOMM',
     SDP_PSM: 'SDP',
-    AVDTP_PSM: 'AVDTP'
-    # TODO: add more PSM values
+    avdtp.AVDTP_PSM: 'AVDTP',
 }
 
 
 # -----------------------------------------------------------------------------
 class PacketTracer:
     class AclStream:
-        def __init__(self, analyzer):
+        psms: MutableMapping[int, int]
+        peer: PacketTracer.AclStream
+        avdtp_assemblers: MutableMapping[int, avdtp.MessageAssembler]
+
+        def __init__(self, analyzer: PacketTracer.Analyzer) -> None:
             self.analyzer = analyzer
             self.packet_assembler = HCI_AclDataPacketAssembler(self.on_acl_pdu)
             self.avdtp_assemblers = {}  # AVDTP assemblers, by source_cid
             self.psms = {}  # PSM, by source_cid
-            self.peer = None  # ACL stream in the other direction
 
         # pylint: disable=too-many-nested-blocks
-        def on_acl_pdu(self, pdu):
+        def on_acl_pdu(self, pdu: bytes) -> None:
             l2cap_pdu = L2CAP_PDU.from_bytes(pdu)
 
             if l2cap_pdu.cid == ATT_CID:
@@ -81,26 +92,30 @@ class PacketTracer:
 
                 # Check if this signals a new channel
                 if control_frame.code == L2CAP_CONNECTION_REQUEST:
-                    self.psms[control_frame.source_cid] = control_frame.psm
+                    connection_request = cast(L2CAP_Connection_Request, control_frame)
+                    self.psms[connection_request.source_cid] = connection_request.psm
                 elif control_frame.code == L2CAP_CONNECTION_RESPONSE:
+                    connection_response = cast(L2CAP_Connection_Response, control_frame)
                     if (
-                        control_frame.result
+                        connection_response.result
                         == L2CAP_Connection_Response.CONNECTION_SUCCESSFUL
                     ):
                         if self.peer:
-                            if psm := self.peer.psms.get(control_frame.source_cid):
+                            if psm := self.peer.psms.get(
+                                connection_response.source_cid
+                            ):
                                 # Found a pending connection
-                                self.psms[control_frame.destination_cid] = psm
+                                self.psms[connection_response.destination_cid] = psm
 
                                 # For AVDTP connections, create a packet assembler for
                                 # each direction
-                                if psm == AVDTP_PSM:
+                                if psm == avdtp.AVDTP_PSM:
                                     self.avdtp_assemblers[
-                                        control_frame.source_cid
-                                    ] = AVDTP_MessageAssembler(self.on_avdtp_message)
+                                        connection_response.source_cid
+                                    ] = avdtp.MessageAssembler(self.on_avdtp_message)
                                     self.peer.avdtp_assemblers[
-                                        control_frame.destination_cid
-                                    ] = AVDTP_MessageAssembler(
+                                        connection_response.destination_cid
+                                    ] = avdtp.MessageAssembler(
                                         self.peer.on_avdtp_message
                                     )
 
@@ -113,7 +128,7 @@ class PacketTracer:
                     elif psm == RFCOMM_PSM:
                         rfcomm_frame = RFCOMM_Frame.from_bytes(l2cap_pdu.payload)
                         self.analyzer.emit(rfcomm_frame)
-                    elif psm == AVDTP_PSM:
+                    elif psm == avdtp.AVDTP_PSM:
                         self.analyzer.emit(
                             f'{color("L2CAP", "green")} [CID={l2cap_pdu.cid}, '
                             f'PSM=AVDTP]: {l2cap_pdu.payload.hex()}'
@@ -130,22 +145,26 @@ class PacketTracer:
                 else:
                     self.analyzer.emit(l2cap_pdu)
 
-        def on_avdtp_message(self, transaction_label, message):
+        def on_avdtp_message(
+            self, transaction_label: int, message: avdtp.Message
+        ) -> None:
             self.analyzer.emit(
                 f'{color("AVDTP", "green")} [{transaction_label}] {message}'
             )
 
-        def feed_packet(self, packet):
+        def feed_packet(self, packet: HCI_AclDataPacket) -> None:
             self.packet_assembler.feed_packet(packet)
 
     class Analyzer:
-        def __init__(self, label, emit_message):
+        acl_streams: MutableMapping[int, PacketTracer.AclStream]
+        peer: PacketTracer.Analyzer
+
+        def __init__(self, label: str, emit_message: Callable[..., None]) -> None:
             self.label = label
             self.emit_message = emit_message
             self.acl_streams = {}  # ACL streams, by connection handle
-            self.peer = None  # Analyzer in the other direction
 
-        def start_acl_stream(self, connection_handle):
+        def start_acl_stream(self, connection_handle: int) -> PacketTracer.AclStream:
             logger.info(
                 f'[{self.label}] +++ Creating ACL stream for connection '
                 f'0x{connection_handle:04X}'
@@ -160,7 +179,7 @@ class PacketTracer:
 
             return stream
 
-        def end_acl_stream(self, connection_handle):
+        def end_acl_stream(self, connection_handle: int) -> None:
             if connection_handle in self.acl_streams:
                 logger.info(
                     f'[{self.label}] --- Removing ACL stream for connection '
@@ -171,23 +190,29 @@ class PacketTracer:
                 # Let the other forwarder know so it can cleanup its stream as well
                 self.peer.end_acl_stream(connection_handle)
 
-        def on_packet(self, packet):
+        def on_packet(self, packet: HCI_Packet) -> None:
             self.emit(packet)
 
             if packet.hci_packet_type == HCI_ACL_DATA_PACKET:
+                acl_packet = cast(HCI_AclDataPacket, packet)
                 # Look for an existing stream for this handle, create one if it is the
                 # first ACL packet for that connection handle
-                if (stream := self.acl_streams.get(packet.connection_handle)) is None:
-                    stream = self.start_acl_stream(packet.connection_handle)
-                stream.feed_packet(packet)
+                if (
+                    stream := self.acl_streams.get(acl_packet.connection_handle)
+                ) is None:
+                    stream = self.start_acl_stream(acl_packet.connection_handle)
+                stream.feed_packet(acl_packet)
             elif packet.hci_packet_type == HCI_EVENT_PACKET:
-                if packet.event_code == HCI_DISCONNECTION_COMPLETE_EVENT:
-                    self.end_acl_stream(packet.connection_handle)
+                event_packet = cast(HCI_Event, packet)
+                if event_packet.event_code == HCI_DISCONNECTION_COMPLETE_EVENT:
+                    self.end_acl_stream(
+                        cast(HCI_Disconnection_Complete_Event, packet).connection_handle
+                    )
 
-        def emit(self, message):
+        def emit(self, message: Any) -> None:
             self.emit_message(f'[{self.label}] {message}')
 
-    def trace(self, packet, direction=0):
+    def trace(self, packet: HCI_Packet, direction: int = 0) -> None:
         if direction == 0:
             self.host_to_controller_analyzer.on_packet(packet)
         else:
@@ -195,10 +220,10 @@ class PacketTracer:
 
     def __init__(
         self,
-        host_to_controller_label=color('HOST->CONTROLLER', 'blue'),
-        controller_to_host_label=color('CONTROLLER->HOST', 'cyan'),
-        emit_message=logger.info,
-    ):
+        host_to_controller_label: str = color('HOST->CONTROLLER', 'blue'),
+        controller_to_host_label: str = color('CONTROLLER->HOST', 'cyan'),
+        emit_message: Callable[..., None] = logger.info,
+    ) -> None:
         self.host_to_controller_analyzer = PacketTracer.Analyzer(
             host_to_controller_label, emit_message
         )

bumble/hfp.py

@@ -15,16 +15,19 @@
 # -----------------------------------------------------------------------------
 # Imports
 # -----------------------------------------------------------------------------
+import collections.abc
 import logging
 import asyncio
 import dataclasses
 import enum
 import traceback
-from typing import Dict, List, Union, Set
+import warnings
+from typing import Dict, List, Union, Set, Any, TYPE_CHECKING
 
 from . import at
 from . import rfcomm
 
+from bumble.colors import color
 from bumble.core import (
     ProtocolError,
     BT_GENERIC_AUDIO_SERVICE,
@@ -32,6 +35,11 @@ from bumble.core import (
     BT_L2CAP_PROTOCOL_ID,
     BT_RFCOMM_PROTOCOL_ID,
 )
+from bumble.hci import (
+    HCI_Enhanced_Setup_Synchronous_Connection_Command,
+    CodingFormat,
+    CodecID,
+)
 from bumble.sdp import (
     DataElement,
     ServiceAttribute,
@@ -48,6 +56,72 @@ from bumble.sdp import (
 # -----------------------------------------------------------------------------
 logger = logging.getLogger(__name__)
 
+# -----------------------------------------------------------------------------
+# Error
+# -----------------------------------------------------------------------------
+
+
+class HfpProtocolError(ProtocolError):
+    def __init__(self, error_name: str = '', details: str = ''):
+        super().__init__(None, 'hfp', error_name, details)
+
+
+# -----------------------------------------------------------------------------
+# Protocol Support
+# -----------------------------------------------------------------------------
+
+
+# -----------------------------------------------------------------------------
+class HfpProtocol:
+    dlc: rfcomm.DLC
+    buffer: str
+    lines: collections.deque
+    lines_available: asyncio.Event
+
+    def __init__(self, dlc: rfcomm.DLC) -> None:
+        warnings.warn("See HfProtocol", DeprecationWarning)
+        self.dlc = dlc
+        self.buffer = ''
+        self.lines = collections.deque()
+        self.lines_available = asyncio.Event()
+
+        dlc.sink = self.feed
+
+    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')
+
+        logger.debug(f'<<< Data received: {data}')
+
+        # Add to the buffer and look for lines
+        self.buffer += data
+        while (separator := self.buffer.find('\r')) >= 0:
+            line = self.buffer[:separator].strip()
+            self.buffer = self.buffer[separator + 1 :]
+            if len(line) > 0:
+                self.on_line(line)
+
+    def on_line(self, line: str) -> None:
+        self.lines.append(line)
+        self.lines_available.set()
+
+    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: str) -> None:
+        logger.debug(color(f'>>> {line}', 'yellow'))
+        self.dlc.write('\r\n' + line + '\r\n')
+
+    async def next_line(self) -> str:
+        await self.lines_available.wait()
+        line = self.lines.popleft()
+        if not self.lines:
+            self.lines_available.clear()
+        logger.debug(color(f'<<< {line}', 'green'))
+        return line
+
 
 # -----------------------------------------------------------------------------
 # Normative protocol definitions
@@ -302,8 +376,12 @@ class HfProtocol:
 
     dlc: rfcomm.DLC
     command_lock: asyncio.Lock
-    response_queue: asyncio.Queue
-    unsolicited_queue: asyncio.Queue
+    if TYPE_CHECKING:
+        response_queue: asyncio.Queue[AtResponse]
+        unsolicited_queue: asyncio.Queue[AtResponse]
+    else:
+        response_queue: asyncio.Queue
+        unsolicited_queue: asyncio.Queue
     read_buffer: bytearray
 
     def __init__(self, dlc: rfcomm.DLC, configuration: Configuration):
@@ -368,7 +446,7 @@ class HfProtocol:
         else:
             logger.warning(f"dropping unexpected response with code '{response.code}'")
 
-    # Send an AT command and wait for the peer resposne.
+    # Send an AT command and wait for the peer response.
     # Wait for the AT responses sent by the peer, to the status code.
     # Raises asyncio.TimeoutError if the status is not received
     # after a timeout (default 1 second).
@@ -390,7 +468,7 @@ class HfProtocol:
                 )
                 if result.code == 'OK':
                     if response_type == AtResponseType.SINGLE and len(responses) != 1:
-                        raise ProtocolError("NO ANSWER")
+                        raise HfpProtocolError("NO ANSWER")
 
                     if response_type == AtResponseType.MULTIPLE:
                         return responses
@@ -398,7 +476,7 @@ class HfProtocol:
                         return responses[0]
                     return None
                 if result.code in STATUS_CODES:
-                    raise ProtocolError(result.code)
+                    raise HfpProtocolError(result.code)
                 responses.append(result)
 
     # 4.2.1 Service Level Connection Initialization.
@@ -747,3 +825,175 @@ def sdp_records(
             DataElement.unsigned_integer_16(hf_supported_features),
         ),
     ]
+
+
+# -----------------------------------------------------------------------------
+# ESCO Codec Default Parameters
+# -----------------------------------------------------------------------------
+
+
+# Hands-Free Profile v1.8, 5.7 Codec Interoperability Requirements
+class DefaultCodecParameters(enum.IntEnum):
+    SCO_CVSD_D0 = enum.auto()
+    SCO_CVSD_D1 = enum.auto()
+    ESCO_CVSD_S1 = enum.auto()
+    ESCO_CVSD_S2 = enum.auto()
+    ESCO_CVSD_S3 = enum.auto()
+    ESCO_CVSD_S4 = enum.auto()
+    ESCO_MSBC_T1 = enum.auto()
+    ESCO_MSBC_T2 = enum.auto()
+
+
+@dataclasses.dataclass
+class EscoParameters:
+    # Codec specific
+    transmit_coding_format: CodingFormat
+    receive_coding_format: CodingFormat
+    packet_type: HCI_Enhanced_Setup_Synchronous_Connection_Command.PacketType
+    retransmission_effort: HCI_Enhanced_Setup_Synchronous_Connection_Command.RetransmissionEffort
+    max_latency: int
+
+    # Common
+    input_coding_format: CodingFormat = CodingFormat(CodecID.LINEAR_PCM)
+    output_coding_format: CodingFormat = CodingFormat(CodecID.LINEAR_PCM)
+    input_coded_data_size: int = 16
+    output_coded_data_size: int = 16
+    input_pcm_data_format: HCI_Enhanced_Setup_Synchronous_Connection_Command.PcmDataFormat = (
+        HCI_Enhanced_Setup_Synchronous_Connection_Command.PcmDataFormat.TWOS_COMPLEMENT
+    )
+    output_pcm_data_format: HCI_Enhanced_Setup_Synchronous_Connection_Command.PcmDataFormat = (
+        HCI_Enhanced_Setup_Synchronous_Connection_Command.PcmDataFormat.TWOS_COMPLEMENT
+    )
+    input_pcm_sample_payload_msb_position: int = 0
+    output_pcm_sample_payload_msb_position: int = 0
+    input_data_path: HCI_Enhanced_Setup_Synchronous_Connection_Command.DataPath = (
+        HCI_Enhanced_Setup_Synchronous_Connection_Command.DataPath.HCI
+    )
+    output_data_path: HCI_Enhanced_Setup_Synchronous_Connection_Command.DataPath = (
+        HCI_Enhanced_Setup_Synchronous_Connection_Command.DataPath.HCI
+    )
+    input_transport_unit_size: int = 0
+    output_transport_unit_size: int = 0
+    input_bandwidth: int = 16000
+    output_bandwidth: int = 16000
+    transmit_bandwidth: int = 8000
+    receive_bandwidth: int = 8000
+    transmit_codec_frame_size: int = 60
+    receive_codec_frame_size: int = 60
+
+    def asdict(self) -> Dict[str, Any]:
+        # dataclasses.asdict() will recursively deep-copy the entire object,
+        # which is expensive and breaks CodingFormat object, so let it simply copy here.
+        return self.__dict__
+
+
+_ESCO_PARAMETERS_CVSD_D0 = EscoParameters(
+    transmit_coding_format=CodingFormat(CodecID.CVSD),
+    receive_coding_format=CodingFormat(CodecID.CVSD),
+    max_latency=0xFFFF,
+    packet_type=HCI_Enhanced_Setup_Synchronous_Connection_Command.PacketType.HV1,
+    retransmission_effort=HCI_Enhanced_Setup_Synchronous_Connection_Command.RetransmissionEffort.NO_RETRANSMISSION,
+)
+
+_ESCO_PARAMETERS_CVSD_D1 = EscoParameters(
+    transmit_coding_format=CodingFormat(CodecID.CVSD),
+    receive_coding_format=CodingFormat(CodecID.CVSD),
+    max_latency=0xFFFF,
+    packet_type=HCI_Enhanced_Setup_Synchronous_Connection_Command.PacketType.HV3,
+    retransmission_effort=HCI_Enhanced_Setup_Synchronous_Connection_Command.RetransmissionEffort.NO_RETRANSMISSION,
+)
+
+_ESCO_PARAMETERS_CVSD_S1 = EscoParameters(
+    transmit_coding_format=CodingFormat(CodecID.CVSD),
+    receive_coding_format=CodingFormat(CodecID.CVSD),
+    max_latency=0x0007,
+    packet_type=(
+        HCI_Enhanced_Setup_Synchronous_Connection_Command.PacketType.EV3
+        | HCI_Enhanced_Setup_Synchronous_Connection_Command.PacketType.NO_2_EV3
+        | HCI_Enhanced_Setup_Synchronous_Connection_Command.PacketType.NO_3_EV3
+        | HCI_Enhanced_Setup_Synchronous_Connection_Command.PacketType.NO_2_EV5
+        | HCI_Enhanced_Setup_Synchronous_Connection_Command.PacketType.NO_3_EV5
+    ),
+    retransmission_effort=HCI_Enhanced_Setup_Synchronous_Connection_Command.RetransmissionEffort.OPTIMIZE_FOR_POWER,
+)
+
+_ESCO_PARAMETERS_CVSD_S2 = EscoParameters(
+    transmit_coding_format=CodingFormat(CodecID.CVSD),
+    receive_coding_format=CodingFormat(CodecID.CVSD),
+    max_latency=0x0007,
+    packet_type=(
+        HCI_Enhanced_Setup_Synchronous_Connection_Command.PacketType.EV3
+        | HCI_Enhanced_Setup_Synchronous_Connection_Command.PacketType.NO_3_EV3
+        | HCI_Enhanced_Setup_Synchronous_Connection_Command.PacketType.NO_2_EV5
+        | HCI_Enhanced_Setup_Synchronous_Connection_Command.PacketType.NO_3_EV5
+    ),
+    retransmission_effort=HCI_Enhanced_Setup_Synchronous_Connection_Command.RetransmissionEffort.OPTIMIZE_FOR_POWER,
+)
+
+_ESCO_PARAMETERS_CVSD_S3 = EscoParameters(
+    transmit_coding_format=CodingFormat(CodecID.CVSD),
+    receive_coding_format=CodingFormat(CodecID.CVSD),
+    max_latency=0x000A,
+    packet_type=(
+        HCI_Enhanced_Setup_Synchronous_Connection_Command.PacketType.EV3
+        | HCI_Enhanced_Setup_Synchronous_Connection_Command.PacketType.NO_3_EV3
+        | HCI_Enhanced_Setup_Synchronous_Connection_Command.PacketType.NO_2_EV5
+        | HCI_Enhanced_Setup_Synchronous_Connection_Command.PacketType.NO_3_EV5
+    ),
+    retransmission_effort=HCI_Enhanced_Setup_Synchronous_Connection_Command.RetransmissionEffort.OPTIMIZE_FOR_POWER,
+)
+
+_ESCO_PARAMETERS_CVSD_S4 = EscoParameters(
+    transmit_coding_format=CodingFormat(CodecID.CVSD),
+    receive_coding_format=CodingFormat(CodecID.CVSD),
+    max_latency=0x000C,
+    packet_type=(
+        HCI_Enhanced_Setup_Synchronous_Connection_Command.PacketType.EV3
+        | HCI_Enhanced_Setup_Synchronous_Connection_Command.PacketType.NO_3_EV3
+        | HCI_Enhanced_Setup_Synchronous_Connection_Command.PacketType.NO_2_EV5
+        | HCI_Enhanced_Setup_Synchronous_Connection_Command.PacketType.NO_3_EV5
+    ),
+    retransmission_effort=HCI_Enhanced_Setup_Synchronous_Connection_Command.RetransmissionEffort.OPTIMIZE_FOR_QUALITY,
+)
+
+_ESCO_PARAMETERS_MSBC_T1 = EscoParameters(
+    transmit_coding_format=CodingFormat(CodecID.MSBC),
+    receive_coding_format=CodingFormat(CodecID.MSBC),
+    max_latency=0x0008,
+    packet_type=(
+        HCI_Enhanced_Setup_Synchronous_Connection_Command.PacketType.EV3
+        | HCI_Enhanced_Setup_Synchronous_Connection_Command.PacketType.NO_3_EV3
+        | HCI_Enhanced_Setup_Synchronous_Connection_Command.PacketType.NO_2_EV5
+        | HCI_Enhanced_Setup_Synchronous_Connection_Command.PacketType.NO_3_EV5
+    ),
+    input_bandwidth=32000,
+    output_bandwidth=32000,
+    retransmission_effort=HCI_Enhanced_Setup_Synchronous_Connection_Command.RetransmissionEffort.OPTIMIZE_FOR_QUALITY,
+)
+
+_ESCO_PARAMETERS_MSBC_T2 = EscoParameters(
+    transmit_coding_format=CodingFormat(CodecID.MSBC),
+    receive_coding_format=CodingFormat(CodecID.MSBC),
+    max_latency=0x000D,
+    packet_type=(
+        HCI_Enhanced_Setup_Synchronous_Connection_Command.PacketType.EV3
+        | HCI_Enhanced_Setup_Synchronous_Connection_Command.PacketType.NO_2_EV3
+        | HCI_Enhanced_Setup_Synchronous_Connection_Command.PacketType.NO_3_EV3
+        | HCI_Enhanced_Setup_Synchronous_Connection_Command.PacketType.NO_2_EV5
+        | HCI_Enhanced_Setup_Synchronous_Connection_Command.PacketType.NO_3_EV5
+    ),
+    input_bandwidth=32000,
+    output_bandwidth=32000,
+    retransmission_effort=HCI_Enhanced_Setup_Synchronous_Connection_Command.RetransmissionEffort.OPTIMIZE_FOR_QUALITY,
+)
+
+ESCO_PARAMETERS = {
+    DefaultCodecParameters.SCO_CVSD_D0: _ESCO_PARAMETERS_CVSD_D0,
+    DefaultCodecParameters.SCO_CVSD_D1: _ESCO_PARAMETERS_CVSD_D1,
+    DefaultCodecParameters.ESCO_CVSD_S1: _ESCO_PARAMETERS_CVSD_S1,
+    DefaultCodecParameters.ESCO_CVSD_S2: _ESCO_PARAMETERS_CVSD_S2,
+    DefaultCodecParameters.ESCO_CVSD_S3: _ESCO_PARAMETERS_CVSD_S3,
+    DefaultCodecParameters.ESCO_CVSD_S4: _ESCO_PARAMETERS_CVSD_S4,
+    DefaultCodecParameters.ESCO_MSBC_T1: _ESCO_PARAMETERS_MSBC_T1,
+    DefaultCodecParameters.ESCO_MSBC_T2: _ESCO_PARAMETERS_MSBC_T2,
+}

bumble/hid.py

@@ -0,0 +1,333 @@
+# Copyright 2021-2022 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# -----------------------------------------------------------------------------
+# Imports
+# -----------------------------------------------------------------------------
+from __future__ import annotations
+from dataclasses import dataclass
+import logging
+import enum
+
+from pyee import EventEmitter
+from typing import Optional, TYPE_CHECKING
+
+from bumble import l2cap
+from bumble.colors import color
+from bumble.core import InvalidStateError, ProtocolError
+
+if TYPE_CHECKING:
+    from bumble.device import Device, Connection
+
+
+# -----------------------------------------------------------------------------
+# Logging
+# -----------------------------------------------------------------------------
+logger = logging.getLogger(__name__)
+
+
+# -----------------------------------------------------------------------------
+# Constants
+# -----------------------------------------------------------------------------
+# fmt: on
+HID_CONTROL_PSM = 0x0011
+HID_INTERRUPT_PSM = 0x0013
+
+
+class Message:
+    message_type: MessageType
+    # Report types
+    class ReportType(enum.IntEnum):
+        OTHER_REPORT = 0x00
+        INPUT_REPORT = 0x01
+        OUTPUT_REPORT = 0x02
+        FEATURE_REPORT = 0x03
+
+    # Handshake parameters
+    class Handshake(enum.IntEnum):
+        SUCCESSFUL = 0x00
+        NOT_READY = 0x01
+        ERR_INVALID_REPORT_ID = 0x02
+        ERR_UNSUPPORTED_REQUEST = 0x03
+        ERR_UNKNOWN = 0x0E
+        ERR_FATAL = 0x0F
+
+    # Message Type
+    class MessageType(enum.IntEnum):
+        HANDSHAKE = 0x00
+        CONTROL = 0x01
+        GET_REPORT = 0x04
+        SET_REPORT = 0x05
+        GET_PROTOCOL = 0x06
+        SET_PROTOCOL = 0x07
+        DATA = 0x0A
+
+    # Protocol modes
+    class ProtocolMode(enum.IntEnum):
+        BOOT_PROTOCOL = 0x00
+        REPORT_PROTOCOL = 0x01
+
+    # Control Operations
+    class ControlCommand(enum.IntEnum):
+        SUSPEND = 0x03
+        EXIT_SUSPEND = 0x04
+        VIRTUAL_CABLE_UNPLUG = 0x05
+
+    # Class Method to derive header
+    @classmethod
+    def header(cls, lower_bits: int = 0x00) -> bytes:
+        return bytes([(cls.message_type << 4) | lower_bits])
+
+
+# HIDP messages
+@dataclass
+class GetReportMessage(Message):
+    report_type: int
+    report_id: int
+    buffer_size: int
+    message_type = Message.MessageType.GET_REPORT
+
+    def __bytes__(self) -> bytes:
+        packet_bytes = bytearray()
+        packet_bytes.append(self.report_id)
+        packet_bytes.extend(
+            [(self.buffer_size & 0xFF), ((self.buffer_size >> 8) & 0xFF)]
+        )
+        if self.report_type == Message.ReportType.OTHER_REPORT:
+            return self.header(self.report_type) + packet_bytes
+        else:
+            return self.header(0x08 | self.report_type) + packet_bytes
+
+
+@dataclass
+class SetReportMessage(Message):
+    report_type: int
+    data: bytes
+    message_type = Message.MessageType.SET_REPORT
+
+    def __bytes__(self) -> bytes:
+        return self.header(self.report_type) + self.data
+
+
+@dataclass
+class GetProtocolMessage(Message):
+    message_type = Message.MessageType.GET_PROTOCOL
+
+    def __bytes__(self) -> bytes:
+        return self.header()
+
+
+@dataclass
+class SetProtocolMessage(Message):
+    protocol_mode: int
+    message_type = Message.MessageType.SET_PROTOCOL
+
+    def __bytes__(self) -> bytes:
+        return self.header(self.protocol_mode)
+
+
+@dataclass
+class Suspend(Message):
+    message_type = Message.MessageType.CONTROL
+
+    def __bytes__(self) -> bytes:
+        return self.header(Message.ControlCommand.SUSPEND)
+
+
+@dataclass
+class ExitSuspend(Message):
+    message_type = Message.MessageType.CONTROL
+
+    def __bytes__(self) -> bytes:
+        return self.header(Message.ControlCommand.EXIT_SUSPEND)
+
+
+@dataclass
+class VirtualCableUnplug(Message):
+    message_type = Message.MessageType.CONTROL
+
+    def __bytes__(self) -> bytes:
+        return self.header(Message.ControlCommand.VIRTUAL_CABLE_UNPLUG)
+
+
+@dataclass
+class SendData(Message):
+    data: bytes
+    message_type = Message.MessageType.DATA
+
+    def __bytes__(self) -> bytes:
+        return self.header(Message.ReportType.OUTPUT_REPORT) + self.data
+
+
+# -----------------------------------------------------------------------------
+class Host(EventEmitter):
+    l2cap_ctrl_channel: Optional[l2cap.ClassicChannel]
+    l2cap_intr_channel: Optional[l2cap.ClassicChannel]
+
+    def __init__(self, device: Device, connection: Connection) -> None:
+        super().__init__()
+        self.device = device
+        self.connection = connection
+
+        self.l2cap_ctrl_channel = None
+        self.l2cap_intr_channel = None
+
+        # Register ourselves with the L2CAP channel manager
+        device.register_l2cap_server(HID_CONTROL_PSM, self.on_connection)
+        device.register_l2cap_server(HID_INTERRUPT_PSM, self.on_connection)
+
+    async def connect_control_channel(self) -> None:
+        # Create a new L2CAP connection - control channel
+        try:
+            self.l2cap_ctrl_channel = await self.device.l2cap_channel_manager.connect(
+                self.connection, HID_CONTROL_PSM
+            )
+        except ProtocolError:
+            logging.exception(f'L2CAP connection failed.')
+            raise
+
+        assert self.l2cap_ctrl_channel is not None
+        # Become a sink for the L2CAP channel
+        self.l2cap_ctrl_channel.sink = self.on_ctrl_pdu
+
+    async def connect_interrupt_channel(self) -> None:
+        # Create a new L2CAP connection - interrupt channel
+        try:
+            self.l2cap_intr_channel = await self.device.l2cap_channel_manager.connect(
+                self.connection, HID_INTERRUPT_PSM
+            )
+        except ProtocolError:
+            logging.exception(f'L2CAP connection failed.')
+            raise
+
+        assert self.l2cap_intr_channel is not None
+        # Become a sink for the L2CAP channel
+        self.l2cap_intr_channel.sink = self.on_intr_pdu
+
+    async def disconnect_interrupt_channel(self) -> None:
+        if self.l2cap_intr_channel is None:
+            raise InvalidStateError('invalid state')
+        channel = self.l2cap_intr_channel
+        self.l2cap_intr_channel = None
+        await channel.disconnect()
+
+    async def disconnect_control_channel(self) -> None:
+        if self.l2cap_ctrl_channel is None:
+            raise InvalidStateError('invalid state')
+        channel = self.l2cap_ctrl_channel
+        self.l2cap_ctrl_channel = None
+        await channel.disconnect()
+
+    def on_connection(self, l2cap_channel: l2cap.ClassicChannel) -> None:
+        logger.debug(f'+++ New L2CAP connection: {l2cap_channel}')
+        l2cap_channel.on('open', lambda: self.on_l2cap_channel_open(l2cap_channel))
+
+    def on_l2cap_channel_open(self, l2cap_channel: l2cap.ClassicChannel) -> None:
+        if l2cap_channel.psm == HID_CONTROL_PSM:
+            self.l2cap_ctrl_channel = l2cap_channel
+            self.l2cap_ctrl_channel.sink = self.on_ctrl_pdu
+        else:
+            self.l2cap_intr_channel = l2cap_channel
+            self.l2cap_intr_channel.sink = self.on_intr_pdu
+        logger.debug(f'$$$ L2CAP channel open: {l2cap_channel}')
+
+    def on_ctrl_pdu(self, pdu: bytes) -> None:
+        logger.debug(f'<<< HID CONTROL PDU: {pdu.hex()}')
+        # Here we will receive all kinds of packets, parse and then call respective callbacks
+        message_type = pdu[0] >> 4
+        param = pdu[0] & 0x0F
+
+        if message_type == Message.MessageType.HANDSHAKE:
+            logger.debug(f'<<< HID HANDSHAKE: {Message.Handshake(param).name}')
+            self.emit('handshake', Message.Handshake(param))
+        elif message_type == Message.MessageType.DATA:
+            logger.debug('<<< HID CONTROL DATA')
+            self.emit('data', pdu)
+        elif message_type == Message.MessageType.CONTROL:
+            if param == Message.ControlCommand.SUSPEND:
+                logger.debug('<<< HID SUSPEND')
+                self.emit('suspend', pdu)
+            elif param == Message.ControlCommand.EXIT_SUSPEND:
+                logger.debug('<<< HID EXIT SUSPEND')
+                self.emit('exit_suspend', pdu)
+            elif param == Message.ControlCommand.VIRTUAL_CABLE_UNPLUG:
+                logger.debug('<<< HID VIRTUAL CABLE UNPLUG')
+                self.emit('virtual_cable_unplug')
+            else:
+                logger.debug('<<< HID CONTROL OPERATION UNSUPPORTED')
+        else:
+            logger.debug('<<< HID CONTROL DATA')
+            self.emit('data', pdu)
+
+    def on_intr_pdu(self, pdu: bytes) -> None:
+        logger.debug(f'<<< HID INTERRUPT PDU: {pdu.hex()}')
+        self.emit("data", pdu)
+
+    def get_report(self, report_type: int, report_id: int, buffer_size: int) -> None:
+        msg = GetReportMessage(
+            report_type=report_type, report_id=report_id, buffer_size=buffer_size
+        )
+        hid_message = bytes(msg)
+        logger.debug(f'>>> HID CONTROL GET REPORT, PDU: {hid_message.hex()}')
+        self.send_pdu_on_ctrl(hid_message)
+
+    def set_report(self, report_type: int, data: bytes):
+        msg = SetReportMessage(report_type=report_type, data=data)
+        hid_message = bytes(msg)
+        logger.debug(f'>>> HID CONTROL SET REPORT, PDU:{hid_message.hex()}')
+        self.send_pdu_on_ctrl(hid_message)
+
+    def get_protocol(self):
+        msg = GetProtocolMessage()
+        hid_message = bytes(msg)
+        logger.debug(f'>>> HID CONTROL GET PROTOCOL, PDU: {hid_message.hex()}')
+        self.send_pdu_on_ctrl(hid_message)
+
+    def set_protocol(self, protocol_mode: int):
+        msg = SetProtocolMessage(protocol_mode=protocol_mode)
+        hid_message = bytes(msg)
+        logger.debug(f'>>> HID CONTROL SET PROTOCOL, PDU: {hid_message.hex()}')
+        self.send_pdu_on_ctrl(hid_message)
+
+    def send_pdu_on_ctrl(self, msg: bytes) -> None:
+        assert self.l2cap_ctrl_channel
+        self.l2cap_ctrl_channel.send_pdu(msg)
+
+    def send_pdu_on_intr(self, msg: bytes) -> None:
+        assert self.l2cap_intr_channel
+        self.l2cap_intr_channel.send_pdu(msg)
+
+    def send_data(self, data):
+        msg = SendData(data)
+        hid_message = bytes(msg)
+        logger.debug(f'>>> HID INTERRUPT SEND DATA, PDU: {hid_message.hex()}')
+        self.send_pdu_on_intr(hid_message)
+
+    def suspend(self):
+        msg = Suspend()
+        hid_message = bytes(msg)
+        logger.debug(f'>>> HID CONTROL SUSPEND, PDU:{hid_message.hex()}')
+        self.send_pdu_on_ctrl(msg)
+
+    def exit_suspend(self):
+        msg = ExitSuspend()
+        hid_message = bytes(msg)
+        logger.debug(f'>>> HID CONTROL EXIT SUSPEND, PDU:{hid_message.hex()}')
+        self.send_pdu_on_ctrl(msg)
+
+    def virtual_cable_unplug(self):
+        msg = VirtualCableUnplug()
+        hid_message = bytes(msg)
+        logger.debug(f'>>> HID CONTROL VIRTUAL CABLE UNPLUG, PDU: {hid_message.hex()}')
+        self.send_pdu_on_ctrl(msg)

bumble/host.py

@@ -21,7 +21,7 @@ import collections
 import logging
 import struct
 
-from typing import Optional
+from typing import Optional, TYPE_CHECKING, Dict, Callable, Awaitable, cast
 
 from bumble.colors import color
 from bumble.l2cap import L2CAP_PDU
@@ -32,8 +32,8 @@ from .hci import (
     Address,
     HCI_ACL_DATA_PACKET,
     HCI_COMMAND_PACKET,
-    HCI_COMMAND_COMPLETE_EVENT,
     HCI_EVENT_PACKET,
+    HCI_ISO_DATA_PACKET,
     HCI_LE_READ_BUFFER_SIZE_COMMAND,
     HCI_LE_READ_LOCAL_SUPPORTED_FEATURES_COMMAND,
     HCI_LE_READ_SUGGESTED_DEFAULT_DATA_LENGTH_COMMAND,
@@ -43,6 +43,7 @@ from .hci import (
     HCI_RESET_COMMAND,
     HCI_SUCCESS,
     HCI_SUPPORTED_COMMANDS_FLAGS,
+    HCI_SYNCHRONOUS_DATA_PACKET,
     HCI_VERSION_BLUETOOTH_CORE_4_0,
     HCI_AclDataPacket,
     HCI_AclDataPacketAssembler,
@@ -51,6 +52,7 @@ from .hci import (
     HCI_Constant,
     HCI_Error,
     HCI_Event,
+    HCI_IsoDataPacket,
     HCI_LE_Long_Term_Key_Request_Negative_Reply_Command,
     HCI_LE_Long_Term_Key_Request_Reply_Command,
     HCI_LE_Read_Buffer_Size_Command,
@@ -67,6 +69,7 @@ from .hci import (
     HCI_Read_Local_Version_Information_Command,
     HCI_Reset_Command,
     HCI_Set_Event_Mask_Command,
+    HCI_SynchronousDataPacket,
 )
 from .core import (
     BT_BR_EDR_TRANSPORT,
@@ -77,6 +80,9 @@ from .core import (
 from .utils import AbortableEventEmitter
 from .transport.common import TransportLostError
 
+if TYPE_CHECKING:
+    from .transport.common import TransportSink, TransportSource
+
 
 # -----------------------------------------------------------------------------
 # Logging
@@ -116,10 +122,21 @@ class Connection:
 
 # -----------------------------------------------------------------------------
 class Host(AbortableEventEmitter):
-    def __init__(self, controller_source=None, controller_sink=None):
+    connections: Dict[int, Connection]
+    acl_packet_queue: collections.deque[HCI_AclDataPacket]
+    hci_sink: TransportSink
+    long_term_key_provider: Optional[
+        Callable[[int, bytes, int], Awaitable[Optional[bytes]]]
+    ]
+    link_key_provider: Optional[Callable[[Address], Awaitable[Optional[bytes]]]]
+
+    def __init__(
+        self,
+        controller_source: Optional[TransportSource] = None,
+        controller_sink: Optional[TransportSink] = None,
+    ) -> None:
         super().__init__()
 
-        self.hci_sink = None
         self.hci_metadata = None
         self.ready = False  # True when we can accept incoming packets
         self.reset_done = False
@@ -226,7 +243,7 @@ class Host(AbortableEventEmitter):
             # understand
             le_event_mask = bytes.fromhex('1F00000000000000')
         else:
-            le_event_mask = bytes.fromhex('FFFFF00000000000')
+            le_event_mask = bytes.fromhex('FFFFFFFF00000000')
 
         await self.send_command(
             HCI_LE_Set_Event_Mask_Command(le_event_mask=le_event_mask)
@@ -299,7 +316,7 @@ class Host(AbortableEventEmitter):
         self.reset_done = True
 
     @property
-    def controller(self):
+    def controller(self) -> TransportSink:
         return self.hci_sink
 
     @controller.setter
@@ -308,13 +325,12 @@ class Host(AbortableEventEmitter):
         if controller:
             controller.set_packet_sink(self)
 
-    def set_packet_sink(self, sink):
+    def set_packet_sink(self, sink: TransportSink) -> None:
         self.hci_sink = sink
 
     def send_hci_packet(self, packet: HCI_Packet) -> None:
         if self.snooper:
             self.snooper.snoop(bytes(packet), Snooper.Direction.HOST_TO_CONTROLLER)
-
         self.hci_sink.on_packet(bytes(packet))
 
     async def send_command(self, command, check_result=False):
@@ -471,12 +487,16 @@ class Host(AbortableEventEmitter):
             self.snooper.snoop(bytes(packet), Snooper.Direction.CONTROLLER_TO_HOST)
 
         # If the packet is a command, invoke the handler for this packet
-        if isinstance(packet, HCI_Command):
-            self.on_hci_command_packet(packet)
-        elif isinstance(packet, HCI_Event):
-            self.on_hci_event_packet(packet)
-        elif isinstance(packet, HCI_AclDataPacket):
-            self.on_hci_acl_data_packet(packet)
+        if packet.hci_packet_type == HCI_COMMAND_PACKET:
+            self.on_hci_command_packet(cast(HCI_Command, packet))
+        elif packet.hci_packet_type == HCI_EVENT_PACKET:
+            self.on_hci_event_packet(cast(HCI_Event, packet))
+        elif packet.hci_packet_type == HCI_ACL_DATA_PACKET:
+            self.on_hci_acl_data_packet(cast(HCI_AclDataPacket, packet))
+        elif packet.hci_packet_type == HCI_SYNCHRONOUS_DATA_PACKET:
+            self.on_hci_sco_data_packet(cast(HCI_SynchronousDataPacket, packet))
+        elif packet.hci_packet_type == HCI_ISO_DATA_PACKET:
+            self.on_hci_iso_data_packet(cast(HCI_IsoDataPacket, packet))
         else:
             logger.warning(f'!!! unknown packet type {packet.hci_packet_type}')
 
@@ -493,6 +513,14 @@ class Host(AbortableEventEmitter):
         if connection := self.connections.get(packet.connection_handle):
             connection.on_hci_acl_data_packet(packet)
 
+    def on_hci_sco_data_packet(self, packet: HCI_SynchronousDataPacket) -> None:
+        # Experimental
+        self.emit('sco_packet', packet.connection_handle, packet)
+
+    def on_hci_iso_data_packet(self, packet: HCI_IsoDataPacket) -> None:
+        # Experimental
+        self.emit('iso_packet', packet.connection_handle, packet)
+
     def on_l2cap_pdu(self, connection: Connection, cid: int, pdu: bytes) -> None:
         self.emit('l2cap_pdu', connection.handle, cid, pdu)
 
@@ -693,6 +721,24 @@ class Host(AbortableEventEmitter):
     def on_hci_le_extended_advertising_report_event(self, event):
         self.on_hci_le_advertising_report_event(event)
 
+    def on_hci_le_cis_request_event(self, event):
+        self.emit(
+            'cis_request',
+            event.acl_connection_handle,
+            event.cis_connection_handle,
+            event.cig_id,
+            event.cis_id,
+        )
+
+    def on_hci_le_cis_established_event(self, event):
+        # The remaining parameters are unused for now.
+        if event.status == HCI_SUCCESS:
+            self.emit('cis_establishment', event.connection_handle)
+        else:
+            self.emit(
+                'cis_establishment_failure', event.connection_handle, event.status
+            )
+
     def on_hci_le_remote_connection_parameter_request_event(self, event):
         if event.connection_handle not in self.connections:
             logger.warning('!!! REMOTE CONNECTION PARAMETER REQUEST: unknown handle')
@@ -746,7 +792,25 @@ class Host(AbortableEventEmitter):
         asyncio.create_task(send_long_term_key())
 
     def on_hci_synchronous_connection_complete_event(self, event):
-        pass
+        if event.status == HCI_SUCCESS:
+            # Create/update the connection
+            logger.debug(
+                f'### SCO CONNECTION: [0x{event.connection_handle:04X}] '
+                f'{event.bd_addr}'
+            )
+
+            # Notify the client
+            self.emit(
+                'sco_connection',
+                event.bd_addr,
+                event.connection_handle,
+                event.link_type,
+            )
+        else:
+            logger.debug(f'### SCO CONNECTION FAILED: {event.status}')
+
+            # Notify the client
+            self.emit('sco_connection_failure', event.bd_addr, event.status)
 
     def on_hci_synchronous_connection_changed_event(self, event):
         pass

bumble/pairing.py

@@ -15,7 +15,9 @@
 # -----------------------------------------------------------------------------
 # Imports
 # -----------------------------------------------------------------------------
+from __future__ import annotations
 import enum
+from dataclasses import dataclass
 from typing import Optional, Tuple
 
 from .hci import (
@@ -35,7 +37,60 @@ from .smp import (
     SMP_ID_KEY_DISTRIBUTION_FLAG,
     SMP_SIGN_KEY_DISTRIBUTION_FLAG,
     SMP_LINK_KEY_DISTRIBUTION_FLAG,
+    OobContext,
+    OobLegacyContext,
+    OobSharedData,
 )
+from .core import AdvertisingData, LeRole
+
+
+# -----------------------------------------------------------------------------
+@dataclass
+class OobData:
+    """OOB data that can be sent from one device to another."""
+
+    address: Optional[Address] = None
+    role: Optional[LeRole] = None
+    shared_data: Optional[OobSharedData] = None
+    legacy_context: Optional[OobLegacyContext] = None
+
+    @classmethod
+    def from_ad(cls, ad: AdvertisingData) -> OobData:
+        instance = cls()
+        shared_data_c: Optional[bytes] = None
+        shared_data_r: Optional[bytes] = None
+        for ad_type, ad_data in ad.ad_structures:
+            if ad_type == AdvertisingData.LE_BLUETOOTH_DEVICE_ADDRESS:
+                instance.address = Address(ad_data)
+            elif ad_type == AdvertisingData.LE_ROLE:
+                instance.role = LeRole(ad_data[0])
+            elif ad_type == AdvertisingData.LE_SECURE_CONNECTIONS_CONFIRMATION_VALUE:
+                shared_data_c = ad_data
+            elif ad_type == AdvertisingData.LE_SECURE_CONNECTIONS_RANDOM_VALUE:
+                shared_data_r = ad_data
+            elif ad_type == AdvertisingData.SECURITY_MANAGER_TK_VALUE:
+                instance.legacy_context = OobLegacyContext(tk=ad_data)
+        if shared_data_c and shared_data_r:
+            instance.shared_data = OobSharedData(c=shared_data_c, r=shared_data_r)
+
+        return instance
+
+    def to_ad(self) -> AdvertisingData:
+        ad_structures = []
+        if self.address is not None:
+            ad_structures.append(
+                (AdvertisingData.LE_BLUETOOTH_DEVICE_ADDRESS, bytes(self.address))
+            )
+        if self.role is not None:
+            ad_structures.append((AdvertisingData.LE_ROLE, bytes([self.role])))
+        if self.shared_data is not None:
+            ad_structures.extend(self.shared_data.to_ad().ad_structures)
+        if self.legacy_context is not None:
+            ad_structures.append(
+                (AdvertisingData.SECURITY_MANAGER_TK_VALUE, self.legacy_context.tk)
+            )
+
+        return AdvertisingData(ad_structures)
 
 
 # -----------------------------------------------------------------------------
@@ -173,6 +228,14 @@ class PairingConfig:
         PUBLIC = Address.PUBLIC_DEVICE_ADDRESS
         RANDOM = Address.RANDOM_DEVICE_ADDRESS
 
+    @dataclass
+    class OobConfig:
+        """Config for OOB pairing."""
+
+        our_context: Optional[OobContext]
+        peer_data: Optional[OobSharedData]
+        legacy_context: Optional[OobLegacyContext]
+
     def __init__(
         self,
         sc: bool = True,
@@ -180,17 +243,20 @@ class PairingConfig:
         bonding: bool = True,
         delegate: Optional[PairingDelegate] = None,
         identity_address_type: Optional[AddressType] = None,
+        oob: Optional[OobConfig] = None,
     ) -> None:
         self.sc = sc
         self.mitm = mitm
         self.bonding = bonding
         self.delegate = delegate or PairingDelegate()
         self.identity_address_type = identity_address_type
+        self.oob = oob
 
     def __str__(self) -> str:
         return (
             f'PairingConfig(sc={self.sc}, '
             f'mitm={self.mitm}, bonding={self.bonding}, '
             f'identity_address_type={self.identity_address_type}, '
-            f'delegate[{self.delegate.io_capability}])'
+            f'delegate[{self.delegate.io_capability}]), '
+            f'oob[{self.oob}])'
         )

bumble/pandora/config.py

@@ -12,6 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+from __future__ import annotations
 from bumble.pairing import PairingConfig, PairingDelegate
 from dataclasses import dataclass
 from typing import Any, Dict

bumble/pandora/device.py

@@ -14,6 +14,7 @@
 
 """Generic & dependency free Bumble (reference) device."""
 
+from __future__ import annotations
 from bumble import transport
 from bumble.core import (
     BT_GENERIC_AUDIO_SERVICE,

bumble/pandora/host.py

@@ -12,6 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+from __future__ import annotations
 import asyncio
 import bumble.device
 import grpc

bumble/pandora/security.py

@@ -12,7 +12,9 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+from __future__ import annotations
 import asyncio
+import contextlib
 import grpc
 import logging
 
@@ -27,8 +29,8 @@ from bumble.core import (
 )
 from bumble.device import Connection as BumbleConnection, Device
 from bumble.hci import HCI_Error
+from bumble.utils import EventWatcher
 from bumble.pairing import PairingConfig, PairingDelegate as BasePairingDelegate
-from contextlib import suppress
 from google.protobuf import any_pb2  # pytype: disable=pyi-error
 from google.protobuf import empty_pb2  # pytype: disable=pyi-error
 from google.protobuf import wrappers_pb2  # pytype: disable=pyi-error
@@ -232,7 +234,11 @@ class SecurityService(SecurityServicer):
                 sc=config.pairing_sc_enable,
                 mitm=config.pairing_mitm_enable,
                 bonding=config.pairing_bonding_enable,
-                identity_address_type=config.identity_address_type,
+                identity_address_type=(
+                    PairingConfig.AddressType.PUBLIC
+                    if connection.self_address.is_public
+                    else config.identity_address_type
+                ),
                 delegate=PairingDelegate(
                     connection,
                     self,
@@ -294,23 +300,35 @@ class SecurityService(SecurityServicer):
             try:
                 self.log.debug('Pair...')
 
-                if (
-                    connection.transport == BT_LE_TRANSPORT
-                    and connection.role == BT_PERIPHERAL_ROLE
-                ):
-                    wait_for_security: asyncio.Future[
-                        bool
-                    ] = asyncio.get_running_loop().create_future()
-                    connection.on("pairing", lambda *_: wait_for_security.set_result(True))  # type: ignore
-                    connection.on("pairing_failure", wait_for_security.set_exception)
+                security_result = asyncio.get_running_loop().create_future()
 
-                    connection.request_pairing()
+                with contextlib.closing(EventWatcher()) as watcher:
 
-                    await wait_for_security
-                else:
-                    await connection.pair()
+                    @watcher.on(connection, 'pairing')
+                    def on_pairing(*_: Any) -> None:
+                        security_result.set_result('success')
 
-                self.log.debug('Paired')
+                    @watcher.on(connection, 'pairing_failure')
+                    def on_pairing_failure(*_: Any) -> None:
+                        security_result.set_result('pairing_failure')
+
+                    @watcher.on(connection, 'disconnection')
+                    def on_disconnection(*_: Any) -> None:
+                        security_result.set_result('connection_died')
+
+                    if (
+                        connection.transport == BT_LE_TRANSPORT
+                        and connection.role == BT_PERIPHERAL_ROLE
+                    ):
+                        connection.request_pairing()
+                    else:
+                        await connection.pair()
+
+                    result = await security_result
+
+                self.log.debug(f'Pairing session complete, status={result}')
+                if result != 'success':
+                    return SecureResponse(**{result: empty_pb2.Empty()})
             except asyncio.CancelledError:
                 self.log.warning("Connection died during encryption")
                 return SecureResponse(connection_died=empty_pb2.Empty())
@@ -369,6 +387,7 @@ class SecurityService(SecurityServicer):
             str
         ] = asyncio.get_running_loop().create_future()
         authenticate_task: Optional[asyncio.Future[None]] = None
+        pair_task: Optional[asyncio.Future[None]] = None
 
         async def authenticate() -> None:
             assert connection
@@ -415,6 +434,10 @@ class SecurityService(SecurityServicer):
                 if authenticate_task is None:
                     authenticate_task = asyncio.create_task(authenticate())
 
+        def pair(*_: Any) -> None:
+            if self.need_pairing(connection, level):
+                pair_task = asyncio.create_task(connection.pair())
+
         listeners: Dict[str, Callable[..., None]] = {
             'disconnection': set_failure('connection_died'),
             'pairing_failure': set_failure('pairing_failure'),
@@ -425,23 +448,21 @@ class SecurityService(SecurityServicer):
             'connection_encryption_change': on_encryption_change,
             'classic_pairing': try_set_success,
             'classic_pairing_failure': set_failure('pairing_failure'),
+            'security_request': pair,
         }
 
-        # register event handlers
-        for event, listener in listeners.items():
-            connection.on(event, listener)
+        with contextlib.closing(EventWatcher()) as watcher:
+            # register event handlers
+            for event, listener in listeners.items():
+                watcher.on(connection, event, listener)
 
-        # security level already reached
-        if self.reached_security_level(connection, level):
-            return WaitSecurityResponse(success=empty_pb2.Empty())
+            # security level already reached
+            if self.reached_security_level(connection, level):
+                return WaitSecurityResponse(success=empty_pb2.Empty())
 
-        self.log.debug('Wait for security...')
-        kwargs = {}
-        kwargs[await wait_for_security] = empty_pb2.Empty()
-
-        # remove event handlers
-        for event, listener in listeners.items():
-            connection.remove_listener(event, listener)  # type: ignore
+            self.log.debug('Wait for security...')
+            kwargs = {}
+            kwargs[await wait_for_security] = empty_pb2.Empty()
 
         # wait for `authenticate` to finish if any
         if authenticate_task is not None:
@@ -452,6 +473,15 @@ class SecurityService(SecurityServicer):
                 pass
             self.log.debug('Authenticated')
 
+        # wait for `pair` to finish if any
+        if pair_task is not None:
+            self.log.debug('Wait for authentication...')
+            try:
+                await pair_task  # type: ignore
+            except:
+                pass
+            self.log.debug('paired')
+
         return WaitSecurityResponse(**kwargs)
 
     def reached_security_level(
@@ -523,7 +553,7 @@ class SecurityStorageService(SecurityStorageServicer):
         self.log.debug(f"DeleteBond: {address}")
 
         if self.device.keystore is not None:
-            with suppress(KeyError):
+            with contextlib.suppress(KeyError):
                 await self.device.keystore.delete(str(address))
 
         return empty_pb2.Empty()

bumble/pandora/utils.py

@@ -12,6 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+from __future__ import annotations
 import contextlib
 import functools
 import grpc

bumble/profiles/asha_service.py

@@ -19,6 +19,8 @@
 import struct
 import logging
 from typing import List
+
+from bumble import l2cap
 from ..core import AdvertisingData
 from ..device import Device, Connection
 from ..gatt import (
@@ -149,7 +151,10 @@ class AshaService(TemplateService):
             channel.sink = on_data
 
         # let the server find a free PSM
-        self.psm = self.device.register_l2cap_channel_server(self.psm, on_coc, 8)
+        self.psm = device.create_l2cap_server(
+            spec=l2cap.LeCreditBasedChannelSpec(psm=self.psm, max_credits=8),
+            handler=on_coc,
+        ).psm
         self.le_psm_out_characteristic = Characteristic(
             GATT_ASHA_LE_PSM_OUT_CHARACTERISTIC,
             Characteristic.Properties.READ,

bumble/profiles/bap.py

@@ -0,0 +1,496 @@
+# Copyright 2021-2023 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+# -----------------------------------------------------------------------------
+# Imports
+# -----------------------------------------------------------------------------
+from __future__ import annotations
+
+from collections.abc import Sequence
+import dataclasses
+import enum
+import struct
+import functools
+from typing import Optional, List, Union
+
+from bumble import hci
+from bumble import gatt
+from bumble import gatt_client
+
+
+# -----------------------------------------------------------------------------
+# Constants
+# -----------------------------------------------------------------------------
+
+
+class AudioLocation(enum.IntFlag):
+    '''Bluetooth Assigned Numbers, Section 6.12.1 - Audio Location'''
+
+    # fmt: off
+    NOT_ALLOWED             = 0x00000000
+    FRONT_LEFT              = 0x00000001
+    FRONT_RIGHT             = 0x00000002
+    FRONT_CENTER            = 0x00000004
+    LOW_FREQUENCY_EFFECTS_1 = 0x00000008
+    BACK_LEFT               = 0x00000010
+    BACK_RIGHT              = 0x00000020
+    FRONT_LEFT_OF_CENTER    = 0x00000040
+    FRONT_RIGHT_OF_CENTER   = 0x00000080
+    BACK_CENTER             = 0x00000100
+    LOW_FREQUENCY_EFFECTS_2 = 0x00000200
+    SIDE_LEFT               = 0x00000400
+    SIDE_RIGHT              = 0x00000800
+    TOP_FRONT_LEFT          = 0x00001000
+    TOP_FRONT_RIGHT         = 0x00002000
+    TOP_FRONT_CENTER        = 0x00004000
+    TOP_CENTER              = 0x00008000
+    TOP_BACK_LEFT           = 0x00010000
+    TOP_BACK_RIGHT          = 0x00020000
+    TOP_SIDE_LEFT           = 0x00040000
+    TOP_SIDE_RIGHT          = 0x00080000
+    TOP_BACK_CENTER         = 0x00100000
+    BOTTOM_FRONT_CENTER     = 0x00200000
+    BOTTOM_FRONT_LEFT       = 0x00400000
+    BOTTOM_FRONT_RIGHT      = 0x00800000
+    FRONT_LEFT_WIDE         = 0x01000000
+    FRONT_RIGHT_WIDE        = 0x02000000
+    LEFT_SURROUND           = 0x04000000
+    RIGHT_SURROUND          = 0x08000000
+
+
+class AudioInputType(enum.IntEnum):
+    '''Bluetooth Assigned Numbers, Section 6.12.2 - Audio Input Type'''
+
+    # fmt: off
+    UNSPECIFIED = 0x00
+    BLUETOOTH   = 0x01
+    MICROPHONE  = 0x02
+    ANALOG      = 0x03
+    DIGITAL     = 0x04
+    RADIO       = 0x05
+    STREAMING   = 0x06
+    AMBIENT     = 0x07
+
+
+class ContextType(enum.IntFlag):
+    '''Bluetooth Assigned Numbers, Section 6.12.3 - Context Type'''
+
+    # fmt: off
+    PROHIBITED       = 0x0000
+    CONVERSATIONAL   = 0x0002
+    MEDIA            = 0x0004
+    GAME             = 0x0008
+    INSTRUCTIONAL    = 0x0010
+    VOICE_ASSISTANTS = 0x0020
+    LIVE             = 0x0040
+    SOUND_EFFECTS    = 0x0080
+    NOTIFICATIONS    = 0x0100
+    RINGTONE         = 0x0200
+    ALERTS           = 0x0400
+    EMERGENCY_ALARM  = 0x0800
+
+
+class SamplingFrequency(enum.IntEnum):
+    '''Bluetooth Assigned Numbers, Section 6.12.5.1 - Sampling Frequency'''
+
+    # fmt: off
+    FREQ_8000    = 0x01 
+    FREQ_11025   = 0x02
+    FREQ_16000   = 0x03
+    FREQ_22050   = 0x04
+    FREQ_24000   = 0x05
+    FREQ_32000   = 0x06
+    FREQ_44100   = 0x07
+    FREQ_48000   = 0x08
+    FREQ_88200   = 0x09
+    FREQ_96000   = 0x0A
+    FREQ_176400  = 0x0B
+    FREQ_192000  = 0x0C
+    FREQ_384000  = 0x0D
+    # fmt: on
+
+    @classmethod
+    def from_hz(cls, frequency: int) -> SamplingFrequency:
+        return {
+            8000: SamplingFrequency.FREQ_8000,
+            11025: SamplingFrequency.FREQ_11025,
+            16000: SamplingFrequency.FREQ_16000,
+            22050: SamplingFrequency.FREQ_22050,
+            24000: SamplingFrequency.FREQ_24000,
+            32000: SamplingFrequency.FREQ_32000,
+            44100: SamplingFrequency.FREQ_44100,
+            48000: SamplingFrequency.FREQ_48000,
+            88200: SamplingFrequency.FREQ_88200,
+            96000: SamplingFrequency.FREQ_96000,
+            176400: SamplingFrequency.FREQ_176400,
+            192000: SamplingFrequency.FREQ_192000,
+            384000: SamplingFrequency.FREQ_384000,
+        }[frequency]
+
+    @property
+    def hz(self) -> int:
+        return {
+            SamplingFrequency.FREQ_8000: 8000,
+            SamplingFrequency.FREQ_11025: 11025,
+            SamplingFrequency.FREQ_16000: 16000,
+            SamplingFrequency.FREQ_22050: 22050,
+            SamplingFrequency.FREQ_24000: 24000,
+            SamplingFrequency.FREQ_32000: 32000,
+            SamplingFrequency.FREQ_44100: 44100,
+            SamplingFrequency.FREQ_48000: 48000,
+            SamplingFrequency.FREQ_88200: 88200,
+            SamplingFrequency.FREQ_96000: 96000,
+            SamplingFrequency.FREQ_176400: 176400,
+            SamplingFrequency.FREQ_192000: 192000,
+            SamplingFrequency.FREQ_384000: 384000,
+        }[self]
+
+
+class SupportedSamplingFrequency(enum.IntFlag):
+    '''Bluetooth Assigned Numbers, Section 6.12.4.1 - Sample Frequency'''
+
+    # fmt: off
+    FREQ_8000    = 1 << (SamplingFrequency.FREQ_8000 - 1)
+    FREQ_11025   = 1 << (SamplingFrequency.FREQ_11025 - 1)
+    FREQ_16000   = 1 << (SamplingFrequency.FREQ_16000 - 1)
+    FREQ_22050   = 1 << (SamplingFrequency.FREQ_22050 - 1)
+    FREQ_24000   = 1 << (SamplingFrequency.FREQ_24000 - 1)
+    FREQ_32000   = 1 << (SamplingFrequency.FREQ_32000 - 1)
+    FREQ_44100   = 1 << (SamplingFrequency.FREQ_44100 - 1)
+    FREQ_48000   = 1 << (SamplingFrequency.FREQ_48000 - 1)
+    FREQ_88200   = 1 << (SamplingFrequency.FREQ_88200 - 1)
+    FREQ_96000   = 1 << (SamplingFrequency.FREQ_96000 - 1)
+    FREQ_176400  = 1 << (SamplingFrequency.FREQ_176400 - 1)
+    FREQ_192000  = 1 << (SamplingFrequency.FREQ_192000 - 1)
+    FREQ_384000  = 1 << (SamplingFrequency.FREQ_384000 - 1)
+    # fmt: on
+
+    @classmethod
+    def from_hz(cls, frequencies: Sequence[int]) -> SupportedSamplingFrequency:
+        MAPPING = {
+            8000: SupportedSamplingFrequency.FREQ_8000,
+            11025: SupportedSamplingFrequency.FREQ_11025,
+            16000: SupportedSamplingFrequency.FREQ_16000,
+            22050: SupportedSamplingFrequency.FREQ_22050,
+            24000: SupportedSamplingFrequency.FREQ_24000,
+            32000: SupportedSamplingFrequency.FREQ_32000,
+            44100: SupportedSamplingFrequency.FREQ_44100,
+            48000: SupportedSamplingFrequency.FREQ_48000,
+            88200: SupportedSamplingFrequency.FREQ_88200,
+            96000: SupportedSamplingFrequency.FREQ_96000,
+            176400: SupportedSamplingFrequency.FREQ_176400,
+            192000: SupportedSamplingFrequency.FREQ_192000,
+            384000: SupportedSamplingFrequency.FREQ_384000,
+        }
+
+        return functools.reduce(
+            lambda x, y: x | MAPPING[y],
+            frequencies,
+            cls(0),
+        )
+
+
+class FrameDuration(enum.IntEnum):
+    '''Bluetooth Assigned Numbers, Section 6.12.5.2 - Frame Duration'''
+
+    # fmt: off
+    DURATION_7500_US  = 0x00
+    DURATION_10000_US = 0x01
+
+
+class SupportedFrameDuration(enum.IntFlag):
+    '''Bluetooth Assigned Numbers, Section 6.12.4.2 - Frame Duration'''
+
+    # fmt: off
+    DURATION_7500_US_SUPPORTED  = 0b0001
+    DURATION_10000_US_SUPPORTED = 0b0010
+    DURATION_7500_US_PREFERRED  = 0b0001
+    DURATION_10000_US_PREFERRED = 0b0010
+
+
+# -----------------------------------------------------------------------------
+# Utils
+# -----------------------------------------------------------------------------
+
+
+def bits_to_channel_counts(data: int) -> List[int]:
+    pos = 0
+    counts = []
+    while data != 0:
+        # Bit 0 = count 1
+        # Bit 1 = count 2, and so on
+        pos += 1
+        if data & 1:
+            counts.append(pos)
+        data >>= 1
+    return counts
+
+
+def channel_counts_to_bits(counts: Sequence[int]) -> int:
+    return sum(set([1 << (count - 1) for count in counts]))
+
+
+# -----------------------------------------------------------------------------
+# Structures
+# -----------------------------------------------------------------------------
+
+
+@dataclasses.dataclass
+class CodecSpecificCapabilities:
+    '''See:
+    * Bluetooth Assigned Numbers, 6.12.4 - Codec Specific Capabilities LTV Structures
+    * Basic Audio Profile, 4.3.1 - Codec_Specific_Capabilities LTV requirements
+    '''
+
+    class Type(enum.IntEnum):
+        # fmt: off
+        SAMPLING_FREQUENCY   = 0x01
+        FRAME_DURATION       = 0x02
+        AUDIO_CHANNEL_COUNT  = 0x03
+        OCTETS_PER_FRAME     = 0x04
+        CODEC_FRAMES_PER_SDU = 0x05
+
+    supported_sampling_frequencies: SupportedSamplingFrequency
+    supported_frame_durations: SupportedFrameDuration
+    supported_audio_channel_counts: Sequence[int]
+    min_octets_per_codec_frame: int
+    max_octets_per_codec_frame: int
+    supported_max_codec_frames_per_sdu: int
+
+    @classmethod
+    def from_bytes(cls, data: bytes) -> CodecSpecificCapabilities:
+        offset = 0
+        # Allowed default values.
+        supported_audio_channel_counts = [1]
+        supported_max_codec_frames_per_sdu = 1
+        while offset < len(data):
+            length, type = struct.unpack_from('BB', data, offset)
+            offset += 2
+            value = int.from_bytes(data[offset : offset + length - 1], 'little')
+            offset += length - 1
+
+            if type == CodecSpecificCapabilities.Type.SAMPLING_FREQUENCY:
+                supported_sampling_frequencies = SupportedSamplingFrequency(value)
+            elif type == CodecSpecificCapabilities.Type.FRAME_DURATION:
+                supported_frame_durations = SupportedFrameDuration(value)
+            elif type == CodecSpecificCapabilities.Type.AUDIO_CHANNEL_COUNT:
+                supported_audio_channel_counts = bits_to_channel_counts(value)
+            elif type == CodecSpecificCapabilities.Type.OCTETS_PER_FRAME:
+                min_octets_per_sample = value & 0xFFFF
+                max_octets_per_sample = value >> 16
+            elif type == CodecSpecificCapabilities.Type.CODEC_FRAMES_PER_SDU:
+                supported_max_codec_frames_per_sdu = value
+
+        # It is expected here that if some fields are missing, an error should be raised.
+        return CodecSpecificCapabilities(
+            supported_sampling_frequencies=supported_sampling_frequencies,
+            supported_frame_durations=supported_frame_durations,
+            supported_audio_channel_counts=supported_audio_channel_counts,
+            min_octets_per_codec_frame=min_octets_per_sample,
+            max_octets_per_codec_frame=max_octets_per_sample,
+            supported_max_codec_frames_per_sdu=supported_max_codec_frames_per_sdu,
+        )
+
+    def __bytes__(self) -> bytes:
+        return struct.pack(
+            '<BBHBBBBBBBBHHBBB',
+            3,
+            CodecSpecificCapabilities.Type.SAMPLING_FREQUENCY,
+            self.supported_sampling_frequencies,
+            2,
+            CodecSpecificCapabilities.Type.FRAME_DURATION,
+            self.supported_frame_durations,
+            2,
+            CodecSpecificCapabilities.Type.AUDIO_CHANNEL_COUNT,
+            channel_counts_to_bits(self.supported_audio_channel_counts),
+            5,
+            CodecSpecificCapabilities.Type.OCTETS_PER_FRAME,
+            self.min_octets_per_codec_frame,
+            self.max_octets_per_codec_frame,
+            2,
+            CodecSpecificCapabilities.Type.CODEC_FRAMES_PER_SDU,
+            self.supported_max_codec_frames_per_sdu,
+        )
+
+
+@dataclasses.dataclass
+class PacRecord:
+    coding_format: hci.CodingFormat
+    codec_specific_capabilities: Union[CodecSpecificCapabilities, bytes]
+    # TODO: Parse Metadata
+    metadata: bytes = b''
+
+    @classmethod
+    def from_bytes(cls, data: bytes) -> PacRecord:
+        offset, coding_format = hci.CodingFormat.parse_from_bytes(data, 0)
+        codec_specific_capabilities_size = data[offset]
+
+        offset += 1
+        codec_specific_capabilities_bytes = data[
+            offset : offset + codec_specific_capabilities_size
+        ]
+        offset += codec_specific_capabilities_size
+        metadata_size = data[offset]
+        metadata = data[offset : offset + metadata_size]
+
+        codec_specific_capabilities: Union[CodecSpecificCapabilities, bytes]
+        if coding_format.codec_id == hci.CodecID.VENDOR_SPECIFIC:
+            codec_specific_capabilities = codec_specific_capabilities_bytes
+        else:
+            codec_specific_capabilities = CodecSpecificCapabilities.from_bytes(
+                codec_specific_capabilities_bytes
+            )
+
+        return PacRecord(
+            coding_format=coding_format,
+            codec_specific_capabilities=codec_specific_capabilities,
+            metadata=metadata,
+        )
+
+    def __bytes__(self) -> bytes:
+        capabilities_bytes = bytes(self.codec_specific_capabilities)
+        return (
+            bytes(self.coding_format)
+            + bytes([len(capabilities_bytes)])
+            + capabilities_bytes
+            + bytes([len(self.metadata)])
+            + self.metadata
+        )
+
+
+# -----------------------------------------------------------------------------
+# Server
+# -----------------------------------------------------------------------------
+class PublishedAudioCapabilitiesService(gatt.TemplateService):
+    UUID = gatt.GATT_PUBLISHED_AUDIO_CAPABILITIES_SERVICE
+
+    sink_pac: Optional[gatt.Characteristic]
+    sink_audio_locations: Optional[gatt.Characteristic]
+    source_pac: Optional[gatt.Characteristic]
+    source_audio_locations: Optional[gatt.Characteristic]
+    available_audio_contexts: gatt.Characteristic
+    supported_audio_contexts: gatt.Characteristic
+
+    def __init__(
+        self,
+        supported_source_context: ContextType,
+        supported_sink_context: ContextType,
+        available_source_context: ContextType,
+        available_sink_context: ContextType,
+        sink_pac: Sequence[PacRecord] = [],
+        sink_audio_locations: Optional[AudioLocation] = None,
+        source_pac: Sequence[PacRecord] = [],
+        source_audio_locations: Optional[AudioLocation] = None,
+    ) -> None:
+        characteristics = []
+
+        self.supported_audio_contexts = gatt.Characteristic(
+            uuid=gatt.GATT_SUPPORTED_AUDIO_CONTEXTS_CHARACTERISTIC,
+            properties=gatt.Characteristic.Properties.READ,
+            permissions=gatt.Characteristic.Permissions.READABLE,
+            value=struct.pack('<HH', supported_sink_context, supported_source_context),
+        )
+        characteristics.append(self.supported_audio_contexts)
+
+        self.available_audio_contexts = gatt.Characteristic(
+            uuid=gatt.GATT_AVAILABLE_AUDIO_CONTEXTS_CHARACTERISTIC,
+            properties=gatt.Characteristic.Properties.READ
+            | gatt.Characteristic.Properties.NOTIFY,
+            permissions=gatt.Characteristic.Permissions.READABLE,
+            value=struct.pack('<HH', available_sink_context, available_source_context),
+        )
+        characteristics.append(self.available_audio_contexts)
+
+        if sink_pac:
+            self.sink_pac = gatt.Characteristic(
+                uuid=gatt.GATT_SINK_PAC_CHARACTERISTIC,
+                properties=gatt.Characteristic.Properties.READ,
+                permissions=gatt.Characteristic.Permissions.READABLE,
+                value=bytes([len(sink_pac)]) + b''.join(map(bytes, sink_pac)),
+            )
+            characteristics.append(self.sink_pac)
+
+        if sink_audio_locations is not None:
+            self.sink_audio_locations = gatt.Characteristic(
+                uuid=gatt.GATT_SINK_AUDIO_LOCATION_CHARACTERISTIC,
+                properties=gatt.Characteristic.Properties.READ,
+                permissions=gatt.Characteristic.Permissions.READABLE,
+                value=struct.pack('<I', sink_audio_locations),
+            )
+            characteristics.append(self.sink_audio_locations)
+
+        if source_pac:
+            self.source_pac = gatt.Characteristic(
+                uuid=gatt.GATT_SOURCE_PAC_CHARACTERISTIC,
+                properties=gatt.Characteristic.Properties.READ,
+                permissions=gatt.Characteristic.Permissions.READABLE,
+                value=bytes([len(source_pac)]) + b''.join(map(bytes, source_pac)),
+            )
+            characteristics.append(self.source_pac)
+
+        if source_audio_locations is not None:
+            self.source_audio_locations = gatt.Characteristic(
+                uuid=gatt.GATT_SOURCE_AUDIO_LOCATION_CHARACTERISTIC,
+                properties=gatt.Characteristic.Properties.READ,
+                permissions=gatt.Characteristic.Permissions.READABLE,
+                value=struct.pack('<I', source_audio_locations),
+            )
+            characteristics.append(self.source_audio_locations)
+
+        super().__init__(characteristics)
+
+
+# -----------------------------------------------------------------------------
+# Client
+# -----------------------------------------------------------------------------
+class PublishedAudioCapabilitiesServiceProxy(gatt_client.ProfileServiceProxy):
+    SERVICE_CLASS = PublishedAudioCapabilitiesService
+
+    sink_pac: Optional[gatt_client.CharacteristicProxy] = None
+    sink_audio_locations: Optional[gatt_client.CharacteristicProxy] = None
+    source_pac: Optional[gatt_client.CharacteristicProxy] = None
+    source_audio_locations: Optional[gatt_client.CharacteristicProxy] = None
+    available_audio_contexts: gatt_client.CharacteristicProxy
+    supported_audio_contexts: gatt_client.CharacteristicProxy
+
+    def __init__(self, service_proxy: gatt_client.ServiceProxy):
+        self.service_proxy = service_proxy
+
+        self.available_audio_contexts = service_proxy.get_characteristics_by_uuid(
+            gatt.GATT_AVAILABLE_AUDIO_CONTEXTS_CHARACTERISTIC
+        )[0]
+        self.supported_audio_contexts = service_proxy.get_characteristics_by_uuid(
+            gatt.GATT_SUPPORTED_AUDIO_CONTEXTS_CHARACTERISTIC
+        )[0]
+
+        if characteristics := service_proxy.get_characteristics_by_uuid(
+            gatt.GATT_SINK_PAC_CHARACTERISTIC
+        ):
+            self.sink_pac = characteristics[0]
+
+        if characteristics := service_proxy.get_characteristics_by_uuid(
+            gatt.GATT_SOURCE_PAC_CHARACTERISTIC
+        ):
+            self.source_pac = characteristics[0]
+
+        if characteristics := service_proxy.get_characteristics_by_uuid(
+            gatt.GATT_SINK_AUDIO_LOCATION_CHARACTERISTIC
+        ):
+            self.sink_audio_locations = characteristics[0]
+
+        if characteristics := service_proxy.get_characteristics_by_uuid(
+            gatt.GATT_SOURCE_AUDIO_LOCATION_CHARACTERISTIC
+        ):
+            self.source_audio_locations = characteristics[0]

bumble/profiles/csip.py

@@ -0,0 +1,147 @@
+# Copyright 2021-2023 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+# -----------------------------------------------------------------------------
+# Imports
+# -----------------------------------------------------------------------------
+from __future__ import annotations
+import enum
+import struct
+from typing import Optional
+
+from bumble import gatt
+from bumble import gatt_client
+
+
+# -----------------------------------------------------------------------------
+# Constants
+# -----------------------------------------------------------------------------
+class SirkType(enum.IntEnum):
+    '''Coordinated Set Identification Service - 5.1 Set Identity Resolving Key.'''
+
+    ENCRYPTED = 0x00
+    PLAINTEXT = 0x01
+
+
+class MemberLock(enum.IntEnum):
+    '''Coordinated Set Identification Service - 5.3 Set Member Lock.'''
+
+    UNLOCKED = 0x01
+    LOCKED = 0x02
+
+
+# -----------------------------------------------------------------------------
+# Utils
+# -----------------------------------------------------------------------------
+# TODO: Implement RSI Generator
+
+
+# -----------------------------------------------------------------------------
+# Server
+# -----------------------------------------------------------------------------
+class CoordinatedSetIdentificationService(gatt.TemplateService):
+    UUID = gatt.GATT_COORDINATED_SET_IDENTIFICATION_SERVICE
+
+    set_identity_resolving_key_characteristic: gatt.Characteristic
+    coordinated_set_size_characteristic: Optional[gatt.Characteristic] = None
+    set_member_lock_characteristic: Optional[gatt.Characteristic] = None
+    set_member_rank_characteristic: Optional[gatt.Characteristic] = None
+
+    def __init__(
+        self,
+        set_identity_resolving_key: bytes,
+        coordinated_set_size: Optional[int] = None,
+        set_member_lock: Optional[MemberLock] = None,
+        set_member_rank: Optional[int] = None,
+    ) -> None:
+        characteristics = []
+
+        self.set_identity_resolving_key_characteristic = gatt.Characteristic(
+            uuid=gatt.GATT_SET_IDENTITY_RESOLVING_KEY_CHARACTERISTIC,
+            properties=gatt.Characteristic.Properties.READ
+            | gatt.Characteristic.Properties.NOTIFY,
+            permissions=gatt.Characteristic.Permissions.READABLE,
+            # TODO: Implement encrypted SIRK reader.
+            value=struct.pack('B', SirkType.PLAINTEXT) + set_identity_resolving_key,
+        )
+        characteristics.append(self.set_identity_resolving_key_characteristic)
+
+        if coordinated_set_size is not None:
+            self.coordinated_set_size_characteristic = gatt.Characteristic(
+                uuid=gatt.GATT_COORDINATED_SET_SIZE_CHARACTERISTIC,
+                properties=gatt.Characteristic.Properties.READ
+                | gatt.Characteristic.Properties.NOTIFY,
+                permissions=gatt.Characteristic.Permissions.READABLE,
+                value=struct.pack('B', coordinated_set_size),
+            )
+            characteristics.append(self.coordinated_set_size_characteristic)
+
+        if set_member_lock is not None:
+            self.set_member_lock_characteristic = gatt.Characteristic(
+                uuid=gatt.GATT_SET_MEMBER_LOCK_CHARACTERISTIC,
+                properties=gatt.Characteristic.Properties.READ
+                | gatt.Characteristic.Properties.NOTIFY
+                | gatt.Characteristic.Properties.WRITE,
+                permissions=gatt.Characteristic.Permissions.READABLE
+                | gatt.Characteristic.Permissions.WRITEABLE,
+                value=struct.pack('B', set_member_lock),
+            )
+            characteristics.append(self.set_member_lock_characteristic)
+
+        if set_member_rank is not None:
+            self.set_member_rank_characteristic = gatt.Characteristic(
+                uuid=gatt.GATT_SET_MEMBER_RANK_CHARACTERISTIC,
+                properties=gatt.Characteristic.Properties.READ
+                | gatt.Characteristic.Properties.NOTIFY,
+                permissions=gatt.Characteristic.Permissions.READABLE,
+                value=struct.pack('B', set_member_rank),
+            )
+            characteristics.append(self.set_member_rank_characteristic)
+
+        super().__init__(characteristics)
+
+
+# -----------------------------------------------------------------------------
+# Client
+# -----------------------------------------------------------------------------
+class CoordinatedSetIdentificationProxy(gatt_client.ProfileServiceProxy):
+    SERVICE_CLASS = CoordinatedSetIdentificationService
+
+    set_identity_resolving_key: gatt_client.CharacteristicProxy
+    coordinated_set_size: Optional[gatt_client.CharacteristicProxy] = None
+    set_member_lock: Optional[gatt_client.CharacteristicProxy] = None
+    set_member_rank: Optional[gatt_client.CharacteristicProxy] = None
+
+    def __init__(self, service_proxy: gatt_client.ServiceProxy) -> None:
+        self.service_proxy = service_proxy
+
+        self.set_identity_resolving_key = service_proxy.get_characteristics_by_uuid(
+            gatt.GATT_SET_IDENTITY_RESOLVING_KEY_CHARACTERISTIC
+        )[0]
+
+        if characteristics := service_proxy.get_characteristics_by_uuid(
+            gatt.GATT_COORDINATED_SET_SIZE_CHARACTERISTIC
+        ):
+            self.coordinated_set_size = characteristics[0]
+
+        if characteristics := service_proxy.get_characteristics_by_uuid(
+            gatt.GATT_SET_MEMBER_LOCK_CHARACTERISTIC
+        ):
+            self.set_member_lock = characteristics[0]
+
+        if characteristics := service_proxy.get_characteristics_by_uuid(
+            gatt.GATT_SET_MEMBER_RANK_CHARACTERISTIC
+        ):
+            self.set_member_rank = characteristics[0]

bumble/profiles/heart_rate_service.py

@@ -42,12 +42,12 @@ class HeartRateService(TemplateService):
     RESET_ENERGY_EXPENDED = 0x01
 
     class BodySensorLocation(IntEnum):
-        OTHER = (0,)
-        CHEST = (1,)
-        WRIST = (2,)
-        FINGER = (3,)
-        HAND = (4,)
-        EAR_LOBE = (5,)
+        OTHER = 0
+        CHEST = 1
+        WRIST = 2
+        FINGER = 3
+        HAND = 4
+        EAR_LOBE = 5
         FOOT = 6
 
     class HeartRateMeasurement:

bumble/rfcomm.py

@@ -20,13 +20,29 @@ from __future__ import annotations
 import logging
 import asyncio
 import enum
+from typing import Callable, Dict, List, Optional, Tuple, Union, TYPE_CHECKING
 
 from pyee import EventEmitter
-from typing import Optional, Tuple, Callable, Dict, Union, TYPE_CHECKING
 
 from . import core, l2cap
 from .colors import color
-from .core import BT_BR_EDR_TRANSPORT, InvalidStateError, ProtocolError
+from .core import (
+    UUID,
+    BT_RFCOMM_PROTOCOL_ID,
+    BT_BR_EDR_TRANSPORT,
+    BT_L2CAP_PROTOCOL_ID,
+    InvalidStateError,
+    ProtocolError,
+)
+from .sdp import (
+    SDP_SERVICE_RECORD_HANDLE_ATTRIBUTE_ID,
+    SDP_BROWSE_GROUP_LIST_ATTRIBUTE_ID,
+    SDP_SERVICE_CLASS_ID_LIST_ATTRIBUTE_ID,
+    SDP_PROTOCOL_DESCRIPTOR_LIST_ATTRIBUTE_ID,
+    SDP_PUBLIC_BROWSE_ROOT,
+    DataElement,
+    ServiceAttribute,
+)
 
 if TYPE_CHECKING:
     from bumble.device import Device, Connection
@@ -111,6 +127,50 @@ RFCOMM_DYNAMIC_CHANNEL_NUMBER_END   = 30
 # fmt: on
 
 
+# -----------------------------------------------------------------------------
+def make_service_sdp_records(
+    service_record_handle: int, channel: int, uuid: Optional[UUID] = None
+) -> List[ServiceAttribute]:
+    """
+    Create SDP records for an RFComm service given a channel number and an
+    optional UUID. A Service Class Attribute is included only if the UUID is not None.
+    """
+    records = [
+        ServiceAttribute(
+            SDP_SERVICE_RECORD_HANDLE_ATTRIBUTE_ID,
+            DataElement.unsigned_integer_32(service_record_handle),
+        ),
+        ServiceAttribute(
+            SDP_BROWSE_GROUP_LIST_ATTRIBUTE_ID,
+            DataElement.sequence([DataElement.uuid(SDP_PUBLIC_BROWSE_ROOT)]),
+        ),
+        ServiceAttribute(
+            SDP_PROTOCOL_DESCRIPTOR_LIST_ATTRIBUTE_ID,
+            DataElement.sequence(
+                [
+                    DataElement.sequence([DataElement.uuid(BT_L2CAP_PROTOCOL_ID)]),
+                    DataElement.sequence(
+                        [
+                            DataElement.uuid(BT_RFCOMM_PROTOCOL_ID),
+                            DataElement.unsigned_integer_8(channel),
+                        ]
+                    ),
+                ]
+            ),
+        ),
+    ]
+
+    if uuid:
+        records.append(
+            ServiceAttribute(
+                SDP_SERVICE_CLASS_ID_LIST_ATTRIBUTE_ID,
+                DataElement.sequence([DataElement.uuid(uuid)]),
+            )
+        )
+
+    return records
+
+
 # -----------------------------------------------------------------------------
 def compute_fcs(buffer: bytes) -> int:
     result = 0xFF
@@ -614,7 +674,7 @@ class Multiplexer(EventEmitter):
     acceptor: Optional[Callable[[int], bool]]
     dlcs: Dict[int, DLC]
 
-    def __init__(self, l2cap_channel: l2cap.Channel, role: Role) -> None:
+    def __init__(self, l2cap_channel: l2cap.ClassicChannel, role: Role) -> None:
         super().__init__()
         self.role = role
         self.l2cap_channel = l2cap_channel
@@ -827,10 +887,9 @@ class Multiplexer(EventEmitter):
 # -----------------------------------------------------------------------------
 class Client:
     multiplexer: Optional[Multiplexer]
-    l2cap_channel: Optional[l2cap.Channel]
+    l2cap_channel: Optional[l2cap.ClassicChannel]
 
-    def __init__(self, device: Device, connection: Connection) -> None:
-        self.device = device
+    def __init__(self, connection: Connection) -> None:
         self.connection = connection
         self.l2cap_channel = None
         self.multiplexer = None
@@ -838,15 +897,15 @@ class Client:
     async def start(self) -> Multiplexer:
         # Create a new L2CAP connection
         try:
-            self.l2cap_channel = await self.device.l2cap_channel_manager.connect(
-                self.connection, RFCOMM_PSM
+            self.l2cap_channel = await self.connection.create_l2cap_channel(
+                spec=l2cap.ClassicChannelSpec(RFCOMM_PSM)
             )
         except ProtocolError as error:
             logger.warning(f'L2CAP connection failed: {error}')
             raise
 
         assert self.l2cap_channel is not None
-        # Create a mutliplexer to manage DLCs with the server
+        # Create a multiplexer to manage DLCs with the server
         self.multiplexer = Multiplexer(self.l2cap_channel, Multiplexer.Role.INITIATOR)
 
         # Connect the multiplexer
@@ -876,7 +935,9 @@ class Server(EventEmitter):
         self.acceptors = {}
 
         # Register ourselves with the L2CAP channel manager
-        device.register_l2cap_server(RFCOMM_PSM, self.on_connection)
+        device.create_l2cap_server(
+            spec=l2cap.ClassicChannelSpec(psm=RFCOMM_PSM), handler=self.on_connection
+        )
 
     def listen(self, acceptor: Callable[[DLC], None], channel: int = 0) -> int:
         if channel:
@@ -900,11 +961,11 @@ class Server(EventEmitter):
         self.acceptors[channel] = acceptor
         return channel
 
-    def on_connection(self, l2cap_channel: l2cap.Channel) -> None:
+    def on_connection(self, l2cap_channel: l2cap.ClassicChannel) -> None:
         logger.debug(f'+++ new L2CAP connection: {l2cap_channel}')
         l2cap_channel.on('open', lambda: self.on_l2cap_channel_open(l2cap_channel))
 
-    def on_l2cap_channel_open(self, l2cap_channel: l2cap.Channel) -> None:
+    def on_l2cap_channel_open(self, l2cap_channel: l2cap.ClassicChannel) -> None:
         logger.debug(f'$$$ L2CAP channel open: {l2cap_channel}')
 
         # Create a new multiplexer for the channel

bumble/sdp.py

@@ -167,7 +167,7 @@ class DataElement:
         UUID: lambda x: DataElement(
             DataElement.UUID, core.UUID.from_bytes(bytes(reversed(x)))
         ),
-        TEXT_STRING: lambda x: DataElement(DataElement.TEXT_STRING, x.decode('utf8')),
+        TEXT_STRING: lambda x: DataElement(DataElement.TEXT_STRING, x),
         BOOLEAN: lambda x: DataElement(DataElement.BOOLEAN, x[0] == 1),
         SEQUENCE: lambda x: DataElement(
             DataElement.SEQUENCE, DataElement.list_from_bytes(x)
@@ -229,7 +229,7 @@ class DataElement:
         return DataElement(DataElement.UUID, value)
 
     @staticmethod
-    def text_string(value: str) -> DataElement:
+    def text_string(value: bytes) -> DataElement:
         return DataElement(DataElement.TEXT_STRING, value)
 
     @staticmethod
@@ -376,7 +376,7 @@ class DataElement:
                 raise ValueError('invalid value_size')
         elif self.type == DataElement.UUID:
             data = bytes(reversed(bytes(self.value)))
-        elif self.type in (DataElement.TEXT_STRING, DataElement.URL):
+        elif self.type == DataElement.URL:
             data = self.value.encode('utf8')
         elif self.type == DataElement.BOOLEAN:
             data = bytes([1 if self.value else 0])
@@ -758,16 +758,17 @@ class SDP_ServiceSearchAttributeResponse(SDP_PDU):
 
 # -----------------------------------------------------------------------------
 class Client:
-    channel: Optional[l2cap.Channel]
+    channel: Optional[l2cap.ClassicChannel]
 
-    def __init__(self, device: Device) -> None:
-        self.device = device
+    def __init__(self, connection: Connection) -> None:
+        self.connection = connection
         self.pending_request = None
         self.channel = None
 
-    async def connect(self, connection: Connection) -> None:
-        result = await self.device.l2cap_channel_manager.connect(connection, SDP_PSM)
-        self.channel = result
+    async def connect(self) -> None:
+        self.channel = await self.connection.create_l2cap_channel(
+            spec=l2cap.ClassicChannelSpec(SDP_PSM)
+        )
 
     async def disconnect(self) -> None:
         if self.channel:
@@ -921,7 +922,7 @@ class Client:
 # -----------------------------------------------------------------------------
 class Server:
     CONTINUATION_STATE = bytes([0x01, 0x43])
-    channel: Optional[l2cap.Channel]
+    channel: Optional[l2cap.ClassicChannel]
     Service = NewType('Service', List[ServiceAttribute])
     service_records: Dict[int, Service]
     current_response: Union[None, bytes, Tuple[int, List[int]]]
@@ -933,7 +934,9 @@ class Server:
         self.current_response = None
 
     def register(self, l2cap_channel_manager: l2cap.ChannelManager) -> None:
-        l2cap_channel_manager.register_server(SDP_PSM, self.on_connection)
+        l2cap_channel_manager.create_classic_server(
+            spec=l2cap.ClassicChannelSpec(psm=SDP_PSM), handler=self.on_connection
+        )
 
     def send_response(self, response):
         logger.debug(f'{color(">>> Sending SDP Response", "blue")}: {response}')

bumble/smp.py

@@ -27,6 +27,7 @@ import logging
 import asyncio
 import enum
 import secrets
+from dataclasses import dataclass
 from typing import (
     TYPE_CHECKING,
     Any,
@@ -37,6 +38,7 @@ from typing import (
     Optional,
     Tuple,
     Type,
+    cast,
 )
 
 from pyee import EventEmitter
@@ -52,6 +54,7 @@ from .core import (
     BT_BR_EDR_TRANSPORT,
     BT_CENTRAL_ROLE,
     BT_LE_TRANSPORT,
+    AdvertisingData,
     ProtocolError,
     name_or_number,
 )
@@ -184,8 +187,8 @@ SMP_KEYPRESS_AUTHREQ = 0b00010000
 SMP_CT2_AUTHREQ      = 0b00100000
 
 # Crypto salt
-SMP_CTKD_H7_LEBR_SALT = bytes.fromhex('00000000000000000000000000000000746D7031')
-SMP_CTKD_H7_BRLE_SALT = bytes.fromhex('00000000000000000000000000000000746D7032')
+SMP_CTKD_H7_LEBR_SALT = bytes.fromhex('000000000000000000000000746D7031')
+SMP_CTKD_H7_BRLE_SALT = bytes.fromhex('000000000000000000000000746D7032')
 
 # fmt: on
 # pylint: enable=line-too-long
@@ -562,6 +565,54 @@ class PairingMethod(enum.IntEnum):
     CTKD_OVER_CLASSIC = 4
 
 
+# -----------------------------------------------------------------------------
+class OobContext:
+    """Cryptographic context for LE SC OOB pairing."""
+
+    ecc_key: crypto.EccKey
+    r: bytes
+
+    def __init__(
+        self, ecc_key: Optional[crypto.EccKey] = None, r: Optional[bytes] = None
+    ) -> None:
+        self.ecc_key = crypto.EccKey.generate() if ecc_key is None else ecc_key
+        self.r = crypto.r() if r is None else r
+
+    def share(self) -> OobSharedData:
+        pkx = self.ecc_key.x[::-1]
+        return OobSharedData(c=crypto.f4(pkx, pkx, self.r, bytes(1)), r=self.r)
+
+
+# -----------------------------------------------------------------------------
+class OobLegacyContext:
+    """Cryptographic context for LE Legacy OOB pairing."""
+
+    tk: bytes
+
+    def __init__(self, tk: Optional[bytes] = None) -> None:
+        self.tk = crypto.r() if tk is None else tk
+
+
+# -----------------------------------------------------------------------------
+@dataclass
+class OobSharedData:
+    """Shareable data for LE SC OOB pairing."""
+
+    c: bytes
+    r: bytes
+
+    def to_ad(self) -> AdvertisingData:
+        return AdvertisingData(
+            [
+                (AdvertisingData.LE_SECURE_CONNECTIONS_CONFIRMATION_VALUE, self.c),
+                (AdvertisingData.LE_SECURE_CONNECTIONS_RANDOM_VALUE, self.r),
+            ]
+        )
+
+    def __str__(self) -> str:
+        return f'OOB(C={self.c.hex()}, R={self.r.hex()})'
+
+
 # -----------------------------------------------------------------------------
 class Session:
     # I/O Capability to pairing method decision matrix
@@ -626,6 +677,13 @@ class Session:
         },
     }
 
+    ea: bytes
+    eb: bytes
+    ltk: bytes
+    preq: bytes
+    pres: bytes
+    tk: bytes
+
     def __init__(
         self,
         manager: Manager,
@@ -635,17 +693,10 @@ class Session:
     ) -> None:
         self.manager = manager
         self.connection = connection
-        self.preq: Optional[bytes] = None
-        self.pres: Optional[bytes] = None
-        self.ea = None
-        self.eb = None
-        self.tk = bytes(16)
-        self.r = bytes(16)
         self.stk = None
-        self.ltk = None
         self.ltk_ediv = 0
         self.ltk_rand = bytes(8)
-        self.link_key = None
+        self.link_key: Optional[bytes] = None
         self.initiator_key_distribution: int = 0
         self.responder_key_distribution: int = 0
         self.peer_random_value: Optional[bytes] = None
@@ -658,7 +709,7 @@ class Session:
         self.peer_bd_addr: Optional[Address] = None
         self.peer_signature_key = None
         self.peer_expected_distributions: List[Type[SMP_Command]] = []
-        self.dh_key = None
+        self.dh_key = b''
         self.confirm_value = None
         self.passkey: Optional[int] = None
         self.passkey_ready = asyncio.Event()
@@ -711,8 +762,8 @@ class Session:
         self.io_capability = pairing_config.delegate.io_capability
         self.peer_io_capability = SMP_NO_INPUT_NO_OUTPUT_IO_CAPABILITY
 
-        # OOB (not supported yet)
-        self.oob = False
+        # OOB
+        self.oob_data_flag = 0 if pairing_config.oob is None else 1
 
         # Set up addresses
         self_address = connection.self_address
@@ -728,9 +779,35 @@ class Session:
             self.ia = bytes(peer_address)
             self.iat = 1 if peer_address.is_random else 0
 
+        # Select the ECC key, TK and r initial value
+        if pairing_config.oob:
+            self.peer_oob_data = pairing_config.oob.peer_data
+            if pairing_config.sc:
+                if pairing_config.oob.our_context is None:
+                    raise ValueError(
+                        "oob pairing config requires a context when sc is True"
+                    )
+                self.r = pairing_config.oob.our_context.r
+                self.ecc_key = pairing_config.oob.our_context.ecc_key
+                if pairing_config.oob.legacy_context is not None:
+                    self.tk = pairing_config.oob.legacy_context.tk
+            else:
+                if pairing_config.oob.legacy_context is None:
+                    raise ValueError(
+                        "oob pairing config requires a legacy context when sc is False"
+                    )
+                self.r = bytes(16)
+                self.ecc_key = manager.ecc_key
+                self.tk = pairing_config.oob.legacy_context.tk
+        else:
+            self.peer_oob_data = None
+            self.r = bytes(16)
+            self.ecc_key = manager.ecc_key
+            self.tk = bytes(16)
+
     @property
     def pkx(self) -> Tuple[bytes, bytes]:
-        return (bytes(reversed(self.manager.ecc_key.x)), self.peer_public_key_x)
+        return (self.ecc_key.x[::-1], self.peer_public_key_x)
 
     @property
     def pka(self) -> bytes:
@@ -767,7 +844,10 @@ class Session:
         return None
 
     def decide_pairing_method(
-        self, auth_req: int, initiator_io_capability: int, responder_io_capability: int
+        self,
+        auth_req: int,
+        initiator_io_capability: int,
+        responder_io_capability: int,
     ) -> None:
         if self.connection.transport == BT_BR_EDR_TRANSPORT:
             self.pairing_method = PairingMethod.CTKD_OVER_CLASSIC
@@ -908,7 +988,7 @@ class Session:
 
         command = SMP_Pairing_Request_Command(
             io_capability=self.io_capability,
-            oob_data_flag=0,
+            oob_data_flag=self.oob_data_flag,
             auth_req=self.auth_req,
             maximum_encryption_key_size=16,
             initiator_key_distribution=self.initiator_key_distribution,
@@ -920,7 +1000,7 @@ class Session:
     def send_pairing_response_command(self) -> None:
         response = SMP_Pairing_Response_Command(
             io_capability=self.io_capability,
-            oob_data_flag=0,
+            oob_data_flag=self.oob_data_flag,
             auth_req=self.auth_req,
             maximum_encryption_key_size=16,
             initiator_key_distribution=self.initiator_key_distribution,
@@ -981,8 +1061,8 @@ class Session:
     def send_public_key_command(self) -> None:
         self.send_command(
             SMP_Pairing_Public_Key_Command(
-                public_key_x=bytes(reversed(self.manager.ecc_key.x)),
-                public_key_y=bytes(reversed(self.manager.ecc_key.y)),
+                public_key_x=self.ecc_key.x[::-1],
+                public_key_y=self.ecc_key.y[::-1],
             )
         )
 
@@ -1010,7 +1090,7 @@ class Session:
         # We can now encrypt the connection with the short term key, so that we can
         # distribute the long term and/or other keys over an encrypted connection
         self.manager.device.host.send_command_sync(
-            HCI_LE_Enable_Encryption_Command(  # type: ignore[call-arg]
+            HCI_LE_Enable_Encryption_Command(
                 connection_handle=self.connection.handle,
                 random_number=bytes(8),
                 encrypted_diversifier=0,
@@ -1018,18 +1098,54 @@ class Session:
             )
         )
 
-    async def derive_ltk(self) -> None:
-        link_key = await self.manager.device.get_link_key(self.connection.peer_address)
-        assert link_key is not None
+    @classmethod
+    def derive_ltk(cls, link_key: bytes, ct2: bool) -> bytes:
+        '''Derives Long Term Key from Link Key.
+
+        Args:
+            link_key: BR/EDR Link Key bytes in little-endian.
+            ct2: whether ct2 is supported on both devices.
+        Returns:
+            LE Long Tern Key bytes in little-endian.
+        '''
         ilk = (
             crypto.h7(salt=SMP_CTKD_H7_BRLE_SALT, w=link_key)
-            if self.ct2
+            if ct2
             else crypto.h6(link_key, b'tmp2')
         )
-        self.ltk = crypto.h6(ilk, b'brle')
+        return crypto.h6(ilk, b'brle')
+
+    @classmethod
+    def derive_link_key(cls, ltk: bytes, ct2: bool) -> bytes:
+        '''Derives Link Key from Long Term Key.
+
+        Args:
+            ltk: LE Long Term Key bytes in little-endian.
+            ct2: whether ct2 is supported on both devices.
+        Returns:
+            BR/EDR Link Key bytes in little-endian.
+        '''
+        ilk = (
+            crypto.h7(salt=SMP_CTKD_H7_LEBR_SALT, w=ltk)
+            if ct2
+            else crypto.h6(ltk, b'tmp1')
+        )
+        return crypto.h6(ilk, b'lebr')
+
+    async def get_link_key_and_derive_ltk(self) -> None:
+        '''Retrieves BR/EDR Link Key from storage and derive it to LE LTK.'''
+        link_key = await self.manager.device.get_link_key(self.connection.peer_address)
+        if link_key is None:
+            logging.warning(
+                'Try to derive LTK but host does not have the LK. Send a SMP_PAIRING_FAILED but the procedure will not be paused!'
+            )
+            self.send_pairing_failed(
+                SMP_CROSS_TRANSPORT_KEY_DERIVATION_NOT_ALLOWED_ERROR
+            )
+        else:
+            self.ltk = self.derive_ltk(link_key, self.ct2)
 
     def distribute_keys(self) -> None:
-
         # Distribute the keys as required
         if self.is_initiator:
             # CTKD: Derive LTK from LinkKey
@@ -1038,7 +1154,7 @@ class Session:
                 and self.initiator_key_distribution & SMP_ENC_KEY_DISTRIBUTION_FLAG
             ):
                 self.ctkd_task = self.connection.abort_on(
-                    'disconnection', self.derive_ltk()
+                    'disconnection', self.get_link_key_and_derive_ltk()
                 )
             elif not self.sc:
                 # Distribute the LTK, EDIV and RAND
@@ -1068,12 +1184,7 @@ class Session:
 
             # CTKD, calculate BR/EDR link key
             if self.initiator_key_distribution & SMP_LINK_KEY_DISTRIBUTION_FLAG:
-                ilk = (
-                    crypto.h7(salt=SMP_CTKD_H7_LEBR_SALT, w=self.ltk)
-                    if self.ct2
-                    else crypto.h6(self.ltk, b'tmp1')
-                )
-                self.link_key = crypto.h6(ilk, b'lebr')
+                self.link_key = self.derive_link_key(self.ltk, self.ct2)
 
         else:
             # CTKD: Derive LTK from LinkKey
@@ -1082,7 +1193,7 @@ class Session:
                 and self.responder_key_distribution & SMP_ENC_KEY_DISTRIBUTION_FLAG
             ):
                 self.ctkd_task = self.connection.abort_on(
-                    'disconnection', self.derive_ltk()
+                    'disconnection', self.get_link_key_and_derive_ltk()
                 )
             # Distribute the LTK, EDIV and RAND
             elif not self.sc:
@@ -1112,12 +1223,7 @@ class Session:
 
             # CTKD, calculate BR/EDR link key
             if self.responder_key_distribution & SMP_LINK_KEY_DISTRIBUTION_FLAG:
-                ilk = (
-                    crypto.h7(salt=SMP_CTKD_H7_LEBR_SALT, w=self.ltk)
-                    if self.ct2
-                    else crypto.h6(self.ltk, b'tmp1')
-                )
-                self.link_key = crypto.h6(ilk, b'lebr')
+                self.link_key = self.derive_link_key(self.ltk, self.ct2)
 
     def compute_peer_expected_distributions(self, key_distribution_flags: int) -> None:
         # Set our expectations for what to wait for in the key distribution phase
@@ -1295,7 +1401,7 @@ class Session:
             try:
                 handler(command)
             except Exception as error:
-                logger.warning(f'{color("!!! Exception in handler:", "red")} {error}')
+                logger.exception(f'{color("!!! Exception in handler:", "red")} {error}')
                 response = SMP_Pairing_Failed_Command(
                     reason=SMP_UNSPECIFIED_REASON_ERROR
                 )
@@ -1332,15 +1438,28 @@ class Session:
         self.sc = self.sc and (command.auth_req & SMP_SC_AUTHREQ != 0)
         self.ct2 = self.ct2 and (command.auth_req & SMP_CT2_AUTHREQ != 0)
 
-        # Check for OOB
-        if command.oob_data_flag != 0:
-            self.send_pairing_failed(SMP_OOB_NOT_AVAILABLE_ERROR)
-            return
+        # Infer the pairing method
+        if (self.sc and (self.oob_data_flag != 0 or command.oob_data_flag != 0)) or (
+            not self.sc and (self.oob_data_flag != 0 and command.oob_data_flag != 0)
+        ):
+            # Use OOB
+            self.pairing_method = PairingMethod.OOB
+            if not self.sc and self.tk is None:
+                # For legacy OOB, TK is required.
+                logger.warning("legacy OOB without TK")
+                self.send_pairing_failed(SMP_OOB_NOT_AVAILABLE_ERROR)
+                return
+            if command.oob_data_flag == 0:
+                # The peer doesn't have OOB data, use r=0
+                self.r = bytes(16)
+        else:
+            # Decide which pairing method to use from the IO capability
+            self.decide_pairing_method(
+                command.auth_req,
+                command.io_capability,
+                self.io_capability,
+            )
 
-        # Decide which pairing method to use
-        self.decide_pairing_method(
-            command.auth_req, command.io_capability, self.io_capability
-        )
         logger.debug(f'pairing method: {self.pairing_method.name}')
 
         # Key distribution
@@ -1389,15 +1508,26 @@ class Session:
         self.bonding = self.bonding and (command.auth_req & SMP_BONDING_AUTHREQ != 0)
         self.sc = self.sc and (command.auth_req & SMP_SC_AUTHREQ != 0)
 
-        # Check for OOB
-        if self.sc and command.oob_data_flag:
-            self.send_pairing_failed(SMP_OOB_NOT_AVAILABLE_ERROR)
-            return
+        # Infer the pairing method
+        if (self.sc and (self.oob_data_flag != 0 or command.oob_data_flag != 0)) or (
+            not self.sc and (self.oob_data_flag != 0 and command.oob_data_flag != 0)
+        ):
+            # Use OOB
+            self.pairing_method = PairingMethod.OOB
+            if not self.sc and self.tk is None:
+                # For legacy OOB, TK is required.
+                logger.warning("legacy OOB without TK")
+                self.send_pairing_failed(SMP_OOB_NOT_AVAILABLE_ERROR)
+                return
+            if command.oob_data_flag == 0:
+                # The peer doesn't have OOB data, use r=0
+                self.r = bytes(16)
+        else:
+            # Decide which pairing method to use from the IO capability
+            self.decide_pairing_method(
+                command.auth_req, self.io_capability, command.io_capability
+            )
 
-        # Decide which pairing method to use
-        self.decide_pairing_method(
-            command.auth_req, self.io_capability, command.io_capability
-        )
         logger.debug(f'pairing method: {self.pairing_method.name}')
 
         # Key distribution
@@ -1548,12 +1678,13 @@ class Session:
                 if self.passkey_step < 20:
                     self.send_pairing_confirm_command()
                     return
-            else:
+            elif self.pairing_method != PairingMethod.OOB:
                 return
         else:
             if self.pairing_method in (
                 PairingMethod.JUST_WORKS,
                 PairingMethod.NUMERIC_COMPARISON,
+                PairingMethod.OOB,
             ):
                 self.send_pairing_random_command()
             elif self.pairing_method == PairingMethod.PASSKEY:
@@ -1590,6 +1721,7 @@ class Session:
         if self.pairing_method in (
             PairingMethod.JUST_WORKS,
             PairingMethod.NUMERIC_COMPARISON,
+            PairingMethod.OOB,
         ):
             ra = bytes(16)
             rb = ra
@@ -1598,7 +1730,6 @@ class Session:
             ra = self.passkey.to_bytes(16, byteorder='little')
             rb = ra
         else:
-            # OOB not implemented yet
             return
 
         assert self.preq and self.pres
@@ -1650,18 +1781,33 @@ class Session:
         self.peer_public_key_y = command.public_key_y
 
         # Compute the DH key
-        self.dh_key = bytes(
-            reversed(
-                self.manager.ecc_key.dh(
-                    bytes(reversed(command.public_key_x)),
-                    bytes(reversed(command.public_key_y)),
-                )
-            )
-        )
+        self.dh_key = self.ecc_key.dh(
+            command.public_key_x[::-1],
+            command.public_key_y[::-1],
+        )[::-1]
         logger.debug(f'DH key: {self.dh_key.hex()}')
 
+        if self.pairing_method == PairingMethod.OOB:
+            # Check against shared OOB data
+            if self.peer_oob_data:
+                confirm_verifier = crypto.f4(
+                    self.peer_public_key_x,
+                    self.peer_public_key_x,
+                    self.peer_oob_data.r,
+                    bytes(1),
+                )
+                if not self.check_expected_value(
+                    self.peer_oob_data.c,
+                    confirm_verifier,
+                    SMP_CONFIRM_VALUE_FAILED_ERROR,
+                ):
+                    return
+
         if self.is_initiator:
-            self.send_pairing_confirm_command()
+            if self.pairing_method == PairingMethod.OOB:
+                self.send_pairing_random_command()
+            else:
+                self.send_pairing_confirm_command()
         else:
             if self.pairing_method == PairingMethod.PASSKEY:
                 self.display_or_input_passkey()
@@ -1672,6 +1818,7 @@ class Session:
             if self.pairing_method in (
                 PairingMethod.JUST_WORKS,
                 PairingMethod.NUMERIC_COMPARISON,
+                PairingMethod.OOB,
             ):
                 # We can now send the confirmation value
                 self.send_pairing_confirm_command()
@@ -1700,7 +1847,6 @@ class Session:
             else:
                 self.send_pairing_dhkey_check_command()
         else:
-            assert self.ltk
             self.start_encryption(self.ltk)
 
     def on_smp_pairing_failed_command(
@@ -1750,6 +1896,7 @@ class Manager(EventEmitter):
     sessions: Dict[int, Session]
     pairing_config_factory: Callable[[Connection], PairingConfig]
     session_proxy: Type[Session]
+    _ecc_key: Optional[crypto.EccKey]
 
     def __init__(
         self,
@@ -1771,7 +1918,26 @@ class Manager(EventEmitter):
         cid = SMP_BR_CID if connection.transport == BT_BR_EDR_TRANSPORT else SMP_CID
         connection.send_l2cap_pdu(cid, command.to_bytes())
 
+    def on_smp_security_request_command(
+        self, connection: Connection, request: SMP_Security_Request_Command
+    ) -> None:
+        connection.emit('security_request', request.auth_req)
+
     def on_smp_pdu(self, connection: Connection, pdu: bytes) -> None:
+        # Parse the L2CAP payload into an SMP Command object
+        command = SMP_Command.from_bytes(pdu)
+        logger.debug(
+            f'<<< Received SMP Command on connection [0x{connection.handle:04X}] '
+            f'{connection.peer_address}: {command}'
+        )
+
+        # Security request is more than just pairing, so let applications handle them
+        if command.code == SMP_SECURITY_REQUEST_COMMAND:
+            self.on_smp_security_request_command(
+                connection, cast(SMP_Security_Request_Command, command)
+            )
+            return
+
         # Look for a session with this connection, and create one if none exists
         if not (session := self.sessions.get(connection.handle)):
             if connection.role == BT_CENTRAL_ROLE:
@@ -1782,13 +1948,6 @@ class Manager(EventEmitter):
             )
             self.sessions[connection.handle] = session
 
-        # Parse the L2CAP payload into an SMP Command object
-        command = SMP_Command.from_bytes(pdu)
-        logger.debug(
-            f'<<< Received SMP Command on connection [0x{connection.handle:04X}] '
-            f'{connection.peer_address}: {command}'
-        )
-
         # Delegate the handling of the command to the session
         session.on_smp_command(command)
 

bumble/transport/__init__.py

@@ -20,7 +20,6 @@ import logging
 import os
 
 from .common import Transport, AsyncPipeSink, SnoopingTransport
-from ..controller import Controller
 from ..snoop import create_snooper
 
 # -----------------------------------------------------------------------------
@@ -119,7 +118,8 @@ async def _open_transport(name: str) -> Transport:
     if scheme == 'file':
         from .file import open_file_transport
 
-        return await open_file_transport(spec[0] if spec else None)
+        assert spec is not None
+        return await open_file_transport(spec[0])
 
     if scheme == 'vhci':
         from .vhci import open_vhci_transport
@@ -134,12 +134,14 @@ async def _open_transport(name: str) -> Transport:
     if scheme == 'usb':
         from .usb import open_usb_transport
 
-        return await open_usb_transport(spec[0] if spec else None)
+        assert spec is not None
+        return await open_usb_transport(spec[0])
 
     if scheme == 'pyusb':
         from .pyusb import open_pyusb_transport
 
-        return await open_pyusb_transport(spec[0] if spec else None)
+        assert spec is not None
+        return await open_pyusb_transport(spec[0])
 
     if scheme == 'android-emulator':
         from .android_emulator import open_android_emulator_transport
@@ -168,6 +170,7 @@ async def open_transport_or_link(name: str) -> Transport:
 
     """
     if name.startswith('link-relay:'):
+        from ..controller import Controller
         from ..link import RemoteLink  # lazy import
 
         link = RemoteLink(name[11:])

bumble/transport/android_emulator.py

@@ -18,7 +18,9 @@
 import logging
 import grpc.aio
 
-from .common import PumpedTransport, PumpedPacketSource, PumpedPacketSink
+from typing import Optional, Union
+
+from .common import PumpedTransport, PumpedPacketSource, PumpedPacketSink, Transport
 
 # pylint: disable=no-name-in-module
 from .grpc_protobuf.emulated_bluetooth_pb2_grpc import EmulatedBluetoothServiceStub
@@ -33,7 +35,7 @@ logger = logging.getLogger(__name__)
 
 
 # -----------------------------------------------------------------------------
-async def open_android_emulator_transport(spec):
+async def open_android_emulator_transport(spec: Optional[str]) -> Transport:
     '''
     Open a transport connection to an Android emulator via its gRPC interface.
     The parameter string has this syntax:
@@ -66,7 +68,7 @@ async def open_android_emulator_transport(spec):
     # Parse the parameters
     mode = 'host'
     server_host = 'localhost'
-    server_port = 8554
+    server_port = '8554'
     if spec is not None:
         params = spec.split(',')
         for param in params:
@@ -82,6 +84,7 @@ async def open_android_emulator_transport(spec):
     logger.debug(f'connecting to gRPC server at {server_address}')
     channel = grpc.aio.insecure_channel(server_address)
 
+    service: Union[EmulatedBluetoothServiceStub, VhciForwardingServiceStub]
     if mode == 'host':
         # Connect as a host
         service = EmulatedBluetoothServiceStub(channel)
@@ -94,10 +97,13 @@ async def open_android_emulator_transport(spec):
         raise ValueError('invalid mode')
 
     # Create the transport object
-    transport = PumpedTransport(
-        PumpedPacketSource(hci_device.read),
-        PumpedPacketSink(hci_device.write),
-        channel.close,
+    class EmulatorTransport(PumpedTransport):
+        async def close(self):
+            await super().close()
+            await channel.close()
+
+    transport = EmulatorTransport(
+        PumpedPacketSource(hci_device.read), PumpedPacketSink(hci_device.write)
     )
     transport.start()
 

bumble/transport/android_netsim.py

@@ -18,11 +18,12 @@
 import asyncio
 import atexit
 import logging
-import grpc.aio
 import os
 import pathlib
 import sys
-from typing import Optional
+from typing import Dict, Optional
+
+import grpc.aio
 
 from .common import (
     ParserSource,
@@ -33,8 +34,8 @@ from .common import (
 )
 
 # pylint: disable=no-name-in-module
-from .grpc_protobuf.packet_streamer_pb2_grpc import PacketStreamerStub
 from .grpc_protobuf.packet_streamer_pb2_grpc import (
+    PacketStreamerStub,
     PacketStreamerServicer,
     add_PacketStreamerServicer_to_server,
 )
@@ -43,6 +44,7 @@ from .grpc_protobuf.hci_packet_pb2 import HCIPacket
 from .grpc_protobuf.startup_pb2 import Chip, ChipInfo
 from .grpc_protobuf.common_pb2 import ChipKind
 
+
 # -----------------------------------------------------------------------------
 # Logging
 # -----------------------------------------------------------------------------
@@ -74,14 +76,20 @@ def get_ini_dir() -> Optional[pathlib.Path]:
 
 
 # -----------------------------------------------------------------------------
-def find_grpc_port() -> int:
+def ini_file_name(instance_number: int) -> str:
+    suffix = f'_{instance_number}' if instance_number > 0 else ''
+    return f'netsim{suffix}.ini'
+
+
+# -----------------------------------------------------------------------------
+def find_grpc_port(instance_number: int) -> int:
     if not (ini_dir := get_ini_dir()):
         logger.debug('no known directory for .ini file')
         return 0
 
-    ini_file = ini_dir / 'netsim.ini'
+    ini_file = ini_dir / ini_file_name(instance_number)
+    logger.debug(f'Looking for .ini file at {ini_file}')
     if ini_file.is_file():
-        logger.debug(f'Found .ini file at {ini_file}')
         with open(ini_file, 'r') as ini_file_data:
             for line in ini_file_data.readlines():
                 if '=' in line:
@@ -90,12 +98,14 @@ def find_grpc_port() -> int:
                         logger.debug(f'gRPC port = {value}')
                         return int(value)
 
+        logger.debug('no grpc.port property found in .ini file')
+
     # Not found
     return 0
 
 
 # -----------------------------------------------------------------------------
-def publish_grpc_port(grpc_port) -> bool:
+def publish_grpc_port(grpc_port: int, instance_number: int) -> bool:
     if not (ini_dir := get_ini_dir()):
         logger.debug('no known directory for .ini file')
         return False
@@ -104,7 +114,7 @@ def publish_grpc_port(grpc_port) -> bool:
         logger.debug('ini directory does not exist')
         return False
 
-    ini_file = ini_dir / 'netsim.ini'
+    ini_file = ini_dir / ini_file_name(instance_number)
     try:
         ini_file.write_text(f'grpc.port={grpc_port}\n')
         logger.debug(f"published gRPC port at {ini_file}")
@@ -121,13 +131,16 @@ def publish_grpc_port(grpc_port) -> bool:
 
 
 # -----------------------------------------------------------------------------
-async def open_android_netsim_controller_transport(server_host, server_port):
+async def open_android_netsim_controller_transport(
+    server_host: Optional[str], server_port: int, options: Dict[str, str]
+) -> Transport:
     if not server_port:
         raise ValueError('invalid port')
     if server_host == '_' or not server_host:
         server_host = 'localhost'
 
-    if not publish_grpc_port(server_port):
+    instance_number = int(options.get('instance', "0"))
+    if not publish_grpc_port(server_port, instance_number):
         logger.warning("unable to publish gRPC port")
 
     class HciDevice:
@@ -184,15 +197,12 @@ async def open_android_netsim_controller_transport(server_host, server_port):
                 logger.debug(f'<<< PACKET: {data.hex()}')
                 self.on_data_received(data)
 
-        def send_packet(self, data):
-            async def send():
-                await self.context.write(
-                    PacketResponse(
-                        hci_packet=HCIPacket(packet_type=data[0], packet=data[1:])
-                    )
+        async def send_packet(self, data):
+            return await self.context.write(
+                PacketResponse(
+                    hci_packet=HCIPacket(packet_type=data[0], packet=data[1:])
                 )
-
-            self.loop.create_task(send())
+            )
 
         def terminate(self):
             self.task.cancel()
@@ -226,17 +236,17 @@ async def open_android_netsim_controller_transport(server_host, server_port):
                 logger.debug('gRPC server cancelled')
                 await self.grpc_server.stop(None)
 
-        def on_packet(self, packet):
+        async def send_packet(self, packet):
             if not self.device:
                 logger.debug('no device, dropping packet')
                 return
 
-            self.device.send_packet(packet)
+            return await self.device.send_packet(packet)
 
         async def StreamPackets(self, _request_iterator, context):
             logger.debug('StreamPackets request')
 
-            # Check that we won't already have a device
+            # Check that we don't already have a device
             if self.device:
                 logger.debug('busy, already serving a device')
                 return PacketResponse(error='Busy')
@@ -259,15 +269,42 @@ async def open_android_netsim_controller_transport(server_host, server_port):
     await server.start()
     asyncio.get_running_loop().create_task(server.serve())
 
-    class GrpcServerTransport(Transport):
-        async def close(self):
-            await super().close()
-
-    return GrpcServerTransport(server, server)
+    sink = PumpedPacketSink(server.send_packet)
+    sink.start()
+    return Transport(server, sink)
 
 
 # -----------------------------------------------------------------------------
-async def open_android_netsim_host_transport(server_host, server_port, options):
+async def open_android_netsim_host_transport_with_address(
+    server_host: Optional[str],
+    server_port: int,
+    options: Optional[Dict[str, str]] = None,
+):
+    if server_host == '_' or not server_host:
+        server_host = 'localhost'
+
+    if not server_port:
+        # Look for the gRPC config in a .ini file
+        instance_number = 0 if options is None else int(options.get('instance', '0'))
+        server_port = find_grpc_port(instance_number)
+        if not server_port:
+            raise RuntimeError('gRPC server port not found')
+
+    # Connect to the gRPC server
+    server_address = f'{server_host}:{server_port}'
+    logger.debug(f'Connecting to gRPC server at {server_address}')
+    channel = grpc.aio.insecure_channel(server_address)
+
+    return await open_android_netsim_host_transport_with_channel(
+        channel,
+        options,
+    )
+
+
+# -----------------------------------------------------------------------------
+async def open_android_netsim_host_transport_with_channel(
+    channel, options: Optional[Dict[str, str]] = None
+):
     # Wrapper for I/O operations
     class HciDevice:
         def __init__(self, name, manufacturer, hci_device):
@@ -286,10 +323,12 @@ async def open_android_netsim_host_transport(server_host, server_port, options):
         async def read(self):
             response = await self.hci_device.read()
             response_type = response.WhichOneof('response_type')
+
             if response_type == 'error':
                 logger.warning(f'received error: {response.error}')
                 raise RuntimeError(response.error)
-            elif response_type == 'hci_packet':
+
+            if response_type == 'hci_packet':
                 return (
                     bytes([response.hci_packet.packet_type])
                     + response.hci_packet.packet
@@ -304,24 +343,9 @@ async def open_android_netsim_host_transport(server_host, server_port, options):
                 )
             )
 
-    name = options.get('name', DEFAULT_NAME)
+    name = DEFAULT_NAME if options is None else options.get('name', DEFAULT_NAME)
     manufacturer = DEFAULT_MANUFACTURER
 
-    if server_host == '_' or not server_host:
-        server_host = 'localhost'
-
-    if not server_port:
-        # Look for the gRPC config in a .ini file
-        server_host = 'localhost'
-        server_port = find_grpc_port()
-        if not server_port:
-            raise RuntimeError('gRPC server port not found')
-
-    # Connect to the gRPC server
-    server_address = f'{server_host}:{server_port}'
-    logger.debug(f'Connecting to gRPC server at {server_address}')
-    channel = grpc.aio.insecure_channel(server_address)
-
     # Connect as a host
     service = PacketStreamerStub(channel)
     hci_device = HciDevice(
@@ -332,10 +356,14 @@ async def open_android_netsim_host_transport(server_host, server_port, options):
     await hci_device.start()
 
     # Create the transport object
-    transport = PumpedTransport(
+    class GrpcTransport(PumpedTransport):
+        async def close(self):
+            await super().close()
+            await channel.close()
+
+    transport = GrpcTransport(
         PumpedPacketSource(hci_device.read),
         PumpedPacketSink(hci_device.write),
-        channel.close,
     )
     transport.start()
 
@@ -343,7 +371,7 @@ async def open_android_netsim_host_transport(server_host, server_port, options):
 
 
 # -----------------------------------------------------------------------------
-async def open_android_netsim_transport(spec):
+async def open_android_netsim_transport(spec: Optional[str]) -> Transport:
     '''
     Open a transport connection as a client or server, implementing Android's `netsim`
     simulator protocol over gRPC.
@@ -357,6 +385,11 @@ async def open_android_netsim_transport(spec):
         to connect *to* a netsim server (netsim is the controller), or accept
         connections *as* a netsim-compatible server.
 
+      instance=<n>
+        Specifies an instance number, with <n> > 0. This is used to determine which
+        .init file to use. In `host` mode, it is ignored when the <host>:<port>
+        specifier is present, since in that case no .ini file is used.
+
     In `host` mode:
       The <host>:<port> part is optional. When not specified, the transport
       looks for a netsim .ini file, from which it will read the `grpc.backend.port`
@@ -385,14 +418,15 @@ async def open_android_netsim_transport(spec):
     params = spec.split(',') if spec else []
     if params and ':' in params[0]:
         # Explicit <host>:<port>
-        host, port = params[0].split(':')
+        host, port_str = params[0].split(':')
+        port = int(port_str)
         params_offset = 1
     else:
         host = None
         port = 0
         params_offset = 0
 
-    options = {}
+    options: Dict[str, str] = {}
     for param in params[params_offset:]:
         if '=' not in param:
             raise ValueError('invalid parameter, expected <name>=<value>')
@@ -401,10 +435,12 @@ async def open_android_netsim_transport(spec):
 
     mode = options.get('mode', 'host')
     if mode == 'host':
-        return await open_android_netsim_host_transport(host, port, options)
+        return await open_android_netsim_host_transport_with_address(
+            host, port, options
+        )
     if mode == 'controller':
         if host is None:
             raise ValueError('<host>:<port> missing')
-        return await open_android_netsim_controller_transport(host, port)
+        return await open_android_netsim_controller_transport(host, port, options)
 
     raise ValueError('invalid mode option')

bumble/transport/common.py

@@ -20,11 +20,12 @@ import contextlib
 import struct
 import asyncio
 import logging
-from typing import ContextManager
+import io
+from typing import ContextManager, Tuple, Optional, Protocol, Dict
 
-from .. import hci
-from ..colors import color
-from ..snoop import Snooper
+from bumble import hci
+from bumble.colors import color
+from bumble.snoop import Snooper
 
 
 # -----------------------------------------------------------------------------
@@ -36,7 +37,7 @@ logger = logging.getLogger(__name__)
 # Information needed to parse HCI packets with a generic parser:
 # For each packet type, the info represents:
 # (length-size, length-offset, unpack-type)
-HCI_PACKET_INFO = {
+HCI_PACKET_INFO: Dict[int, Tuple[int, int, str]] = {
     hci.HCI_COMMAND_PACKET: (1, 2, 'B'),
     hci.HCI_ACL_DATA_PACKET: (2, 2, 'H'),
     hci.HCI_SYNCHRONOUS_DATA_PACKET: (1, 2, 'B'),
@@ -44,6 +45,8 @@ HCI_PACKET_INFO = {
 }
 
 
+# -----------------------------------------------------------------------------
+# Errors
 # -----------------------------------------------------------------------------
 class TransportLostError(Exception):
     """
@@ -51,24 +54,36 @@ class TransportLostError(Exception):
     """
 
 
+# -----------------------------------------------------------------------------
+# Typing Protocols
+# -----------------------------------------------------------------------------
+class TransportSink(Protocol):
+    def on_packet(self, packet: bytes) -> None:
+        ...
+
+
+class TransportSource(Protocol):
+    terminated: asyncio.Future[None]
+
+    def set_packet_sink(self, sink: TransportSink) -> None:
+        ...
+
+
 # -----------------------------------------------------------------------------
 class PacketPump:
     """
     Pump HCI packets from a reader to a sink.
     """
 
-    def __init__(self, reader, sink):
+    def __init__(self, reader: AsyncPacketReader, sink: TransportSink) -> None:
         self.reader = reader
         self.sink = sink
 
-    async def run(self):
+    async def run(self) -> None:
         while True:
             try:
-                # Get a packet from the source
-                packet = hci.HCI_Packet.from_bytes(await self.reader.next_packet())
-
                 # Deliver the packet to the sink
-                self.sink.on_packet(packet)
+                self.sink.on_packet(await self.reader.next_packet())
             except Exception as error:
                 logger.warning(f'!!! {error}')
 
@@ -86,18 +101,22 @@ class PacketParser:
     NEED_LENGTH = 1
     NEED_BODY = 2
 
-    def __init__(self, sink=None):
+    sink: Optional[TransportSink]
+    extended_packet_info: Dict[int, Tuple[int, int, str]]
+    packet_info: Optional[Tuple[int, int, str]] = None
+
+    def __init__(self, sink: Optional[TransportSink] = None) -> None:
         self.sink = sink
         self.extended_packet_info = {}
         self.reset()
 
-    def reset(self):
+    def reset(self) -> None:
         self.state = PacketParser.NEED_TYPE
         self.bytes_needed = 1
         self.packet = bytearray()
         self.packet_info = None
 
-    def feed_data(self, data):
+    def feed_data(self, data: bytes) -> None:
         data_offset = 0
         data_left = len(data)
         while data_left and self.bytes_needed:
@@ -118,6 +137,7 @@ class PacketParser:
                     self.state = PacketParser.NEED_LENGTH
                     self.bytes_needed = self.packet_info[0] + self.packet_info[1]
                 elif self.state == PacketParser.NEED_LENGTH:
+                    assert self.packet_info is not None
                     body_length = struct.unpack_from(
                         self.packet_info[2], self.packet, 1 + self.packet_info[1]
                     )[0]
@@ -130,12 +150,12 @@ class PacketParser:
                         try:
                             self.sink.on_packet(bytes(self.packet))
                         except Exception as error:
-                            logger.warning(
+                            logger.exception(
                                 color(f'!!! Exception in on_packet: {error}', 'red')
                             )
                     self.reset()
 
-    def set_packet_sink(self, sink):
+    def set_packet_sink(self, sink: TransportSink) -> None:
         self.sink = sink
 
 
@@ -145,10 +165,10 @@ class PacketReader:
     Reader that reads HCI packets from a sync source.
     """
 
-    def __init__(self, source):
+    def __init__(self, source: io.BufferedReader) -> None:
         self.source = source
 
-    def next_packet(self):
+    def next_packet(self) -> Optional[bytes]:
         # Get the packet type
         packet_type = self.source.read(1)
         if len(packet_type) != 1:
@@ -157,7 +177,7 @@ class PacketReader:
         # Get the packet info based on its type
         packet_info = HCI_PACKET_INFO.get(packet_type[0])
         if packet_info is None:
-            raise ValueError(f'invalid packet type {packet_type} found')
+            raise ValueError(f'invalid packet type {packet_type[0]} found')
 
         # Read the header (that includes the length)
         header_size = packet_info[0] + packet_info[1]
@@ -180,17 +200,17 @@ class AsyncPacketReader:
     Reader that reads HCI packets from an async source.
     """
 
-    def __init__(self, source):
+    def __init__(self, source: asyncio.StreamReader) -> None:
         self.source = source
 
-    async def next_packet(self):
+    async def next_packet(self) -> bytes:
         # Get the packet type
         packet_type = await self.source.readexactly(1)
 
         # Get the packet info based on its type
         packet_info = HCI_PACKET_INFO.get(packet_type[0])
         if packet_info is None:
-            raise ValueError(f'invalid packet type {packet_type} found')
+            raise ValueError(f'invalid packet type {packet_type[0]} found')
 
         # Read the header (that includes the length)
         header_size = packet_info[0] + packet_info[1]
@@ -209,11 +229,11 @@ class AsyncPipeSink:
     Sink that forwards packets asynchronously to another sink.
     """
 
-    def __init__(self, sink):
+    def __init__(self, sink: TransportSink) -> None:
         self.sink = sink
         self.loop = asyncio.get_running_loop()
 
-    def on_packet(self, packet):
+    def on_packet(self, packet: bytes) -> None:
         self.loop.call_soon(self.sink.on_packet, packet)
 
 
@@ -223,50 +243,48 @@ class ParserSource:
     Base class designed to be subclassed by transport-specific source classes
     """
 
-    terminated: asyncio.Future
+    terminated: asyncio.Future[None]
     parser: PacketParser
 
-    def __init__(self):
+    def __init__(self) -> None:
         self.parser = PacketParser()
         self.terminated = asyncio.get_running_loop().create_future()
 
-    def set_packet_sink(self, sink):
+    def set_packet_sink(self, sink: TransportSink) -> None:
         self.parser.set_packet_sink(sink)
 
-    def on_transport_lost(self):
+    def on_transport_lost(self) -> None:
         self.terminated.set_result(None)
         if self.parser.sink:
-            try:
+            if hasattr(self.parser.sink, 'on_transport_lost'):
                 self.parser.sink.on_transport_lost()
-            except AttributeError:
-                pass
 
-    async def wait_for_termination(self):
+    async def wait_for_termination(self) -> None:
         """
         Convenience method for backward compatibility. Prefer using the `terminated`
         attribute instead.
         """
         return await self.terminated
 
-    def close(self):
+    def close(self) -> None:
         pass
 
 
 # -----------------------------------------------------------------------------
 class StreamPacketSource(asyncio.Protocol, ParserSource):
-    def data_received(self, data):
+    def data_received(self, data: bytes) -> None:
         self.parser.feed_data(data)
 
 
 # -----------------------------------------------------------------------------
 class StreamPacketSink:
-    def __init__(self, transport):
+    def __init__(self, transport: asyncio.WriteTransport) -> None:
         self.transport = transport
 
-    def on_packet(self, packet):
+    def on_packet(self, packet: bytes) -> None:
         self.transport.write(packet)
 
-    def close(self):
+    def close(self) -> None:
         self.transport.close()
 
 
@@ -286,7 +304,7 @@ class Transport:
         ...
     """
 
-    def __init__(self, source, sink):
+    def __init__(self, source: TransportSource, sink: TransportSink) -> None:
         self.source = source
         self.sink = sink
 
@@ -300,34 +318,39 @@ class Transport:
         return iter((self.source, self.sink))
 
     async def close(self) -> None:
-        self.source.close()
-        self.sink.close()
+        if hasattr(self.source, 'close'):
+            self.source.close()
+        if hasattr(self.sink, 'close'):
+            self.sink.close()
 
 
 # -----------------------------------------------------------------------------
 class PumpedPacketSource(ParserSource):
-    def __init__(self, receive):
+    pump_task: Optional[asyncio.Task[None]]
+
+    def __init__(self, receive) -> None:
         super().__init__()
         self.receive_function = receive
         self.pump_task = None
 
-    def start(self):
-        async def pump_packets():
+    def start(self) -> None:
+        async def pump_packets() -> None:
             while True:
                 try:
                     packet = await self.receive_function()
                     self.parser.feed_data(packet)
-                except asyncio.exceptions.CancelledError:
+                except asyncio.CancelledError:
                     logger.debug('source pump task done')
+                    self.terminated.set_result(None)
                     break
                 except Exception as error:
                     logger.warning(f'exception while waiting for packet: {error}')
-                    self.terminated.set_result(error)
+                    self.terminated.set_exception(error)
                     break
 
         self.pump_task = asyncio.create_task(pump_packets())
 
-    def close(self):
+    def close(self) -> None:
         if self.pump_task:
             self.pump_task.cancel()
 
@@ -339,7 +362,7 @@ class PumpedPacketSink:
         self.packet_queue = asyncio.Queue()
         self.pump_task = None
 
-    def on_packet(self, packet):
+    def on_packet(self, packet: bytes) -> None:
         self.packet_queue.put_nowait(packet)
 
     def start(self):
@@ -348,7 +371,7 @@ class PumpedPacketSink:
                 try:
                     packet = await self.packet_queue.get()
                     await self.send_function(packet)
-                except asyncio.exceptions.CancelledError:
+                except asyncio.CancelledError:
                     logger.debug('sink pump task done')
                     break
                 except Exception as error:
@@ -364,18 +387,20 @@ class PumpedPacketSink:
 
 # -----------------------------------------------------------------------------
 class PumpedTransport(Transport):
-    def __init__(self, source, sink, close_function):
-        super().__init__(source, sink)
-        self.close_function = close_function
+    source: PumpedPacketSource
+    sink: PumpedPacketSink
 
-    def start(self):
+    def __init__(
+        self,
+        source: PumpedPacketSource,
+        sink: PumpedPacketSink,
+    ) -> None:
+        super().__init__(source, sink)
+
+    def start(self) -> None:
         self.source.start()
         self.sink.start()
 
-    async def close(self):
-        await super().close()
-        await self.close_function()
-
 
 # -----------------------------------------------------------------------------
 class SnoopingTransport(Transport):
@@ -397,31 +422,38 @@ class SnoopingTransport(Transport):
         raise RuntimeError('unexpected code path')  # Satisfy the type checker
 
     class Source:
-        def __init__(self, source, snooper):
+        sink: TransportSink
+
+        def __init__(self, source: TransportSource, snooper: Snooper):
             self.source = source
             self.snooper = snooper
-            self.sink = None
+            self.terminated = source.terminated
 
-        def set_packet_sink(self, sink):
+        def set_packet_sink(self, sink: TransportSink) -> None:
             self.sink = sink
             self.source.set_packet_sink(self)
 
-        def on_packet(self, packet):
+        def on_packet(self, packet: bytes) -> None:
             self.snooper.snoop(packet, Snooper.Direction.CONTROLLER_TO_HOST)
             if self.sink:
                 self.sink.on_packet(packet)
 
     class Sink:
-        def __init__(self, sink, snooper):
+        def __init__(self, sink: TransportSink, snooper: Snooper) -> None:
             self.sink = sink
             self.snooper = snooper
 
-        def on_packet(self, packet):
+        def on_packet(self, packet: bytes) -> None:
             self.snooper.snoop(packet, Snooper.Direction.HOST_TO_CONTROLLER)
             if self.sink:
                 self.sink.on_packet(packet)
 
-    def __init__(self, transport, snooper, close_snooper=None):
+    def __init__(
+        self,
+        transport: Transport,
+        snooper: Snooper,
+        close_snooper=None,
+    ) -> None:
         super().__init__(
             self.Source(transport.source, snooper), self.Sink(transport.sink, snooper)
         )

bumble/transport/file.py

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

bumble/transport/hci_socket.py

@@ -23,6 +23,8 @@ import socket
 import ctypes
 import collections
 
+from typing import Optional
+
 from .common import Transport, ParserSource
 
 
@@ -33,7 +35,7 @@ logger = logging.getLogger(__name__)
 
 
 # -----------------------------------------------------------------------------
-async def open_hci_socket_transport(spec):
+async def open_hci_socket_transport(spec: Optional[str]) -> Transport:
     '''
     Open an HCI Socket (only available on some platforms).
     The parameter string is either empty (to use the first/default Bluetooth adapter)
@@ -45,9 +47,9 @@ async def open_hci_socket_transport(spec):
     # Create a raw HCI socket
     try:
         hci_socket = socket.socket(
-            socket.AF_BLUETOOTH,
-            socket.SOCK_RAW | socket.SOCK_NONBLOCK,
-            socket.BTPROTO_HCI,
+            socket.AF_BLUETOOTH,  # type: ignore[attr-defined]
+            socket.SOCK_RAW | socket.SOCK_NONBLOCK,  # type: ignore[attr-defined]
+            socket.BTPROTO_HCI,  # type: ignore[attr-defined]
         )
     except AttributeError as error:
         # Not supported on this platform
@@ -78,7 +80,7 @@ async def open_hci_socket_transport(spec):
     bind_address = struct.pack(
         # pylint: disable=no-member
         '<HHH',
-        socket.AF_BLUETOOTH,
+        socket.AF_BLUETOOTH,  # type: ignore[attr-defined]
         adapter_index,
         HCI_CHANNEL_USER,
     )

bumble/transport/pty.py

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

bumble/transport/pyusb.py

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

bumble/transport/serial.py

@@ -28,7 +28,7 @@ logger = logging.getLogger(__name__)
 
 
 # -----------------------------------------------------------------------------
-async def open_serial_transport(spec):
+async def open_serial_transport(spec: str) -> Transport:
     '''
     Open a serial port transport.
     The parameter string has this syntax:

bumble/transport/tcp_client.py

@@ -27,7 +27,7 @@ logger = logging.getLogger(__name__)
 
 
 # -----------------------------------------------------------------------------
-async def open_tcp_client_transport(spec):
+async def open_tcp_client_transport(spec: str) -> Transport:
     '''
     Open a TCP client transport.
     The parameter string has this syntax:

bumble/transport/tcp_server.py

@@ -15,6 +15,7 @@
 # -----------------------------------------------------------------------------
 # Imports
 # -----------------------------------------------------------------------------
+from __future__ import annotations
 import asyncio
 import logging
 
@@ -27,7 +28,7 @@ logger = logging.getLogger(__name__)
 
 
 # -----------------------------------------------------------------------------
-async def open_tcp_server_transport(spec):
+async def open_tcp_server_transport(spec: str) -> Transport:
     '''
     Open a TCP server transport.
     The parameter string has this syntax:
@@ -42,7 +43,7 @@ async def open_tcp_server_transport(spec):
         async def close(self):
             await super().close()
 
-    class TcpServerProtocol:
+    class TcpServerProtocol(asyncio.BaseProtocol):
         def __init__(self, packet_source, packet_sink):
             self.packet_source = packet_source
             self.packet_sink = packet_sink

bumble/transport/udp.py

@@ -27,7 +27,7 @@ logger = logging.getLogger(__name__)
 
 
 # -----------------------------------------------------------------------------
-async def open_udp_transport(spec):
+async def open_udp_transport(spec: str) -> Transport:
     '''
     Open a UDP transport.
     The parameter string has this syntax:

bumble/transport/usb.py

@@ -24,9 +24,10 @@ import platform
 
 import usb1
 
-from .common import Transport, ParserSource
-from .. import hci
-from ..colors import color
+from bumble.transport.common import Transport, ParserSource
+from bumble import hci
+from bumble.colors import color
+from bumble.utils import AsyncRunner
 
 
 # -----------------------------------------------------------------------------
@@ -60,7 +61,7 @@ def load_libusb():
             usb1.loadLibrary(libusb_dll)
 
 
-async def open_usb_transport(spec):
+async def open_usb_transport(spec: str) -> Transport:
     '''
     Open a USB transport.
     The moniker string has this syntax:
@@ -113,7 +114,7 @@ async def open_usb_transport(spec):
         def __init__(self, device, acl_out):
             self.device = device
             self.acl_out = acl_out
-            self.transfer = device.getTransfer()
+            self.acl_out_transfer = device.getTransfer()
             self.packets = collections.deque()  # Queue of packets waiting to be sent
             self.loop = asyncio.get_running_loop()
             self.cancel_done = self.loop.create_future()
@@ -137,21 +138,20 @@ async def open_usb_transport(spec):
                 # The queue was previously empty, re-prime the pump
                 self.process_queue()
 
-        def on_packet_sent(self, transfer):
+        def transfer_callback(self, transfer):
             status = transfer.getStatus()
-            # logger.debug(f'<<< USB out transfer callback: status={status}')
 
             # pylint: disable=no-member
             if status == usb1.TRANSFER_COMPLETED:
-                self.loop.call_soon_threadsafe(self.on_packet_sent_)
+                self.loop.call_soon_threadsafe(self.on_packet_sent)
             elif status == usb1.TRANSFER_CANCELLED:
                 self.loop.call_soon_threadsafe(self.cancel_done.set_result, None)
             else:
                 logger.warning(
-                    color(f'!!! out transfer not completed: status={status}', 'red')
+                    color(f'!!! OUT transfer not completed: status={status}', 'red')
                 )
 
-        def on_packet_sent_(self):
+        def on_packet_sent(self):
             if self.packets:
                 self.packets.popleft()
                 self.process_queue()
@@ -163,22 +163,20 @@ async def open_usb_transport(spec):
             packet = self.packets[0]
             packet_type = packet[0]
             if packet_type == hci.HCI_ACL_DATA_PACKET:
-                self.transfer.setBulk(
-                    self.acl_out, packet[1:], callback=self.on_packet_sent
+                self.acl_out_transfer.setBulk(
+                    self.acl_out, packet[1:], callback=self.transfer_callback
                 )
-                logger.debug('submit ACL')
-                self.transfer.submit()
+                self.acl_out_transfer.submit()
             elif packet_type == hci.HCI_COMMAND_PACKET:
-                self.transfer.setControl(
+                self.acl_out_transfer.setControl(
                     USB_RECIPIENT_DEVICE | USB_REQUEST_TYPE_CLASS,
                     0,
                     0,
                     0,
                     packet[1:],
-                    callback=self.on_packet_sent,
+                    callback=self.transfer_callback,
                 )
-                logger.debug('submit COMMAND')
-                self.transfer.submit()
+                self.acl_out_transfer.submit()
             else:
                 logger.warning(color(f'unsupported packet type {packet_type}', 'red'))
 
@@ -193,11 +191,11 @@ async def open_usb_transport(spec):
             self.packets.clear()
 
             # If we have a transfer in flight, cancel it
-            if self.transfer.isSubmitted():
+            if self.acl_out_transfer.isSubmitted():
                 # Try to cancel the transfer, but that may fail because it may have
                 # already completed
                 try:
-                    self.transfer.cancel()
+                    self.acl_out_transfer.cancel()
 
                     logger.debug('waiting for OUT transfer cancellation to be done...')
                     await self.cancel_done
@@ -206,27 +204,22 @@ async def open_usb_transport(spec):
                     logger.debug('OUT transfer likely already completed')
 
     class UsbPacketSource(asyncio.Protocol, ParserSource):
-        def __init__(self, context, device, metadata, acl_in, events_in):
+        def __init__(self, device, metadata, acl_in, events_in):
             super().__init__()
-            self.context = context
             self.device = device
             self.metadata = metadata
             self.acl_in = acl_in
+            self.acl_in_transfer = None
             self.events_in = events_in
+            self.events_in_transfer = None
             self.loop = asyncio.get_running_loop()
             self.queue = asyncio.Queue()
             self.dequeue_task = None
-            self.closed = False
-            self.event_loop_done = self.loop.create_future()
             self.cancel_done = {
                 hci.HCI_EVENT_PACKET: self.loop.create_future(),
                 hci.HCI_ACL_DATA_PACKET: self.loop.create_future(),
             }
-            self.events_in_transfer = None
-            self.acl_in_transfer = None
-
-            # Create a thread to process events
-            self.event_thread = threading.Thread(target=self.run)
+            self.closed = False
 
         def start(self):
             # Set up transfer objects for input
@@ -234,7 +227,7 @@ async def open_usb_transport(spec):
             self.events_in_transfer.setInterrupt(
                 self.events_in,
                 READ_SIZE,
-                callback=self.on_packet_received,
+                callback=self.transfer_callback,
                 user_data=hci.HCI_EVENT_PACKET,
             )
             self.events_in_transfer.submit()
@@ -243,22 +236,23 @@ async def open_usb_transport(spec):
             self.acl_in_transfer.setBulk(
                 self.acl_in,
                 READ_SIZE,
-                callback=self.on_packet_received,
+                callback=self.transfer_callback,
                 user_data=hci.HCI_ACL_DATA_PACKET,
             )
             self.acl_in_transfer.submit()
 
             self.dequeue_task = self.loop.create_task(self.dequeue())
-            self.event_thread.start()
 
-        def on_packet_received(self, transfer):
+        @property
+        def usb_transfer_submitted(self):
+            return (
+                self.events_in_transfer.isSubmitted()
+                or self.acl_in_transfer.isSubmitted()
+            )
+
+        def transfer_callback(self, transfer):
             packet_type = transfer.getUserData()
             status = transfer.getStatus()
-            # logger.debug(
-            #     f'<<< USB IN transfer callback: status={status} '
-            #     f'packet_type={packet_type} '
-            #     f'length={transfer.getActualLength()}'
-            # )
 
             # pylint: disable=no-member
             if status == usb1.TRANSFER_COMPLETED:
@@ -267,18 +261,18 @@ async def open_usb_transport(spec):
                     + transfer.getBuffer()[: transfer.getActualLength()]
                 )
                 self.loop.call_soon_threadsafe(self.queue.put_nowait, packet)
+
+                # Re-submit the transfer so we can receive more data
+                transfer.submit()
             elif status == usb1.TRANSFER_CANCELLED:
                 self.loop.call_soon_threadsafe(
                     self.cancel_done[packet_type].set_result, None
                 )
-                return
             else:
                 logger.warning(
-                    color(f'!!! transfer not completed: status={status}', 'red')
+                    color(f'!!! IN transfer not completed: status={status}', 'red')
                 )
-
-            # Re-submit the transfer so we can receive more data
-            transfer.submit()
+                self.loop.call_soon_threadsafe(self.on_transport_lost)
 
         async def dequeue(self):
             while not self.closed:
@@ -288,21 +282,6 @@ async def open_usb_transport(spec):
                     return
                 self.parser.feed_data(packet)
 
-        def run(self):
-            logger.debug('starting USB event loop')
-            while (
-                self.events_in_transfer.isSubmitted()
-                or self.acl_in_transfer.isSubmitted()
-            ):
-                # pylint: disable=no-member
-                try:
-                    self.context.handleEvents()
-                except usb1.USBErrorInterrupted:
-                    pass
-
-            logger.debug('USB event loop done')
-            self.loop.call_soon_threadsafe(self.event_loop_done.set_result, None)
-
         def close(self):
             self.closed = True
 
@@ -331,15 +310,14 @@ async def open_usb_transport(spec):
                             f'IN[{packet_type}] transfer likely already completed'
                         )
 
-            # Wait for the thread to terminate
-            await self.event_loop_done
-
     class UsbTransport(Transport):
         def __init__(self, context, device, interface, setting, source, sink):
             super().__init__(source, sink)
             self.context = context
             self.device = device
             self.interface = interface
+            self.loop = asyncio.get_running_loop()
+            self.event_loop_done = self.loop.create_future()
 
             # Get exclusive access
             device.claimInterface(interface)
@@ -352,6 +330,22 @@ async def open_usb_transport(spec):
             source.start()
             sink.start()
 
+            # Create a thread to process events
+            self.event_thread = threading.Thread(target=self.run)
+            self.event_thread.start()
+
+        def run(self):
+            logger.debug('starting USB event loop')
+            while self.source.usb_transfer_submitted:
+                # pylint: disable=no-member
+                try:
+                    self.context.handleEvents()
+                except usb1.USBErrorInterrupted:
+                    pass
+
+            logger.debug('USB event loop done')
+            self.loop.call_soon_threadsafe(self.event_loop_done.set_result, None)
+
         async def close(self):
             self.source.close()
             self.sink.close()
@@ -361,6 +355,9 @@ async def open_usb_transport(spec):
             self.device.close()
             self.context.close()
 
+            # Wait for the thread to terminate
+            await self.event_loop_done
+
     # Find the device according to the spec moniker
     load_libusb()
     context = usb1.USBContext()
@@ -540,7 +537,7 @@ async def open_usb_transport(spec):
             except usb1.USBError:
                 logger.warning('failed to set configuration')
 
-        source = UsbPacketSource(context, device, device_metadata, acl_in, events_in)
+        source = UsbPacketSource(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:

bumble/transport/vhci.py

@@ -17,6 +17,9 @@
 # -----------------------------------------------------------------------------
 import logging
 
+from typing import Optional
+
+from .common import Transport
 from .file import open_file_transport
 
 # -----------------------------------------------------------------------------
@@ -26,7 +29,7 @@ logger = logging.getLogger(__name__)
 
 
 # -----------------------------------------------------------------------------
-async def open_vhci_transport(spec):
+async def open_vhci_transport(spec: Optional[str]) -> Transport:
     '''
     Open a VHCI transport (only available on some platforms).
     The parameter string is either empty (to use the default VHCI device
@@ -42,15 +45,15 @@ async def open_vhci_transport(spec):
     # Override the source's `data_received` method so that we can
     # filter out the vendor packet that is received just after the
     # initial open
-    def vhci_data_received(data):
+    def vhci_data_received(data: bytes) -> None:
         if len(data) > 0 and data[0] == HCI_VENDOR_PKT:
             if len(data) == 4:
                 hci_index = data[2] << 8 | data[3]
                 logger.info(f'HCI index {hci_index}')
         else:
-            transport.source.parser.feed_data(data)
+            transport.source.parser.feed_data(data)  # type: ignore
 
-    transport.source.data_received = vhci_data_received
+    transport.source.data_received = vhci_data_received  # type: ignore
 
     # Write the initial config
     transport.sink.on_packet(bytes([HCI_VENDOR_PKT, HCI_BREDR]))

bumble/transport/ws_client.py

@@ -16,9 +16,9 @@
 # Imports
 # -----------------------------------------------------------------------------
 import logging
-import websockets
+import websockets.client
 
-from .common import PumpedPacketSource, PumpedPacketSink, PumpedTransport
+from .common import PumpedPacketSource, PumpedPacketSink, PumpedTransport, Transport
 
 # -----------------------------------------------------------------------------
 # Logging
@@ -27,23 +27,25 @@ logger = logging.getLogger(__name__)
 
 
 # -----------------------------------------------------------------------------
-async def open_ws_client_transport(spec):
+async def open_ws_client_transport(spec: str) -> Transport:
     '''
     Open a WebSocket client transport.
     The parameter string has this syntax:
-    <remote-host>:<remote-port>
+    <websocket-url>
 
-    Example: 127.0.0.1:9001
+    Example: ws://localhost:7681/v1/websocket/bt
     '''
 
-    remote_host, remote_port = spec.split(':')
-    uri = f'ws://{remote_host}:{remote_port}'
-    websocket = await websockets.connect(uri)
+    websocket = await websockets.client.connect(spec)
 
-    transport = PumpedTransport(
+    class WsTransport(PumpedTransport):
+        async def close(self):
+            await super().close()
+            await websocket.close()
+
+    transport = WsTransport(
         PumpedPacketSource(websocket.recv),
         PumpedPacketSink(websocket.send),
-        websocket.close,
     )
     transport.start()
     return transport

bumble/transport/ws_server.py

@@ -15,7 +15,6 @@
 # -----------------------------------------------------------------------------
 # Imports
 # -----------------------------------------------------------------------------
-import asyncio
 import logging
 import websockets
 
@@ -28,7 +27,7 @@ logger = logging.getLogger(__name__)
 
 
 # -----------------------------------------------------------------------------
-async def open_ws_server_transport(spec):
+async def open_ws_server_transport(spec: str) -> Transport:
     '''
     Open a WebSocket server transport.
     The parameter string has this syntax:

bumble/utils.py

@@ -15,13 +15,26 @@
 # -----------------------------------------------------------------------------
 # Imports
 # -----------------------------------------------------------------------------
+from __future__ import annotations
 import asyncio
 import logging
 import traceback
 import collections
 import sys
-from typing import Awaitable, Set, TypeVar
-from functools import wraps
+import warnings
+from typing import (
+    Awaitable,
+    Set,
+    TypeVar,
+    List,
+    Tuple,
+    Callable,
+    Any,
+    Optional,
+    Union,
+    overload,
+)
+from functools import wraps, partial
 from pyee import EventEmitter
 
 from .colors import color
@@ -64,6 +77,102 @@ def composite_listener(cls):
     return cls
 
 
+# -----------------------------------------------------------------------------
+_Handler = TypeVar('_Handler', bound=Callable)
+
+
+class EventWatcher:
+    '''A wrapper class to control the lifecycle of event handlers better.
+
+    Usage:
+    ```
+    watcher = EventWatcher()
+
+    def on_foo():
+        ...
+    watcher.on(emitter, 'foo', on_foo)
+
+    @watcher.on(emitter, 'bar')
+    def on_bar():
+        ...
+
+    # Close all event handlers watching through this watcher
+    watcher.close()
+    ```
+
+    As context:
+    ```
+    with contextlib.closing(EventWatcher()) as context:
+        @context.on(emitter, 'foo')
+        def on_foo():
+            ...
+    # on_foo() has been removed here!
+    ```
+    '''
+
+    handlers: List[Tuple[EventEmitter, str, Callable[..., Any]]]
+
+    def __init__(self) -> None:
+        self.handlers = []
+
+    @overload
+    def on(self, emitter: EventEmitter, event: str) -> Callable[[_Handler], _Handler]:
+        ...
+
+    @overload
+    def on(self, emitter: EventEmitter, event: str, handler: _Handler) -> _Handler:
+        ...
+
+    def on(
+        self, emitter: EventEmitter, event: str, handler: Optional[_Handler] = None
+    ) -> Union[_Handler, Callable[[_Handler], _Handler]]:
+        '''Watch an event until the context is closed.
+
+        Args:
+            emitter: EventEmitter to watch
+            event: Event name
+            handler: (Optional) Event handler. When nothing is passed, this method works as a decorator.
+        '''
+
+        def wrapper(f: _Handler) -> _Handler:
+            self.handlers.append((emitter, event, f))
+            emitter.on(event, f)
+            return f
+
+        return wrapper if handler is None else wrapper(handler)
+
+    @overload
+    def once(self, emitter: EventEmitter, event: str) -> Callable[[_Handler], _Handler]:
+        ...
+
+    @overload
+    def once(self, emitter: EventEmitter, event: str, handler: _Handler) -> _Handler:
+        ...
+
+    def once(
+        self, emitter: EventEmitter, event: str, handler: Optional[_Handler] = None
+    ) -> Union[_Handler, Callable[[_Handler], _Handler]]:
+        '''Watch an event for once.
+
+        Args:
+            emitter: EventEmitter to watch
+            event: Event name
+            handler: (Optional) Event handler. When nothing passed, this method works as a decorator.
+        '''
+
+        def wrapper(f: _Handler) -> _Handler:
+            self.handlers.append((emitter, event, f))
+            emitter.once(event, f)
+            return f
+
+        return wrapper if handler is None else wrapper(handler)
+
+    def close(self) -> None:
+        for emitter, event, handler in self.handlers:
+            if handler in emitter.listeners(event):
+                emitter.remove_listener(event, handler)
+
+
 # -----------------------------------------------------------------------------
 _T = TypeVar('_T')
 
@@ -302,3 +411,52 @@ class FlowControlAsyncPipe:
                     self.resume_source()
 
             self.check_pump()
+
+
+async def async_call(function, *args, **kwargs):
+    """
+    Immediately calls the function with provided args and kwargs, wrapping it in an async function.
+    Rust's `pyo3_asyncio` library needs functions to be marked async to properly inject a running loop.
+
+    result = await async_call(some_function, ...)
+    """
+    return function(*args, **kwargs)
+
+
+def wrap_async(function):
+    """
+    Wraps the provided function in an async function.
+    """
+    return partial(async_call, function)
+
+
+def deprecated(msg: str):
+    """
+    Throw deprecation warning before execution.
+    """
+
+    def wrapper(function):
+        @wraps(function)
+        def inner(*args, **kwargs):
+            warnings.warn(msg, DeprecationWarning)
+            return function(*args, **kwargs)
+
+        return inner
+
+    return wrapper
+
+
+def experimental(msg: str):
+    """
+    Throws a future warning before execution.
+    """
+
+    def wrapper(function):
+        @wraps(function)
+        def inner(*args, **kwargs):
+            warnings.warn(msg, FutureWarning)
+            return function(*args, **kwargs)
+
+        return inner
+
+    return wrapper

bumble/vendor/android/hci.py

@@ -0,0 +1,318 @@
+# 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 struct
+
+from bumble.hci import (
+    name_or_number,
+    hci_vendor_command_op_code,
+    Address,
+    HCI_Constant,
+    HCI_Object,
+    HCI_Command,
+    HCI_Vendor_Event,
+    STATUS_SPEC,
+)
+
+
+# -----------------------------------------------------------------------------
+# Constants
+# -----------------------------------------------------------------------------
+
+# Android Vendor Specific Commands and Events.
+# Only a subset of the commands are implemented here currently.
+#
+# pylint: disable-next=line-too-long
+# See https://source.android.com/docs/core/connect/bluetooth/hci_requirements#chip-capabilities-and-configuration
+HCI_LE_GET_VENDOR_CAPABILITIES_COMMAND = hci_vendor_command_op_code(0x153)
+HCI_LE_APCF_COMMAND = hci_vendor_command_op_code(0x157)
+HCI_GET_CONTROLLER_ACTIVITY_ENERGY_INFO_COMMAND = hci_vendor_command_op_code(0x159)
+HCI_A2DP_HARDWARE_OFFLOAD_COMMAND = hci_vendor_command_op_code(0x15D)
+HCI_BLUETOOTH_QUALITY_REPORT_COMMAND = hci_vendor_command_op_code(0x15E)
+HCI_DYNAMIC_AUDIO_BUFFER_COMMAND = hci_vendor_command_op_code(0x15F)
+
+HCI_BLUETOOTH_QUALITY_REPORT_EVENT = 0x58
+
+HCI_Command.register_commands(globals())
+HCI_Vendor_Event.register_subevents(globals())
+
+
+# -----------------------------------------------------------------------------
+@HCI_Command.command(
+    return_parameters_fields=[
+        ('status', STATUS_SPEC),
+        ('max_advt_instances', 1),
+        ('offloaded_resolution_of_private_address', 1),
+        ('total_scan_results_storage', 2),
+        ('max_irk_list_sz', 1),
+        ('filtering_support', 1),
+        ('max_filter', 1),
+        ('activity_energy_info_support', 1),
+        ('version_supported', 2),
+        ('total_num_of_advt_tracked', 2),
+        ('extended_scan_support', 1),
+        ('debug_logging_supported', 1),
+        ('le_address_generation_offloading_support', 1),
+        ('a2dp_source_offload_capability_mask', 4),
+        ('bluetooth_quality_report_support', 1),
+        ('dynamic_audio_buffer_support', 4),
+    ]
+)
+class HCI_LE_Get_Vendor_Capabilities_Command(HCI_Command):
+    # pylint: disable=line-too-long
+    '''
+    See https://source.android.com/docs/core/connect/bluetooth/hci_requirements#vendor-specific-capabilities
+    '''
+
+    @classmethod
+    def parse_return_parameters(cls, parameters):
+        # There are many versions of this data structure, so we need to parse until
+        # there are no more bytes to parse, and leave un-signal parameters set to
+        # None (older versions)
+        nones = {field: None for field, _ in cls.return_parameters_fields}
+        return_parameters = HCI_Object(cls.return_parameters_fields, **nones)
+
+        try:
+            offset = 0
+            for field in cls.return_parameters_fields:
+                field_name, field_type = field
+                field_value, field_size = HCI_Object.parse_field(
+                    parameters, offset, field_type
+                )
+                setattr(return_parameters, field_name, field_value)
+                offset += field_size
+        except struct.error:
+            pass
+
+        return return_parameters
+
+
+# -----------------------------------------------------------------------------
+@HCI_Command.command(
+    fields=[
+        (
+            'opcode',
+            {
+                'size': 1,
+                'mapper': lambda x: HCI_LE_APCF_Command.opcode_name(x),
+            },
+        ),
+        ('payload', '*'),
+    ],
+    return_parameters_fields=[
+        ('status', STATUS_SPEC),
+        (
+            'opcode',
+            {
+                'size': 1,
+                'mapper': lambda x: HCI_LE_APCF_Command.opcode_name(x),
+            },
+        ),
+        ('payload', '*'),
+    ],
+)
+class HCI_LE_APCF_Command(HCI_Command):
+    # pylint: disable=line-too-long
+    '''
+    See https://source.android.com/docs/core/connect/bluetooth/hci_requirements#le_apcf_command
+
+    NOTE: the subcommand-specific payloads are left as opaque byte arrays in this
+    implementation. A future enhancement may define subcommand-specific data structures.
+    '''
+
+    # APCF Subcommands
+    # TODO: use the OpenIntEnum class (when upcoming PR is merged)
+    APCF_ENABLE = 0x00
+    APCF_SET_FILTERING_PARAMETERS = 0x01
+    APCF_BROADCASTER_ADDRESS = 0x02
+    APCF_SERVICE_UUID = 0x03
+    APCF_SERVICE_SOLICITATION_UUID = 0x04
+    APCF_LOCAL_NAME = 0x05
+    APCF_MANUFACTURER_DATA = 0x06
+    APCF_SERVICE_DATA = 0x07
+    APCF_TRANSPORT_DISCOVERY_SERVICE = 0x08
+    APCF_AD_TYPE_FILTER = 0x09
+    APCF_READ_EXTENDED_FEATURES = 0xFF
+
+    OPCODE_NAMES = {
+        APCF_ENABLE: 'APCF_ENABLE',
+        APCF_SET_FILTERING_PARAMETERS: 'APCF_SET_FILTERING_PARAMETERS',
+        APCF_BROADCASTER_ADDRESS: 'APCF_BROADCASTER_ADDRESS',
+        APCF_SERVICE_UUID: 'APCF_SERVICE_UUID',
+        APCF_SERVICE_SOLICITATION_UUID: 'APCF_SERVICE_SOLICITATION_UUID',
+        APCF_LOCAL_NAME: 'APCF_LOCAL_NAME',
+        APCF_MANUFACTURER_DATA: 'APCF_MANUFACTURER_DATA',
+        APCF_SERVICE_DATA: 'APCF_SERVICE_DATA',
+        APCF_TRANSPORT_DISCOVERY_SERVICE: 'APCF_TRANSPORT_DISCOVERY_SERVICE',
+        APCF_AD_TYPE_FILTER: 'APCF_AD_TYPE_FILTER',
+        APCF_READ_EXTENDED_FEATURES: 'APCF_READ_EXTENDED_FEATURES',
+    }
+
+    @classmethod
+    def opcode_name(cls, opcode):
+        return name_or_number(cls.OPCODE_NAMES, opcode)
+
+
+# -----------------------------------------------------------------------------
+@HCI_Command.command(
+    return_parameters_fields=[
+        ('status', STATUS_SPEC),
+        ('total_tx_time_ms', 4),
+        ('total_rx_time_ms', 4),
+        ('total_idle_time_ms', 4),
+        ('total_energy_used', 4),
+    ],
+)
+class HCI_Get_Controller_Activity_Energy_Info_Command(HCI_Command):
+    # pylint: disable=line-too-long
+    '''
+    See https://source.android.com/docs/core/connect/bluetooth/hci_requirements#le_get_controller_activity_energy_info
+    '''
+
+
+# -----------------------------------------------------------------------------
+@HCI_Command.command(
+    fields=[
+        (
+            'opcode',
+            {
+                'size': 1,
+                'mapper': lambda x: HCI_A2DP_Hardware_Offload_Command.opcode_name(x),
+            },
+        ),
+        ('payload', '*'),
+    ],
+    return_parameters_fields=[
+        ('status', STATUS_SPEC),
+        (
+            'opcode',
+            {
+                'size': 1,
+                'mapper': lambda x: HCI_A2DP_Hardware_Offload_Command.opcode_name(x),
+            },
+        ),
+        ('payload', '*'),
+    ],
+)
+class HCI_A2DP_Hardware_Offload_Command(HCI_Command):
+    # pylint: disable=line-too-long
+    '''
+    See https://source.android.com/docs/core/connect/bluetooth/hci_requirements#a2dp-hardware-offload-support
+
+    NOTE: the subcommand-specific payloads are left as opaque byte arrays in this
+    implementation. A future enhancement may define subcommand-specific data structures.
+    '''
+
+    # A2DP Hardware Offload Subcommands
+    # TODO: use the OpenIntEnum class (when upcoming PR is merged)
+    START_A2DP_OFFLOAD = 0x01
+    STOP_A2DP_OFFLOAD = 0x02
+
+    OPCODE_NAMES = {
+        START_A2DP_OFFLOAD: 'START_A2DP_OFFLOAD',
+        STOP_A2DP_OFFLOAD: 'STOP_A2DP_OFFLOAD',
+    }
+
+    @classmethod
+    def opcode_name(cls, opcode):
+        return name_or_number(cls.OPCODE_NAMES, opcode)
+
+
+# -----------------------------------------------------------------------------
+@HCI_Command.command(
+    fields=[
+        (
+            'opcode',
+            {
+                'size': 1,
+                'mapper': lambda x: HCI_Dynamic_Audio_Buffer_Command.opcode_name(x),
+            },
+        ),
+        ('payload', '*'),
+    ],
+    return_parameters_fields=[
+        ('status', STATUS_SPEC),
+        (
+            'opcode',
+            {
+                'size': 1,
+                'mapper': lambda x: HCI_Dynamic_Audio_Buffer_Command.opcode_name(x),
+            },
+        ),
+        ('payload', '*'),
+    ],
+)
+class HCI_Dynamic_Audio_Buffer_Command(HCI_Command):
+    # pylint: disable=line-too-long
+    '''
+    See https://source.android.com/docs/core/connect/bluetooth/hci_requirements#dynamic-audio-buffer-command
+
+    NOTE: the subcommand-specific payloads are left as opaque byte arrays in this
+    implementation. A future enhancement may define subcommand-specific data structures.
+    '''
+
+    # Dynamic Audio Buffer Subcommands
+    # TODO: use the OpenIntEnum class (when upcoming PR is merged)
+    GET_AUDIO_BUFFER_TIME_CAPABILITY = 0x01
+
+    OPCODE_NAMES = {
+        GET_AUDIO_BUFFER_TIME_CAPABILITY: 'GET_AUDIO_BUFFER_TIME_CAPABILITY',
+    }
+
+    @classmethod
+    def opcode_name(cls, opcode):
+        return name_or_number(cls.OPCODE_NAMES, opcode)
+
+
+# -----------------------------------------------------------------------------
+@HCI_Vendor_Event.event(
+    fields=[
+        ('quality_report_id', 1),
+        ('packet_types', 1),
+        ('connection_handle', 2),
+        ('connection_role', {'size': 1, 'mapper': HCI_Constant.role_name}),
+        ('tx_power_level', -1),
+        ('rssi', -1),
+        ('snr', 1),
+        ('unused_afh_channel_count', 1),
+        ('afh_select_unideal_channel_count', 1),
+        ('lsto', 2),
+        ('connection_piconet_clock', 4),
+        ('retransmission_count', 4),
+        ('no_rx_count', 4),
+        ('nak_count', 4),
+        ('last_tx_ack_timestamp', 4),
+        ('flow_off_count', 4),
+        ('last_flow_on_timestamp', 4),
+        ('buffer_overflow_bytes', 4),
+        ('buffer_underflow_bytes', 4),
+        ('bdaddr', Address.parse_address),
+        ('cal_failed_item_count', 1),
+        ('tx_total_packets', 4),
+        ('tx_unacked_packets', 4),
+        ('tx_flushed_packets', 4),
+        ('tx_last_subevent_packets', 4),
+        ('crc_error_packets', 4),
+        ('rx_duplicate_packets', 4),
+        ('vendor_specific_parameters', '*'),
+    ]
+)
+class HCI_Bluetooth_Quality_Report_Event(HCI_Vendor_Event):
+    # pylint: disable=line-too-long
+    '''
+    See https://source.android.com/docs/core/connect/bluetooth/hci_requirements#bluetooth-quality-report-sub-event
+    '''

bumble/vendor/zephyr/hci.py

@@ -0,0 +1,88 @@
+# Copyright 2021-2023 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# -----------------------------------------------------------------------------
+# Imports
+# -----------------------------------------------------------------------------
+from bumble.hci import (
+    hci_vendor_command_op_code,
+    HCI_Command,
+    STATUS_SPEC,
+)
+
+
+# -----------------------------------------------------------------------------
+# Constants
+# -----------------------------------------------------------------------------
+
+# Zephyr RTOS Vendor Specific Commands and Events.
+# Only a subset of the commands are implemented here currently.
+#
+# pylint: disable-next=line-too-long
+# See https://github.com/zephyrproject-rtos/zephyr/blob/main/include/zephyr/bluetooth/hci_vs.h
+HCI_WRITE_TX_POWER_LEVEL_COMMAND = hci_vendor_command_op_code(0x000E)
+HCI_READ_TX_POWER_LEVEL_COMMAND = hci_vendor_command_op_code(0x000F)
+
+HCI_Command.register_commands(globals())
+
+
+# -----------------------------------------------------------------------------
+class TX_Power_Level_Command:
+    '''
+    Base class for read and write TX power level HCI commands
+    '''
+
+    TX_POWER_HANDLE_TYPE_ADV = 0x00
+    TX_POWER_HANDLE_TYPE_SCAN = 0x01
+    TX_POWER_HANDLE_TYPE_CONN = 0x02
+
+
+# -----------------------------------------------------------------------------
+@HCI_Command.command(
+    fields=[('handle_type', 1), ('connection_handle', 2), ('tx_power_level', -1)],
+    return_parameters_fields=[
+        ('status', STATUS_SPEC),
+        ('handle_type', 1),
+        ('connection_handle', 2),
+        ('selected_tx_power_level', -1),
+    ],
+)
+class HCI_Write_Tx_Power_Level_Command(HCI_Command, TX_Power_Level_Command):
+    '''
+    Write TX power level. See BT_HCI_OP_VS_WRITE_TX_POWER_LEVEL in
+    https://github.com/zephyrproject-rtos/zephyr/blob/main/include/zephyr/bluetooth/hci_vs.h
+
+    Power level is in dB. Connection handle for TX_POWER_HANDLE_TYPE_ADV and
+    TX_POWER_HANDLE_TYPE_SCAN should be zero.
+    '''
+
+
+# -----------------------------------------------------------------------------
+@HCI_Command.command(
+    fields=[('handle_type', 1), ('connection_handle', 2)],
+    return_parameters_fields=[
+        ('status', STATUS_SPEC),
+        ('handle_type', 1),
+        ('connection_handle', 2),
+        ('tx_power_level', -1),
+    ],
+)
+class HCI_Read_Tx_Power_Level_Command(HCI_Command, TX_Power_Level_Command):
+    '''
+    Read TX power level. See BT_HCI_OP_VS_READ_TX_POWER_LEVEL in
+    https://github.com/zephyrproject-rtos/zephyr/blob/main/include/zephyr/bluetooth/hci_vs.h
+
+    Power level is in dB. Connection handle for TX_POWER_HANDLE_TYPE_ADV and
+    TX_POWER_HANDLE_TYPE_SCAN should be zero.
+    '''

docs/mkdocs/mkdocs.yml

@@ -10,7 +10,7 @@ nav:
     - Contributing: development/contributing.md
     - Code Style: development/code_style.md
   - Use Cases:
-    - Overview: use_cases/index.md
+    - use_cases/index.md
     - Use Case 1: use_cases/use_case_1.md
     - Use Case 2: use_cases/use_case_2.md
     - Use Case 3: use_cases/use_case_3.md
@@ -23,7 +23,7 @@ nav:
     - GATT: components/gatt.md
     - Security Manager: components/security_manager.md
   - Transports:
-    - Overview: transports/index.md
+    - transports/index.md
     - Serial: transports/serial.md
     - USB: transports/usb.md
     - PTY: transports/pty.md
@@ -37,14 +37,14 @@ nav:
     - Android Emulator: transports/android_emulator.md
     - File: transports/file.md
   - Drivers:
-    - Overview: drivers/index.md
+    - drivers/index.md
     - Realtek: drivers/realtek.md
   - API:
     - Guide: api/guide.md
     - Examples: api/examples.md
     - Reference: api/reference.md
   - Apps & Tools:
-    - Overview: apps_and_tools/index.md
+    - apps_and_tools/index.md
     - Console: apps_and_tools/console.md
     - Bench: apps_and_tools/bench.md
     - Speaker: apps_and_tools/speaker.md
@@ -57,15 +57,25 @@ nav:
     - USB Probe: apps_and_tools/usb_probe.md
     - Link Relay: apps_and_tools/link_relay.md
   - Hardware:
-    - Overview: hardware/index.md
+    - hardware/index.md
   - Platforms:
-    - Overview: platforms/index.md
+    - platforms/index.md
     - macOS: platforms/macos.md
     - Linux: platforms/linux.md
     - Windows: platforms/windows.md
     - Android: platforms/android.md
+    - Zephyr: platforms/zephyr.md
   - Examples:
-    - Overview: examples/index.md
+    - examples/index.md
+  - Extras:
+    - extras/index.md
+    - Android Remote HCI: extras/android_remote_hci.md
+    - Android BT Bench: extras/android_bt_bench.md
+  - Hive:
+    - hive/index.md
+    - Speaker: hive/web/speaker/speaker.html
+    - Scanner: hive/web/scanner/scanner.html
+    - Heart Rate Monitor: hive/web/heart_rate_monitor/heart_rate_monitor.html
 
 copyright: Copyright 2021-2023 Google LLC
 
@@ -74,6 +84,8 @@ theme:
   logo: 'images/logo.png'
   favicon: 'images/favicon.ico'
   custom_dir: 'theme'
+  features:
+    - navigation.indexes
 
 plugins:
   - mkdocstrings:
@@ -98,6 +110,8 @@ markdown_extensions:
   - pymdownx.emoji:
       emoji_index: !!python/name:materialx.emoji.twemoji
       emoji_generator: !!python/name:materialx.emoji.to_svg
+  - pymdownx.tabbed:
+      alternate_style: true
   - codehilite:
       guess_lang: false
   - toc:

docs/mkdocs/src/extras/android_bt_bench.md

@@ -0,0 +1,64 @@
+ANDROID BENCH APP
+=================
+
+This Android app that is compatible with the Bumble `bench` command line app.
+This app can be used to test the throughput and latency between two Android
+devices, or between an Android device and another device running the Bumble
+`bench` app.
+Only the RFComm Client, RFComm Server, L2CAP Client and L2CAP Server modes are
+supported.
+
+Building
+--------
+
+You can build the app by running `./gradlew build` (use `gradlew.bat` on Windows) from the `BtBench` top level directory.
+You can also build with Android Studio: open the `BtBench` project. You can build and/or debug from there.
+
+If the build succeeds, you can find the app APKs (debug and release) at:
+
+  * [Release] ``app/build/outputs/apk/release/app-release-unsigned.apk``
+  * [Debug] ``app/build/outputs/apk/debug/app-debug.apk``
+
+
+Running
+-------
+
+### Starting the app
+You can start the app from the Android launcher, from Android Studio, or with `adb`
+
+#### Launching from the launcher
+Just tap the app icon on the launcher, check the parameters, and tap
+one of the benchmark action buttons.
+
+#### Launching with `adb`
+Using the `am` command, you can start the activity, and pass it arguments so that you can
+automatically start the benchmark test, and/or set the parameters.
+
+| Parameter Name         | Parameter Type | Description
+|------------------------|----------------|------------
+| autostart              | String         | Benchmark to start. (rfcomm-client, rfcomm-server, l2cap-client or l2cap-server)
+| packet-count           | Integer        | Number of packets to send (rfcomm-client and l2cap-client only)
+| packet-size            | Integer        | Number of bytes per packet (rfcomm-client and l2cap-client only)
+| peer-bluetooth-address | Integer        | Peer Bluetooth address to connect to (rfcomm-client and l2cap-client | only)
+
+
+!!! tip "Launching from adb with auto-start"
+    In this example, we auto-start the Rfcomm Server bench action.
+    ```bash
+    $ adb shell am start -n com.github.google.bumble.btbench/.MainActivity --es autostart rfcomm-server
+    ```
+
+!!! tip "Launching from adb with auto-start and some parameters"
+    In this example, we auto-start the Rfcomm Client bench action, set the packet count to 100,
+    and the packet size to 1024, and connect to DA:4C:10:DE:17:02
+    ```bash
+    $ adb shell am start -n com.github.google.bumble.btbench/.MainActivity --es autostart rfcomm-client --ei packet-count 100 --ei packet-size 1024 --es peer-bluetooth-address DA:4C:10:DE:17:02
+    ```
+
+#### Selecting a Peer Bluetooth Address
+The app's main activity has a "Peer Bluetooth Address" setting where you can change the address.
+
+!!! note "Bluetooth Address for L2CAP vs RFComm"
+    For BLE (L2CAP mode), the address of a device typically changes regularly (it is randomized for privacy), whereas the Bluetooth Classic addresses will remain the same (RFComm mode).
+    If two devices are paired and bonded, then they will each "see" a non-changing address for each other even with BLE (Resolvable Private Address)
+

docs/mkdocs/src/extras/android_remote_hci.md

@@ -0,0 +1,141 @@
+ANDROID REMOTE HCI APP
+======================
+
+This application allows using an android phone's built-in Bluetooth controller with 
+a Bumble host stack running outside the phone (typically a development laptop or desktop).
+The app runs an HCI proxy between a TCP socket on the "outside" and the Bluetooth HCI HAL
+on the "inside". (See [this page](https://source.android.com/docs/core/connect/bluetooth) for a high level 
+description of the Android Bluetooth HCI HAL).
+The HCI packets received on the TCP socket are forwarded to the phone's controller, and the 
+packets coming from the controller are forwarded to the TCP socket.
+
+
+Building
+--------
+
+You can build the app by running `./gradlew build` (use `gradlew.bat` on Windows) from the `RemoteHCI` top level directory.
+You can also build with Android Studio: open the `RemoteHCI` project. You can build and/or debug from there.
+
+If the build succeeds, you can find the app APKs (debug and release) at:
+
+  * [Release] ``app/build/outputs/apk/release/app-release-unsigned.apk``
+  * [Debug] ``app/build/outputs/apk/debug/app-debug.apk``
+
+
+Running
+-------
+
+### Preconditions
+When the proxy starts (tapping the "Start" button in the app's main activity), it will try to 
+bind to the Bluetooth HAL. This requires disabling SELinux temporarily, and being the only HAL client.
+
+#### Disabling SELinux
+Binding to the Bluetooth HCI HAL requires certain SELinux permissions that can't simply be changed
+on a device without rebuilding its system image. To bypass these restrictions, you will need
+to disable SELinux on your phone (please be aware that this is global, not just for the proxy app,
+so proceed with caution).
+In order to disable SELinux, you need to root the phone (it may be advisable to do this on a
+development phone).
+
+!!! tip "Disabling SELinux Temporarily"
+    Restart `adb` as root:
+    ```bash
+    $ adb root
+    ```
+
+    Then disable SELinux
+    ```bash
+    $ adb shell setenforce 0
+    ```
+
+    Once you're done using the proxy, you can restore SELinux, if you need to, with
+    ```bash
+    $ adb shell setenforce 1
+    ```
+
+    This state will also reset to the normal SELinux enforcement when you reboot.
+
+#### Stopping the bluetooth process
+Since the Bluetooth HAL service can only accept one client, and that in normal conditions 
+that client is the Android's bluetooth stack, it is required to first shut down the 
+Android bluetooth stack process.
+
+!!! tip "Checking if the Bluetooth process is running"
+    ```bash
+    $ adb shell "ps -A | grep com.google.android.bluetooth"
+    ```
+    If the process is running, you will get a line like:
+    ```
+    bluetooth 10759 876 17455796 136620 do_epoll_wait 0 S com.google.android.bluetooth
+    ```
+    If you don't, it means that the process is not running and you are clear to proceed.
+
+Simply turning Bluetooth off from the phone's settings does not ensure that the bluetooth process will exit.
+If the bluetooth process is still running after toggling Bluetooth off from the settings, you may try enabling
+Airplane Mode, then rebooting. The bluetooth process should, in theory, not restart after the reboot.
+
+!!! tip "Stopping the bluetooth process with adb"
+    ```bash
+    $ adb shell cmd bluetooth_manager disable
+    ```
+
+### Starting the app
+You can start the app from the Android launcher, from Android Studio, or with `adb`
+
+#### Launching from the launcher
+Just tap the app icon on the launcher, check the TCP port that is configured, and tap
+the "Start" button.
+
+#### Launching with `adb`
+Using the `am` command, you can start the activity, and pass it arguments so that you can
+automatically start the proxy, and/or set the port number.
+
+!!! tip "Launching from adb with auto-start"
+    ```bash
+    $ adb shell am start -n com.github.google.bumble.remotehci/.MainActivity --ez autostart true
+    ```
+
+!!! tip "Launching from adb with auto-start and a port"
+    In this example, we auto-start the proxy upon launch, with the port set to 9995
+    ```bash
+    $ adb shell am start -n com.github.google.bumble.remotehci/.MainActivity --ez autostart true --ei port 9995
+    ```
+
+#### Selecting a TCP port
+The RemoteHCI app's main activity has a "TCP Port" setting where you can change the port on
+which the proxy is accepting connections. If the default value isn't suitable, you can 
+change it there (you can also use the special value 0 to let the OS assign a port number for you).
+
+### Connecting to the proxy
+To connect the Bumble stack to the proxy, you need to be able to reach the phone's network 
+stack. This can be done over the phone's WiFi connection, or, alternatively, using an `adb`
+TCP forward (which should be faster than over WiFi).
+
+!!! tip "Forwarding TCP with `adb`"
+    To connect to the proxy via an `adb` TCP forward, use:
+    ```bash
+    $ adb forward tcp:<outside-port> tcp:<inside-port>
+    ```
+    Where ``<outside-port>`` is the port number for a listening socket on your laptop or 
+    desktop machine, and <inside-port> is the TCP port selected in the app's user interface.
+    Those two ports may be the same, of course.
+    For example, with the default TCP port 9993:
+    ```bash
+    $ adb forward tcp:9993 tcp:9993
+    ```
+
+Once you've ensured that you can reach the proxy's TCP port on the phone, either directly or
+via an `adb` forward, you can then use it as a Bumble transport, using the transport name: 
+``tcp-client:<host>:<port>`` syntax.
+
+!!! example "Connecting a Bumble client"
+    Connecting the `bumble-controller-info` app to the phone's controller.
+    Assuming you have set up an `adb` forward on port 9993:
+    ```bash
+    $ bumble-controller-info tcp-client:localhost:9993
+    ```
+
+    Or over WiFi with, in this example, the IP address of the phone being ```192.168.86.27```
+    ```bash
+    $ bumble-controller-info tcp-client:192.168.86.27:9993
+    ```

docs/mkdocs/src/extras/index.md

@@ -0,0 +1,19 @@
+EXTRAS
+======
+
+A collection of add-ons, apps and tools, to the Bumble project.
+
+Android Remote HCI
+------------------
+
+Allows using an Android phone's built-in Bluetooth controller with a Bumble
+stack running on a development machine.
+See [Android Remote HCI](android_remote_hci.md) for details.
+
+Android BT Bench
+----------------
+
+An Android app that is compatible with the Bumble `bench` command line app.
+This app can be used to test the throughput and latency between two Android
+devices, or between an Android device and another device running the Bumble
+`bench` app.

docs/mkdocs/src/hardware/index.md

@@ -3,7 +3,7 @@ HARDWARE
 
 The Bumble Host connects to a controller over an [HCI Transport](../transports/index.md).
 To use a hardware controller attached to the host on which the host application is running, the transport is typically either [HCI over UART](../transports/serial.md) or [HCI over USB](../transports/usb.md).
-On Linux, the [VHCI Transport](../transports/vhci.md) can be used to communicate with any controller hardware managed by the operating system. Alternatively, a remote controller (a phyiscal controller attached to a remote host) can be used by connecting one of the networked transports (such as the [TCP Client transport](../transports/tcp_client.md), the [TCP Server transport](../transports/tcp_server.md) or the [UDP Transport](../transports/udp.md)) to an [HCI Bridge](../apps_and_tools/hci_bridge) bridging the network transport to a physical controller on a remote host.
+On Linux, the [VHCI Transport](../transports/vhci.md) can be used to communicate with any controller hardware managed by the operating system. Alternatively, a remote controller (a phyiscal controller attached to a remote host) can be used by connecting one of the networked transports (such as the [TCP Client transport](../transports/tcp_client.md), the [TCP Server transport](../transports/tcp_server.md) or the [UDP Transport](../transports/udp.md)) to an [HCI Bridge](../apps_and_tools/hci_bridge.md) bridging the network transport to a physical controller on a remote host.
 
 In theory, any controller that is compliant with the HCI over UART or HCI over USB protocols can be used.
 

docs/mkdocs/src/hive/index.md

@@ -0,0 +1,59 @@
+HIVE
+====
+
+Welcome to the Bumble Hive.
+This is a collection of apps and virtual devices that can run entirely in a browser page.
+The code for the apps and devices, as well as the Bumble runtime code, runs via [Pyodide](https://pyodide.org/).
+Pyodide is a Python distribution for the browser and Node.js based on WebAssembly.
+
+The Bumble stack uses a WebSocket to exchange HCI packets with a virtual or physical
+Bluetooth controller.
+
+The apps and devices in the hive can be accessed by following the links below. Each
+page has a settings button that may be used to configure the WebSocket URL to use for
+the virtual HCI connection. This will typically be the WebSocket URL for a `netsim`
+daemon.
+There is also a [TOML index](index.toml) that can be used by tools to know at which URL to access
+each of the apps and devices, as well as their names and short descriptions.
+
+!!! tip "Using `netsim`"
+    When the `netsimd` daemon is running (for example when using the Android Emulator that
+    is included in Android Studio), the daemon listens for connections on a TCP port.
+    To find out what this TCP port is, you can read the `netsim.ini` file that `netsimd`
+    creates, it includes a line with `web.port=<tcp-port>` (for example `web.port=7681`).
+    The location of the `netsim.ini` file is platform-specific.
+
+    === "macOS"
+        On macOS, the directory where `netsim.ini` is stored is $TMPDIR
+        ```bash
+            $ cat $TMPDIR/netsim.ini
+        ```
+
+    === "Linux"
+        On Linux, the directory where `netsim.ini` is stored is $XDG_RUNTIME_DIR
+        ```bash
+            $ cat $XDG_RUNTIME_DIR/netsim.ini
+        ```
+
+
+!!! tip "Using a local radio"
+    You can connect the hive virtual apps and devices to a local Bluetooth radio, like,
+    for example, a USB dongle.
+    For that, you need to run a local HCI bridge to bridge a local HCI device to a WebSocket
+    that a web page can connect to.
+    Use the `bumble-hci-bridge` app, with the host transport set to a WebSocket server on an
+    available port (ex: `ws-server:_:7682`) and the controller transport set to the transport
+    name for the radio you want to use (ex: `usb:0` for the first USB dongle)
+
+
+Applications
+------------
+
+  * [Scanner](web/scanner/scanner.html) - Scans for BLE devices.
+
+Virtual Devices
+---------------
+
+  * [Speaker](web/speaker/speaker.html) - Virtual speaker that plays audio in a browser page.
+  * [Heart Rate Monitor](web/heart_rate_monitor/heart_rate_monitor.html) - Virtual heart rate monitor.
+

docs/mkdocs/src/hive/index.toml

@@ -0,0 +1,21 @@
+version = "1.0.0"
+base_url = "https://google.github.io/bumble/hive/web"
+default_hci_query_param = "hci"
+
+[[index]]
+name = "speaker"
+description = "Bumble Virtual Speaker"
+type = "Device"
+url = "speaker/speaker.html"
+
+[[index]]
+name = "scanner"
+description = "Simple Scanner Application"
+type = "Application"
+url = "scanner/scanner.html"
+
+[[index]]
+name = "heart-rate-monitor"
+description = "Virtual Heart Rate Monitor"
+type = "Device"
+url = "heart_rate_monitor/heart_rate_monitor.html"

docs/mkdocs/src/hive/web/bumble.js

@@ -0,0 +1 @@
+../../../../../web/bumble.js

docs/mkdocs/src/hive/web/heart_rate_monitor/heart_rate_monitor.html

@@ -0,0 +1 @@
+../../../../../../web/heart_rate_monitor/heart_rate_monitor.html

docs/mkdocs/src/hive/web/heart_rate_monitor/heart_rate_monitor.js

@@ -0,0 +1 @@
+../../../../../../web/heart_rate_monitor/heart_rate_monitor.js

docs/mkdocs/src/hive/web/heart_rate_monitor/heart_rate_monitor.py

@@ -0,0 +1 @@
+../../../../../../web/heart_rate_monitor/heart_rate_monitor.py

docs/mkdocs/src/hive/web/scanner/scanner.css

@@ -0,0 +1 @@
+../../../../../../web/scanner/scanner.css

docs/mkdocs/src/hive/web/scanner/scanner.html

@@ -0,0 +1 @@
+../../../../../../web/scanner/scanner.html

docs/mkdocs/src/hive/web/scanner/scanner.js

@@ -0,0 +1 @@
+../../../../../../web/scanner/scanner.js

docs/mkdocs/src/hive/web/scanner/scanner.py

@@ -0,0 +1 @@
+../../../../../../web/scanner/scanner.py

docs/mkdocs/src/hive/web/speaker/logo.svg

@@ -0,0 +1 @@
+../../../../../../web/speaker/logo.svg

docs/mkdocs/src/hive/web/speaker/speaker.css

@@ -0,0 +1 @@
+../../../../../../web/speaker/speaker.css

docs/mkdocs/src/hive/web/speaker/speaker.html

@@ -0,0 +1 @@
+../../../../../../web/speaker/speaker.html

docs/mkdocs/src/hive/web/speaker/speaker.js

@@ -0,0 +1 @@
+../../../../../../web/speaker/speaker.js

docs/mkdocs/src/hive/web/speaker/speaker.py

@@ -0,0 +1 @@
+../../../../../../web/speaker/speaker.py

docs/mkdocs/src/hive/web/ui.js

@@ -0,0 +1 @@
+../../../../../web/ui.js

docs/mkdocs/src/index.md

@@ -152,11 +152,23 @@ Some platforms support features that not all platforms support
 
 See the [Platforms page](platforms/index.md) for details.
 
+
+Hive
+----
+
+The Hive is a collection of example apps and virtual devices that are implemented using the
+Python Bumble API, running entirely in a web page. This is a convenient way to try out some
+of the examples without any Python installation, when you have some other virtual Bluetooth
+device that you can connect to or from, such as the Android Emulator.
+
+See the [Bumble Hive](hive/index.md) for details.
+
 Roadmap
 -------
 
 Future features to be considered include:
 
+  * More profiles
   * More device examples
   * Add a new type of virtual link (beyond the two existing ones) to allow for link-level simulation (timing, loss, etc)
   * Bindings for languages other than Python

docs/mkdocs/src/platforms/index.md

@@ -9,3 +9,4 @@ For platform-specific information, see the following pages:
   * :material-linux: Linux - see the [Linux platform page](linux.md)
   * :material-microsoft-windows: Windows - see the [Windows platform page](windows.md)
   * :material-android: Android - see the [Android platform page](android.md)
+  * :material-memory: Zephyr - see the [Zephyr platform page](zephyr.md)

docs/mkdocs/src/platforms/zephyr.md

@@ -0,0 +1,51 @@
+:material-memory: ZEPHYR PLATFORM
+=================================
+
+Set TX Power on nRF52840
+------------------------
+
+The Nordic nRF52840 supports Zephyr's vendor specific HCI command for setting TX
+power during advertising, connection, or scanning. With the example [HCI
+USB](https://docs.zephyrproject.org/latest/samples/bluetooth/hci_usb/README.html)
+application, an [nRF52840
+dongle](https://www.nordicsemi.com/Products/Development-
+hardware/nRF52840-Dongle) can be used as a Bumble controller.
+
+To add dynamic TX power support to the HCI USB application, add the following to
+`zephyr/samples/bluetooth/hci_usb/prj.conf` and build.
+
+```
+CONFIG_BT_CTLR_ADVANCED_FEATURES=y
+CONFIG_BT_CTLR_CONN_RSSI=y
+CONFIG_BT_CTLR_TX_PWR_DYNAMIC_CONTROL=y
+```
+
+Alternatively, a prebuilt firmware application can be downloaded here:
+[hci_usb.zip](../downloads/zephyr/hci_usb.zip).
+
+Put the nRF52840 dongle into bootloader mode by pressing the RESET button. The
+LED should pulse red. Load the firmware application with the `nrfutil` tool:
+
+```
+nrfutil dfu usb-serial -pkg hci_usb.zip -p /dev/ttyACM0
+```
+
+The vendor specific HCI commands to read and write TX power are defined in
+`bumble/vendor/zephyr/hci.py` and may be used as such:
+
+```python
+from bumble.vendor.zephyr.hci import HCI_Write_Tx_Power_Level_Command
+
+# set advertising power to -4 dB
+response = await host.send_command(
+    HCI_Write_Tx_Power_Level_Command(
+        handle_type=HCI_Write_Tx_Power_Level_Command.TX_POWER_HANDLE_TYPE_ADV,
+        connection_handle=0,
+        tx_power_level=-4,
+    )
+)
+
+if response.return_parameters.status == HCI_SUCCESS:
+    print(f"TX power set to {response.return_parameters.selected_tx_power_level}")
+
+```

docs/mkdocs/src/transports/android_emulator.md

@@ -14,7 +14,7 @@ connections.
 
 ## Moniker
 The moniker syntax for an Android Emulator "netsim" transport is: `android-netsim:[<host>:<port>][<options>]`,
-where `<options>` is a ','-separated list of `<name>=<value>` pairs`.
+where `<options>` is a comma-separated list of `<name>=<value>` pairs.
 The `mode` parameter name can specify running as a host or a controller, and `<hostname>:<port>` can specify a host name (or IP address) and TCP port number on which to reach the gRPC server for the emulator (in "host" mode), or to accept gRPC connections (in "controller" mode).
 Both the `mode=<host|controller>` and `<hostname>:<port>` parameters are optional (so the moniker `android-netsim` by itself is a valid moniker, which will create a transport in `host` mode, connected to `localhost` on the default gRPC port for the Netsim background process).
 

examples/heart_rate_server.py

@@ -29,6 +29,7 @@ from bumble.device import Device
 from bumble.transport import open_transport_or_link
 from bumble.profiles.device_information_service import DeviceInformationService
 from bumble.profiles.heart_rate_service import HeartRateService
+from bumble.utils import AsyncRunner
 
 
 # -----------------------------------------------------------------------------
@@ -98,6 +99,17 @@ async def main():
             )
         )
 
+        # Notify subscribers of the current value as soon as they subscribe
+        @heart_rate_service.heart_rate_measurement_characteristic.on('subscription')
+        def on_subscription(connection, notify_enabled, indicate_enabled):
+            if notify_enabled or indicate_enabled:
+                AsyncRunner.spawn(
+                    device.notify_subscriber(
+                        connection,
+                        heart_rate_service.heart_rate_measurement_characteristic,
+                    )
+                )
+
         # Go!
         await device.power_on()
         await device.start_advertising(auto_restart=True)

examples/hid_key_map.py

@@ -0,0 +1,248 @@
+# shift map
+
+# letters
+shift_map = {
+    'a': 'A',
+    'b': 'B',
+    'c': 'C',
+    'd': 'D',
+    'e': 'E',
+    'f': 'F',
+    'g': 'G',
+    'h': 'H',
+    'i': 'I',
+    'j': 'J',
+    'k': 'K',
+    'l': 'L',
+    'm': 'M',
+    'n': 'N',
+    'o': 'O',
+    'p': 'P',
+    'q': 'Q',
+    'r': 'R',
+    's': 'S',
+    't': 'T',
+    'u': 'U',
+    'v': 'V',
+    'w': 'W',
+    'x': 'X',
+    'y': 'Y',
+    'z': 'Z',
+    # numbers
+    '1': '!',
+    '2': '@',
+    '3': '#',
+    '4': '$',
+    '5': '%',
+    '6': '^',
+    '7': '&',
+    '8': '*',
+    '9': '(',
+    '0': ')',
+    # symbols
+    '-': '_',
+    '=': '+',
+    '[': '{',
+    ']': '}',
+    '\\': '|',
+    ';': ':',
+    '\'': '"',
+    ',': '<',
+    '.': '>',
+    '/': '?',
+    '`': '~',
+}
+
+# hex map
+
+# modifier keys
+mod_keys = {
+    '00': '',
+    '01': 'left_ctrl',
+    '02': 'left_shift',
+    '04': 'left_alt',
+    '08': 'left_meta',
+    '10': 'right_ctrl',
+    '20': 'right_shift',
+    '40': 'right_alt',
+    '80': 'right_meta',
+}
+
+# base keys
+
+base_keys = {
+    # meta
+    '00': '',  # none
+    '01': 'error_ovf',
+    # letters
+    '04': 'a',
+    '05': 'b',
+    '06': 'c',
+    '07': 'd',
+    '08': 'e',
+    '09': 'f',
+    '0a': 'g',
+    '0b': 'h',
+    '0c': 'i',
+    '0d': 'j',
+    '0e': 'k',
+    '0f': 'l',
+    '10': 'm',
+    '11': 'n',
+    '12': 'o',
+    '13': 'p',
+    '14': 'q',
+    '15': 'r',
+    '16': 's',
+    '17': 't',
+    '18': 'u',
+    '19': 'v',
+    '1a': 'w',
+    '1b': 'x',
+    '1c': 'y',
+    '1d': 'z',
+    # numbers
+    '1e': '1',
+    '1f': '2',
+    '20': '3',
+    '21': '4',
+    '22': '5',
+    '23': '6',
+    '24': '7',
+    '25': '8',
+    '26': '9',
+    '27': '0',
+    # misc
+    '28': 'enter',  # enter \n
+    '29': 'esc',
+    '2a': 'backspace',
+    '2b': 'tab',
+    '2c': 'spacebar',  # space
+    '2d': '-',
+    '2e': '=',
+    '2f': '[',
+    '30': ']',
+    '31': '\\',
+    '32': '=',
+    '33': '_SEMICOLON',
+    '34': 'KEY_APOSTROPHE',
+    '35': 'KEY_GRAVE',
+    '36': 'KEY_COMMA',
+    '37': 'KEY_DOT',
+    '38': 'KEY_SLASH',
+    '39': 'KEY_CAPSLOCK',
+    '3a': 'KEY_F1',
+    '3b': 'KEY_F2',
+    '3c': 'KEY_F3',
+    '3d': 'KEY_F4',
+    '3e': 'KEY_F5',
+    '3f': 'KEY_F6',
+    '40': 'KEY_F7',
+    '41': 'KEY_F8',
+    '42': 'KEY_F9',
+    '43': 'KEY_F10',
+    '44': 'KEY_F11',
+    '45': 'KEY_F12',
+    '46': 'KEY_SYSRQ',
+    '47': 'KEY_SCROLLLOCK',
+    '48': 'KEY_PAUSE',
+    '49': 'KEY_INSERT',
+    '4a': 'KEY_HOME',
+    '4b': 'KEY_PAGEUP',
+    '4c': 'KEY_DELETE',
+    '4d': 'KEY_END',
+    '4e': 'KEY_PAGEDOWN',
+    '4f': 'KEY_RIGHT',
+    '50': 'KEY_LEFT',
+    '51': 'KEY_DOWN',
+    '52': 'KEY_UP',
+    '53': 'KEY_NUMLOCK',
+    '54': 'KEY_KPSLASH',
+    '55': 'KEY_KPASTERISK',
+    '56': 'KEY_KPMINUS',
+    '57': 'KEY_KPPLUS',
+    '58': 'KEY_KPENTER',
+    '59': 'KEY_KP1',
+    '5a': 'KEY_KP2',
+    '5b': 'KEY_KP3',
+    '5c': 'KEY_KP4',
+    '5d': 'KEY_KP5',
+    '5e': 'KEY_KP6',
+    '5f': 'KEY_KP7',
+    '60': 'KEY_KP8',
+    '61': 'KEY_KP9',
+    '62': 'KEY_KP0',
+    '63': 'KEY_KPDOT',
+    '64': 'KEY_102ND',
+    '65': 'KEY_COMPOSE',
+    '66': 'KEY_POWER',
+    '67': 'KEY_KPEQUAL',
+    '68': 'KEY_F13',
+    '69': 'KEY_F14',
+    '6a': 'KEY_F15',
+    '6b': 'KEY_F16',
+    '6c': 'KEY_F17',
+    '6d': 'KEY_F18',
+    '6e': 'KEY_F19',
+    '6f': 'KEY_F20',
+    '70': 'KEY_F21',
+    '71': 'KEY_F22',
+    '72': 'KEY_F23',
+    '73': 'KEY_F24',
+    '74': 'KEY_OPEN',
+    '75': 'KEY_HELP',
+    '76': 'KEY_PROPS',
+    '77': 'KEY_FRONT',
+    '78': 'KEY_STOP',
+    '79': 'KEY_AGAIN',
+    '7a': 'KEY_UNDO',
+    '7b': 'KEY_CUT',
+    '7c': 'KEY_COPY',
+    '7d': 'KEY_PASTE',
+    '7e': 'KEY_FIND',
+    '7f': 'KEY_MUTE',
+    '80': 'KEY_VOLUMEUP',
+    '81': 'KEY_VOLUMEDOWN',
+    '85': 'KEY_KPCOMMA',
+    '87': 'KEY_RO',
+    '88': 'KEY_KATAKANAHIRAGANA',
+    '89': 'KEY_YEN',
+    '8a': 'KEY_HENKAN',
+    '8b': 'KEY_MUHENKAN',
+    '8c': 'KEY_KPJPCOMMA',
+    '90': 'KEY_HANGEUL',
+    '91': 'KEY_HANJA',
+    '92': 'KEY_KATAKANA',
+    '93': 'KEY_HIRAGANA',
+    '94': 'KEY_ZENKAKUHANKAKU',
+    'b6': 'KEY_KPLEFTPAREN',
+    'b7': 'KEY_KPRIGHTPAREN',
+    'e0': 'KEY_LEFTCTRL',
+    'e1': 'KEY_LEFTSHIFT',
+    'e2': 'KEY_LEFTALT',
+    'e3': 'KEY_LEFTMETA',
+    'e4': 'KEY_RIGHTCTRL',
+    'e5': 'KEY_RIGHTSHIFT',
+    'e6': 'KEY_RIGHTALT',
+    'e7': 'KEY_RIGHTMETA',
+    'e8': 'KEY_MEDIA_PLAYPAUSE',
+    'e9': 'KEY_MEDIA_STOPCD',
+    'ea': 'KEY_MEDIA_PREVIOUSSONG',
+    'eb': 'KEY_MEDIA_NEXTSONG',
+    'ec': 'KEY_MEDIA_EJECTCD',
+    'ed': 'KEY_MEDIA_VOLUMEUP',
+    'ee': 'KEY_MEDIA_VOLUMEDOWN',
+    'ef': 'KEY_MEDIA_MUTE',
+    'f0': 'KEY_MEDIA_WWW',
+    'f1': 'KEY_MEDIA_BACK',
+    'f2': 'KEY_MEDIA_FORWARD',
+    'f3': 'KEY_MEDIA_STOP',
+    'f4': 'KEY_MEDIA_FIND',
+    'f5': 'KEY_MEDIA_SCROLLUP',
+    'f6': 'KEY_MEDIA_SCROLLDOWN',
+    'f7': 'KEY_MEDIA_EDIT',
+    'f8': 'KEY_MEDIA_SLEEP',
+    'f9': 'KEY_MEDIA_COFFEE',
+    'fa': 'KEY_MEDIA_REFRESH',
+    'fb': 'KEY_MEDIA_CALC',
+}

examples/hid_report_parser.py

@@ -0,0 +1,159 @@
+from bumble.colors import color
+from hid_key_map import base_keys, mod_keys, shift_map
+
+
+# ------------------------------------------------------------------------------
+def get_key(modifier: str, key: str) -> str:
+    if modifier == '22':
+        modifier = '02'
+    if modifier in mod_keys:
+        modifier = mod_keys[modifier]
+    else:
+        return ''
+    if key in base_keys:
+        key = base_keys[key]
+    else:
+        return ''
+    if (modifier == 'left_shift' or modifier == 'right_shift') and key in shift_map:
+        key = shift_map[key]
+
+    return key
+
+
+class Keyboard:
+    def __init__(self):  # type: ignore
+        self.report = [
+            [  # Bit array for Modifier keys
+                0,  # Right GUI - (usually the Windows key)
+                0,  # Right ALT
+                0,  # Right Shift
+                0,  # Right Control
+                0,  # Left GUI - (usually the Windows key)
+                0,  # Left ALT
+                0,  # Left Shift
+                0,  # Left Control
+            ],
+            0x00,  # Vendor reserved
+            '',  # Rest is space for 6 keys
+            '',
+            '',
+            '',
+            '',
+            '',
+        ]
+
+    def decode_keyboard_report(self, input_report: bytes, report_length: int) -> None:
+        if report_length >= 8:
+            modifier = input_report[1]
+            self.report[0] = [int(x) for x in '{0:08b}'.format(modifier)]
+            self.report[0].reverse()  # type: ignore
+
+            modifier_key = str((modifier & 0x22).to_bytes(1, "big").hex())
+            keycodes = []
+            for k in range(3, report_length):
+                keycodes.append(str(input_report[k].to_bytes(1, "big").hex()))
+                self.report[k - 1] = get_key(modifier_key, keycodes[k - 3])
+        else:
+            print(color('Warning: Not able to parse report', 'yellow'))
+
+    def print_keyboard_report(self) -> None:
+        print(color('\tKeyboard Input Received', 'green', None, 'bold'))
+        print(color(f'Keys:', 'white', None, 'bold'))
+        for i in range(1, 7):
+            print(
+                color(f' Key{i}{" ":>8s}=  ', 'cyan', None, 'bold'), self.report[i + 1]
+            )
+        print(color(f'\nModifier Keys:', 'white', None, 'bold'))
+        print(
+            color(f'  Left Ctrl   : ', 'cyan'),
+            f'{self.report[0][0] == 1!s:<5}',  # type: ignore
+            color(f'  Left Shift  : ', 'cyan'),
+            f'{self.report[0][1] == 1!s:<5}',  # type: ignore
+            color(f'  Left ALT    : ', 'cyan'),
+            f'{self.report[0][2] == 1!s:<5}',  # type: ignore
+            color(f'  Left GUI    : ', 'cyan'),
+            f'{self.report[0][3] == 1!s:<5}\n',  # type: ignore
+            color(f' Right Ctrl  : ', 'cyan'),
+            f'{self.report[0][4] == 1!s:<5}',  # type: ignore
+            color(f'  Right Shift : ', 'cyan'),
+            f'{self.report[0][5] == 1!s:<5}',  # type: ignore
+            color(f'  Right ALT   : ', 'cyan'),
+            f'{self.report[0][6] == 1!s:<5}',  # type: ignore
+            color(f'  Right GUI   : ', 'cyan'),
+            f'{self.report[0][7] == 1!s:<5}',  # type: ignore
+        )
+
+
+# ------------------------------------------------------------------------------
+class Mouse:
+    def __init__(self):  # type: ignore
+        self.report = [
+            [  # Bit array for Buttons
+                0,  # Button 1 (primary/trigger
+                0,  # Button 2 (secondary)
+                0,  # Button 3 (tertiary)
+                0,  # Button 4
+                0,  # Button 5
+                0,  # unused padding bits
+                0,  # unused padding bits
+                0,  # unused padding bits
+            ],
+            0,  # X
+            0,  # Y
+            0,  # Wheel
+            0,  # AC Pan
+        ]
+
+    def decode_mouse_report(self, input_report: bytes, report_length: int) -> None:
+        self.report[0] = [int(x) for x in '{0:08b}'.format(input_report[1])]
+        self.report[0].reverse()  # type: ignore
+        self.report[1] = input_report[2]
+        self.report[2] = input_report[3]
+        if report_length in [5, 6]:
+            self.report[3] = input_report[4]
+            self.report[4] = input_report[5] if report_length == 6 else 0
+
+    def print_mouse_report(self) -> None:
+        print(color('\tMouse Input Received', 'green', None, 'bold'))
+        print(
+            color(f' Button 1 (primary/trigger) = ', 'cyan'),
+            self.report[0][0] == 1,  # type: ignore
+            color(f'\n Button 2 (secondary)       = ', 'cyan'),
+            self.report[0][1] == 1,  # type: ignore
+            color(f'\n Button 3 (tertiary)        = ', 'cyan'),
+            self.report[0][2] == 1,  # type: ignore
+            color(f'\n Button4                    = ', 'cyan'),
+            self.report[0][3] == 1,  # type: ignore
+            color(f'\n Button5                    = ', 'cyan'),
+            self.report[0][4] == 1,  # type: ignore
+            color(f'\n X (X-axis displacement)    = ', 'cyan'),
+            self.report[1],
+            color(f'\n Y (Y-axis displacement)    = ', 'cyan'),
+            self.report[2],
+            color(f'\n Wheel                      = ', 'cyan'),
+            self.report[3],
+            color(f'\n AC PAN                     = ', 'cyan'),
+            self.report[4],
+        )
+
+
+# ------------------------------------------------------------------------------
+class ReportParser:
+    @staticmethod
+    def parse_input_report(input_report: bytes) -> None:
+
+        report_id = input_report[0]  # pylint: disable=unsubscriptable-object
+        report_length = len(input_report)
+
+        # Keyboard input report (report id = 1)
+        if report_id == 1 and report_length >= 8:
+            keyboard = Keyboard()  # type: ignore
+            keyboard.decode_keyboard_report(input_report, report_length)
+            keyboard.print_keyboard_report()
+        # Mouse input report (report id = 2)
+        elif report_id == 2 and report_length in [4, 5, 6]:
+            mouse = Mouse()  # type: ignore
+            mouse.decode_mouse_report(input_report, report_length)
+            mouse.print_mouse_report()
+        else:
+            print(color(f'Warning: Parse Error Report ID {report_id}', 'yellow'))

examples/leaudio.json

@@ -0,0 +1,5 @@
+{
+    "name": "Bumble-LEA",
+    "keystore": "JsonKeyStore",
+    "advertising_interval": 100
+}

examples/run_a2dp_info.py

@@ -53,10 +53,10 @@ def sdp_records():
 
 # -----------------------------------------------------------------------------
 # pylint: disable-next=too-many-nested-blocks
-async def find_a2dp_service(device, connection):
+async def find_a2dp_service(connection):
     # Connect to the SDP Server
-    sdp_client = SDP_Client(device)
-    await sdp_client.connect(connection)
+    sdp_client = SDP_Client(connection)
+    await sdp_client.connect()
 
     # Search for services with an Audio Sink service class
     search_result = await sdp_client.search_attributes(
@@ -177,7 +177,7 @@ async def main():
         print('*** Encryption on')
 
         # Look for an A2DP service
-        avdtp_version = await find_a2dp_service(device, connection)
+        avdtp_version = await find_a2dp_service(connection)
         if not avdtp_version:
             print(color('!!! no AVDTP service found'))
             return