Merge pull request #329 from google/gbg/le-oob

le oob

.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,11 +41,13 @@ jobs:
       run: |
         inv build
         inv build.mkdocs
+
   build-rust:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: [ "3.8", "3.9", "3.10" ]
+        python-version: [ "3.8", "3.9", "3.10", "3.11" ]
+        rust-version: [ "1.70.0", "stable" ]
       fail-fast: false
     steps:
       - name: Check out from Git
@@ -54,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]"
@@ -62,9 +64,19 @@ jobs:
         uses: actions-rust-lang/setup-rust-toolchain@v1
         with:
           components: clippy,rustfmt
-      - name: Rust Lints
-        run: cd rust && cargo fmt --check && cargo clippy --all-targets -- --deny warnings
+          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
+        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
+        run: cd rust && cargo build --features bumble-tools --bin bumble

.vscode/settings.json

@@ -39,12 +39,15 @@
         "libusb",
         "MITM",
         "NDIS",
+        "netsim",
         "NONBLOCK",
         "NONCONN",
         "OXIMETER",
         "popleft",
+        "protobuf",
         "psms",
         "pyee",
+        "Pyodide",
         "pyusb",
         "rfcomm",
         "ROHC",

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,
@@ -85,6 +86,7 @@ DEFAULT_LINGER_TIME = 1.0
 
 DEFAULT_RFCOMM_CHANNEL = 8
 
+
 # -----------------------------------------------------------------------------
 # Utils
 # -----------------------------------------------------------------------------
@@ -197,6 +199,7 @@ class PacketType(enum.IntEnum):
 
 PACKET_FLAG_LAST = 1
 
+
 # -----------------------------------------------------------------------------
 # Sender
 # -----------------------------------------------------------------------------
@@ -659,17 +662,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 +700,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,
@@ -706,12 +711,11 @@ class L2capServer(StreamedPacketIO):
         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,
+        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'))
 

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

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

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'))
 
@@ -105,7 +105,7 @@ class ServerBridge:
                             asyncio.create_task(self.pipe.l2cap_channel.disconnect())
 
                     def data_received(self, data):
-                        print(f'<<< Received on TCP: {len(data)}')
+                        print(color(f'<<< [TCP DATA]: {len(data)} bytes', 'blue'))
                         self.pipe.l2cap_channel.write(data)
 
                 try:
@@ -123,6 +123,7 @@ class ServerBridge:
                     await self.l2cap_channel.disconnect()
 
             def on_l2cap_close(self):
+                print(color('*** L2CAP channel closed', 'red'))
                 self.l2cap_channel = None
                 if self.tcp_transport is not None:
                     self.tcp_transport.close()
@@ -194,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,
@@ -286,6 +292,7 @@ async def pair(
     bond,
     ctkd,
     io,
+    oob,
     prompt,
     request,
     print_keys,
@@ -306,6 +313,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 +334,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 +350,51 @@ 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,
+            )
 
             if not request:
                 try:
@@ -421,6 +463,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'
@@ -441,6 +491,7 @@ def main(
     bond,
     ctkd,
     io,
+    oob,
     prompt,
     request,
     print_keys,
@@ -464,6 +515,7 @@ def main(
             bond,
             ctkd,
             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/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/device.py

@@ -23,7 +23,20 @@ import asyncio
 import logging
 from contextlib import asynccontextmanager, AsyncExitStack
 from dataclasses import dataclass
-from typing import Any, Callable, ClassVar, Dict, List, Optional, Tuple, Type, Union
+from typing import (
+    Any,
+    Callable,
+    ClassVar,
+    Dict,
+    List,
+    Optional,
+    Tuple,
+    Type,
+    Union,
+    cast,
+    overload,
+    TYPE_CHECKING,
+)
 
 from .colors import color
 from .att import ATT_CID, ATT_DEFAULT_MTU, ATT_PDU
@@ -130,6 +143,7 @@ from .core import (
     BT_LE_TRANSPORT,
     BT_PERIPHERAL_ROLE,
     AdvertisingData,
+    ConnectionParameterUpdateError,
     CommandTimeoutError,
     ConnectionPHY,
     InvalidStateError,
@@ -139,6 +153,7 @@ from .utils import (
     CompositeEventEmitter,
     setup_event_forwarding,
     composite_listener,
+    deprecated,
 )
 from .keys import (
     KeyStore,
@@ -152,6 +167,9 @@ from . import sdp
 from . import l2cap
 from . import core
 
+if TYPE_CHECKING:
+    from .transport.common import TransportSource, TransportSink
+
 
 # -----------------------------------------------------------------------------
 # Logging
@@ -655,9 +673,7 @@ class Connection(CompositeEventEmitter):
     def send_l2cap_pdu(self, cid: int, pdu: bytes) -> None:
         self.device.send_l2cap_pdu(self.handle, cid, pdu)
 
-    def create_l2cap_connector(self, psm):
-        return self.device.create_l2cap_connector(self, psm)
-
+    @deprecated("Please use create_l2cap_channel()")
     async def open_l2cap_channel(
         self,
         psm,
@@ -667,6 +683,23 @@ class Connection(CompositeEventEmitter):
     ):
         return await self.device.open_l2cap_channel(self, psm, max_credits, mtu, mps)
 
+    @overload
+    async def create_l2cap_channel(
+        self, spec: l2cap.ClassicChannelSpec
+    ) -> l2cap.ClassicChannel:
+        ...
+
+    @overload
+    async def create_l2cap_channel(
+        self, spec: l2cap.LeCreditBasedChannelSpec
+    ) -> l2cap.LeCreditBasedChannel:
+        ...
+
+    async def create_l2cap_channel(
+        self, spec: Union[l2cap.ClassicChannelSpec, l2cap.LeCreditBasedChannelSpec]
+    ) -> Union[l2cap.ClassicChannel, l2cap.LeCreditBasedChannel]:
+        return await self.device.create_l2cap_channel(connection=self, spec=spec)
+
     async def disconnect(
         self, reason: int = HCI_REMOTE_USER_TERMINATED_CONNECTION_ERROR
     ) -> None:
@@ -709,6 +742,7 @@ class Connection(CompositeEventEmitter):
         connection_interval_max,
         max_latency,
         supervision_timeout,
+        use_l2cap=False,
     ):
         return await self.device.update_connection_parameters(
             self,
@@ -716,6 +750,7 @@ class Connection(CompositeEventEmitter):
             connection_interval_max,
             max_latency,
             supervision_timeout,
+            use_l2cap=use_l2cap,
         )
 
     async def set_phy(self, tx_phys=None, rx_phys=None, phy_options=None):
@@ -812,6 +847,9 @@ class DeviceConfiguration:
         self.connectable = config.get('connectable', self.connectable)
         self.discoverable = config.get('discoverable', self.discoverable)
         self.gatt_services = config.get('gatt_services', self.gatt_services)
+        self.address_resolution_offload = config.get(
+            'address_resolution_offload', self.address_resolution_offload
+        )
 
         # Load or synthesize an IRK
         irk = config.get('irk')
@@ -942,7 +980,13 @@ class Device(CompositeEventEmitter):
             pass
 
     @classmethod
-    def with_hci(cls, name, address, hci_source, hci_sink):
+    def with_hci(
+        cls,
+        name: str,
+        address: Address,
+        hci_source: TransportSource,
+        hci_sink: TransportSink,
+    ) -> Device:
         '''
         Create a Device instance with a Host configured to communicate with a controller
         through an HCI source/sink
@@ -951,18 +995,25 @@ class Device(CompositeEventEmitter):
         return cls(name=name, address=address, host=host)
 
     @classmethod
-    def from_config_file(cls, filename):
+    def from_config_file(cls, filename: str) -> Device:
         config = DeviceConfiguration()
         config.load_from_file(filename)
         return cls(config=config)
 
     @classmethod
-    def from_config_with_hci(cls, config, hci_source, hci_sink):
+    def from_config_with_hci(
+        cls,
+        config: DeviceConfiguration,
+        hci_source: TransportSource,
+        hci_sink: TransportSink,
+    ) -> Device:
         host = Host(controller_source=hci_source, controller_sink=hci_sink)
         return cls(config=config, host=host)
 
     @classmethod
-    def from_config_file_with_hci(cls, filename, hci_source, hci_sink):
+    def from_config_file_with_hci(
+        cls, filename: str, hci_source: TransportSource, hci_sink: TransportSink
+    ) -> Device:
         config = DeviceConfiguration()
         config.load_from_file(filename)
         return cls.from_config_with_hci(config, hci_source, hci_sink)
@@ -1150,15 +1201,11 @@ class Device(CompositeEventEmitter):
 
         return None
 
-    def create_l2cap_connector(self, connection, psm):
-        return lambda: self.l2cap_channel_manager.connect(connection, psm)
-
-    def create_l2cap_registrar(self, psm):
-        return lambda handler: self.register_l2cap_server(psm, handler)
-
-    def register_l2cap_server(self, psm, server):
-        self.l2cap_channel_manager.register_server(psm, server)
+    @deprecated("Please use create_l2cap_server()")
+    def register_l2cap_server(self, psm, server) -> int:
+        return self.l2cap_channel_manager.register_server(psm, server)
 
+    @deprecated("Please use create_l2cap_server()")
     def register_l2cap_channel_server(
         self,
         psm,
@@ -1171,6 +1218,7 @@ class Device(CompositeEventEmitter):
             psm, server, max_credits, mtu, mps
         )
 
+    @deprecated("Please use create_l2cap_channel()")
     async def open_l2cap_channel(
         self,
         connection,
@@ -1183,6 +1231,74 @@ class Device(CompositeEventEmitter):
             connection, psm, max_credits, mtu, mps
         )
 
+    @overload
+    async def create_l2cap_channel(
+        self,
+        connection: Connection,
+        spec: l2cap.ClassicChannelSpec,
+    ) -> l2cap.ClassicChannel:
+        ...
+
+    @overload
+    async def create_l2cap_channel(
+        self,
+        connection: Connection,
+        spec: l2cap.LeCreditBasedChannelSpec,
+    ) -> l2cap.LeCreditBasedChannel:
+        ...
+
+    async def create_l2cap_channel(
+        self,
+        connection: Connection,
+        spec: Union[l2cap.ClassicChannelSpec, l2cap.LeCreditBasedChannelSpec],
+    ) -> Union[l2cap.ClassicChannel, l2cap.LeCreditBasedChannel]:
+        if isinstance(spec, l2cap.ClassicChannelSpec):
+            return await self.l2cap_channel_manager.create_classic_channel(
+                connection=connection, spec=spec
+            )
+        if isinstance(spec, l2cap.LeCreditBasedChannelSpec):
+            return await self.l2cap_channel_manager.create_le_credit_based_channel(
+                connection=connection, spec=spec
+            )
+
+    @overload
+    def create_l2cap_server(
+        self,
+        spec: l2cap.ClassicChannelSpec,
+        handler: Optional[Callable[[l2cap.ClassicChannel], Any]] = None,
+    ) -> l2cap.ClassicChannelServer:
+        ...
+
+    @overload
+    def create_l2cap_server(
+        self,
+        spec: l2cap.LeCreditBasedChannelSpec,
+        handler: Optional[Callable[[l2cap.LeCreditBasedChannel], Any]] = None,
+    ) -> l2cap.LeCreditBasedChannelServer:
+        ...
+
+    def create_l2cap_server(
+        self,
+        spec: Union[l2cap.ClassicChannelSpec, l2cap.LeCreditBasedChannelSpec],
+        handler: Union[
+            Callable[[l2cap.ClassicChannel], Any],
+            Callable[[l2cap.LeCreditBasedChannel], Any],
+            None,
+        ] = None,
+    ) -> Union[l2cap.ClassicChannelServer, l2cap.LeCreditBasedChannelServer]:
+        if isinstance(spec, l2cap.ClassicChannelSpec):
+            return self.l2cap_channel_manager.create_classic_server(
+                spec=spec,
+                handler=cast(Callable[[l2cap.ClassicChannel], Any], handler),
+            )
+        elif isinstance(spec, l2cap.LeCreditBasedChannelSpec):
+            return self.l2cap_channel_manager.create_le_credit_based_server(
+                handler=cast(Callable[[l2cap.LeCreditBasedChannel], Any], handler),
+                spec=spec,
+            )
+        else:
+            raise ValueError(f'Unexpected mode {spec}')
+
     def send_l2cap_pdu(self, connection_handle: int, cid: int, pdu: bytes) -> None:
         self.host.send_l2cap_pdu(connection_handle, cid, pdu)
 
@@ -1192,7 +1308,7 @@ class Device(CompositeEventEmitter):
                 self.host.send_command(command, check_result), self.command_timeout
             )
         except asyncio.TimeoutError as error:
-            logger.warning('!!! Command timed out')
+            logger.warning(f'!!! Command {command.name} timed out')
             raise CommandTimeoutError() from error
 
     async def power_on(self) -> None:
@@ -1293,6 +1409,9 @@ class Device(CompositeEventEmitter):
         # Done
         self.powered_on = True
 
+    async def reset(self) -> None:
+        await self.host.reset()
+
     async def power_off(self) -> None:
         if self.powered_on:
             await self.host.flush()
@@ -1395,10 +1514,10 @@ class Device(CompositeEventEmitter):
             check_result=True,
         )
 
-        self.advertising_own_address_type = own_address_type
-        self.auto_restart_advertising = auto_restart
         self.advertising_type = advertising_type
+        self.advertising_own_address_type = own_address_type
         self.advertising = True
+        self.auto_restart_advertising = auto_restart
 
     async def stop_advertising(self) -> None:
         # Disable advertising
@@ -1408,9 +1527,9 @@ class Device(CompositeEventEmitter):
                 check_result=True,
             )
 
+            self.advertising_type = None
             self.advertising_own_address_type = None
             self.advertising = False
-            self.advertising_type = None
             self.auto_restart_advertising = False
 
     @property
@@ -2083,11 +2202,30 @@ class Device(CompositeEventEmitter):
         supervision_timeout,
         min_ce_length=0,
         max_ce_length=0,
-    ):
+        use_l2cap=False,
+    ) -> None:
         '''
         NOTE: the name of the parameters may look odd, but it just follows the names
         used in the Bluetooth spec.
         '''
+
+        if use_l2cap:
+            if connection.role != BT_PERIPHERAL_ROLE:
+                raise InvalidStateError(
+                    'only peripheral can update connection parameters with l2cap'
+                )
+            l2cap_result = (
+                await self.l2cap_channel_manager.update_connection_parameters(
+                    connection,
+                    connection_interval_min,
+                    connection_interval_max,
+                    max_latency,
+                    supervision_timeout,
+                )
+            )
+            if l2cap_result != l2cap.L2CAP_CONNECTION_PARAMETERS_ACCEPTED_RESULT:
+                raise ConnectionParameterUpdateError(l2cap_result)
+
         result = await self.send_command(
             HCI_LE_Connection_Update_Command(
                 connection_handle=connection.handle,
@@ -2097,7 +2235,7 @@ class Device(CompositeEventEmitter):
                 supervision_timeout=supervision_timeout,
                 min_ce_length=min_ce_length,
                 max_ce_length=max_ce_length,
-            )
+            )  # type: ignore[call-arg]
         )
         if result.status != HCI_Command_Status_Event.PENDING:
             raise HCI_StatusError(result)
@@ -2238,9 +2376,11 @@ class Device(CompositeEventEmitter):
     def request_pairing(self, connection):
         return self.smp_manager.request_pairing(connection)
 
-    async def get_long_term_key(self, connection_handle, rand, ediv):
+    async def get_long_term_key(
+        self, connection_handle: int, rand: bytes, ediv: int
+    ) -> Optional[bytes]:
         if (connection := self.lookup_connection(connection_handle)) is None:
-            return
+            return None
 
         # Start by looking for the key in an SMP session
         ltk = self.smp_manager.get_long_term_key(connection, rand, ediv)
@@ -2260,6 +2400,7 @@ class Device(CompositeEventEmitter):
 
                 if connection.role == BT_PERIPHERAL_ROLE and keys.ltk_peripheral:
                     return keys.ltk_peripheral.value
+        return None
 
     async def get_link_key(self, address: Address) -> Optional[bytes]:
         if self.keystore is None:
@@ -2578,7 +2719,6 @@ class Device(CompositeEventEmitter):
                 own_address_type = self.advertising_own_address_type
 
             # We are no longer advertising
-            self.advertising_own_address_type = None
             self.advertising = False
 
             if own_address_type in (
@@ -2635,7 +2775,6 @@ class Device(CompositeEventEmitter):
             and self.advertising
             and self.advertising_type.is_directed
         ):
-            self.advertising_own_address_type = None
             self.advertising = False
 
         # Notify listeners
@@ -2706,7 +2845,9 @@ class Device(CompositeEventEmitter):
             self.abort_on(
                 'flush',
                 self.start_advertising(
-                    advertising_type=self.advertising_type, auto_restart=True
+                    advertising_type=self.advertising_type,
+                    own_address_type=self.advertising_own_address_type,
+                    auto_restart=True,
                 ),
             )
 

bumble/drivers/__init__.py

@@ -21,6 +21,8 @@ like loading firmware after a cold start.
 # -----------------------------------------------------------------------------
 import abc
 import logging
+import pathlib
+import platform
 from . import rtk
 
 
@@ -66,3 +68,24 @@ async def get_driver_for_host(host):
         return driver
 
     return None
+
+
+def project_data_dir() -> pathlib.Path:
+    """
+    Returns:
+        A path to an OS-specific directory for bumble data. The directory is created if
+         it doesn't exist.
+    """
+    import platformdirs
+
+    if platform.system() == 'Darwin':
+        # platformdirs doesn't handle macOS right: it doesn't assemble a bundle id
+        # out of author & project
+        return platformdirs.user_data_path(
+            appname='com.google.bumble', ensure_exists=True
+        )
+    else:
+        # windows and linux don't use the com qualifier
+        return platformdirs.user_data_path(
+            appname='bumble', appauthor='google', ensure_exists=True
+        )

bumble/drivers/rtk.py

@@ -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
@@ -446,6 +439,11 @@ class Driver:
             # When the environment variable is set, don't look elsewhere
             return None
 
+        # Then, look where the firmware download tool writes by default
+        if (path := rtk_firmware_dir() / file_name).is_file():
+            logger.debug(f"{file_name} found in project data dir")
+            return path
+
         # Then, look in the package's driver directory
         if (path := pathlib.Path(__file__).parent / "rtk_fw" / file_name).is_file():
             logger.debug(f"{file_name} found in package dir")
@@ -646,3 +644,16 @@ class Driver:
         await self.download_firmware()
         await self.host.send_command(HCI_Reset_Command(), check_result=True)
         logger.info(f"loaded FW image {self.driver_info.fw_name}")
+
+
+def rtk_firmware_dir() -> pathlib.Path:
+    """
+    Returns:
+        A path to a subdir of the project data dir for Realtek firmware.
+         The directory is created if it doesn't exist.
+    """
+    from bumble.drivers import project_data_dir
+
+    p = project_data_dir() / "firmware" / "realtek"
+    p.mkdir(parents=True, exist_ok=True)
+    return p

bumble/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
@@ -187,7 +187,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 +210,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 +239,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 +255,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 +271,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 +280,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 +328,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 +350,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 +371,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 +388,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 +399,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 +522,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 +602,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 +615,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,18 @@ 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,
+    TYPE_CHECKING,
+)
 
 from pyee import EventEmitter
 
@@ -66,8 +77,12 @@ from .gatt import (
     GATT_INCLUDE_ATTRIBUTE_TYPE,
     Characteristic,
     ClientCharacteristicConfigurationBits,
+    TemplateService,
 )
 
+if TYPE_CHECKING:
+    from bumble.device import Connection
+
 # -----------------------------------------------------------------------------
 # Logging
 # -----------------------------------------------------------------------------
@@ -78,16 +93,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 +112,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})'
 
 
@@ -136,14 +151,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 +186,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:
@@ -195,7 +212,7 @@ class CharacteristicProxy(AttributeProxy):
 
         return await self.client.unsubscribe(self, subscriber)
 
-    def __str__(self):
+    def __str__(self) -> str:
         return (
             f'Characteristic(handle=0x{self.handle:04X}, '
             f'uuid={self.uuid}, '
@@ -207,7 +224,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 +233,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,8 +246,12 @@ class ProfileServiceProxy:
 class Client:
     services: List[ServiceProxy]
     cached_values: Dict[int, Tuple[datetime, bytes]]
+    notification_subscribers: Dict[int, Callable[[bytes], Any]]
+    indication_subscribers: Dict[int, 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)
@@ -241,16 +264,16 @@ class Client:
         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 +302,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 +336,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 +388,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 +460,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 +493,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 +505,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(
@@ -721,7 +746,7 @@ class Client:
 
         return descriptors
 
-    async def discover_attributes(self):
+    async def discover_attributes(self) -> List[AttributeProxy]:
         '''
         Discover all attributes, regardless of type
         '''
@@ -844,7 +869,9 @@ class Client:
             # 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
+    ) -> Any:
         '''
         See Vol 3, Part G - 4.8.1 Read Characteristic Value
 
@@ -905,7 +932,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 +989,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 +1024,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 +1047,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()}'
@@ -1060,7 +1095,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/hci.py

@@ -16,11 +16,12 @@
 # Imports
 # -----------------------------------------------------------------------------
 from __future__ import annotations
-import struct
 import collections
-import logging
+import enum
 import functools
-from typing import Dict, Type, Union, Callable, Any, Optional
+import logging
+import struct
+from typing import Any, Dict, Callable, Optional, Type, Union
 
 from .colors import color
 from .core import (
@@ -47,6 +48,10 @@ def hci_command_op_code(ogf, ocf):
     return ogf << 10 | ocf
 
 
+def hci_vendor_command_op_code(ocf):
+    return hci_command_op_code(HCI_VENDOR_OGF, ocf)
+
+
 def key_with_value(dictionary, target_value):
     for key, value in dictionary.items():
         if value == target_value:
@@ -101,6 +106,8 @@ def phy_list_to_bits(phys):
 # fmt: off
 # pylint: disable=line-too-long
 
+HCI_VENDOR_OGF = 0x3F
+
 # HCI Version
 HCI_VERSION_BLUETOOTH_CORE_1_0B    = 0
 HCI_VERSION_BLUETOOTH_CORE_1_1     = 1
@@ -115,6 +122,7 @@ HCI_VERSION_BLUETOOTH_CORE_5_0     = 9
 HCI_VERSION_BLUETOOTH_CORE_5_1     = 10
 HCI_VERSION_BLUETOOTH_CORE_5_2     = 11
 HCI_VERSION_BLUETOOTH_CORE_5_3     = 12
+HCI_VERSION_BLUETOOTH_CORE_5_4     = 13
 
 HCI_VERSION_NAMES = {
     HCI_VERSION_BLUETOOTH_CORE_1_0B:    'HCI_VERSION_BLUETOOTH_CORE_1_0B',
@@ -129,7 +137,8 @@ HCI_VERSION_NAMES = {
     HCI_VERSION_BLUETOOTH_CORE_5_0:     'HCI_VERSION_BLUETOOTH_CORE_5_0',
     HCI_VERSION_BLUETOOTH_CORE_5_1:     'HCI_VERSION_BLUETOOTH_CORE_5_1',
     HCI_VERSION_BLUETOOTH_CORE_5_2:     'HCI_VERSION_BLUETOOTH_CORE_5_2',
-    HCI_VERSION_BLUETOOTH_CORE_5_3:     'HCI_VERSION_BLUETOOTH_CORE_5_3'
+    HCI_VERSION_BLUETOOTH_CORE_5_3:     'HCI_VERSION_BLUETOOTH_CORE_5_3',
+    HCI_VERSION_BLUETOOTH_CORE_5_4:     'HCI_VERSION_BLUETOOTH_CORE_5_4',
 }
 
 # LMP Version
@@ -206,10 +215,8 @@ HCI_INQUIRY_RESPONSE_NOTIFICATION_EVENT                          = 0X56
 HCI_AUTHENTICATED_PAYLOAD_TIMEOUT_EXPIRED_EVENT                  = 0X57
 HCI_SAM_STATUS_CHANGE_EVENT                                      = 0X58
 
-HCI_EVENT_NAMES = {
-    event_code: event_name for (event_name, event_code) in globals().items()
-    if event_name.startswith('HCI_') and event_name.endswith('_EVENT')
-}
+HCI_VENDOR_EVENT = 0xFF
+
 
 # HCI Subevent Codes
 HCI_LE_CONNECTION_COMPLETE_EVENT                         = 0x01
@@ -248,10 +255,6 @@ HCI_LE_TRANSMIT_POWER_REPORTING_EVENT                    = 0X21
 HCI_LE_BIGINFO_ADVERTISING_REPORT_EVENT                  = 0X22
 HCI_LE_SUBRATE_CHANGE_EVENT                              = 0X23
 
-HCI_SUBEVENT_NAMES = {
-    event_code: event_name for (event_name, event_code) in globals().items()
-    if event_name.startswith('HCI_LE_') and event_name.endswith('_EVENT') and event_code != HCI_LE_META_EVENT
-}
 
 # HCI Command
 HCI_INQUIRY_COMMAND                                                      = hci_command_op_code(0x01, 0x0001)
@@ -557,10 +560,6 @@ HCI_LE_SET_DATA_RELATED_ADDRESS_CHANGES_COMMAND                          = hci_c
 HCI_LE_SET_DEFAULT_SUBRATE_COMMAND                                       = hci_command_op_code(0x08, 0x007D)
 HCI_LE_SUBRATE_REQUEST_COMMAND                                           = hci_command_op_code(0x08, 0x007E)
 
-HCI_COMMAND_NAMES = {
-    command_code: command_name for (command_name, command_code) in globals().items()
-    if command_name.startswith('HCI_') and command_name.endswith('_COMMAND')
-}
 
 # HCI Error Codes
 # See Bluetooth spec Vol 2, Part D - 1.3 LIST OF ERROR CODES
@@ -1372,6 +1371,7 @@ HCI_LE_SUPPORTED_FEATURES_NAMES = {
     if feature_name.startswith('HCI_') and feature_name.endswith('_LE_SUPPORTED_FEATURE')
 }
 
+
 # fmt: on
 # pylint: enable=line-too-long
 # pylint: disable=invalid-name
@@ -1927,6 +1927,9 @@ class HCI_Packet:
         if packet_type == HCI_ACL_DATA_PACKET:
             return HCI_AclDataPacket.from_bytes(packet)
 
+        if packet_type == HCI_SYNCHRONOUS_DATA_PACKET:
+            return HCI_SynchronousDataPacket.from_bytes(packet)
+
         if packet_type == HCI_EVENT_PACKET:
             return HCI_Event.from_bytes(packet)
 
@@ -1960,6 +1963,7 @@ class HCI_Command(HCI_Packet):
     '''
 
     hci_packet_type = HCI_COMMAND_PACKET
+    command_names: Dict[int, str] = {}
     command_classes: Dict[int, Type[HCI_Command]] = {}
 
     @staticmethod
@@ -1970,9 +1974,9 @@ class HCI_Command(HCI_Packet):
 
         def inner(cls):
             cls.name = cls.__name__.upper()
-            cls.op_code = key_with_value(HCI_COMMAND_NAMES, cls.name)
+            cls.op_code = key_with_value(cls.command_names, cls.name)
             if cls.op_code is None:
-                raise KeyError(f'command {cls.name} not found in HCI_COMMAND_NAMES')
+                raise KeyError(f'command {cls.name} not found in command_names')
             cls.fields = fields
             cls.return_parameters_fields = return_parameters_fields
 
@@ -1991,6 +1995,18 @@ class HCI_Command(HCI_Packet):
 
         return inner
 
+    @staticmethod
+    def command_map(symbols: Dict[str, Any]) -> Dict[int, str]:
+        return {
+            command_code: command_name
+            for (command_name, command_code) in symbols.items()
+            if command_name.startswith('HCI_') and command_name.endswith('_COMMAND')
+        }
+
+    @classmethod
+    def register_commands(cls, symbols: Dict[str, Any]) -> None:
+        cls.command_names.update(cls.command_map(symbols))
+
     @staticmethod
     def from_bytes(packet: bytes) -> HCI_Command:
         op_code, length = struct.unpack_from('<HB', packet, 1)
@@ -2015,7 +2031,7 @@ class HCI_Command(HCI_Packet):
 
     @staticmethod
     def command_name(op_code):
-        name = HCI_COMMAND_NAMES.get(op_code)
+        name = HCI_Command.command_names.get(op_code)
         if name is not None:
             return name
         return f'[OGF=0x{op_code >> 10:02x}, OCF=0x{op_code & 0x3FF:04x}]'
@@ -2024,6 +2040,16 @@ class HCI_Command(HCI_Packet):
     def create_return_parameters(cls, **kwargs):
         return HCI_Object(cls.return_parameters_fields, **kwargs)
 
+    @classmethod
+    def parse_return_parameters(cls, parameters):
+        if not cls.return_parameters_fields:
+            return None
+        return_parameters = HCI_Object.from_bytes(
+            parameters, 0, cls.return_parameters_fields
+        )
+        return_parameters.fields = cls.return_parameters_fields
+        return return_parameters
+
     def __init__(self, op_code, parameters=None, **kwargs):
         super().__init__(HCI_Command.command_name(op_code))
         if (fields := getattr(self, 'fields', None)) and kwargs:
@@ -2053,6 +2079,9 @@ class HCI_Command(HCI_Packet):
         return result
 
 
+HCI_Command.register_commands(globals())
+
+
 # -----------------------------------------------------------------------------
 @HCI_Command.command(
     [
@@ -2269,6 +2298,19 @@ class HCI_Read_Clock_Offset_Command(HCI_Command):
     '''
 
 
+# -----------------------------------------------------------------------------
+@HCI_Command.command(
+    fields=[
+        ('bd_addr', Address.parse_address),
+        ('reason', {'size': 1, 'mapper': HCI_Constant.error_name}),
+    ],
+)
+class HCI_Reject_Synchronous_Connection_Request_Command(HCI_Command):
+    '''
+    See Bluetooth spec @ 7.1.28 Reject Synchronous Connection Request Command
+    '''
+
+
 # -----------------------------------------------------------------------------
 @HCI_Command.command(
     fields=[
@@ -2430,6 +2472,51 @@ class HCI_Enhanced_Setup_Synchronous_Connection_Command(HCI_Command):
     See Bluetooth spec @ 7.1.45 Enhanced Setup Synchronous Connection Command
     '''
 
+    class CodingFormat(enum.IntEnum):
+        U_LOG = 0x00
+        A_LOG = 0x01
+        CVSD = 0x02
+        TRANSPARENT = 0x03
+        PCM = 0x04
+        MSBC = 0x05
+        LC3 = 0x06
+        G729A = 0x07
+
+        def to_bytes(self):
+            return self.value.to_bytes(5, 'little')
+
+        def __bytes__(self):
+            return self.to_bytes()
+
+    class PcmDataFormat(enum.IntEnum):
+        NA = 0x00
+        ONES_COMPLEMENT = 0x01
+        TWOS_COMPLEMENT = 0x02
+        SIGN_MAGNITUDE = 0x03
+        UNSIGNED = 0x04
+
+    class DataPath(enum.IntEnum):
+        HCI = 0x00
+        PCM = 0x01
+
+    class RetransmissionEffort(enum.IntEnum):
+        NO_RETRANSMISSION = 0x00
+        OPTIMIZE_FOR_POWER = 0x01
+        OPTIMIZE_FOR_QUALITY = 0x02
+        DONT_CARE = 0xFF
+
+    class PacketType(enum.IntFlag):
+        HV1 = 0x0001
+        HV2 = 0x0002
+        HV3 = 0x0004
+        EV3 = 0x0008
+        EV4 = 0x0010
+        EV5 = 0x0020
+        NO_2_EV3 = 0x0040
+        NO_3_EV3 = 0x0080
+        NO_2_EV5 = 0x0100
+        NO_3_EV5 = 0x0200
+
 
 # -----------------------------------------------------------------------------
 @HCI_Command.command(
@@ -4308,8 +4395,8 @@ class HCI_Event(HCI_Packet):
     '''
 
     hci_packet_type = HCI_EVENT_PACKET
+    event_names: Dict[int, str] = {}
     event_classes: Dict[int, Type[HCI_Event]] = {}
-    meta_event_classes: Dict[int, Type[HCI_LE_Meta_Event]] = {}
 
     @staticmethod
     def event(fields=()):
@@ -4319,9 +4406,9 @@ class HCI_Event(HCI_Packet):
 
         def inner(cls):
             cls.name = cls.__name__.upper()
-            cls.event_code = key_with_value(HCI_EVENT_NAMES, cls.name)
+            cls.event_code = key_with_value(cls.event_names, cls.name)
             if cls.event_code is None:
-                raise KeyError('event not found in HCI_EVENT_NAMES')
+                raise KeyError(f'event {cls.name} not found in event_names')
             cls.fields = fields
 
             # Patch the __init__ method to fix the event_code
@@ -4337,12 +4424,30 @@ class HCI_Event(HCI_Packet):
 
         return inner
 
+    @staticmethod
+    def event_map(symbols: Dict[str, Any]) -> Dict[int, str]:
+        return {
+            event_code: event_name
+            for (event_name, event_code) in symbols.items()
+            if event_name.startswith('HCI_')
+            and not event_name.startswith('HCI_LE_')
+            and event_name.endswith('_EVENT')
+        }
+
+    @staticmethod
+    def event_name(event_code):
+        return name_or_number(HCI_Event.event_names, event_code)
+
+    @staticmethod
+    def register_events(symbols: Dict[str, Any]) -> None:
+        HCI_Event.event_names.update(HCI_Event.event_map(symbols))
+
     @staticmethod
     def registered(event_class):
         event_class.name = event_class.__name__.upper()
-        event_class.event_code = key_with_value(HCI_EVENT_NAMES, event_class.name)
+        event_class.event_code = key_with_value(HCI_Event.event_names, event_class.name)
         if event_class.event_code is None:
-            raise KeyError('event not found in HCI_EVENT_NAMES')
+            raise KeyError(f'event {event_class.name} not found in event_names')
 
         # Register a factory for this class
         HCI_Event.event_classes[event_class.event_code] = event_class
@@ -4357,16 +4462,21 @@ class HCI_Event(HCI_Packet):
         if len(parameters) != length:
             raise ValueError('invalid packet length')
 
-        cls: Type[HCI_Event | HCI_LE_Meta_Event] | None
+        cls: Any
         if event_code == HCI_LE_META_EVENT:
             # We do this dispatch here and not in the subclass in order to avoid call
             # loops
             subevent_code = parameters[0]
-            cls = HCI_Event.meta_event_classes.get(subevent_code)
+            cls = HCI_LE_Meta_Event.subevent_classes.get(subevent_code)
             if cls is None:
                 # No class registered, just use a generic class instance
                 return HCI_LE_Meta_Event(subevent_code, parameters)
-
+        elif event_code == HCI_VENDOR_EVENT:
+            subevent_code = parameters[0]
+            cls = HCI_Vendor_Event.subevent_classes.get(subevent_code)
+            if cls is None:
+                # No class registered, just use a generic class instance
+                return HCI_Vendor_Event(subevent_code, parameters)
         else:
             cls = HCI_Event.event_classes.get(event_code)
             if cls is None:
@@ -4384,10 +4494,6 @@ class HCI_Event(HCI_Packet):
             HCI_Object.init_from_bytes(self, parameters, 0, fields)
         return self
 
-    @staticmethod
-    def event_name(event_code):
-        return name_or_number(HCI_EVENT_NAMES, event_code)
-
     def __init__(self, event_code, parameters=None, **kwargs):
         super().__init__(HCI_Event.event_name(event_code))
         if (fields := getattr(self, 'fields', None)) and kwargs:
@@ -4414,71 +4520,111 @@ class HCI_Event(HCI_Packet):
         return result
 
 
+HCI_Event.register_events(globals())
+
+
 # -----------------------------------------------------------------------------
-class HCI_LE_Meta_Event(HCI_Event):
+class HCI_Extended_Event(HCI_Event):
     '''
-    See Bluetooth spec @ 7.7.65 LE Meta Event
+    HCI_Event subclass for events that has a subevent code.
     '''
 
-    @staticmethod
-    def event(fields=()):
+    subevent_names: Dict[int, str] = {}
+    subevent_classes: Dict[int, Type[HCI_Extended_Event]]
+
+    @classmethod
+    def event(cls, fields=()):
         '''
         Decorator used to declare and register subclasses
         '''
 
         def inner(cls):
             cls.name = cls.__name__.upper()
-            cls.subevent_code = key_with_value(HCI_SUBEVENT_NAMES, cls.name)
+            cls.subevent_code = key_with_value(cls.subevent_names, cls.name)
             if cls.subevent_code is None:
-                raise KeyError('subevent not found in HCI_SUBEVENT_NAMES')
+                raise KeyError(f'subevent {cls.name} not found in subevent_names')
             cls.fields = fields
 
             # Patch the __init__ method to fix the subevent_code
+            original_init = cls.__init__
+
             def init(self, parameters=None, **kwargs):
-                return HCI_LE_Meta_Event.__init__(
-                    self, cls.subevent_code, parameters, **kwargs
-                )
+                return original_init(self, cls.subevent_code, parameters, **kwargs)
 
             cls.__init__ = init
 
             # Register a factory for this class
-            HCI_Event.meta_event_classes[cls.subevent_code] = cls
+            cls.subevent_classes[cls.subevent_code] = cls
 
             return cls
 
         return inner
 
+    @classmethod
+    def subevent_name(cls, subevent_code):
+        subevent_name = cls.subevent_names.get(subevent_code)
+        if subevent_name is not None:
+            return subevent_name
+
+        return f'{cls.__name__.upper()}[0x{subevent_code:02X}]'
+
+    @staticmethod
+    def subevent_map(symbols: Dict[str, Any]) -> Dict[int, str]:
+        return {
+            subevent_code: subevent_name
+            for (subevent_name, subevent_code) in symbols.items()
+            if subevent_name.startswith('HCI_') and subevent_name.endswith('_EVENT')
+        }
+
+    @classmethod
+    def register_subevents(cls, symbols: Dict[str, Any]) -> None:
+        cls.subevent_names.update(cls.subevent_map(symbols))
+
     @classmethod
     def from_parameters(cls, parameters):
         self = cls.__new__(cls)
-        HCI_LE_Meta_Event.__init__(self, self.subevent_code, parameters)
+        HCI_Extended_Event.__init__(self, self.subevent_code, parameters)
         if fields := getattr(self, 'fields', None):
             HCI_Object.init_from_bytes(self, parameters, 1, fields)
         return self
 
-    @staticmethod
-    def subevent_name(subevent_code):
-        return name_or_number(HCI_SUBEVENT_NAMES, subevent_code)
-
     def __init__(self, subevent_code, parameters, **kwargs):
         self.subevent_code = subevent_code
         if parameters is None and (fields := getattr(self, 'fields', None)) and kwargs:
             parameters = bytes([subevent_code]) + HCI_Object.dict_to_bytes(
                 kwargs, fields
             )
-        super().__init__(HCI_LE_META_EVENT, parameters, **kwargs)
+        super().__init__(self.event_code, parameters, **kwargs)
 
         # Override the name in order to adopt the subevent name instead
         self.name = self.subevent_name(subevent_code)
 
-    def __str__(self):
-        result = color(self.subevent_name(self.subevent_code), 'magenta')
-        if fields := getattr(self, 'fields', None):
-            result += ':\n' + HCI_Object.format_fields(self.__dict__, fields, '  ')
-        else:
-            if self.parameters:
-                result += f': {self.parameters.hex()}'
-        return result
+
+# -----------------------------------------------------------------------------
+class HCI_LE_Meta_Event(HCI_Extended_Event):
+    '''
+    See Bluetooth spec @ 7.7.65 LE Meta Event
+    '''
+
+    event_code: int = HCI_LE_META_EVENT
+    subevent_classes = {}
+
+    @staticmethod
+    def subevent_map(symbols: Dict[str, Any]) -> Dict[int, str]:
+        return {
+            subevent_code: subevent_name
+            for (subevent_name, subevent_code) in symbols.items()
+            if subevent_name.startswith('HCI_LE_') and subevent_name.endswith('_EVENT')
+        }
+
+
+HCI_LE_Meta_Event.register_subevents(globals())
+
+
+# -----------------------------------------------------------------------------
+class HCI_Vendor_Event(HCI_Extended_Event):
+    event_code: int = HCI_VENDOR_EVENT
+    subevent_classes = {}
 
 
 # -----------------------------------------------------------------------------
@@ -4592,7 +4738,7 @@ class HCI_LE_Advertising_Report_Event(HCI_LE_Meta_Event):
         return f'{color(self.subevent_name(self.subevent_code), "magenta")}:\n{reports}'
 
 
-HCI_Event.meta_event_classes[
+HCI_LE_Meta_Event.subevent_classes[
     HCI_LE_ADVERTISING_REPORT_EVENT
 ] = HCI_LE_Advertising_Report_Event
 
@@ -4846,7 +4992,7 @@ class HCI_LE_Extended_Advertising_Report_Event(HCI_LE_Meta_Event):
         return f'{color(self.subevent_name(self.subevent_code), "magenta")}:\n{reports}'
 
 
-HCI_Event.meta_event_classes[
+HCI_LE_Meta_Event.subevent_classes[
     HCI_LE_EXTENDED_ADVERTISING_REPORT_EVENT
 ] = HCI_LE_Extended_Advertising_Report_Event
 
@@ -5120,11 +5266,11 @@ class HCI_Command_Complete_Event(HCI_Event):
             self.return_parameters = self.return_parameters[0]
         else:
             cls = HCI_Command.command_classes.get(self.command_opcode)
-            if cls and cls.return_parameters_fields:
-                self.return_parameters = HCI_Object.from_bytes(
-                    self.return_parameters, 0, cls.return_parameters_fields
-                )
-                self.return_parameters.fields = cls.return_parameters_fields
+            if cls:
+                # Try to parse the return parameters bytes into an object.
+                return_parameters = cls.parse_return_parameters(self.return_parameters)
+                if return_parameters is not None:
+                    self.return_parameters = return_parameters
 
         return self
 
@@ -5655,6 +5801,64 @@ class HCI_AclDataPacket(HCI_Packet):
         )
 
 
+# -----------------------------------------------------------------------------
+class HCI_SynchronousDataPacket(HCI_Packet):
+    '''
+    See Bluetooth spec @ 5.4.3 HCI SCO Data Packets
+    '''
+
+    hci_packet_type = HCI_SYNCHRONOUS_DATA_PACKET
+
+    @staticmethod
+    def from_bytes(packet: bytes) -> HCI_SynchronousDataPacket:
+        # Read the header
+        h, data_total_length = struct.unpack_from('<HB', packet, 1)
+        connection_handle = h & 0xFFF
+        packet_status = (h >> 12) & 0b11
+        rfu = (h >> 14) & 0b11
+        data = packet[4:]
+        if len(data) != data_total_length:
+            raise ValueError(
+                f'invalid packet length {len(data)} != {data_total_length}'
+            )
+        return HCI_SynchronousDataPacket(
+            connection_handle, packet_status, rfu, data_total_length, data
+        )
+
+    def to_bytes(self) -> bytes:
+        h = (self.packet_status << 12) | (self.rfu << 14) | self.connection_handle
+        return (
+            struct.pack('<BHB', HCI_SYNCHRONOUS_DATA_PACKET, h, self.data_total_length)
+            + self.data
+        )
+
+    def __init__(
+        self,
+        connection_handle: int,
+        packet_status: int,
+        rfu: int,
+        data_total_length: int,
+        data: bytes,
+    ) -> None:
+        self.connection_handle = connection_handle
+        self.packet_status = packet_status
+        self.rfu = rfu
+        self.data_total_length = data_total_length
+        self.data = data
+
+    def __bytes__(self) -> bytes:
+        return self.to_bytes()
+
+    def __str__(self) -> str:
+        return (
+            f'{color("SCO", "blue")}: '
+            f'handle=0x{self.connection_handle:04x}, '
+            f'ps={self.packet_status}, rfu={self.rfu}, '
+            f'data_total_length={self.data_total_length}, '
+            f'data={self.data.hex()}'
+        )
+
+
 # -----------------------------------------------------------------------------
 class HCI_AclDataPacketAssembler:
     current_data: Optional[bytes]

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, 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,7 @@ from bumble.core import (
     BT_L2CAP_PROTOCOL_ID,
     BT_RFCOMM_PROTOCOL_ID,
 )
+from bumble.hci import HCI_Enhanced_Setup_Synchronous_Connection_Command
 from bumble.sdp import (
     DataElement,
     ServiceAttribute,
@@ -48,6 +52,71 @@ 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 +371,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 +441,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 +463,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 +471,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 +820,170 @@ 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: HCI_Enhanced_Setup_Synchronous_Connection_Command.CodingFormat
+    receive_coding_format: HCI_Enhanced_Setup_Synchronous_Connection_Command.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: HCI_Enhanced_Setup_Synchronous_Connection_Command.CodingFormat = (
+        HCI_Enhanced_Setup_Synchronous_Connection_Command.CodingFormat.TRANSPARENT
+    )
+    output_coding_format: HCI_Enhanced_Setup_Synchronous_Connection_Command.CodingFormat = (
+        HCI_Enhanced_Setup_Synchronous_Connection_Command.CodingFormat.TRANSPARENT
+    )
+    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
+
+
+_ESCO_PARAMETERS_CVSD_D0 = EscoParameters(
+    transmit_coding_format=HCI_Enhanced_Setup_Synchronous_Connection_Command.CodingFormat.CVSD,
+    receive_coding_format=HCI_Enhanced_Setup_Synchronous_Connection_Command.CodingFormat.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=HCI_Enhanced_Setup_Synchronous_Connection_Command.CodingFormat.CVSD,
+    receive_coding_format=HCI_Enhanced_Setup_Synchronous_Connection_Command.CodingFormat.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=HCI_Enhanced_Setup_Synchronous_Connection_Command.CodingFormat.CVSD,
+    receive_coding_format=HCI_Enhanced_Setup_Synchronous_Connection_Command.CodingFormat.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=HCI_Enhanced_Setup_Synchronous_Connection_Command.CodingFormat.CVSD,
+    receive_coding_format=HCI_Enhanced_Setup_Synchronous_Connection_Command.CodingFormat.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=HCI_Enhanced_Setup_Synchronous_Connection_Command.CodingFormat.CVSD,
+    receive_coding_format=HCI_Enhanced_Setup_Synchronous_Connection_Command.CodingFormat.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=HCI_Enhanced_Setup_Synchronous_Connection_Command.CodingFormat.CVSD,
+    receive_coding_format=HCI_Enhanced_Setup_Synchronous_Connection_Command.CodingFormat.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=HCI_Enhanced_Setup_Synchronous_Connection_Command.CodingFormat.MSBC,
+    receive_coding_format=HCI_Enhanced_Setup_Synchronous_Connection_Command.CodingFormat.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
+    ),
+    retransmission_effort=HCI_Enhanced_Setup_Synchronous_Connection_Command.RetransmissionEffort.OPTIMIZE_FOR_QUALITY,
+)
+
+_ESCO_PARAMETERS_MSBC_T2 = EscoParameters(
+    transmit_coding_format=HCI_Enhanced_Setup_Synchronous_Connection_Command.CodingFormat.MSBC,
+    receive_coding_format=HCI_Enhanced_Setup_Synchronous_Connection_Command.CodingFormat.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
+    ),
+    retransmission_effort=HCI_Enhanced_Setup_Synchronous_Connection_Command.RetransmissionEffort.OPTIMIZE_FOR_QUALITY,
+)
+
+ESCO_PERAMETERS = {
+    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,332 @@
+# 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 asyncio
+import enum
+
+from pyee import EventEmitter
+from typing import Optional, Tuple, Callable, Dict, Union, TYPE_CHECKING
+
+from . import core, l2cap  # type: ignore
+from .colors import color  # type: ignore
+from .core import BT_BR_EDR_TRANSPORT, InvalidStateError, ProtocolError  # type: ignore
+
+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:
+        self.l2cap_ctrl_channel.send_pdu(msg)  # type: ignore
+
+    def send_pdu_on_intr(self, msg: bytes) -> None:
+        self.l2cap_intr_channel.send_pdu(msg)  # type: ignore
+
+    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
@@ -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,
@@ -67,16 +68,21 @@ 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,
     BT_LE_TRANSPORT,
     ConnectionPHY,
     ConnectionParameters,
+    InvalidStateError,
 )
 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
@@ -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,14 @@ 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))
         else:
             logger.warning(f'!!! unknown packet type {packet.hci_packet_type}')
 
@@ -493,6 +511,10 @@ 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_l2cap_pdu(self, connection: Connection, cid: int, pdu: bytes) -> None:
         self.emit('l2cap_pdu', connection.handle, cid, pdu)
 
@@ -746,7 +768,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/l2cap.py

@@ -17,6 +17,8 @@
 # -----------------------------------------------------------------------------
 from __future__ import annotations
 import asyncio
+import dataclasses
+import enum
 import logging
 import struct
 
@@ -37,6 +39,7 @@ from typing import (
     TYPE_CHECKING,
 )
 
+from .utils import deprecated
 from .colors import color
 from .core import BT_CENTRAL_ROLE, InvalidStateError, ProtocolError
 from .hci import (
@@ -166,6 +169,34 @@ L2CAP_MTU_CONFIGURATION_PARAMETER_TYPE = 0x01
 # pylint: disable=invalid-name
 
 
+@dataclasses.dataclass
+class ClassicChannelSpec:
+    psm: Optional[int] = None
+    mtu: int = L2CAP_MIN_BR_EDR_MTU
+
+
+@dataclasses.dataclass
+class LeCreditBasedChannelSpec:
+    psm: Optional[int] = None
+    mtu: int = L2CAP_LE_CREDIT_BASED_CONNECTION_DEFAULT_MTU
+    mps: int = L2CAP_LE_CREDIT_BASED_CONNECTION_DEFAULT_MPS
+    max_credits: int = L2CAP_LE_CREDIT_BASED_CONNECTION_DEFAULT_INITIAL_CREDITS
+
+    def __post_init__(self):
+        if (
+            self.max_credits < 1
+            or self.max_credits > L2CAP_LE_CREDIT_BASED_CONNECTION_MAX_CREDITS
+        ):
+            raise ValueError('max credits out of range')
+        if self.mtu < L2CAP_LE_CREDIT_BASED_CONNECTION_MIN_MTU:
+            raise ValueError('MTU too small')
+        if (
+            self.mps < L2CAP_LE_CREDIT_BASED_CONNECTION_MIN_MPS
+            or self.mps > L2CAP_LE_CREDIT_BASED_CONNECTION_MAX_MPS
+        ):
+            raise ValueError('MPS out of range')
+
+
 class L2CAP_PDU:
     '''
     See Bluetooth spec @ Vol 3, Part A - 3 DATA PACKET FORMAT
@@ -675,57 +706,36 @@ class L2CAP_LE_Flow_Control_Credit(L2CAP_Control_Frame):
 
 
 # -----------------------------------------------------------------------------
-class Channel(EventEmitter):
-    # States
-    CLOSED = 0x00
-    WAIT_CONNECT = 0x01
-    WAIT_CONNECT_RSP = 0x02
-    OPEN = 0x03
-    WAIT_DISCONNECT = 0x04
-    WAIT_CREATE = 0x05
-    WAIT_CREATE_RSP = 0x06
-    WAIT_MOVE = 0x07
-    WAIT_MOVE_RSP = 0x08
-    WAIT_MOVE_CONFIRM = 0x09
-    WAIT_CONFIRM_RSP = 0x0A
+class ClassicChannel(EventEmitter):
+    class State(enum.IntEnum):
+        # States
+        CLOSED = 0x00
+        WAIT_CONNECT = 0x01
+        WAIT_CONNECT_RSP = 0x02
+        OPEN = 0x03
+        WAIT_DISCONNECT = 0x04
+        WAIT_CREATE = 0x05
+        WAIT_CREATE_RSP = 0x06
+        WAIT_MOVE = 0x07
+        WAIT_MOVE_RSP = 0x08
+        WAIT_MOVE_CONFIRM = 0x09
+        WAIT_CONFIRM_RSP = 0x0A
 
-    # CONFIG substates
-    WAIT_CONFIG = 0x10
-    WAIT_SEND_CONFIG = 0x11
-    WAIT_CONFIG_REQ_RSP = 0x12
-    WAIT_CONFIG_RSP = 0x13
-    WAIT_CONFIG_REQ = 0x14
-    WAIT_IND_FINAL_RSP = 0x15
-    WAIT_FINAL_RSP = 0x16
-    WAIT_CONTROL_IND = 0x17
-
-    STATE_NAMES = {
-        CLOSED: 'CLOSED',
-        WAIT_CONNECT: 'WAIT_CONNECT',
-        WAIT_CONNECT_RSP: 'WAIT_CONNECT_RSP',
-        OPEN: 'OPEN',
-        WAIT_DISCONNECT: 'WAIT_DISCONNECT',
-        WAIT_CREATE: 'WAIT_CREATE',
-        WAIT_CREATE_RSP: 'WAIT_CREATE_RSP',
-        WAIT_MOVE: 'WAIT_MOVE',
-        WAIT_MOVE_RSP: 'WAIT_MOVE_RSP',
-        WAIT_MOVE_CONFIRM: 'WAIT_MOVE_CONFIRM',
-        WAIT_CONFIRM_RSP: 'WAIT_CONFIRM_RSP',
-        WAIT_CONFIG: 'WAIT_CONFIG',
-        WAIT_SEND_CONFIG: 'WAIT_SEND_CONFIG',
-        WAIT_CONFIG_REQ_RSP: 'WAIT_CONFIG_REQ_RSP',
-        WAIT_CONFIG_RSP: 'WAIT_CONFIG_RSP',
-        WAIT_CONFIG_REQ: 'WAIT_CONFIG_REQ',
-        WAIT_IND_FINAL_RSP: 'WAIT_IND_FINAL_RSP',
-        WAIT_FINAL_RSP: 'WAIT_FINAL_RSP',
-        WAIT_CONTROL_IND: 'WAIT_CONTROL_IND',
-    }
+        # CONFIG substates
+        WAIT_CONFIG = 0x10
+        WAIT_SEND_CONFIG = 0x11
+        WAIT_CONFIG_REQ_RSP = 0x12
+        WAIT_CONFIG_RSP = 0x13
+        WAIT_CONFIG_REQ = 0x14
+        WAIT_IND_FINAL_RSP = 0x15
+        WAIT_FINAL_RSP = 0x16
+        WAIT_CONTROL_IND = 0x17
 
     connection_result: Optional[asyncio.Future[None]]
     disconnection_result: Optional[asyncio.Future[None]]
     response: Optional[asyncio.Future[bytes]]
     sink: Optional[Callable[[bytes], Any]]
-    state: int
+    state: State
     connection: Connection
 
     def __init__(
@@ -741,7 +751,7 @@ class Channel(EventEmitter):
         self.manager = manager
         self.connection = connection
         self.signaling_cid = signaling_cid
-        self.state = Channel.CLOSED
+        self.state = self.State.CLOSED
         self.mtu = mtu
         self.psm = psm
         self.source_cid = source_cid
@@ -751,13 +761,11 @@ class Channel(EventEmitter):
         self.disconnection_result = None
         self.sink = None
 
-    def change_state(self, new_state: int) -> None:
-        logger.debug(
-            f'{self} state change -> {color(Channel.STATE_NAMES[new_state], "cyan")}'
-        )
+    def _change_state(self, new_state: State) -> None:
+        logger.debug(f'{self} state change -> {color(new_state.name, "cyan")}')
         self.state = new_state
 
-    def send_pdu(self, pdu: SupportsBytes | bytes) -> None:
+    def send_pdu(self, pdu: Union[SupportsBytes, bytes]) -> None:
         self.manager.send_pdu(self.connection, self.destination_cid, pdu)
 
     def send_control_frame(self, frame: L2CAP_Control_Frame) -> None:
@@ -767,7 +775,7 @@ class Channel(EventEmitter):
         # Check that there isn't already a request pending
         if self.response:
             raise InvalidStateError('request already pending')
-        if self.state != Channel.OPEN:
+        if self.state != self.State.OPEN:
             raise InvalidStateError('channel not open')
 
         self.response = asyncio.get_running_loop().create_future()
@@ -787,14 +795,14 @@ class Channel(EventEmitter):
             )
 
     async def connect(self) -> None:
-        if self.state != Channel.CLOSED:
+        if self.state != self.State.CLOSED:
             raise InvalidStateError('invalid state')
 
         # Check that we can start a new connection
         if self.connection_result:
             raise RuntimeError('connection already pending')
 
-        self.change_state(Channel.WAIT_CONNECT_RSP)
+        self._change_state(self.State.WAIT_CONNECT_RSP)
         self.send_control_frame(
             L2CAP_Connection_Request(
                 identifier=self.manager.next_identifier(self.connection),
@@ -814,10 +822,10 @@ class Channel(EventEmitter):
             self.connection_result = None
 
     async def disconnect(self) -> None:
-        if self.state != Channel.OPEN:
+        if self.state != self.State.OPEN:
             raise InvalidStateError('invalid state')
 
-        self.change_state(Channel.WAIT_DISCONNECT)
+        self._change_state(self.State.WAIT_DISCONNECT)
         self.send_control_frame(
             L2CAP_Disconnection_Request(
                 identifier=self.manager.next_identifier(self.connection),
@@ -832,8 +840,8 @@ class Channel(EventEmitter):
         return await self.disconnection_result
 
     def abort(self) -> None:
-        if self.state == self.OPEN:
-            self.change_state(self.CLOSED)
+        if self.state == self.State.OPEN:
+            self._change_state(self.State.CLOSED)
             self.emit('close')
 
     def send_configure_request(self) -> None:
@@ -856,7 +864,7 @@ class Channel(EventEmitter):
 
     def on_connection_request(self, request) -> None:
         self.destination_cid = request.source_cid
-        self.change_state(Channel.WAIT_CONNECT)
+        self._change_state(self.State.WAIT_CONNECT)
         self.send_control_frame(
             L2CAP_Connection_Response(
                 identifier=request.identifier,
@@ -866,24 +874,24 @@ class Channel(EventEmitter):
                 status=0x0000,
             )
         )
-        self.change_state(Channel.WAIT_CONFIG)
+        self._change_state(self.State.WAIT_CONFIG)
         self.send_configure_request()
-        self.change_state(Channel.WAIT_CONFIG_REQ_RSP)
+        self._change_state(self.State.WAIT_CONFIG_REQ_RSP)
 
     def on_connection_response(self, response):
-        if self.state != Channel.WAIT_CONNECT_RSP:
+        if self.state != self.State.WAIT_CONNECT_RSP:
             logger.warning(color('invalid state', 'red'))
             return
 
         if response.result == L2CAP_Connection_Response.CONNECTION_SUCCESSFUL:
             self.destination_cid = response.destination_cid
-            self.change_state(Channel.WAIT_CONFIG)
+            self._change_state(self.State.WAIT_CONFIG)
             self.send_configure_request()
-            self.change_state(Channel.WAIT_CONFIG_REQ_RSP)
+            self._change_state(self.State.WAIT_CONFIG_REQ_RSP)
         elif response.result == L2CAP_Connection_Response.CONNECTION_PENDING:
             pass
         else:
-            self.change_state(Channel.CLOSED)
+            self._change_state(self.State.CLOSED)
             self.connection_result.set_exception(
                 ProtocolError(
                     response.result,
@@ -895,9 +903,9 @@ class Channel(EventEmitter):
 
     def on_configure_request(self, request) -> None:
         if self.state not in (
-            Channel.WAIT_CONFIG,
-            Channel.WAIT_CONFIG_REQ,
-            Channel.WAIT_CONFIG_REQ_RSP,
+            self.State.WAIT_CONFIG,
+            self.State.WAIT_CONFIG_REQ,
+            self.State.WAIT_CONFIG_REQ_RSP,
         ):
             logger.warning(color('invalid state', 'red'))
             return
@@ -918,25 +926,28 @@ class Channel(EventEmitter):
                 options=request.options,  # TODO: don't accept everything blindly
             )
         )
-        if self.state == Channel.WAIT_CONFIG:
-            self.change_state(Channel.WAIT_SEND_CONFIG)
+        if self.state == self.State.WAIT_CONFIG:
+            self._change_state(self.State.WAIT_SEND_CONFIG)
             self.send_configure_request()
-            self.change_state(Channel.WAIT_CONFIG_RSP)
-        elif self.state == Channel.WAIT_CONFIG_REQ:
-            self.change_state(Channel.OPEN)
+            self._change_state(self.State.WAIT_CONFIG_RSP)
+        elif self.state == self.State.WAIT_CONFIG_REQ:
+            self._change_state(self.State.OPEN)
             if self.connection_result:
                 self.connection_result.set_result(None)
                 self.connection_result = None
             self.emit('open')
-        elif self.state == Channel.WAIT_CONFIG_REQ_RSP:
-            self.change_state(Channel.WAIT_CONFIG_RSP)
+        elif self.state == self.State.WAIT_CONFIG_REQ_RSP:
+            self._change_state(self.State.WAIT_CONFIG_RSP)
 
     def on_configure_response(self, response) -> None:
         if response.result == L2CAP_Configure_Response.SUCCESS:
-            if self.state == Channel.WAIT_CONFIG_REQ_RSP:
-                self.change_state(Channel.WAIT_CONFIG_REQ)
-            elif self.state in (Channel.WAIT_CONFIG_RSP, Channel.WAIT_CONTROL_IND):
-                self.change_state(Channel.OPEN)
+            if self.state == self.State.WAIT_CONFIG_REQ_RSP:
+                self._change_state(self.State.WAIT_CONFIG_REQ)
+            elif self.state in (
+                self.State.WAIT_CONFIG_RSP,
+                self.State.WAIT_CONTROL_IND,
+            ):
+                self._change_state(self.State.OPEN)
                 if self.connection_result:
                     self.connection_result.set_result(None)
                     self.connection_result = None
@@ -966,7 +977,7 @@ class Channel(EventEmitter):
             # TODO: decide how to fail gracefully
 
     def on_disconnection_request(self, request) -> None:
-        if self.state in (Channel.OPEN, Channel.WAIT_DISCONNECT):
+        if self.state in (self.State.OPEN, self.State.WAIT_DISCONNECT):
             self.send_control_frame(
                 L2CAP_Disconnection_Response(
                     identifier=request.identifier,
@@ -974,14 +985,14 @@ class Channel(EventEmitter):
                     source_cid=request.source_cid,
                 )
             )
-            self.change_state(Channel.CLOSED)
+            self._change_state(self.State.CLOSED)
             self.emit('close')
             self.manager.on_channel_closed(self)
         else:
             logger.warning(color('invalid state', 'red'))
 
     def on_disconnection_response(self, response) -> None:
-        if self.state != Channel.WAIT_DISCONNECT:
+        if self.state != self.State.WAIT_DISCONNECT:
             logger.warning(color('invalid state', 'red'))
             return
 
@@ -992,7 +1003,7 @@ class Channel(EventEmitter):
             logger.warning('unexpected source or destination CID')
             return
 
-        self.change_state(Channel.CLOSED)
+        self._change_state(self.State.CLOSED)
         if self.disconnection_result:
             self.disconnection_result.set_result(None)
             self.disconnection_result = None
@@ -1004,42 +1015,32 @@ class Channel(EventEmitter):
             f'Channel({self.source_cid}->{self.destination_cid}, '
             f'PSM={self.psm}, '
             f'MTU={self.mtu}, '
-            f'state={Channel.STATE_NAMES[self.state]})'
+            f'state={self.state.name})'
         )
 
 
 # -----------------------------------------------------------------------------
-class LeConnectionOrientedChannel(EventEmitter):
+class LeCreditBasedChannel(EventEmitter):
     """
     LE Credit-based Connection Oriented Channel
     """
 
-    INIT = 0
-    CONNECTED = 1
-    CONNECTING = 2
-    DISCONNECTING = 3
-    DISCONNECTED = 4
-    CONNECTION_ERROR = 5
-
-    STATE_NAMES = {
-        INIT: 'INIT',
-        CONNECTED: 'CONNECTED',
-        CONNECTING: 'CONNECTING',
-        DISCONNECTING: 'DISCONNECTING',
-        DISCONNECTED: 'DISCONNECTED',
-        CONNECTION_ERROR: 'CONNECTION_ERROR',
-    }
+    class State(enum.IntEnum):
+        INIT = 0
+        CONNECTED = 1
+        CONNECTING = 2
+        DISCONNECTING = 3
+        DISCONNECTED = 4
+        CONNECTION_ERROR = 5
 
     out_queue: Deque[bytes]
-    connection_result: Optional[asyncio.Future[LeConnectionOrientedChannel]]
+    connection_result: Optional[asyncio.Future[LeCreditBasedChannel]]
     disconnection_result: Optional[asyncio.Future[None]]
+    in_sdu: Optional[bytes]
     out_sdu: Optional[bytes]
-    state: int
+    state: State
     connection: Connection
-
-    @staticmethod
-    def state_name(state: int) -> str:
-        return name_or_number(LeConnectionOrientedChannel.STATE_NAMES, state)
+    sink: Optional[Callable[[bytes], Any]]
 
     def __init__(
         self,
@@ -1083,30 +1084,28 @@ class LeConnectionOrientedChannel(EventEmitter):
         self.drained.set()
 
         if connected:
-            self.state = LeConnectionOrientedChannel.CONNECTED
+            self.state = self.State.CONNECTED
         else:
-            self.state = LeConnectionOrientedChannel.INIT
+            self.state = self.State.INIT
 
-    def change_state(self, new_state: int) -> None:
-        logger.debug(
-            f'{self} state change -> {color(self.state_name(new_state), "cyan")}'
-        )
+    def _change_state(self, new_state: State) -> None:
+        logger.debug(f'{self} state change -> {color(new_state.name, "cyan")}')
         self.state = new_state
 
-        if new_state == self.CONNECTED:
+        if new_state == self.State.CONNECTED:
             self.emit('open')
-        elif new_state == self.DISCONNECTED:
+        elif new_state == self.State.DISCONNECTED:
             self.emit('close')
 
-    def send_pdu(self, pdu: SupportsBytes | bytes) -> None:
+    def send_pdu(self, pdu: Union[SupportsBytes, bytes]) -> None:
         self.manager.send_pdu(self.connection, self.destination_cid, pdu)
 
     def send_control_frame(self, frame: L2CAP_Control_Frame) -> None:
         self.manager.send_control_frame(self.connection, L2CAP_LE_SIGNALING_CID, frame)
 
-    async def connect(self) -> LeConnectionOrientedChannel:
+    async def connect(self) -> LeCreditBasedChannel:
         # Check that we're in the right state
-        if self.state != self.INIT:
+        if self.state != self.State.INIT:
             raise InvalidStateError('not in a connectable state')
 
         # Check that we can start a new connection
@@ -1114,7 +1113,7 @@ class LeConnectionOrientedChannel(EventEmitter):
         if identifier in self.manager.le_coc_requests:
             raise RuntimeError('too many concurrent connection requests')
 
-        self.change_state(self.CONNECTING)
+        self._change_state(self.State.CONNECTING)
         request = L2CAP_LE_Credit_Based_Connection_Request(
             identifier=identifier,
             le_psm=self.le_psm,
@@ -1134,10 +1133,10 @@ class LeConnectionOrientedChannel(EventEmitter):
 
     async def disconnect(self) -> None:
         # Check that we're connected
-        if self.state != self.CONNECTED:
+        if self.state != self.State.CONNECTED:
             raise InvalidStateError('not connected')
 
-        self.change_state(self.DISCONNECTING)
+        self._change_state(self.State.DISCONNECTING)
         self.flush_output()
         self.send_control_frame(
             L2CAP_Disconnection_Request(
@@ -1153,15 +1152,15 @@ class LeConnectionOrientedChannel(EventEmitter):
         return await self.disconnection_result
 
     def abort(self) -> None:
-        if self.state == self.CONNECTED:
-            self.change_state(self.DISCONNECTED)
+        if self.state == self.State.CONNECTED:
+            self._change_state(self.State.DISCONNECTED)
 
     def on_pdu(self, pdu: bytes) -> None:
         if self.sink is None:
             logger.warning('received pdu without a sink')
             return
 
-        if self.state != self.CONNECTED:
+        if self.state != self.State.CONNECTED:
             logger.warning('received PDU while not connected, dropping')
 
         # Manage the peer credits
@@ -1240,7 +1239,7 @@ class LeConnectionOrientedChannel(EventEmitter):
             self.credits = response.initial_credits
             self.connected = True
             self.connection_result.set_result(self)
-            self.change_state(self.CONNECTED)
+            self._change_state(self.State.CONNECTED)
         else:
             self.connection_result.set_exception(
                 ProtocolError(
@@ -1251,7 +1250,7 @@ class LeConnectionOrientedChannel(EventEmitter):
                     ),
                 )
             )
-            self.change_state(self.CONNECTION_ERROR)
+            self._change_state(self.State.CONNECTION_ERROR)
 
         # Cleanup
         self.connection_result = None
@@ -1271,11 +1270,11 @@ class LeConnectionOrientedChannel(EventEmitter):
                 source_cid=request.source_cid,
             )
         )
-        self.change_state(self.DISCONNECTED)
+        self._change_state(self.State.DISCONNECTED)
         self.flush_output()
 
     def on_disconnection_response(self, response) -> None:
-        if self.state != self.DISCONNECTING:
+        if self.state != self.State.DISCONNECTING:
             logger.warning(color('invalid state', 'red'))
             return
 
@@ -1286,7 +1285,7 @@ class LeConnectionOrientedChannel(EventEmitter):
             logger.warning('unexpected source or destination CID')
             return
 
-        self.change_state(self.DISCONNECTED)
+        self._change_state(self.State.DISCONNECTED)
         if self.disconnection_result:
             self.disconnection_result.set_result(None)
             self.disconnection_result = None
@@ -1339,7 +1338,7 @@ class LeConnectionOrientedChannel(EventEmitter):
                 return
 
     def write(self, data: bytes) -> None:
-        if self.state != self.CONNECTED:
+        if self.state != self.State.CONNECTED:
             logger.warning('not connected, dropping data')
             return
 
@@ -1367,7 +1366,7 @@ class LeConnectionOrientedChannel(EventEmitter):
     def __str__(self) -> str:
         return (
             f'CoC({self.source_cid}->{self.destination_cid}, '
-            f'State={self.state_name(self.state)}, '
+            f'State={self.state.name}, '
             f'PSM={self.le_psm}, '
             f'MTU={self.mtu}/{self.peer_mtu}, '
             f'MPS={self.mps}/{self.peer_mps}, '
@@ -1375,18 +1374,71 @@ class LeConnectionOrientedChannel(EventEmitter):
         )
 
 
+# -----------------------------------------------------------------------------
+class ClassicChannelServer(EventEmitter):
+    def __init__(
+        self,
+        manager: ChannelManager,
+        psm: int,
+        handler: Optional[Callable[[ClassicChannel], Any]],
+        mtu: int,
+    ) -> None:
+        super().__init__()
+        self.manager = manager
+        self.handler = handler
+        self.psm = psm
+        self.mtu = mtu
+
+    def on_connection(self, channel: ClassicChannel) -> None:
+        self.emit('connection', channel)
+        if self.handler:
+            self.handler(channel)
+
+    def close(self) -> None:
+        if self.psm in self.manager.servers:
+            del self.manager.servers[self.psm]
+
+
+# -----------------------------------------------------------------------------
+class LeCreditBasedChannelServer(EventEmitter):
+    def __init__(
+        self,
+        manager: ChannelManager,
+        psm: int,
+        handler: Optional[Callable[[LeCreditBasedChannel], Any]],
+        max_credits: int,
+        mtu: int,
+        mps: int,
+    ) -> None:
+        super().__init__()
+        self.manager = manager
+        self.handler = handler
+        self.psm = psm
+        self.max_credits = max_credits
+        self.mtu = mtu
+        self.mps = mps
+
+    def on_connection(self, channel: LeCreditBasedChannel) -> None:
+        self.emit('connection', channel)
+        if self.handler:
+            self.handler(channel)
+
+    def close(self) -> None:
+        if self.psm in self.manager.le_coc_servers:
+            del self.manager.le_coc_servers[self.psm]
+
+
 # -----------------------------------------------------------------------------
 class ChannelManager:
     identifiers: Dict[int, int]
-    channels: Dict[int, Dict[int, Union[Channel, LeConnectionOrientedChannel]]]
-    servers: Dict[int, Callable[[Channel], Any]]
-    le_coc_channels: Dict[int, Dict[int, LeConnectionOrientedChannel]]
-    le_coc_servers: Dict[
-        int, Tuple[Callable[[LeConnectionOrientedChannel], Any], int, int, int]
-    ]
+    channels: Dict[int, Dict[int, Union[ClassicChannel, LeCreditBasedChannel]]]
+    servers: Dict[int, ClassicChannelServer]
+    le_coc_channels: Dict[int, Dict[int, LeCreditBasedChannel]]
+    le_coc_servers: Dict[int, LeCreditBasedChannelServer]
     le_coc_requests: Dict[int, L2CAP_LE_Credit_Based_Connection_Request]
     fixed_channels: Dict[int, Optional[Callable[[int, bytes], Any]]]
     _host: Optional[Host]
+    connection_parameters_update_response: Optional[asyncio.Future[int]]
 
     def __init__(
         self,
@@ -1408,6 +1460,7 @@ class ChannelManager:
         self.le_coc_requests = {}  # LE CoC connection requests, by identifier
         self.extended_features = extended_features
         self.connectionless_mtu = connectionless_mtu
+        self.connection_parameters_update_response = None
 
     @property
     def host(self) -> Host:
@@ -1460,21 +1513,6 @@ class ChannelManager:
 
         raise RuntimeError('no free CID')
 
-    @staticmethod
-    def check_le_coc_parameters(max_credits: int, mtu: int, mps: int) -> None:
-        if (
-            max_credits < 1
-            or max_credits > L2CAP_LE_CREDIT_BASED_CONNECTION_MAX_CREDITS
-        ):
-            raise ValueError('max credits out of range')
-        if mtu < L2CAP_LE_CREDIT_BASED_CONNECTION_MIN_MTU:
-            raise ValueError('MTU too small')
-        if (
-            mps < L2CAP_LE_CREDIT_BASED_CONNECTION_MIN_MPS
-            or mps > L2CAP_LE_CREDIT_BASED_CONNECTION_MAX_MPS
-        ):
-            raise ValueError('MPS out of range')
-
     def next_identifier(self, connection: Connection) -> int:
         identifier = (self.identifiers.setdefault(connection.handle, 0) + 1) % 256
         self.identifiers[connection.handle] = identifier
@@ -1489,8 +1527,22 @@ class ChannelManager:
         if cid in self.fixed_channels:
             del self.fixed_channels[cid]
 
-    def register_server(self, psm: int, server: Callable[[Channel], Any]) -> int:
-        if psm == 0:
+    @deprecated("Please use create_classic_server")
+    def register_server(
+        self,
+        psm: int,
+        server: Callable[[ClassicChannel], Any],
+    ) -> int:
+        return self.create_classic_server(
+            handler=server, spec=ClassicChannelSpec(psm=psm)
+        ).psm
+
+    def create_classic_server(
+        self,
+        spec: ClassicChannelSpec,
+        handler: Optional[Callable[[ClassicChannel], Any]] = None,
+    ) -> ClassicChannelServer:
+        if not spec.psm:
             # Find a free PSM
             for candidate in range(
                 L2CAP_PSM_DYNAMIC_RANGE_START, L2CAP_PSM_DYNAMIC_RANGE_END + 1, 2
@@ -1499,62 +1551,75 @@ class ChannelManager:
                     continue
                 if candidate in self.servers:
                     continue
-                psm = candidate
+                spec.psm = candidate
                 break
             else:
                 raise InvalidStateError('no free PSM')
         else:
             # Check that the PSM isn't already in use
-            if psm in self.servers:
+            if spec.psm in self.servers:
                 raise ValueError('PSM already in use')
 
             # Check that the PSM is valid
-            if psm % 2 == 0:
+            if spec.psm % 2 == 0:
                 raise ValueError('invalid PSM (not odd)')
-            check = psm >> 8
+            check = spec.psm >> 8
             while check:
                 if check % 2 != 0:
                     raise ValueError('invalid PSM')
                 check >>= 8
 
-        self.servers[psm] = server
+        self.servers[spec.psm] = ClassicChannelServer(self, spec.psm, handler, spec.mtu)
 
-        return psm
+        return self.servers[spec.psm]
 
+    @deprecated("Please use create_le_credit_based_server()")
     def register_le_coc_server(
         self,
         psm: int,
-        server: Callable[[LeConnectionOrientedChannel], Any],
-        max_credits: int = L2CAP_LE_CREDIT_BASED_CONNECTION_DEFAULT_INITIAL_CREDITS,
-        mtu: int = L2CAP_LE_CREDIT_BASED_CONNECTION_DEFAULT_MTU,
-        mps: int = L2CAP_LE_CREDIT_BASED_CONNECTION_DEFAULT_MPS,
+        server: Callable[[LeCreditBasedChannel], Any],
+        max_credits: int,
+        mtu: int,
+        mps: int,
     ) -> int:
-        self.check_le_coc_parameters(max_credits, mtu, mps)
+        return self.create_le_credit_based_server(
+            spec=LeCreditBasedChannelSpec(
+                psm=None if psm == 0 else psm, mtu=mtu, mps=mps, max_credits=max_credits
+            ),
+            handler=server,
+        ).psm
 
-        if psm == 0:
+    def create_le_credit_based_server(
+        self,
+        spec: LeCreditBasedChannelSpec,
+        handler: Optional[Callable[[LeCreditBasedChannel], Any]] = None,
+    ) -> LeCreditBasedChannelServer:
+        if not spec.psm:
             # Find a free PSM
             for candidate in range(
                 L2CAP_LE_PSM_DYNAMIC_RANGE_START, L2CAP_LE_PSM_DYNAMIC_RANGE_END + 1
             ):
                 if candidate in self.le_coc_servers:
                     continue
-                psm = candidate
+                spec.psm = candidate
                 break
             else:
                 raise InvalidStateError('no free PSM')
         else:
             # Check that the PSM isn't already in use
-            if psm in self.le_coc_servers:
+            if spec.psm in self.le_coc_servers:
                 raise ValueError('PSM already in use')
 
-        self.le_coc_servers[psm] = (
-            server,
-            max_credits or L2CAP_LE_CREDIT_BASED_CONNECTION_DEFAULT_INITIAL_CREDITS,
-            mtu or L2CAP_LE_CREDIT_BASED_CONNECTION_DEFAULT_MTU,
-            mps or L2CAP_LE_CREDIT_BASED_CONNECTION_DEFAULT_MPS,
+        self.le_coc_servers[spec.psm] = LeCreditBasedChannelServer(
+            self,
+            spec.psm,
+            handler,
+            max_credits=spec.max_credits,
+            mtu=spec.mtu,
+            mps=spec.mps,
         )
 
-        return psm
+        return self.le_coc_servers[spec.psm]
 
     def on_disconnection(self, connection_handle: int, _reason: int) -> None:
         logger.debug(f'disconnection from {connection_handle}, cleaning up channels')
@@ -1569,7 +1634,7 @@ class ChannelManager:
         if connection_handle in self.identifiers:
             del self.identifiers[connection_handle]
 
-    def send_pdu(self, connection, cid: int, pdu: SupportsBytes | bytes) -> None:
+    def send_pdu(self, connection, cid: int, pdu: Union[SupportsBytes, bytes]) -> None:
         pdu_str = pdu.hex() if isinstance(pdu, bytes) else str(pdu)
         logger.debug(
             f'{color(">>> Sending L2CAP PDU", "blue")} '
@@ -1681,13 +1746,13 @@ class ChannelManager:
             logger.debug(
                 f'creating server channel with cid={source_cid} for psm {request.psm}'
             )
-            channel = Channel(
-                self, connection, cid, request.psm, source_cid, L2CAP_MIN_BR_EDR_MTU
+            channel = ClassicChannel(
+                self, connection, cid, request.psm, source_cid, server.mtu
             )
             connection_channels[source_cid] = channel
 
             # Notify
-            server(channel)
+            server.on_connection(channel)
             channel.on_connection_request(request)
         else:
             logger.warning(
@@ -1865,17 +1930,51 @@ class ChannelManager:
                 ),
             )
 
+    async def update_connection_parameters(
+        self,
+        connection: Connection,
+        interval_min: int,
+        interval_max: int,
+        latency: int,
+        timeout: int,
+    ) -> int:
+        # Check that there isn't already a request pending
+        if self.connection_parameters_update_response:
+            raise InvalidStateError('request already pending')
+        self.connection_parameters_update_response = (
+            asyncio.get_running_loop().create_future()
+        )
+        self.send_control_frame(
+            connection,
+            L2CAP_LE_SIGNALING_CID,
+            L2CAP_Connection_Parameter_Update_Request(
+                interval_min=interval_min,
+                interval_max=interval_max,
+                latency=latency,
+                timeout=timeout,
+            ),
+        )
+        return await self.connection_parameters_update_response
+
     def on_l2cap_connection_parameter_update_response(
         self, connection: Connection, cid: int, response
     ) -> None:
-        # TODO: check response
-        pass
+        if self.connection_parameters_update_response:
+            self.connection_parameters_update_response.set_result(response.result)
+            self.connection_parameters_update_response = None
+        else:
+            logger.warning(
+                color(
+                    'received l2cap_connection_parameter_update_response without a pending request',
+                    'red',
+                )
+            )
 
     def on_l2cap_le_credit_based_connection_request(
         self, connection: Connection, cid: int, request
     ) -> None:
         if request.le_psm in self.le_coc_servers:
-            (server, max_credits, mtu, mps) = self.le_coc_servers[request.le_psm]
+            server = self.le_coc_servers[request.le_psm]
 
             # Check that the CID isn't already used
             le_connection_channels = self.le_coc_channels.setdefault(
@@ -1889,8 +1988,8 @@ class ChannelManager:
                     L2CAP_LE_Credit_Based_Connection_Response(
                         identifier=request.identifier,
                         destination_cid=0,
-                        mtu=mtu,
-                        mps=mps,
+                        mtu=server.mtu,
+                        mps=server.mps,
                         initial_credits=0,
                         # pylint: disable=line-too-long
                         result=L2CAP_LE_Credit_Based_Connection_Response.CONNECTION_REFUSED_SOURCE_CID_ALREADY_ALLOCATED,
@@ -1908,8 +2007,8 @@ class ChannelManager:
                     L2CAP_LE_Credit_Based_Connection_Response(
                         identifier=request.identifier,
                         destination_cid=0,
-                        mtu=mtu,
-                        mps=mps,
+                        mtu=server.mtu,
+                        mps=server.mps,
                         initial_credits=0,
                         # pylint: disable=line-too-long
                         result=L2CAP_LE_Credit_Based_Connection_Response.CONNECTION_REFUSED_NO_RESOURCES_AVAILABLE,
@@ -1922,18 +2021,18 @@ class ChannelManager:
                 f'creating LE CoC server channel with cid={source_cid} for psm '
                 f'{request.le_psm}'
             )
-            channel = LeConnectionOrientedChannel(
+            channel = LeCreditBasedChannel(
                 self,
                 connection,
                 request.le_psm,
                 source_cid,
                 request.source_cid,
-                mtu,
-                mps,
+                server.mtu,
+                server.mps,
                 request.initial_credits,
                 request.mtu,
                 request.mps,
-                max_credits,
+                server.max_credits,
                 True,
             )
             connection_channels[source_cid] = channel
@@ -1946,16 +2045,16 @@ class ChannelManager:
                 L2CAP_LE_Credit_Based_Connection_Response(
                     identifier=request.identifier,
                     destination_cid=source_cid,
-                    mtu=mtu,
-                    mps=mps,
-                    initial_credits=max_credits,
+                    mtu=server.mtu,
+                    mps=server.mps,
+                    initial_credits=server.max_credits,
                     # pylint: disable=line-too-long
                     result=L2CAP_LE_Credit_Based_Connection_Response.CONNECTION_SUCCESSFUL,
                 ),
             )
 
             # Notify
-            server(channel)
+            server.on_connection(channel)
         else:
             logger.info(
                 f'No LE server for connection 0x{connection.handle:04X} '
@@ -2010,37 +2109,51 @@ class ChannelManager:
 
         channel.on_credits(credit.credits)
 
-    def on_channel_closed(self, channel: Channel) -> None:
+    def on_channel_closed(self, channel: ClassicChannel) -> None:
         connection_channels = self.channels.get(channel.connection.handle)
         if connection_channels:
             if channel.source_cid in connection_channels:
                 del connection_channels[channel.source_cid]
 
+    @deprecated("Please use create_le_credit_based_channel()")
     async def open_le_coc(
         self, connection: Connection, psm: int, max_credits: int, mtu: int, mps: int
-    ) -> LeConnectionOrientedChannel:
-        self.check_le_coc_parameters(max_credits, mtu, mps)
+    ) -> LeCreditBasedChannel:
+        return await self.create_le_credit_based_channel(
+            connection=connection,
+            spec=LeCreditBasedChannelSpec(
+                psm=psm, max_credits=max_credits, mtu=mtu, mps=mps
+            ),
+        )
 
+    async def create_le_credit_based_channel(
+        self,
+        connection: Connection,
+        spec: LeCreditBasedChannelSpec,
+    ) -> LeCreditBasedChannel:
         # Find a free CID for the new channel
         connection_channels = self.channels.setdefault(connection.handle, {})
         source_cid = self.find_free_le_cid(connection_channels)
         if source_cid is None:  # Should never happen!
             raise RuntimeError('all CIDs already in use')
 
+        if spec.psm is None:
+            raise ValueError('PSM cannot be None')
+
         # Create the channel
-        logger.debug(f'creating coc channel with cid={source_cid} for psm {psm}')
-        channel = LeConnectionOrientedChannel(
+        logger.debug(f'creating coc channel with cid={source_cid} for psm {spec.psm}')
+        channel = LeCreditBasedChannel(
             manager=self,
             connection=connection,
-            le_psm=psm,
+            le_psm=spec.psm,
             source_cid=source_cid,
             destination_cid=0,
-            mtu=mtu,
-            mps=mps,
+            mtu=spec.mtu,
+            mps=spec.mps,
             credits=0,
             peer_mtu=0,
             peer_mps=0,
-            peer_credits=max_credits,
+            peer_credits=spec.max_credits,
             connected=False,
         )
         connection_channels[source_cid] = channel
@@ -2059,7 +2172,15 @@ class ChannelManager:
 
         return channel
 
-    async def connect(self, connection: Connection, psm: int) -> Channel:
+    @deprecated("Please use create_classic_channel()")
+    async def connect(self, connection: Connection, psm: int) -> ClassicChannel:
+        return await self.create_classic_channel(
+            connection=connection, spec=ClassicChannelSpec(psm=psm)
+        )
+
+    async def create_classic_channel(
+        self, connection: Connection, spec: ClassicChannelSpec
+    ) -> ClassicChannel:
         # NOTE: this implementation hard-codes BR/EDR
 
         # Find a free CID for a new channel
@@ -2068,17 +2189,45 @@ class ChannelManager:
         if source_cid is None:  # Should never happen!
             raise RuntimeError('all CIDs already in use')
 
+        if spec.psm is None:
+            raise ValueError('PSM cannot be None')
+
         # Create the channel
-        logger.debug(f'creating client channel with cid={source_cid} for psm {psm}')
-        channel = Channel(
-            self, connection, L2CAP_SIGNALING_CID, psm, source_cid, L2CAP_MIN_BR_EDR_MTU
+        logger.debug(
+            f'creating client channel with cid={source_cid} for psm {spec.psm}'
+        )
+        channel = ClassicChannel(
+            self,
+            connection,
+            L2CAP_SIGNALING_CID,
+            spec.psm,
+            source_cid,
+            spec.mtu,
         )
         connection_channels[source_cid] = channel
 
         # Connect
         try:
             await channel.connect()
-        except Exception:
+        except Exception as e:
             del connection_channels[source_cid]
+            raise e
 
         return channel
+
+
+# -----------------------------------------------------------------------------
+# Deprecated Classes
+# -----------------------------------------------------------------------------
+
+
+class Channel(ClassicChannel):
+    @deprecated("Please use ClassicChannel")
+    def __init__(self, *args, **kwargs) -> None:
+        super().__init__(*args, **kwargs)
+
+
+class LeConnectionOrientedChannel(LeCreditBasedChannel):
+    @deprecated("Please use LeCreditBasedChannel")
+    def __init__(self, *args, **kwargs) -> None:
+        super().__init__(*args, **kwargs)

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/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,7 +887,7 @@ 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
@@ -838,8 +898,8 @@ 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}')
@@ -876,7 +936,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 +962,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,7 +758,7 @@ class SDP_ServiceSearchAttributeResponse(SDP_PDU):
 
 # -----------------------------------------------------------------------------
 class Client:
-    channel: Optional[l2cap.Channel]
+    channel: Optional[l2cap.ClassicChannel]
 
     def __init__(self, device: Device) -> None:
         self.device = device
@@ -766,8 +766,9 @@ class Client:
         self.channel = None
 
     async def connect(self, connection: Connection) -> None:
-        result = await self.device.l2cap_channel_manager.connect(connection, SDP_PSM)
-        self.channel = result
+        self.channel = await 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,
 )
@@ -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 = bytes(reversed(self.ecc_key.x))
+        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
@@ -639,8 +690,6 @@ class Session:
         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
@@ -658,7 +707,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 +760,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 +777,37 @@ 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 None:
+                    self.tk = None
+                else:
+                    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 (bytes(reversed(self.ecc_key.x)), 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=bytes(reversed(self.ecc_key.x)),
+                public_key_y=bytes(reversed(self.ecc_key.y)),
             )
         )
 
@@ -1029,7 +1109,6 @@ class Session:
         self.ltk = crypto.h6(ilk, b'brle')
 
     def distribute_keys(self) -> None:
-
         # Distribute the keys as required
         if self.is_initiator:
             # CTKD: Derive LTK from LinkKey
@@ -1295,7 +1374,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 +1411,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 +1481,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 +1651,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 +1694,7 @@ class Session:
         if self.pairing_method in (
             PairingMethod.JUST_WORKS,
             PairingMethod.NUMERIC_COMPARISON,
+            PairingMethod.OOB,
         ):
             ra = bytes(16)
             rb = ra
@@ -1598,7 +1703,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
@@ -1652,7 +1756,7 @@ class Session:
         # Compute the DH key
         self.dh_key = bytes(
             reversed(
-                self.manager.ecc_key.dh(
+                self.ecc_key.dh(
                     bytes(reversed(command.public_key_x)),
                     bytes(reversed(command.public_key_y)),
                 )
@@ -1660,8 +1764,27 @@ class Session:
         )
         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 +1795,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()
@@ -1771,7 +1895,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 +1925,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]
@@ -135,7 +155,7 @@ class PacketParser:
                             )
                     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

@@ -60,7 +60,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:

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

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,24 @@ 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
+  - 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 +83,8 @@ theme:
   logo: 'images/logo.png'
   favicon: 'images/favicon.ico'
   custom_dir: 'theme'
+  features:
+    - navigation.indexes
 
 plugins:
   - mkdocstrings:
@@ -98,6 +109,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_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,11 @@
+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.

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

@@ -131,7 +131,7 @@ async def main():
             await device.power_on()
 
             # Create a listener to wait for AVDTP connections
-            listener = Listener(Listener.create_registrar(device))
+            listener = Listener.for_device(device)
             listener.on('connection', on_avdtp_connection)
 
             if len(sys.argv) >= 5:

examples/run_a2dp_source.py

@@ -179,7 +179,7 @@ async def main():
                 await stream_packets(read, protocol)
             else:
                 # Create a listener to wait for AVDTP connections
-                listener = Listener(Listener.create_registrar(device), version=(1, 2))
+                listener = Listener.for_device(device=device, version=(1, 2))
                 listener.on(
                     'connection', lambda protocol: on_avdtp_connection(read, protocol)
                 )

examples/run_asha_sink.py

@@ -21,6 +21,7 @@ import sys
 import os
 import logging
 
+from bumble import l2cap
 from bumble.core import AdvertisingData
 from bumble.device import Device
 from bumble.transport import open_transport_or_link
@@ -95,8 +96,10 @@ async def main():
 
             channel.sink = on_data
 
-        psm = device.register_l2cap_channel_server(0, on_coc, 8)
-        print(f'### LE_PSM_OUT = {psm}')
+        server = device.create_l2cap_server(
+            spec=l2cap.LeCreditBasedChannelSpec(max_credits=8), handler=on_coc
+        )
+        print(f'### LE_PSM_OUT = {server.psm}')
 
         # Add the ASHA service to the GATT server
         read_only_properties_characteristic = Characteristic(
@@ -147,7 +150,7 @@ async def main():
             ASHA_LE_PSM_OUT_CHARACTERISTIC,
             Characteristic.Properties.READ,
             Characteristic.READABLE,
-            struct.pack('<H', psm),
+            struct.pack('<H', server.psm),
         )
         device.add_service(
             Service(

examples/run_hfp_gateway.py

@@ -16,11 +16,9 @@
 # Imports
 # -----------------------------------------------------------------------------
 import asyncio
-import collections
 import sys
 import os
 import logging
-from typing import Union
 
 from bumble.colors import color
 
@@ -32,8 +30,8 @@ from bumble.core import (
     BT_RFCOMM_PROTOCOL_ID,
     BT_BR_EDR_TRANSPORT,
 )
-from bumble import rfcomm
-from bumble.rfcomm import Client
+from bumble import rfcomm, hfp
+from bumble.hci import HCI_SynchronousDataPacket
 from bumble.sdp import (
     Client as SDP_Client,
     DataElement,
@@ -47,61 +45,6 @@ from bumble.sdp import (
 logger = logging.getLogger(__name__)
 
 
-# -----------------------------------------------------------------------------
-# Protocol Support
-# -----------------------------------------------------------------------------
-
-# -----------------------------------------------------------------------------
-class HfpProtocol:
-    dlc: rfcomm.DLC
-    buffer: str
-    lines: collections.deque
-    lines_available: asyncio.Event
-
-    def __init__(self, dlc: rfcomm.DLC) -> None:
-        self.dlc = dlc
-        self.buffer = ''
-        self.lines = collections.deque()
-        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
-
-
 # -----------------------------------------------------------------------------
 # pylint: disable-next=too-many-nested-blocks
 async def list_rfcomm_channels(device, connection):
@@ -241,7 +184,7 @@ async def main():
 
         # Create a client and start it
         print('@@@ Starting to RFCOMM client...')
-        rfcomm_client = Client(device, connection)
+        rfcomm_client = rfcomm.Client(device, connection)
         rfcomm_mux = await rfcomm_client.start()
         print('@@@ Started')
 
@@ -255,8 +198,15 @@ async def main():
             print('@@@ Disconnected from RFCOMM server')
             return
 
+        def on_sco(connection_handle: int, packet: HCI_SynchronousDataPacket):
+            # Reset packet and loopback
+            packet.packet_status = 0
+            device.host.send_hci_packet(packet)
+
+        device.host.on('sco_packet', on_sco)
+
         # Protocol loop (just for testing at this point)
-        protocol = HfpProtocol(session)
+        protocol = hfp.HfpProtocol(session)
         while True:
             line = await protocol.next_line()
 

examples/run_hid_host.py

@@ -0,0 +1,540 @@
+# Copyright 2021-2022 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# -----------------------------------------------------------------------------
+# Imports
+# -----------------------------------------------------------------------------
+import asyncio
+import sys
+import os
+import logging
+
+from bumble.colors import color
+
+import bumble.core
+from bumble.device import Device
+from bumble.transport import open_transport_or_link
+from bumble.core import (
+    BT_L2CAP_PROTOCOL_ID,
+    BT_HIDP_PROTOCOL_ID,
+    BT_HUMAN_INTERFACE_DEVICE_SERVICE,
+    BT_BR_EDR_TRANSPORT,
+)
+from bumble.hci import Address
+from bumble.hid import Host, Message
+from bumble.sdp import (
+    Client as SDP_Client,
+    DataElement,
+    ServiceAttribute,
+    SDP_PROTOCOL_DESCRIPTOR_LIST_ATTRIBUTE_ID,
+    SDP_SERVICE_CLASS_ID_LIST_ATTRIBUTE_ID,
+    SDP_BLUETOOTH_PROFILE_DESCRIPTOR_LIST_ATTRIBUTE_ID,
+    SDP_ALL_ATTRIBUTES_RANGE,
+    SDP_LANGUAGE_BASE_ATTRIBUTE_ID_LIST_ATTRIBUTE_ID,
+    SDP_ADDITIONAL_PROTOCOL_DESCRIPTOR_LIST_ATTRIBUTE_ID,
+    SDP_SERVICE_RECORD_HANDLE_ATTRIBUTE_ID,
+    SDP_BROWSE_GROUP_LIST_ATTRIBUTE_ID,
+)
+from hid_report_parser import ReportParser
+
+# -----------------------------------------------------------------------------
+# SDP attributes for Bluetooth HID devices
+SDP_HID_SERVICE_NAME_ATTRIBUTE_ID = 0x0100
+SDP_HID_SERVICE_DESCRIPTION_ATTRIBUTE_ID = 0x0101
+SDP_HID_PROVIDER_NAME_ATTRIBUTE_ID = 0x0102
+SDP_HID_DEVICE_RELEASE_NUMBER_ATTRIBUTE_ID = 0x0200  # [DEPRECATED]
+SDP_HID_PARSER_VERSION_ATTRIBUTE_ID = 0x0201
+SDP_HID_DEVICE_SUBCLASS_ATTRIBUTE_ID = 0x0202
+SDP_HID_COUNTRY_CODE_ATTRIBUTE_ID = 0x0203
+SDP_HID_VIRTUAL_CABLE_ATTRIBUTE_ID = 0x0204
+SDP_HID_RECONNECT_INITIATE_ATTRIBUTE_ID = 0x0205
+SDP_HID_DESCRIPTOR_LIST_ATTRIBUTE_ID = 0x0206
+SDP_HID_LANGID_BASE_LIST_ATTRIBUTE_ID = 0x0207
+SDP_HID_SDP_DISABLE_ATTRIBUTE_ID = 0x0208  # [DEPRECATED]
+SDP_HID_BATTERY_POWER_ATTRIBUTE_ID = 0x0209
+SDP_HID_REMOTE_WAKE_ATTRIBUTE_ID = 0x020A
+SDP_HID_PROFILE_VERSION_ATTRIBUTE_ID = 0x020B  # DEPRECATED]
+SDP_HID_SUPERVISION_TIMEOUT_ATTRIBUTE_ID = 0x020C
+SDP_HID_NORMALLY_CONNECTABLE_ATTRIBUTE_ID = 0x020D
+SDP_HID_BOOT_DEVICE_ATTRIBUTE_ID = 0x020E
+SDP_HID_SSR_HOST_MAX_LATENCY_ATTRIBUTE_ID = 0x020F
+SDP_HID_SSR_HOST_MIN_TIMEOUT_ATTRIBUTE_ID = 0x0210
+
+
+# -----------------------------------------------------------------------------
+
+
+async def get_hid_device_sdp_record(device, connection):
+
+    # Connect to the SDP Server
+    sdp_client = SDP_Client(device)
+    await sdp_client.connect(connection)
+    if sdp_client:
+        print(color('Connected to SDP Server', 'blue'))
+    else:
+        print(color('Failed to connect to SDP Server', 'red'))
+
+    # List BT HID Device service in the root browse group
+    service_record_handles = await sdp_client.search_services(
+        [BT_HUMAN_INTERFACE_DEVICE_SERVICE]
+    )
+
+    if len(service_record_handles) < 1:
+        await sdp_client.disconnect()
+        raise Exception(
+            color(f'BT HID Device service not found on peer device!!!!', 'red')
+        )
+
+    # For BT_HUMAN_INTERFACE_DEVICE_SERVICE service, get all its attributes
+    for service_record_handle in service_record_handles:
+        attributes = await sdp_client.get_attributes(
+            service_record_handle, [SDP_ALL_ATTRIBUTES_RANGE]
+        )
+        print(color(f'SERVICE {service_record_handle:04X} attributes:', 'yellow'))
+        print(color(f'SDP attributes for HID device', 'magenta'))
+        for attribute in attributes:
+            if attribute.id == SDP_SERVICE_RECORD_HANDLE_ATTRIBUTE_ID:
+                print(
+                    color('  Service Record Handle : ', 'cyan'),
+                    hex(attribute.value.value),
+                )
+
+            elif attribute.id == SDP_SERVICE_CLASS_ID_LIST_ATTRIBUTE_ID:
+                print(
+                    color('  Service Class : ', 'cyan'), attribute.value.value[0].value
+                )
+
+            elif attribute.id == SDP_BROWSE_GROUP_LIST_ATTRIBUTE_ID:
+                print(
+                    color('  SDP Browse Group List : ', 'cyan'),
+                    attribute.value.value[0].value,
+                )
+
+            elif attribute.id == SDP_PROTOCOL_DESCRIPTOR_LIST_ATTRIBUTE_ID:
+                print(
+                    color('  BT_L2CAP_PROTOCOL_ID : ', 'cyan'),
+                    attribute.value.value[0].value[0].value,
+                )
+                print(
+                    color('  PSM for Bluetooth HID Control channel : ', 'cyan'),
+                    hex(attribute.value.value[0].value[1].value),
+                )
+                print(
+                    color('  BT_HIDP_PROTOCOL_ID : ', 'cyan'),
+                    attribute.value.value[1].value[0].value,
+                )
+
+            elif attribute.id == SDP_LANGUAGE_BASE_ATTRIBUTE_ID_LIST_ATTRIBUTE_ID:
+                print(
+                    color('  Lanugage : ', 'cyan'), hex(attribute.value.value[0].value)
+                )
+                print(
+                    color('  Encoding : ', 'cyan'), hex(attribute.value.value[1].value)
+                )
+                print(
+                    color('  PrimaryLanguageBaseID : ', 'cyan'),
+                    hex(attribute.value.value[2].value),
+                )
+
+            elif attribute.id == SDP_BLUETOOTH_PROFILE_DESCRIPTOR_LIST_ATTRIBUTE_ID:
+                print(
+                    color('  BT_HUMAN_INTERFACE_DEVICE_SERVICE ', 'cyan'),
+                    attribute.value.value[0].value[0].value,
+                )
+                print(
+                    color('  HID Profileversion number : ', 'cyan'),
+                    hex(attribute.value.value[0].value[1].value),
+                )
+
+            elif attribute.id == SDP_ADDITIONAL_PROTOCOL_DESCRIPTOR_LIST_ATTRIBUTE_ID:
+                print(
+                    color('  BT_L2CAP_PROTOCOL_ID : ', 'cyan'),
+                    attribute.value.value[0].value[0].value[0].value,
+                )
+                print(
+                    color('  PSM for Bluetooth HID Interrupt channel : ', 'cyan'),
+                    hex(attribute.value.value[0].value[0].value[1].value),
+                )
+                print(
+                    color('  BT_HIDP_PROTOCOL_ID : ', 'cyan'),
+                    attribute.value.value[0].value[1].value[0].value,
+                )
+
+            elif attribute.id == SDP_HID_SERVICE_NAME_ATTRIBUTE_ID:
+                print(color('  Service Name: ', 'cyan'), attribute.value.value)
+
+            elif attribute.id == SDP_HID_SERVICE_DESCRIPTION_ATTRIBUTE_ID:
+                print(color('  Service Description: ', 'cyan'), attribute.value.value)
+
+            elif attribute.id == SDP_HID_PROVIDER_NAME_ATTRIBUTE_ID:
+                print(color('  Provider Name: ', 'cyan'), attribute.value.value)
+
+            elif attribute.id == SDP_HID_DEVICE_RELEASE_NUMBER_ATTRIBUTE_ID:
+                print(color('  Release Number: ', 'cyan'), hex(attribute.value.value))
+
+            elif attribute.id == SDP_HID_PARSER_VERSION_ATTRIBUTE_ID:
+                print(
+                    color('  HID Parser Version: ', 'cyan'), hex(attribute.value.value)
+                )
+
+            elif attribute.id == SDP_HID_DEVICE_SUBCLASS_ATTRIBUTE_ID:
+                print(
+                    color('  HIDDeviceSubclass: ', 'cyan'), hex(attribute.value.value)
+                )
+
+            elif attribute.id == SDP_HID_COUNTRY_CODE_ATTRIBUTE_ID:
+                print(color('  HIDCountryCode: ', 'cyan'), hex(attribute.value.value))
+
+            elif attribute.id == SDP_HID_VIRTUAL_CABLE_ATTRIBUTE_ID:
+                print(color('  HIDVirtualCable: ', 'cyan'), attribute.value.value)
+
+            elif attribute.id == SDP_HID_RECONNECT_INITIATE_ATTRIBUTE_ID:
+                print(color('  HIDReconnectInitiate: ', 'cyan'), attribute.value.value)
+
+            elif attribute.id == SDP_HID_DESCRIPTOR_LIST_ATTRIBUTE_ID:
+                print(
+                    color('  HID Report Descriptor type: ', 'cyan'),
+                    hex(attribute.value.value[0].value[0].value),
+                )
+                print(
+                    color('  HID Report DescriptorList: ', 'cyan'),
+                    attribute.value.value[0].value[1].value,
+                )
+
+            elif attribute.id == SDP_HID_LANGID_BASE_LIST_ATTRIBUTE_ID:
+                print(
+                    color('  HID LANGID Base Language: ', 'cyan'),
+                    hex(attribute.value.value[0].value[0].value),
+                )
+                print(
+                    color('  HID LANGID Base Bluetooth String Offset: ', 'cyan'),
+                    hex(attribute.value.value[0].value[1].value),
+                )
+
+            elif attribute.id == SDP_HID_BATTERY_POWER_ATTRIBUTE_ID:
+                print(color('  HIDBatteryPower: ', 'cyan'), attribute.value.value)
+
+            elif attribute.id == SDP_HID_REMOTE_WAKE_ATTRIBUTE_ID:
+                print(color('  HIDRemoteWake: ', 'cyan'), attribute.value.value)
+
+            elif attribute.id == SDP_HID_PROFILE_VERSION_ATTRIBUTE_ID:
+                print(
+                    color('  HIDProfileVersion : ', 'cyan'), hex(attribute.value.value)
+                )
+
+            elif attribute.id == SDP_HID_SUPERVISION_TIMEOUT_ATTRIBUTE_ID:
+                print(
+                    color('  HIDSupervisionTimeout: ', 'cyan'),
+                    hex(attribute.value.value),
+                )
+
+            elif attribute.id == SDP_HID_NORMALLY_CONNECTABLE_ATTRIBUTE_ID:
+                print(
+                    color('  HIDNormallyConnectable: ', 'cyan'), attribute.value.value
+                )
+
+            elif attribute.id == SDP_HID_BOOT_DEVICE_ATTRIBUTE_ID:
+                print(color('  HIDBootDevice: ', 'cyan'), attribute.value.value)
+
+            elif attribute.id == SDP_HID_SSR_HOST_MAX_LATENCY_ATTRIBUTE_ID:
+                print(
+                    color('  HIDSSRHostMaxLatency: ', 'cyan'),
+                    hex(attribute.value.value),
+                )
+
+            elif attribute.id == SDP_HID_SSR_HOST_MIN_TIMEOUT_ATTRIBUTE_ID:
+                print(
+                    color('  HIDSSRHostMinTimeout: ', 'cyan'),
+                    hex(attribute.value.value),
+                )
+
+            else:
+                print(
+                    color(
+                        f'  Warning: Attribute ID: {attribute.id} match not found.\n  Attribute Info: {attribute}',
+                        'yellow',
+                    )
+                )
+
+    await sdp_client.disconnect()
+
+
+# -----------------------------------------------------------------------------
+async def get_stream_reader(pipe) -> asyncio.StreamReader:
+    loop = asyncio.get_event_loop()
+    reader = asyncio.StreamReader(loop=loop)
+    protocol = asyncio.StreamReaderProtocol(reader)
+    await loop.connect_read_pipe(lambda: protocol, pipe)
+    return reader
+
+
+# -----------------------------------------------------------------------------
+async def main():
+    if len(sys.argv) < 4:
+        print(
+            'Usage: run_hid_host.py <device-config> <transport-spec> '
+            '<bluetooth-address> [test-mode]'
+        )
+
+        print('example: run_hid_host.py classic1.json usb:0 E1:CA:72:48:C4:E8/P')
+        return
+
+    def on_hid_data_cb(pdu):
+        report_type = pdu[0] & 0x0F
+        if len(pdu) == 1:
+            print(color(f'Warning: No report received', 'yellow'))
+            return
+        report_length = len(pdu[1:])
+        report_id = pdu[1]
+
+        if report_type != Message.ReportType.OTHER_REPORT:
+            print(
+                color(
+                    f' Report type = {report_type}, Report length = {report_length}, Report id = {report_id}',
+                    'blue',
+                    None,
+                    'bold',
+                )
+            )
+
+        if (report_length <= 1) or (report_id == 0):
+            return
+
+        if report_type == Message.ReportType.INPUT_REPORT:
+            ReportParser.parse_input_report(pdu[1:])  # type: ignore
+
+    async def handle_virtual_cable_unplug():
+        await hid_host.disconnect_interrupt_channel()
+        await hid_host.disconnect_control_channel()
+        await device.keystore.delete(target_address)  # type: ignore
+        await connection.disconnect()
+
+    def on_hid_virtual_cable_unplug_cb():
+        asyncio.create_task(handle_virtual_cable_unplug())
+
+    print('<<< connecting to HCI...')
+    async with await open_transport_or_link(sys.argv[2]) as (hci_source, hci_sink):
+        print('<<< CONNECTED')
+
+        # Create a device
+        device = Device.from_config_file_with_hci(sys.argv[1], hci_source, hci_sink)
+        device.classic_enabled = True
+        await device.power_on()
+
+        # Connect to a peer
+        target_address = sys.argv[3]
+        print(f'=== Connecting to {target_address}...')
+        connection = await device.connect(target_address, transport=BT_BR_EDR_TRANSPORT)
+        print(f'=== Connected to {connection.peer_address}!')
+
+        # Request authentication
+        print('*** Authenticating...')
+        await connection.authenticate()
+        print('*** Authenticated...')
+
+        # Enable encryption
+        print('*** Enabling encryption...')
+        await connection.encrypt()
+        print('*** Encryption on')
+
+        await get_hid_device_sdp_record(device, connection)
+
+        # Create HID host and start it
+        print('@@@ Starting HID Host...')
+        hid_host = Host(device, connection)
+
+        # Register for HID data call back
+        hid_host.on('data', on_hid_data_cb)
+
+        # Register for virtual cable unplug call back
+        hid_host.on('virtual_cable_unplug', on_hid_virtual_cable_unplug_cb)
+
+        async def menu():
+            reader = await get_stream_reader(sys.stdin)
+            while True:
+                print(
+                    "\n************************ HID Host Menu *****************************\n"
+                )
+                print(" 1. Connect Control Channel")
+                print(" 2. Connect Interrupt Channel")
+                print(" 3. Disconnect Control Channel")
+                print(" 4. Disconnect Interrupt Channel")
+                print(" 5. Get Report")
+                print(" 6. Set Report")
+                print(" 7. Set Protocol Mode")
+                print(" 8. Get Protocol Mode")
+                print(" 9. Send Report")
+                print("10. Suspend")
+                print("11. Exit Suspend")
+                print("12. Virtual Cable Unplug")
+                print("13. Disconnect device")
+                print("14. Delete Bonding")
+                print("15. Re-connect to device")
+                print("\nEnter your choice : \n")
+
+                choice = await reader.readline()
+                choice = choice.decode('utf-8').strip()
+
+                if choice == '1':
+                    await hid_host.connect_control_channel()
+
+                elif choice == '2':
+                    await hid_host.connect_interrupt_channel()
+
+                elif choice == '3':
+                    await hid_host.disconnect_control_channel()
+
+                elif choice == '4':
+                    await hid_host.disconnect_interrupt_channel()
+
+                elif choice == '5':
+                    print(" 1. Report ID 0x02")
+                    print(" 2. Report ID 0x03")
+                    print(" 3. Report ID 0x05")
+                    choice1 = await reader.readline()
+                    choice1 = choice1.decode('utf-8').strip()
+
+                    if choice1 == '1':
+                        hid_host.get_report(1, 2, 3)
+
+                    elif choice1 == '2':
+                        hid_host.get_report(2, 3, 2)
+
+                    elif choice1 == '3':
+                        hid_host.get_report(3, 5, 3)
+
+                    else:
+                        print('Incorrect option selected')
+
+                elif choice == '6':
+                    print(" 1. Report type 1 and Report id 0x01")
+                    print(" 2. Report type 2 and Report id 0x03")
+                    print(" 3. Report type 3 and Report id 0x05")
+                    choice1 = await reader.readline()
+                    choice1 = choice1.decode('utf-8').strip()
+
+                    if choice1 == '1':
+                        # data includes first octet as report id
+                        data = bytearray(
+                            [0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01]
+                        )
+                        hid_host.set_report(1, data)
+
+                    elif choice1 == '2':
+                        data = bytearray([0x03, 0x01, 0x01])
+                        hid_host.set_report(2, data)
+
+                    elif choice1 == '3':
+                        data = bytearray([0x05, 0x01, 0x01, 0x01])
+                        hid_host.set_report(3, data)
+
+                    else:
+                        print('Incorrect option selected')
+
+                elif choice == '7':
+                    print(" 0. Boot")
+                    print(" 1. Report")
+                    choice1 = await reader.readline()
+                    choice1 = choice1.decode('utf-8').strip()
+
+                    if choice1 == '0':
+                        hid_host.set_protocol(Message.ProtocolMode.BOOT_PROTOCOL)
+
+                    elif choice1 == '1':
+                        hid_host.set_protocol(Message.ProtocolMode.REPORT_PROTOCOL)
+
+                    else:
+                        print('Incorrect option selected')
+
+                elif choice == '8':
+                    hid_host.get_protocol()
+
+                elif choice == '9':
+                    print(" 1. Report ID 0x01")
+                    print(" 2. Report ID 0x03")
+                    choice1 = await reader.readline()
+                    choice1 = choice1.decode('utf-8').strip()
+
+                    if choice1 == '1':
+                        data = bytearray(
+                            [0x01, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00]
+                        )
+                        hid_host.send_data(data)
+
+                    elif choice1 == '2':
+                        data = bytearray([0x03, 0x00, 0x0D, 0xFD, 0x00, 0x00])
+                        hid_host.send_data(data)
+
+                    else:
+                        print('Incorrect option selected')
+
+                elif choice == '10':
+                    hid_host.suspend()
+
+                elif choice == '11':
+                    hid_host.exit_suspend()
+
+                elif choice == '12':
+                    hid_host.virtual_cable_unplug()
+                    try:
+                        await device.keystore.delete(target_address)
+                    except KeyError:
+                        print('Device not found or Device already unpaired.')
+
+                elif choice == '13':
+                    peer_address = Address.from_string_for_transport(
+                        target_address, transport=BT_BR_EDR_TRANSPORT
+                    )
+                    connection = device.find_connection_by_bd_addr(
+                        peer_address, transport=BT_BR_EDR_TRANSPORT
+                    )
+                    if connection is not None:
+                        await connection.disconnect()
+                    else:
+                        print("Already disconnected from device")
+
+                elif choice == '14':
+                    try:
+                        await device.keystore.delete(target_address)
+                        print("Unpair successful")
+                    except KeyError:
+                        print('Device not found or Device already unpaired.')
+
+                elif choice == '15':
+                    connection = await device.connect(
+                        target_address, transport=BT_BR_EDR_TRANSPORT
+                    )
+                    await connection.authenticate()
+                    await connection.encrypt()
+
+                else:
+                    print("Invalid option selected.")
+
+        if (len(sys.argv) > 4) and (sys.argv[4] == 'test-mode'):
+            # Enabling menu for testing
+            await menu()
+        else:
+            # HID Connection
+            # Control channel
+            await hid_host.connect_control_channel()
+            # Interrupt Channel
+            await hid_host.connect_interrupt_channel()
+
+        await hci_source.wait_for_termination()
+
+
+# -----------------------------------------------------------------------------
+
+logging.basicConfig(level=os.environ.get('BUMBLE_LOGLEVEL', 'DEBUG').upper())
+asyncio.run(main())

examples/run_rfcomm_server.py

@@ -20,83 +20,109 @@ import sys
 import os
 import logging
 
+from bumble.core import UUID
 from bumble.device import Device
 from bumble.transport import open_transport_or_link
-from bumble.core import BT_L2CAP_PROTOCOL_ID, BT_RFCOMM_PROTOCOL_ID, UUID
 from bumble.rfcomm import Server
-from bumble.sdp import (
-    DataElement,
-    ServiceAttribute,
-    SDP_PUBLIC_BROWSE_ROOT,
-    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,
-)
+from bumble.utils import AsyncRunner
+from bumble.rfcomm import make_service_sdp_records
 
 
 # -----------------------------------------------------------------------------
-def sdp_records(channel):
+def sdp_records(channel, uuid):
+    service_record_handle = 0x00010001
     return {
-        0x00010001: [
-            ServiceAttribute(
-                SDP_SERVICE_RECORD_HANDLE_ATTRIBUTE_ID,
-                DataElement.unsigned_integer_32(0x00010001),
-            ),
-            ServiceAttribute(
-                SDP_BROWSE_GROUP_LIST_ATTRIBUTE_ID,
-                DataElement.sequence([DataElement.uuid(SDP_PUBLIC_BROWSE_ROOT)]),
-            ),
-            ServiceAttribute(
-                SDP_SERVICE_CLASS_ID_LIST_ATTRIBUTE_ID,
-                DataElement.sequence(
-                    [DataElement.uuid(UUID('E6D55659-C8B4-4B85-96BB-B1143AF6D3AE'))]
-                ),
-            ),
-            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),
-                            ]
-                        ),
-                    ]
-                ),
-            ),
-        ]
+        service_record_handle: make_service_sdp_records(
+            service_record_handle, channel, UUID(uuid)
+        )
     }
 
 
 # -----------------------------------------------------------------------------
-def on_dlc(dlc):
-    print('*** DLC connected', dlc)
-    dlc.sink = lambda data: on_rfcomm_data_received(dlc, data)
+def on_rfcomm_session(rfcomm_session, tcp_server):
+    print('*** RFComm session connected', rfcomm_session)
+    tcp_server.attach_session(rfcomm_session)
 
 
 # -----------------------------------------------------------------------------
-def on_rfcomm_data_received(dlc, data):
-    print(f'<<< Data received: {data.hex()}')
-    try:
-        message = data.decode('utf-8')
-        print(f'<<< Message = {message}')
-    except Exception:
-        pass
+class TcpServerProtocol(asyncio.Protocol):
+    def __init__(self, server):
+        self.server = server
 
-    # Echo everything back
-    dlc.write(data)
+    def connection_made(self, transport):
+        peer_name = transport.get_extra_info('peer_name')
+        print(f'<<< TCP Server: connection from {peer_name}')
+        if self.server:
+            self.server.tcp_transport = transport
+        else:
+            transport.close()
+
+    def connection_lost(self, exc):
+        print('<<< TCP Server: connection lost')
+        if self.server:
+            self.server.tcp_transport = None
+
+    def data_received(self, data):
+        print(f'<<< TCP Server: data received: {len(data)} bytes - {data.hex()}')
+        if self.server:
+            self.server.tcp_data_received(data)
+
+
+# -----------------------------------------------------------------------------
+class TcpServer:
+    def __init__(self, port):
+        self.rfcomm_session = None
+        self.tcp_transport = None
+        AsyncRunner.spawn(self.run(port))
+
+    def attach_session(self, rfcomm_session):
+        if self.rfcomm_session:
+            self.rfcomm_session.sink = None
+
+        self.rfcomm_session = rfcomm_session
+        rfcomm_session.sink = self.rfcomm_data_received
+
+    def rfcomm_data_received(self, data):
+        print(f'<<< RFCOMM Data: {data.hex()}')
+        if self.tcp_transport:
+            self.tcp_transport.write(data)
+        else:
+            print('!!! no TCP connection, dropping data')
+
+    def tcp_data_received(self, data):
+        if self.rfcomm_session:
+            self.rfcomm_session.write(data)
+        else:
+            print('!!! no RFComm session, dropping data')
+
+    async def run(self, port):
+        print(f'$$$ Starting TCP server on port {port}')
+
+        server = await asyncio.get_running_loop().create_server(
+            lambda: TcpServerProtocol(self), '127.0.0.1', port
+        )
+
+        async with server:
+            await server.serve_forever()
 
 
 # -----------------------------------------------------------------------------
 async def main():
-    if len(sys.argv) < 3:
-        print('Usage: run_rfcomm_server.py <device-config> <transport-spec>')
-        print('example: run_rfcomm_server.py classic2.json usb:04b4:f901')
+    if len(sys.argv) < 4:
+        print(
+            'Usage: run_rfcomm_server.py <device-config> <transport-spec> '
+            '<tcp-port> [<uuid>]'
+        )
+        print('example: run_rfcomm_server.py classic2.json usb:0 8888')
         return
 
+    tcp_port = int(sys.argv[3])
+
+    if len(sys.argv) >= 5:
+        uuid = sys.argv[4]
+    else:
+        uuid = 'E6D55659-C8B4-4B85-96BB-B1143AF6D3AE'
+
     print('<<< connecting to HCI...')
     async with await open_transport_or_link(sys.argv[2]) as (hci_source, hci_sink):
         print('<<< connected')
@@ -105,15 +131,20 @@ async def main():
         device = Device.from_config_file_with_hci(sys.argv[1], hci_source, hci_sink)
         device.classic_enabled = True
 
-        # Create and register a server
+        # Create a TCP server
+        tcp_server = TcpServer(tcp_port)
+
+        # Create and register an RFComm server
         rfcomm_server = Server(device)
 
         # Listen for incoming DLC connections
-        channel_number = rfcomm_server.listen(on_dlc)
-        print(f'### Listening for connection on channel {channel_number}')
+        channel_number = rfcomm_server.listen(
+            lambda session: on_rfcomm_session(session, tcp_server)
+        )
+        print(f'### Listening for RFComm connections on channel {channel_number}')
 
         # Setup the SDP to advertise this channel
-        device.sdp_service_records = sdp_records(channel_number)
+        device.sdp_service_records = sdp_records(channel_number, uuid)
 
         # Start the controller
         await device.power_on()

extras/android/RemoteHCI/.gitignore

@@ -0,0 +1,10 @@
+*.iml
+.gradle
+/local.properties
+/.idea
+.DS_Store
+/build
+/captures
+.externalNativeBuild
+.cxx
+local.properties

extras/android/RemoteHCI/app/.gitignore

@@ -0,0 +1 @@
+/build