terminate when unplugged

eSCO codec/HCI definitions + Host support

.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

@@ -56,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]"
@@ -65,15 +65,17 @@ jobs:
         with:
           components: clippy,rustfmt
           toolchain: ${{ matrix.rust-version }}
+      - name: Install Rust dependencies
+        run: cargo install cargo-all-features # allows building/testing combinations of features
       - name: Check License Headers
         run: cd rust && cargo run --features dev-tools --bin file-header check-all
       - name: Rust Build
-        run: cd rust && cargo build --all-targets && cargo build --all-features --all-targets
+        run: cd rust && cargo build --all-targets && cargo build-all-features --all-targets
       # Lints after build so what clippy needs is already built
       - name: Rust Lints
         run: cd rust && cargo fmt --check && cargo clippy --all-targets -- --deny warnings && cargo clippy --all-features --all-targets -- --deny warnings
       - name: Rust Tests
-        run: cd rust && cargo test
+        run: cd rust && cargo test-all-features
       # At some point, hook up publishing the binary. For now, just make sure it builds.
       # Once we're ready to publish binaries, this should be built with `--release`.
       - name: Build Bumble CLI

.vscode/settings.json

@@ -47,6 +47,7 @@
         "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/gg_bridge.py

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

apps/l2cap_bridge.py

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

apps/pair.py

@@ -306,6 +306,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 +327,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

apps/speaker/speaker.py

@@ -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/controller.py

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

@@ -33,6 +33,8 @@ from typing import (
     Tuple,
     Type,
     Union,
+    cast,
+    overload,
     TYPE_CHECKING,
 )
 
@@ -151,6 +153,7 @@ from .utils import (
     CompositeEventEmitter,
     setup_event_forwarding,
     composite_listener,
+    deprecated,
 )
 from .keys import (
     KeyStore,
@@ -670,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,
@@ -682,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:
@@ -829,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')
@@ -1180,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)
-
+    @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,
@@ -1201,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,
@@ -1213,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)
 
@@ -1222,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:
@@ -1323,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()

bumble/hci.py

@@ -17,6 +17,7 @@
 # -----------------------------------------------------------------------------
 from __future__ import annotations
 import collections
+import enum
 import functools
 import logging
 import struct
@@ -121,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',
@@ -135,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
@@ -1368,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
@@ -1923,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)
 
@@ -2291,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=[
@@ -2452,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(
@@ -5736,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

@@ -35,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,
@@ -819,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, TYPE_CHECKING, Dict, Callable, Awaitable
+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,6 +68,7 @@ from .hci import (
     HCI_Read_Local_Version_Information_Command,
     HCI_Reset_Command,
     HCI_Set_Event_Mask_Command,
+    HCI_SynchronousDataPacket,
 )
 from .core import (
     BT_BR_EDR_TRANSPORT,
@@ -485,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}')
 
@@ -507,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)
 
@@ -760,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,7 @@
 # -----------------------------------------------------------------------------
 from __future__ import annotations
 import asyncio
+import dataclasses
 import enum
 import logging
 import struct
@@ -38,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 (
@@ -167,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
@@ -676,7 +706,7 @@ class L2CAP_LE_Flow_Control_Credit(L2CAP_Control_Frame):
 
 
 # -----------------------------------------------------------------------------
-class Channel(EventEmitter):
+class ClassicChannel(EventEmitter):
     class State(enum.IntEnum):
         # States
         CLOSED = 0x00
@@ -990,7 +1020,7 @@ class Channel(EventEmitter):
 
 
 # -----------------------------------------------------------------------------
-class LeConnectionOrientedChannel(EventEmitter):
+class LeCreditBasedChannel(EventEmitter):
     """
     LE Credit-based Connection Oriented Channel
     """
@@ -1004,11 +1034,13 @@ class LeConnectionOrientedChannel(EventEmitter):
         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: State
     connection: Connection
+    sink: Optional[Callable[[bytes], Any]]
 
     def __init__(
         self,
@@ -1071,7 +1103,7 @@ class LeConnectionOrientedChannel(EventEmitter):
     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.State.INIT:
             raise InvalidStateError('not in a connectable state')
@@ -1342,15 +1374,67 @@ 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]
@@ -1429,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
@@ -1458,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
@@ -1468,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')
@@ -1650,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(
@@ -1878,7 +1974,7 @@ class ChannelManager:
         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(
@@ -1892,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,
@@ -1911,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,
@@ -1925,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
@@ -1949,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} '
@@ -2013,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
@@ -2062,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
@@ -2071,10 +2189,20 @@ 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
 
@@ -2086,3 +2214,20 @@ class ChannelManager:
             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/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,6 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+from __future__ import annotations
 import asyncio
 import contextlib
 import grpc
@@ -450,21 +451,18 @@ class SecurityService(SecurityServicer):
             '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:

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

@@ -674,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
@@ -887,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
@@ -898,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}')
@@ -936,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:
@@ -960,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/transport/usb.py

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

bumble/utils.py

@@ -21,6 +21,7 @@ import logging
 import traceback
 import collections
 import sys
+import warnings
 from typing import (
     Awaitable,
     Set,
@@ -427,3 +428,19 @@ 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

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,19 +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:
-    - Overview: extras/index.md
+    - 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
 
@@ -78,6 +83,8 @@ theme:
   logo: 'images/logo.png'
   favicon: 'images/favicon.ico'
   custom_dir: 'theme'
+  features:
+    - navigation.indexes
 
 plugins:
   - mkdocstrings:
@@ -102,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/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/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

@@ -31,6 +31,7 @@ from bumble.core import (
     BT_BR_EDR_TRANSPORT,
 )
 from bumble import rfcomm, hfp
+from bumble.hci import HCI_SynchronousDataPacket
 from bumble.sdp import (
     Client as SDP_Client,
     DataElement,
@@ -197,6 +198,13 @@ 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 = hfp.HfpProtocol(session)
         while True:

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())

extras/android/RemoteHCI/app/src/main/java/com/github/google/bumble/remotehci/MainActivity.kt

@@ -113,7 +113,7 @@ class MainActivity : ComponentActivity() {
 
         val tcpPort = intent.getIntExtra("port", -1)
         if (tcpPort >= 0) {
-            appViewModel.tcpPort = tcpPport
+            appViewModel.tcpPort = tcpPort
         }
 
         setContent {

extras/android/RemoteHCI/gradle/libs.versions.toml

@@ -1,5 +1,5 @@
 [versions]
-agp = "8.3.0-alpha05"
+agp = "8.3.0-alpha11"
 kotlin = "1.8.10"
 core-ktx = "1.9.0"
 junit = "4.13.2"

extras/android/RemoteHCI/gradle/wrapper/gradle-wrapper.properties

@@ -1,6 +1,6 @@
 #Sun Aug 06 12:53:26 PDT 2023
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-8.3-rc-2-bin.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-8.4-bin.zip
 zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists

rust/Cargo.toml

@@ -12,6 +12,13 @@ keywords = ["bluetooth", "ble"]
 categories = ["api-bindings", "network-programming"]
 rust-version = "1.70.0"
 
+# https://github.com/frewsxcv/cargo-all-features#options
+[package.metadata.cargo-all-features]
+# We are interested in testing subset combinations of this feature, so this is redundant
+denylist = ["unstable"]
+# To exercise combinations of any of these features, remove from `always_include_features`
+always_include_features = ["anyhow", "pyo3-asyncio-attributes", "dev-tools", "bumble-tools"]
+
 [dependencies]
 pyo3 = { version = "0.18.3", features = ["macros"] }
 pyo3-asyncio = { version = "0.18.0", features = ["tokio-runtime"] }
@@ -26,6 +33,7 @@ thiserror = "1.0.41"
 bytes = "1.5.0"
 pdl-derive = "0.2.0"
 pdl-runtime = "0.2.0"
+futures = "0.3.28"
 
 # Dev tools
 file-header = { version = "0.1.2", optional = true }
@@ -36,7 +44,6 @@ anyhow = { version = "1.0.71", optional = true }
 clap = { version = "4.3.3", features = ["derive"], optional = true }
 directories = { version = "5.0.1", optional = true }
 env_logger = { version = "0.10.0", optional = true }
-futures = { version = "0.3.28", optional = true }
 log = { version = "0.4.19", optional = true }
 owo-colors = { version = "3.5.0", optional = true }
 reqwest = { version = "0.11.20", features = ["blocking"], optional = true }
@@ -74,6 +81,11 @@ name = "bumble"
 path = "src/main.rs"
 required-features = ["bumble-tools"]
 
+[[example]]
+name = "broadcast"
+path = "examples/broadcast.rs"
+required-features = ["unstable_extended_adv"]
+
 # test entry point that uses pyo3_asyncio's test harness
 [[test]]
 name = "pytests"
@@ -85,5 +97,10 @@ anyhow = ["pyo3/anyhow"]
 pyo3-asyncio-attributes = ["pyo3-asyncio/attributes"]
 dev-tools = ["dep:anyhow", "dep:clap", "dep:file-header", "dep:globset"]
 # separate feature for CLI so that dependencies don't spend time building these
-bumble-tools = ["dep:clap", "anyhow", "dep:anyhow", "dep:directories", "pyo3-asyncio-attributes", "dep:owo-colors", "dep:reqwest", "dep:rusb", "dep:log", "dep:env_logger", "dep:futures"]
+bumble-tools = ["dep:clap", "anyhow", "dep:anyhow", "dep:directories", "pyo3-asyncio-attributes", "dep:owo-colors", "dep:reqwest", "dep:rusb", "dep:log", "dep:env_logger"]
+
+# all the unstable features
+unstable = ["unstable_extended_adv"]
+unstable_extended_adv = []
+
 default = []

rust/examples/battery_client.rs

@@ -33,6 +33,7 @@
 
 use bumble::wrapper::{
     device::{Device, Peer},
+    hci::{packets::AddressType, Address},
     profile::BatteryServiceProxy,
     transport::Transport,
     PyObjectExt,
@@ -52,12 +53,8 @@ async fn main() -> PyResult<()> {
 
     let transport = Transport::open(cli.transport).await?;
 
-    let device = Device::with_hci(
-        "Bumble",
-        "F0:F1:F2:F3:F4:F5",
-        transport.source()?,
-        transport.sink()?,
-    )?;
+    let address = Address::new("F0:F1:F2:F3:F4:F5", AddressType::RandomDeviceAddress)?;
+    let device = Device::with_hci("Bumble", address, transport.source()?, transport.sink()?)?;
 
     device.power_on().await?;
 

rust/examples/broadcast.rs

@@ -63,17 +63,28 @@ async fn main() -> PyResult<()> {
         )
         .map_err(|e| anyhow!(e))?;
 
-    device.set_advertising_data(adv_data)?;
     device.power_on().await?;
 
-    println!("Advertising...");
-    device.start_advertising(true).await?;
+    if cli.extended {
+        println!("Starting extended advertisement...");
+        device.start_advertising_extended(adv_data).await?;
+    } else {
+        device.set_advertising_data(adv_data)?;
+
+        println!("Starting legacy advertisement...");
+        device.start_advertising(true).await?;
+    }
 
     // wait until user kills the process
     tokio::signal::ctrl_c().await?;
 
-    println!("Stopping...");
-    device.stop_advertising().await?;
+    if cli.extended {
+        println!("Stopping extended advertisement...");
+        device.stop_advertising_extended().await?;
+    } else {
+        println!("Stopping legacy advertisement...");
+        device.stop_advertising().await?;
+    }
 
     Ok(())
 }
@@ -86,12 +97,17 @@ struct Cli {
     /// See, for instance, `examples/device1.json` in the Python project.
     #[arg(long)]
     device_config: path::PathBuf,
+
     /// Bumble transport spec.
     ///
     /// <https://google.github.io/bumble/transports/index.html>
     #[arg(long)]
     transport: String,
 
+    /// Whether to perform an extended (BT 5.0) advertisement
+    #[arg(long)]
+    extended: bool,
+
     /// Log HCI commands
     #[arg(long)]
     log_hci: bool,

rust/examples/scanner.rs

@@ -20,7 +20,9 @@
 use bumble::{
     adv::CommonDataType,
     wrapper::{
-        core::AdvertisementDataUnit, device::Device, hci::packets::AddressType,
+        core::AdvertisementDataUnit,
+        device::Device,
+        hci::{packets::AddressType, Address},
         transport::Transport,
     },
 };
@@ -44,12 +46,8 @@ async fn main() -> PyResult<()> {
 
     let transport = Transport::open(cli.transport).await?;
 
-    let mut device = Device::with_hci(
-        "Bumble",
-        "F0:F1:F2:F3:F4:F5",
-        transport.source()?,
-        transport.sink()?,
-    )?;
+    let address = Address::new("F0:F1:F2:F3:F4:F5", AddressType::RandomDeviceAddress)?;
+    let mut device = Device::with_hci("Bumble", address, transport.source()?, transport.sink()?)?;
 
     // in practice, devices can send multiple advertisements from the same address, so we keep
     // track of a timestamp for each set of data

rust/pytests/wrapper.rs

@@ -1,77 +0,0 @@
-// Copyright 2023 Google LLC
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://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.
-
-use bumble::wrapper::{
-    controller::Controller,
-    device::Device,
-    drivers::rtk::DriverInfo,
-    hci::{
-        packets::{
-            AddressType, ErrorCode, ReadLocalVersionInformationBuilder,
-            ReadLocalVersionInformationComplete,
-        },
-        Address, Error,
-    },
-    host::Host,
-    link::Link,
-    transport::Transport,
-};
-use nix::sys::stat::Mode;
-use pyo3::{
-    exceptions::PyException,
-    {PyErr, PyResult},
-};
-
-#[pyo3_asyncio::tokio::test]
-async fn fifo_transport_can_open() -> PyResult<()> {
-    let dir = tempfile::tempdir().unwrap();
-    let mut fifo = dir.path().to_path_buf();
-    fifo.push("bumble-transport-fifo");
-    nix::unistd::mkfifo(&fifo, Mode::S_IRWXU).unwrap();
-
-    let mut t = Transport::open(format!("file:{}", fifo.to_str().unwrap())).await?;
-
-    t.close().await?;
-
-    Ok(())
-}
-
-#[pyo3_asyncio::tokio::test]
-async fn realtek_driver_info_all_drivers() -> PyResult<()> {
-    assert_eq!(12, DriverInfo::all_drivers()?.len());
-    Ok(())
-}
-
-#[pyo3_asyncio::tokio::test]
-async fn hci_command_wrapper_has_correct_methods() -> PyResult<()> {
-    let address = Address::new("F0:F1:F2:F3:F4:F5", &AddressType::RandomDeviceAddress)?;
-    let link = Link::new_local_link()?;
-    let controller = Controller::new("C1", None, None, Some(link), Some(address.clone())).await?;
-    let host = Host::new(controller.clone().into(), controller.into()).await?;
-    let device = Device::new(None, Some(address), None, Some(host), None)?;
-
-    device.power_on().await?;
-
-    // Send some simple command. A successful response means [HciCommandWrapper] has the minimum
-    // required interface for the Python code to think its an [HCI_Command] object.
-    let command = ReadLocalVersionInformationBuilder {};
-    let event: ReadLocalVersionInformationComplete = device
-        .send_command(&command.into(), true)
-        .await?
-        .try_into()
-        .map_err(|e: Error| PyErr::new::<PyException, _>(e.to_string()))?;
-
-    assert_eq!(ErrorCode::Success, event.get_status());
-    Ok(())
-}

rust/pytests/wrapper/drivers.rs

@@ -0,0 +1,22 @@
+// Copyright 2023 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://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.
+
+use bumble::wrapper::drivers::rtk::DriverInfo;
+use pyo3::PyResult;
+
+#[pyo3_asyncio::tokio::test]
+async fn realtek_driver_info_all_drivers() -> PyResult<()> {
+    assert_eq!(12, DriverInfo::all_drivers()?.len());
+    Ok(())
+}

rust/pytests/wrapper/hci.rs

@@ -0,0 +1,86 @@
+// Copyright 2023 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://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.
+
+use bumble::wrapper::{
+    controller::Controller,
+    device::Device,
+    hci::{
+        packets::{
+            AddressType, Enable, ErrorCode, LeScanType, LeScanningFilterPolicy,
+            LeSetScanEnableBuilder, LeSetScanEnableComplete, LeSetScanParametersBuilder,
+            LeSetScanParametersComplete, OwnAddressType,
+        },
+        Address, Error,
+    },
+    host::Host,
+    link::Link,
+};
+use pyo3::{
+    exceptions::PyException,
+    {PyErr, PyResult},
+};
+
+#[pyo3_asyncio::tokio::test]
+async fn test_hci_roundtrip_success_and_failure() -> PyResult<()> {
+    let address = Address::new("F0:F1:F2:F3:F4:F5", AddressType::RandomDeviceAddress)?;
+    let device = create_local_device(address).await?;
+
+    device.power_on().await?;
+
+    // BLE Spec Core v5.3
+    // 7.8.9 LE Set Scan Parameters command
+    // ...
+    // The Host shall not issue this command when scanning is enabled in the
+    // Controller; if it is the Command Disallowed error code shall be used.
+    // ...
+
+    let command = LeSetScanEnableBuilder {
+        filter_duplicates: Enable::Disabled,
+        // will cause failure later
+        le_scan_enable: Enable::Enabled,
+    };
+
+    let event: LeSetScanEnableComplete = device
+        .send_command(command.into(), false)
+        .await?
+        .try_into()
+        .map_err(|e: Error| PyErr::new::<PyException, _>(e.to_string()))?;
+
+    assert_eq!(ErrorCode::Success, event.get_status());
+
+    let command = LeSetScanParametersBuilder {
+        le_scan_type: LeScanType::Passive,
+        le_scan_interval: 0,
+        le_scan_window: 0,
+        own_address_type: OwnAddressType::RandomDeviceAddress,
+        scanning_filter_policy: LeScanningFilterPolicy::AcceptAll,
+    };
+
+    let event: LeSetScanParametersComplete = device
+        .send_command(command.into(), false)
+        .await?
+        .try_into()
+        .map_err(|e: Error| PyErr::new::<PyException, _>(e.to_string()))?;
+
+    assert_eq!(ErrorCode::CommandDisallowed, event.get_status());
+
+    Ok(())
+}
+
+async fn create_local_device(address: Address) -> PyResult<Device> {
+    let link = Link::new_local_link()?;
+    let controller = Controller::new("C1", None, None, Some(link), Some(address.clone())).await?;
+    let host = Host::new(controller.clone().into(), controller.into()).await?;
+    Device::new(None, Some(address), None, Some(host), None)
+}

rust/pytests/wrapper/mod.rs

@@ -0,0 +1,17 @@
+// Copyright 2023 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://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.
+
+mod drivers;
+mod hci;
+mod transport;

rust/pytests/wrapper/transport.rs

@@ -0,0 +1,31 @@
+// Copyright 2023 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://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.
+
+use bumble::wrapper::transport::Transport;
+use nix::sys::stat::Mode;
+use pyo3::PyResult;
+
+#[pyo3_asyncio::tokio::test]
+async fn fifo_transport_can_open() -> PyResult<()> {
+    let dir = tempfile::tempdir().unwrap();
+    let mut fifo = dir.path().to_path_buf();
+    fifo.push("bumble-transport-fifo");
+    nix::unistd::mkfifo(&fifo, Mode::S_IRWXU).unwrap();
+
+    let mut t = Transport::open(format!("file:{}", fifo.to_str().unwrap())).await?;
+
+    t.close().await?;
+
+    Ok(())
+}

rust/src/internal/hci/mod.rs

@@ -94,7 +94,7 @@ impl From<Error> for PacketTypeParseError {
 
 impl WithPacketType<Self> for Command {
     fn to_vec_with_packet_type(self) -> Vec<u8> {
-        prepend_packet_type(PacketType::Command, self.to_vec())
+        prepend_packet_type(PacketType::Command, self)
     }
 
     fn parse_with_packet_type(bytes: &[u8]) -> Result<Self, PacketTypeParseError> {
@@ -104,7 +104,7 @@ impl WithPacketType<Self> for Command {
 
 impl WithPacketType<Self> for Acl {
     fn to_vec_with_packet_type(self) -> Vec<u8> {
-        prepend_packet_type(PacketType::Acl, self.to_vec())
+        prepend_packet_type(PacketType::Acl, self)
     }
 
     fn parse_with_packet_type(bytes: &[u8]) -> Result<Self, PacketTypeParseError> {
@@ -114,7 +114,7 @@ impl WithPacketType<Self> for Acl {
 
 impl WithPacketType<Self> for Sco {
     fn to_vec_with_packet_type(self) -> Vec<u8> {
-        prepend_packet_type(PacketType::Sco, self.to_vec())
+        prepend_packet_type(PacketType::Sco, self)
     }
 
     fn parse_with_packet_type(bytes: &[u8]) -> Result<Self, PacketTypeParseError> {
@@ -124,7 +124,7 @@ impl WithPacketType<Self> for Sco {
 
 impl WithPacketType<Self> for Event {
     fn to_vec_with_packet_type(self) -> Vec<u8> {
-        prepend_packet_type(PacketType::Event, self.to_vec())
+        prepend_packet_type(PacketType::Event, self)
     }
 
     fn parse_with_packet_type(bytes: &[u8]) -> Result<Self, PacketTypeParseError> {
@@ -132,7 +132,9 @@ impl WithPacketType<Self> for Event {
     }
 }
 
-fn prepend_packet_type(packet_type: PacketType, mut packet_bytes: Vec<u8>) -> Vec<u8> {
+fn prepend_packet_type<T: Packet>(packet_type: PacketType, packet: T) -> Vec<u8> {
+    // TODO: refactor if `pdl` crate adds API for writing into buffer (github.com/google/pdl/issues/74)
+    let mut packet_bytes = packet.to_vec();
     packet_bytes.insert(0, packet_type.into());
     packet_bytes
 }

rust/src/internal/hci/tests.rs

@@ -22,9 +22,8 @@ use bytes::Bytes;
 #[test]
 fn prepends_packet_type() {
     let packet_type = PacketType::Event;
-    let packet_bytes = vec![0x00, 0x00, 0x00, 0x00];
-    let actual = prepend_packet_type(packet_type, packet_bytes);
-    assert_eq!(vec![0x04, 0x00, 0x00, 0x00, 0x00], actual);
+    let actual = prepend_packet_type(packet_type, FakePacket { bytes: vec![0xFF] });
+    assert_eq!(vec![0x04, 0xFF], actual);
 }
 
 #[test]
@@ -75,11 +74,15 @@ fn test_packet_roundtrip_with_type() {
 }
 
 #[derive(Debug, PartialEq)]
-struct FakePacket;
+struct FakePacket {
+    bytes: Vec<u8>,
+}
 
 impl FakePacket {
-    fn parse(_bytes: &[u8]) -> Result<Self, Error> {
-        Ok(Self)
+    fn parse(bytes: &[u8]) -> Result<Self, Error> {
+        Ok(Self {
+            bytes: bytes.to_vec(),
+        })
     }
 }
 
@@ -89,6 +92,6 @@ impl Packet for FakePacket {
     }
 
     fn to_vec(self) -> Vec<u8> {
-        Vec::new()
+        self.bytes
     }
 }

rust/src/wrapper/device/mod.rs

@@ -14,7 +14,17 @@
 
 //! Devices and connections to them
 
-use crate::internal::hci::WithPacketType;
+#[cfg(feature = "unstable_extended_adv")]
+use crate::wrapper::{
+    hci::packets::{
+        self, AdvertisingEventProperties, AdvertisingFilterPolicy, Enable, EnabledSet,
+        FragmentPreference, LeSetAdvertisingSetRandomAddressBuilder,
+        LeSetExtendedAdvertisingDataBuilder, LeSetExtendedAdvertisingEnableBuilder,
+        LeSetExtendedAdvertisingParametersBuilder, Operation, OwnAddressType, PeerAddressType,
+        PrimaryPhyType, SecondaryPhyType,
+    },
+    ConversionError,
+};
 use crate::{
     adv::AdvertisementDataBuilder,
     wrapper::{
@@ -22,7 +32,7 @@ use crate::{
         gatt_client::{ProfileServiceProxy, ServiceProxy},
         hci::{
             packets::{Command, ErrorCode, Event},
-            Address, HciCommandWrapper,
+            Address, HciCommand, WithPacketType,
         },
         host::Host,
         l2cap::LeConnectionOrientedChannel,
@@ -39,6 +49,9 @@ use pyo3::{
 use pyo3_asyncio::tokio::into_future;
 use std::path;
 
+#[cfg(test)]
+mod tests;
+
 /// Represents the various properties of some device
 pub struct DeviceConfiguration(PyObject);
 
@@ -69,11 +82,24 @@ impl ToPyObject for DeviceConfiguration {
     }
 }
 
+/// Used for tracking what advertising state a device might be in
+#[derive(PartialEq)]
+enum AdvertisingStatus {
+    AdvertisingLegacy,
+    AdvertisingExtended,
+    NotAdvertising,
+}
+
 /// A device that can send/receive HCI frames.
-#[derive(Clone)]
-pub struct Device(PyObject);
+pub struct Device {
+    obj: PyObject,
+    advertising_status: AdvertisingStatus,
+}
 
 impl Device {
+    #[cfg(feature = "unstable_extended_adv")]
+    const ADVERTISING_HANDLE_EXTENDED: u8 = 0x00;
+
     /// Creates a Device. When optional arguments are not specified, the Python object specifies the
     /// defaults.
     pub fn new(
@@ -94,7 +120,10 @@ impl Device {
             PyModule::import(py, intern!(py, "bumble.device"))?
                 .getattr(intern!(py, "Device"))?
                 .call((), Some(kwargs))
-                .map(|any| Self(any.into()))
+                .map(|any| Self {
+                    obj: any.into(),
+                    advertising_status: AdvertisingStatus::NotAdvertising,
+                })
         })
     }
 
@@ -111,28 +140,38 @@ impl Device {
                     intern!(py, "from_config_file_with_hci"),
                     (device_config, source.0, sink.0),
                 )
-                .map(|any| Self(any.into()))
+                .map(|any| Self {
+                    obj: any.into(),
+                    advertising_status: AdvertisingStatus::NotAdvertising,
+                })
         })
     }
 
     /// Create a Device configured to communicate with a controller through an HCI source/sink
-    pub fn with_hci(name: &str, address: &str, source: Source, sink: Sink) -> PyResult<Self> {
+    pub fn with_hci(name: &str, address: Address, source: Source, sink: Sink) -> PyResult<Self> {
         Python::with_gil(|py| {
             PyModule::import(py, intern!(py, "bumble.device"))?
                 .getattr(intern!(py, "Device"))?
-                .call_method1(intern!(py, "with_hci"), (name, address, source.0, sink.0))
-                .map(|any| Self(any.into()))
+                .call_method1(intern!(py, "with_hci"), (name, address.0, source.0, sink.0))
+                .map(|any| Self {
+                    obj: any.into(),
+                    advertising_status: AdvertisingStatus::NotAdvertising,
+                })
         })
     }
 
     /// Sends an HCI command on this Device, returning the command's event result.
-    pub async fn send_command(&self, command: &Command, check_result: bool) -> PyResult<Event> {
+    ///
+    /// When `check_result` is `true`, then an `Err` will be returned if the controller's response
+    /// did not have an event code of "success".
+    pub async fn send_command(&self, command: Command, check_result: bool) -> PyResult<Event> {
+        let bumble_hci_command = HciCommand::try_from(command)?;
         Python::with_gil(|py| {
-            self.0
+            self.obj
                 .call_method1(
                     py,
                     intern!(py, "send_command"),
-                    (HciCommandWrapper(command.clone()), check_result),
+                    (bumble_hci_command, check_result),
                 )
                 .and_then(|coroutine| into_future(coroutine.as_ref(py)))
         })?
@@ -151,7 +190,7 @@ impl Device {
     /// Turn the device on
     pub async fn power_on(&self) -> PyResult<()> {
         Python::with_gil(|py| {
-            self.0
+            self.obj
                 .call_method0(py, intern!(py, "power_on"))
                 .and_then(|coroutine| into_future(coroutine.as_ref(py)))
         })?
@@ -162,7 +201,7 @@ impl Device {
     /// Connect to a peer
     pub async fn connect(&self, peer_addr: &str) -> PyResult<Connection> {
         Python::with_gil(|py| {
-            self.0
+            self.obj
                 .call_method1(py, intern!(py, "connect"), (peer_addr,))
                 .and_then(|coroutine| into_future(coroutine.as_ref(py)))
         })?
@@ -180,7 +219,7 @@ impl Device {
         });
 
         Python::with_gil(|py| {
-            self.0
+            self.obj
                 .call_method1(py, intern!(py, "add_listener"), ("connection", boxed))
         })
         .map(|_| ())
@@ -191,7 +230,7 @@ impl Device {
         Python::with_gil(|py| {
             let kwargs = PyDict::new(py);
             kwargs.set_item("filter_duplicates", filter_duplicates)?;
-            self.0
+            self.obj
                 .call_method(py, intern!(py, "start_scanning"), (), Some(kwargs))
                 .and_then(|coroutine| into_future(coroutine.as_ref(py)))
         })?
@@ -209,7 +248,7 @@ impl Device {
         });
 
         Python::with_gil(|py| {
-            self.0
+            self.obj
                 .call_method1(py, intern!(py, "add_listener"), ("advertisement", boxed))
         })
         .map(|_| ())
@@ -218,7 +257,7 @@ impl Device {
     /// Set the advertisement data to be used when [Device::start_advertising] is called.
     pub fn set_advertising_data(&mut self, adv_data: AdvertisementDataBuilder) -> PyResult<()> {
         Python::with_gil(|py| {
-            self.0.setattr(
+            self.obj.setattr(
                 py,
                 intern!(py, "advertising_data"),
                 adv_data.into_bytes().as_slice(),
@@ -230,35 +269,162 @@ impl Device {
     /// Returns the host used by the device, if any
     pub fn host(&mut self) -> PyResult<Option<Host>> {
         Python::with_gil(|py| {
-            self.0
+            self.obj
                 .getattr(py, intern!(py, "host"))
                 .map(|obj| obj.into_option(Host::from))
         })
     }
 
     /// Start advertising the data set with [Device.set_advertisement].
+    ///
+    /// When `auto_restart` is set to `true`, then the device will automatically restart advertising
+    /// when a connected device is disconnected.
     pub async fn start_advertising(&mut self, auto_restart: bool) -> PyResult<()> {
+        if self.advertising_status == AdvertisingStatus::AdvertisingExtended {
+            return Err(PyErr::new::<PyException, _>("Already advertising in extended mode. Stop the existing extended advertisement to start a legacy advertisement."));
+        }
+        // Bumble allows (and currently ignores) calling `start_advertising` when already
+        // advertising. Because that behavior may change in the future, we continue to delegate the
+        // handling to bumble.
+
         Python::with_gil(|py| {
             let kwargs = PyDict::new(py);
             kwargs.set_item("auto_restart", auto_restart)?;
 
-            self.0
+            self.obj
                 .call_method(py, intern!(py, "start_advertising"), (), Some(kwargs))
                 .and_then(|coroutine| into_future(coroutine.as_ref(py)))
         })?
         .await
-        .map(|_| ())
+        .map(|_| ())?;
+
+        self.advertising_status = AdvertisingStatus::AdvertisingLegacy;
+        Ok(())
+    }
+
+    /// Start advertising the data set in extended mode, replacing any existing extended adv. The
+    /// advertisement will be non-connectable.
+    ///
+    /// Fails if the device is already advertising in legacy mode.
+    #[cfg(feature = "unstable_extended_adv")]
+    pub async fn start_advertising_extended(
+        &mut self,
+        adv_data: AdvertisementDataBuilder,
+    ) -> PyResult<()> {
+        // TODO: add tests when local controller object supports extended advertisement commands (github.com/google/bumble/pull/238)
+        match self.advertising_status {
+            AdvertisingStatus::AdvertisingLegacy => return Err(PyErr::new::<PyException, _>("Already advertising in legacy mode. Stop the existing legacy advertisement to start an extended advertisement.")),
+            // Stop the current extended advertisement before advertising with new data.
+            // We could just issue an LeSetExtendedAdvertisingData command, but this approach
+            // allows better future flexibility if `start_advertising_extended` were to change.
+            AdvertisingStatus::AdvertisingExtended => self.stop_advertising_extended().await?,
+            _ => {}
+        }
+
+        // set extended params
+        let properties = AdvertisingEventProperties {
+            connectable: 0,
+            scannable: 0,
+            directed: 0,
+            high_duty_cycle: 0,
+            legacy: 0,
+            anonymous: 0,
+            tx_power: 0,
+        };
+        let extended_advertising_params_cmd = LeSetExtendedAdvertisingParametersBuilder {
+            advertising_event_properties: properties,
+            advertising_filter_policy: AdvertisingFilterPolicy::AllDevices,
+            advertising_handle: Self::ADVERTISING_HANDLE_EXTENDED,
+            advertising_sid: 0,
+            advertising_tx_power: 0,
+            own_address_type: OwnAddressType::RandomDeviceAddress,
+            peer_address: default_ignored_peer_address(),
+            peer_address_type: PeerAddressType::PublicDeviceOrIdentityAddress,
+            primary_advertising_channel_map: 7,
+            primary_advertising_interval_max: 200,
+            primary_advertising_interval_min: 100,
+            primary_advertising_phy: PrimaryPhyType::Le1m,
+            scan_request_notification_enable: Enable::Disabled,
+            secondary_advertising_max_skip: 0,
+            secondary_advertising_phy: SecondaryPhyType::Le1m,
+        };
+        self.send_command(extended_advertising_params_cmd.into(), true)
+            .await?;
+
+        // set random address
+        let random_address: packets::Address =
+            self.random_address()?.try_into().map_err(|e| match e {
+                ConversionError::Python(pyerr) => pyerr,
+                ConversionError::Native(e) => PyErr::new::<PyException, _>(format!("{e:?}")),
+            })?;
+        let random_address_cmd = LeSetAdvertisingSetRandomAddressBuilder {
+            advertising_handle: Self::ADVERTISING_HANDLE_EXTENDED,
+            random_address,
+        };
+        self.send_command(random_address_cmd.into(), true).await?;
+
+        // set adv data
+        let advertising_data_cmd = LeSetExtendedAdvertisingDataBuilder {
+            advertising_data: adv_data.into_bytes(),
+            advertising_handle: Self::ADVERTISING_HANDLE_EXTENDED,
+            fragment_preference: FragmentPreference::ControllerMayFragment,
+            operation: Operation::CompleteAdvertisement,
+        };
+        self.send_command(advertising_data_cmd.into(), true).await?;
+
+        // enable adv
+        let extended_advertising_enable_cmd = LeSetExtendedAdvertisingEnableBuilder {
+            enable: Enable::Enabled,
+            enabled_sets: vec![EnabledSet {
+                advertising_handle: Self::ADVERTISING_HANDLE_EXTENDED,
+                duration: 0,
+                max_extended_advertising_events: 0,
+            }],
+        };
+        self.send_command(extended_advertising_enable_cmd.into(), true)
+            .await?;
+
+        self.advertising_status = AdvertisingStatus::AdvertisingExtended;
+        Ok(())
     }
 
     /// Stop advertising.
     pub async fn stop_advertising(&mut self) -> PyResult<()> {
         Python::with_gil(|py| {
-            self.0
+            self.obj
                 .call_method0(py, intern!(py, "stop_advertising"))
                 .and_then(|coroutine| into_future(coroutine.as_ref(py)))
         })?
         .await
-        .map(|_| ())
+        .map(|_| ())?;
+
+        if self.advertising_status == AdvertisingStatus::AdvertisingLegacy {
+            self.advertising_status = AdvertisingStatus::NotAdvertising;
+        }
+        Ok(())
+    }
+
+    /// Stop advertising extended.
+    #[cfg(feature = "unstable_extended_adv")]
+    pub async fn stop_advertising_extended(&mut self) -> PyResult<()> {
+        if AdvertisingStatus::AdvertisingExtended != self.advertising_status {
+            return Ok(());
+        }
+
+        // disable adv
+        let extended_advertising_enable_cmd = LeSetExtendedAdvertisingEnableBuilder {
+            enable: Enable::Disabled,
+            enabled_sets: vec![EnabledSet {
+                advertising_handle: Self::ADVERTISING_HANDLE_EXTENDED,
+                duration: 0,
+                max_extended_advertising_events: 0,
+            }],
+        };
+        self.send_command(extended_advertising_enable_cmd.into(), true)
+            .await?;
+
+        self.advertising_status = AdvertisingStatus::NotAdvertising;
+        Ok(())
     }
 
     /// Registers an L2CAP connection oriented channel server. When a client connects to the server,
@@ -286,7 +452,7 @@ impl Device {
             kwargs.set_opt_item("max_credits", max_credits)?;
             kwargs.set_opt_item("mtu", mtu)?;
             kwargs.set_opt_item("mps", mps)?;
-            self.0.call_method(
+            self.obj.call_method(
                 py,
                 intern!(py, "register_l2cap_channel_server"),
                 (),
@@ -295,6 +461,15 @@ impl Device {
         })?;
         Ok(())
     }
+
+    /// Gets the Device's `random_address` property
+    pub fn random_address(&self) -> PyResult<Address> {
+        Python::with_gil(|py| {
+            self.obj
+                .getattr(py, intern!(py, "random_address"))
+                .map(Address)
+        })
+    }
 }
 
 /// A connection to a remote device.
@@ -451,3 +626,13 @@ impl Advertisement {
         Python::with_gil(|py| self.0.getattr(py, intern!(py, "data")).map(AdvertisingData))
     }
 }
+
+/// Use this address when sending an HCI command that requires providing a peer address, but the
+/// command is such that the peer address will be ignored.
+///
+/// Internal to bumble, this address might mean "any", but a packets::Address typically gets sent
+/// directly to a controller, so we don't have to worry about it.
+#[cfg(feature = "unstable_extended_adv")]
+fn default_ignored_peer_address() -> packets::Address {
+    packets::Address::try_from(0x0000_0000_0000_u64).unwrap()
+}

rust/src/wrapper/device/tests.rs

@@ -0,0 +1,23 @@
+// Copyright 2023 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://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.
+
+#[cfg(feature = "unstable_extended_adv")]
+use crate::wrapper::device::default_ignored_peer_address;
+
+#[test]
+#[cfg(feature = "unstable_extended_adv")]
+fn default_peer_address_does_not_panic() {
+    let result = std::panic::catch_unwind(default_ignored_peer_address);
+    assert!(result.is_ok())
+}

rust/src/wrapper/hci.rs

@@ -14,18 +14,19 @@
 
 //! HCI
 
+// re-export here, and internal usages of these imports should refer to this mod, not the internal
+// mod
+pub(crate) use crate::internal::hci::WithPacketType;
 pub use crate::internal::hci::{packets, Error, Packet};
 
-use crate::{
-    internal::hci::WithPacketType,
-    wrapper::hci::packets::{AddressType, Command, ErrorCode},
+use crate::wrapper::{
+    hci::packets::{AddressType, Command, ErrorCode},
+    ConversionError,
 };
 use itertools::Itertools as _;
 use pyo3::{
-    exceptions::PyException,
-    intern, pyclass, pymethods,
-    types::{PyBytes, PyModule},
-    FromPyObject, IntoPy, PyAny, PyErr, PyObject, PyResult, Python, ToPyObject,
+    exceptions::PyException, intern, types::PyModule, FromPyObject, IntoPy, PyAny, PyErr, PyObject,
+    PyResult, Python, ToPyObject,
 };
 
 /// Provides helpers for interacting with HCI
@@ -43,17 +44,45 @@ impl HciConstant {
     }
 }
 
+/// Bumble's representation of an HCI command.
+pub(crate) struct HciCommand(pub(crate) PyObject);
+
+impl HciCommand {
+    fn from_bytes(bytes: &[u8]) -> PyResult<Self> {
+        Python::with_gil(|py| {
+            PyModule::import(py, intern!(py, "bumble.hci"))?
+                .getattr(intern!(py, "HCI_Command"))?
+                .call_method1(intern!(py, "from_bytes"), (bytes,))
+                .map(|obj| Self(obj.to_object(py)))
+        })
+    }
+}
+
+impl TryFrom<Command> for HciCommand {
+    type Error = PyErr;
+
+    fn try_from(value: Command) -> Result<Self, Self::Error> {
+        HciCommand::from_bytes(&value.to_vec_with_packet_type())
+    }
+}
+
+impl IntoPy<PyObject> for HciCommand {
+    fn into_py(self, _py: Python<'_>) -> PyObject {
+        self.0
+    }
+}
+
 /// A Bluetooth address
 #[derive(Clone)]
 pub struct Address(pub(crate) PyObject);
 
 impl Address {
-    /// Creates a new [Address] object
-    pub fn new(address: &str, address_type: &AddressType) -> PyResult<Self> {
+    /// Creates a new [Address] object.
+    pub fn new(address: &str, address_type: AddressType) -> PyResult<Self> {
         Python::with_gil(|py| {
             PyModule::import(py, intern!(py, "bumble.device"))?
                 .getattr(intern!(py, "Address"))?
-                .call1((address, address_type.to_object(py)))
+                .call1((address, address_type))
                 .map(|any| Self(any.into()))
         })
     }
@@ -118,27 +147,31 @@ impl ToPyObject for Address {
     }
 }
 
-/// Implements minimum necessary interface to be treated as bumble's [HCI_Command].
-/// While pyo3's macros do not support generics, this could probably be refactored to allow multiple
-/// implementations of the HCI_Command methods in the future, if needed.
-#[pyclass]
-pub(crate) struct HciCommandWrapper(pub(crate) Command);
+/// An error meaning that the u64 value did not represent a valid BT address.
+#[derive(Debug)]
+pub struct InvalidAddress(u64);
 
-#[pymethods]
-impl HciCommandWrapper {
-    fn __bytes__(&self, py: Python) -> PyResult<PyObject> {
-        let bytes = PyBytes::new(py, &self.0.clone().to_vec_with_packet_type());
-        Ok(bytes.into_py(py))
-    }
+impl TryInto<packets::Address> for Address {
+    type Error = ConversionError<InvalidAddress>;
 
-    #[getter]
-    fn op_code(&self) -> u16 {
-        self.0.get_op_code().into()
+    fn try_into(self) -> Result<packets::Address, Self::Error> {
+        let addr_le_bytes = self.as_le_bytes().map_err(ConversionError::Python)?;
+
+        // packets::Address only supports converting from a u64 (TODO: update if/when it supports converting from [u8; 6] -- https://github.com/google/pdl/issues/75)
+        // So first we take the python `Address` little-endian bytes (6 bytes), copy them into a
+        // [u8; 8] in little-endian format, and finally convert it into a u64.
+        let mut buf = [0_u8; 8];
+        buf[0..6].copy_from_slice(&addr_le_bytes);
+        let address_u64 = u64::from_le_bytes(buf);
+
+        packets::Address::try_from(address_u64)
+            .map_err(InvalidAddress)
+            .map_err(ConversionError::Native)
     }
 }
 
-impl ToPyObject for AddressType {
-    fn to_object(&self, py: Python<'_>) -> PyObject {
+impl IntoPy<PyObject> for AddressType {
+    fn into_py(self, py: Python<'_>) -> PyObject {
         u8::from(self).to_object(py)
     }
 }

rust/src/wrapper/mod.rs

@@ -132,3 +132,12 @@ pub(crate) fn wrap_python_async<'a>(py: Python<'a>, function: &'a PyAny) -> PyRe
         .getattr(intern!(py, "wrap_async"))?
         .call1((function,))
 }
+
+/// Represents the two major kinds of errors that can occur when converting between Rust and Python.
+pub enum ConversionError<T> {
+    /// Occurs across the Python/native boundary.
+    Python(PyErr),
+    /// Occurs within the native ecosystem, such as when performing more transformations before
+    /// finally converting to the native type.
+    Native(T),
+}

rust/src/wrapper/transport.rs

@@ -15,6 +15,7 @@
 //! HCI packet transport
 
 use crate::wrapper::controller::Controller;
+use futures::executor::block_on;
 use pyo3::{intern, types::PyModule, PyObject, PyResult, Python};
 
 /// A source/sink pair for HCI packet I/O.
@@ -58,9 +59,9 @@ impl Transport {
 
 impl Drop for Transport {
     fn drop(&mut self) {
-        // can't await in a Drop impl, but we can at least spawn a task to do it
-        let obj = self.0.clone();
-        tokio::spawn(async move { Self(obj).close().await });
+        // don't spawn a thread to handle closing, as it may get dropped at program termination,
+        // resulting in `RuntimeWarning: coroutine ... was never awaited` from Python
+        let _ = block_on(self.close());
     }
 }
 

setup.cfg

@@ -91,9 +91,13 @@ development =
     mypy == 1.5.0
     nox >= 2022
     pylint == 2.15.8
+    pyyaml >= 6.0
     types-appdirs >= 1.4.3
     types-invoke >= 1.7.3
     types-protobuf >= 4.21.0
+avatar =
+    pandora-avatar == 0.0.5
+    rootcanal == 1.3.0 ; python_version>='3.10'
 documentation =
     mkdocs >= 1.4.0
     mkdocs-material >= 8.5.6

tasks.py

@@ -125,7 +125,7 @@ def lint(ctx, disable='C,R', errors_only=False):
     print(f">>> Running the linter{qualifier}...")
     try:
         ctx.run(f"pylint {' '.join(options)} bumble apps examples tasks.py")
-        print("The linter is happy. ✅ 😊 🐝'")
+        print("The linter is happy. ✅ 😊 🐝")
     except UnexpectedExit as exc:
         print("Please check your code against the linter messages. ❌")
         raise Exit(code=1) from exc

tests/a2dp_test.py

@@ -185,7 +185,7 @@ async def test_source_sink_1():
         sink.on('rtp_packet', on_rtp_packet)
 
     # Create a listener to wait for AVDTP connections
-    listener = Listener(Listener.create_registrar(two_devices.devices[1]))
+    listener = Listener.for_device(two_devices.devices[1])
     listener.on('connection', on_avdtp_connection)
 
     async def make_connection():

tests/avdtp_test.py

@@ -45,12 +45,14 @@ def test_messages():
     ]
     message = Get_Capabilities_Response(capabilities)
     parsed = Message.create(
-        AVDTP_GET_CAPABILITIES, Message.RESPONSE_ACCEPT, message.payload
+        AVDTP_GET_CAPABILITIES, Message.MessageType.RESPONSE_ACCEPT, message.payload
     )
     assert message.payload == parsed.payload
 
     message = Set_Configuration_Command(3, 4, capabilities)
-    parsed = Message.create(AVDTP_SET_CONFIGURATION, Message.COMMAND, message.payload)
+    parsed = Message.create(
+        AVDTP_SET_CONFIGURATION, Message.MessageType.COMMAND, message.payload
+    )
     assert message.payload == parsed.payload
 
 

tests/keystore_test.py

@@ -94,6 +94,7 @@ def temporary_file():
 
 
 # -----------------------------------------------------------------------------
+@pytest.mark.asyncio
 async def test_basic(temporary_file):
     with open(temporary_file, mode='w', encoding='utf-8') as file:
         file.write("{}")
@@ -125,6 +126,7 @@ async def test_basic(temporary_file):
 
 
 # -----------------------------------------------------------------------------
+@pytest.mark.asyncio
 async def test_parsing(temporary_file):
     with open(temporary_file, mode='w', encoding='utf-8') as file:
         file.write(JSON1)
@@ -137,6 +139,7 @@ async def test_parsing(temporary_file):
 
 
 # -----------------------------------------------------------------------------
+@pytest.mark.asyncio
 async def test_default_namespace(temporary_file):
     with open(temporary_file, mode='w', encoding='utf-8') as file:
         file.write(JSON1)

tests/l2cap_test.py

@@ -22,7 +22,11 @@ import random
 import pytest
 
 from bumble.core import ProtocolError
-from bumble.l2cap import L2CAP_Connection_Request
+from bumble.l2cap import (
+    L2CAP_Connection_Request,
+    ClassicChannelSpec,
+    LeCreditBasedChannelSpec,
+)
 from .test_utils import TwoDevices
 
 
@@ -80,7 +84,9 @@ async def test_basic_connection():
 
     # Check that if there's no one listening, we can't connect
     with pytest.raises(ProtocolError):
-        l2cap_channel = await devices.connections[0].open_l2cap_channel(psm)
+        l2cap_channel = await devices.connections[0].create_l2cap_channel(
+            spec=LeCreditBasedChannelSpec(psm)
+        )
 
     # Now add a listener
     incoming_channel = None
@@ -95,8 +101,12 @@ async def test_basic_connection():
 
         channel.sink = on_data
 
-    devices.devices[1].register_l2cap_channel_server(psm, on_coc)
-    l2cap_channel = await devices.connections[0].open_l2cap_channel(psm)
+    devices.devices[1].create_l2cap_server(
+        spec=LeCreditBasedChannelSpec(psm=1234), handler=on_coc
+    )
+    l2cap_channel = await devices.connections[0].create_l2cap_channel(
+        spec=LeCreditBasedChannelSpec(psm)
+    )
 
     messages = (bytes([1, 2, 3]), bytes([4, 5, 6]), bytes(10000))
     for message in messages:
@@ -138,10 +148,13 @@ async def transfer_payload(max_credits, mtu, mps):
 
         channel.sink = on_data
 
-    psm = devices.devices[1].register_l2cap_channel_server(
-        psm=0, server=on_coc, max_credits=max_credits, mtu=mtu, mps=mps
+    server = devices.devices[1].create_l2cap_server(
+        spec=LeCreditBasedChannelSpec(max_credits=max_credits, mtu=mtu, mps=mps),
+        handler=on_coc,
+    )
+    l2cap_channel = await devices.connections[0].create_l2cap_channel(
+        spec=LeCreditBasedChannelSpec(server.psm)
     )
-    l2cap_channel = await devices.connections[0].open_l2cap_channel(psm)
 
     messages = [bytes([1, 2, 3, 4, 5, 6, 7]) * x for x in (3, 10, 100, 789)]
     for message in messages:
@@ -189,8 +202,12 @@ async def test_bidirectional_transfer():
     def on_client_data(data):
         client_received.append(data)
 
-    psm = devices.devices[1].register_l2cap_channel_server(psm=0, server=on_server_coc)
-    client_channel = await devices.connections[0].open_l2cap_channel(psm)
+    server = devices.devices[1].create_l2cap_server(
+        spec=LeCreditBasedChannelSpec(), handler=on_server_coc
+    )
+    client_channel = await devices.connections[0].create_l2cap_channel(
+        spec=LeCreditBasedChannelSpec(server.psm)
+    )
     client_channel.sink = on_client_data
 
     messages = [bytes([1, 2, 3, 4, 5, 6, 7]) * x for x in (3, 10, 100)]

tests/sdp_test.py

@@ -18,6 +18,7 @@
 import asyncio
 import logging
 import os
+import pytest
 
 from bumble.core import UUID, BT_L2CAP_PROTOCOL_ID, BT_RFCOMM_PROTOCOL_ID
 from bumble.sdp import (
@@ -99,13 +100,13 @@ def test_data_elements() -> None:
     e = DataElement(DataElement.UUID, UUID('61A3512C-09BE-4DDC-A6A6-0B03667AAFC6'))
     basic_check(e)
 
-    e = DataElement(DataElement.TEXT_STRING, 'hello')
+    e = DataElement(DataElement.TEXT_STRING, b'hello')
     basic_check(e)
 
-    e = DataElement(DataElement.TEXT_STRING, 'hello' * 60)
+    e = DataElement(DataElement.TEXT_STRING, b'hello' * 60)
     basic_check(e)
 
-    e = DataElement(DataElement.TEXT_STRING, 'hello' * 20000)
+    e = DataElement(DataElement.TEXT_STRING, b'hello' * 20000)
     basic_check(e)
 
     e = DataElement(DataElement.BOOLEAN, True)
@@ -121,7 +122,7 @@ def test_data_elements() -> None:
         DataElement.SEQUENCE,
         [
             DataElement(DataElement.BOOLEAN, True),
-            DataElement(DataElement.TEXT_STRING, 'hello'),
+            DataElement(DataElement.TEXT_STRING, b'hello'),
         ],
     )
     basic_check(e)
@@ -133,7 +134,7 @@ def test_data_elements() -> None:
         DataElement.ALTERNATIVE,
         [
             DataElement(DataElement.BOOLEAN, True),
-            DataElement(DataElement.TEXT_STRING, 'hello'),
+            DataElement(DataElement.TEXT_STRING, b'hello'),
         ],
     )
     basic_check(e)
@@ -151,19 +152,19 @@ def test_data_elements() -> None:
     e = DataElement.uuid(UUID.from_16_bits(1234))
     basic_check(e)
 
-    e = DataElement.text_string('hello')
+    e = DataElement.text_string(b'hello')
     basic_check(e)
 
     e = DataElement.boolean(True)
     basic_check(e)
 
     e = DataElement.sequence(
-        [DataElement.signed_integer(0, 1), DataElement.text_string('hello')]
+        [DataElement.signed_integer(0, 1), DataElement.text_string(b'hello')]
     )
     basic_check(e)
 
     e = DataElement.alternative(
-        [DataElement.signed_integer(0, 1), DataElement.text_string('hello')]
+        [DataElement.signed_integer(0, 1), DataElement.text_string(b'hello')]
     )
     basic_check(e)
 
@@ -202,6 +203,7 @@ def sdp_records():
 
 
 # -----------------------------------------------------------------------------
+@pytest.mark.asyncio
 async def test_service_search():
     # Setup connections
     devices = TwoDevices()
@@ -224,6 +226,7 @@ async def test_service_search():
 
 
 # -----------------------------------------------------------------------------
+@pytest.mark.asyncio
 async def test_service_attribute():
     # Setup connections
     devices = TwoDevices()
@@ -244,6 +247,7 @@ async def test_service_attribute():
 
 
 # -----------------------------------------------------------------------------
+@pytest.mark.asyncio
 async def test_service_search_attribute():
     # Setup connections
     devices = TwoDevices()

tools/generate_company_id_list.py

@@ -14,25 +14,25 @@
 
 # -----------------------------------------------------------------------------
 # This script generates a python-syntax list of dictionary entries for the
-# company IDs listed at: https://www.bluetooth.com/specifications/assigned-numbers/company-identifiers/
-# The input to this script is the CSV file that can be obtained at that URL
+# company IDs listed at:
+# https://bitbucket.org/bluetooth-SIG/public/src/main/assigned_numbers/company_identifiers/company_identifiers.yaml
+# The input to this script is the YAML file that can be obtained at that URL
 # -----------------------------------------------------------------------------
 
 # -----------------------------------------------------------------------------
 # Imports
 # -----------------------------------------------------------------------------
 import sys
-import csv
+import yaml
 
 # -----------------------------------------------------------------------------
-with open(sys.argv[1], newline='') as csvfile:
-    reader = csv.reader(csvfile, delimiter=',', quotechar='"')
-    lines = []
-    for row in reader:
-        if len(row) == 3 and row[1].startswith('0x'):
-            company_id = row[1]
-            company_name = row[2]
-            escaped_company_name = company_name.replace('"', '\\"')
-            lines.append(f'    {company_id}: "{escaped_company_name}"')
+with open(sys.argv[1], "r") as yaml_file:
+    root = yaml.safe_load(yaml_file)
+    companies = {}
+    for company in root["company_identifiers"]:
+        companies[company["value"]] = company["name"]
 
-    print(',\n'.join(reversed(lines)))
+    for company_id in sorted(companies.keys()):
+        company_name = companies[company_id]
+        escaped_company_name = company_name.replace('"', '\\"')
+        print(f'    0x{company_id:04X}: "{escaped_company_name}",')

web/bumble.js

@@ -5,11 +5,11 @@ function bufferToHex(buffer) {
 class PacketSource {
     constructor(pyodide) {
         this.parser = pyodide.runPython(`
-        from bumble.transport.common import PacketParser
-        class ProxiedPacketParser(PacketParser):
-            def feed_data(self, js_data):
-                super().feed_data(bytes(js_data.to_py()))
-        ProxiedPacketParser()
+            from bumble.transport.common import PacketParser
+            class ProxiedPacketParser(PacketParser):
+                def feed_data(self, js_data):
+                    super().feed_data(bytes(js_data.to_py()))
+            ProxiedPacketParser()
       `);
     }
 
@@ -18,74 +18,171 @@ class PacketSource {
     }
 
     data_received(data) {
-        console.log(`HCI[controller->host]: ${bufferToHex(data)}`);
+        //console.log(`HCI[controller->host]: ${bufferToHex(data)}`);
         this.parser.feed_data(data);
     }
 }
 
 class PacketSink {
-    constructor(writer) {
-        this.writer = writer;
-    }
-
     on_packet(packet) {
+        if (!this.writer) {
+            return;
+        }
         const buffer = packet.toJs({create_proxies : false});
         packet.destroy();
-        console.log(`HCI[host->controller]: ${bufferToHex(buffer)}`);
+        //console.log(`HCI[host->controller]: ${bufferToHex(buffer)}`);
         // TODO: create an async queue here instead of blindly calling write without awaiting
         this.writer(buffer);
     }
 }
 
-export async function connectWebSocketTransport(pyodide, hciWsUrl) {
-    return new Promise((resolve, reject) => {
-        let resolved = false;
-
-        let ws = new WebSocket(hciWsUrl);
-        ws.binaryType = "arraybuffer";
-
-        ws.onopen = () => {
-            console.log("WebSocket open");
-            resolve({
-                packet_source,
-                packet_sink
-            });
-            resolved = true;
-        }
-
-        ws.onclose = () => {
-            console.log("WebSocket close");
-            if (!resolved) {
-                reject(`Failed to connect to ${hciWsUrl}`)
-            }
-        }
-
-        ws.onmessage = (event) => {
-            packet_source.data_received(event.data);
-        }
-
-        const packet_source = new PacketSource(pyodide);
-        const packet_sink = new PacketSink((packet) => ws.send(packet));
-    })
+class LogEvent extends Event {
+    constructor(message) {
+        super('log');
+        this.message = message;
+    }
 }
 
-export async function loadBumble(pyodide, bumblePackage) {
-    // Load the Bumble module
-    await pyodide.loadPackage("micropip");
-    await pyodide.runPythonAsync(`
-        import micropip
-        await micropip.install("${bumblePackage}")
-        package_list = micropip.list()
-        print(package_list)
-    `)
+export class Bumble extends EventTarget {
+    constructor(pyodide) {
+        super();
+        this.pyodide = pyodide;
+    }
 
-    // Mount a filesystem so that we can persist data like the Key Store
-    let mountDir = "/bumble";
-    pyodide.FS.mkdir(mountDir);
-    pyodide.FS.mount(pyodide.FS.filesystems.IDBFS, { root: "." }, mountDir);
+    async loadRuntime(bumblePackage) {
+        // Load pyodide if it isn't provided.
+        if (this.pyodide === undefined) {
+            this.log('Loading Pyodide');
+            this.pyodide = await loadPyodide();
+        }
 
-    // Sync previously persisted filesystem data into memory
-    pyodide.FS.syncfs(true, () => {
-        console.log("FS synced in")
-    });
+        // Load the Bumble module
+        bumblePackage ||= 'bumble';
+        console.log('Installing micropip');
+        this.log(`Installing ${bumblePackage}`)
+        await this.pyodide.loadPackage('micropip');
+        await this.pyodide.runPythonAsync(`
+            import micropip
+            await micropip.install('${bumblePackage}')
+            package_list = micropip.list()
+            print(package_list)
+        `)
+
+        // Mount a filesystem so that we can persist data like the Key Store
+        let mountDir = '/bumble';
+        this.pyodide.FS.mkdir(mountDir);
+        this.pyodide.FS.mount(this.pyodide.FS.filesystems.IDBFS, { root: '.' }, mountDir);
+
+        // Sync previously persisted filesystem data into memory
+        await new Promise(resolve => {
+            this.pyodide.FS.syncfs(true, () => {
+                console.log('FS synced in');
+                resolve();
+            });
+        })
+
+        // Setup the HCI source and sink
+        this.packetSource = new PacketSource(this.pyodide);
+        this.packetSink = new PacketSink();
+    }
+
+    log(message) {
+        this.dispatchEvent(new LogEvent(message));
+    }
+
+    async connectWebSocketTransport(hciWsUrl) {
+        return new Promise((resolve, reject) => {
+            let resolved = false;
+
+            let ws = new WebSocket(hciWsUrl);
+            ws.binaryType = 'arraybuffer';
+
+            ws.onopen = () => {
+                this.log('WebSocket open');
+                resolve();
+                resolved = true;
+            }
+
+            ws.onclose = () => {
+                this.log('WebSocket close');
+                if (!resolved) {
+                    reject(`Failed to connect to ${hciWsUrl}`);
+                }
+            }
+
+            ws.onmessage = (event) => {
+                this.packetSource.data_received(event.data);
+            }
+
+            this.packetSink.writer = (packet) => {
+                if (ws.readyState === WebSocket.OPEN) {
+                    ws.send(packet);
+                }
+            }
+            this.closeTransport = async () => {
+                if (ws.readyState === WebSocket.OPEN) {
+                    ws.close();
+                }
+            }
+        })
+    }
+
+    async loadApp(appUrl) {
+        this.log('Loading app');
+        const script = await (await fetch(appUrl)).text();
+        await this.pyodide.runPythonAsync(script);
+        const pythonMain = this.pyodide.globals.get('main');
+        const app = await pythonMain(this.packetSource, this.packetSink);
+        if (app.on) {
+            app.on('key_store_update', this.onKeystoreUpdate.bind(this));
+        }
+        this.log('App is ready!');
+        return app;
+    }
+
+    onKeystoreUpdate() {
+        // Sync the FS
+        this.pyodide.FS.syncfs(() => {
+            console.log('FS synced out');
+        });
+    }
+}
+
+export async function setupSimpleApp(appUrl, bumbleControls, log) {
+    // Load Bumble
+    log('Loading Bumble');
+    const bumble = new Bumble();
+    bumble.addEventListener('log', (event) => {
+        log(event.message);
+    })
+    const params = (new URL(document.location)).searchParams;
+    await bumble.loadRuntime(params.get('package'));
+
+    log('Bumble is ready!')
+    const app = await bumble.loadApp(appUrl);
+
+    bumbleControls.connector = async (hciWsUrl) => {
+        try {
+            // Connect the WebSocket HCI transport
+            await bumble.connectWebSocketTransport(hciWsUrl);
+
+            // Start the app
+            await app.start();
+
+            return true;
+        } catch (err) {
+            log(err);
+            return false;
+        }
+    }
+    bumbleControls.stopper = async () => {
+        // Stop the app
+        await app.stop();
+
+        // Close the HCI transport
+        await bumble.closeTransport();
+    }
+    bumbleControls.onBumbleLoaded();
+
+    return app;
 }

web/heart_rate_monitor/heart_rate_monitor.html

@@ -0,0 +1,29 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <link rel="stylesheet" href="https://fonts.googleapis.com/icon?family=Material+Icons">
+  <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@24,400,0,0" />
+  <script src="https://cdn.jsdelivr.net/pyodide/v0.24.1/full/pyodide.js"></script>
+  <script type="module" src="../ui.js"></script>
+  <script type="module" src="heart_rate_monitor.js"></script>
+  <style>
+    #hr-value {
+      font-family: sans-serif;
+      font-size: xx-large;
+    }
+
+  </style>
+</head>
+<body>
+    <bumble-controls id="bumble-controls"></bumble-controls><hr>
+    <span class="material-symbols-outlined">
+      cardiology
+    </span>
+    <span id="hr-value">60</span>
+    <br>
+    <button id="hr-up-button" class="mdc-icon-button material-icons"><div class="mdc-icon-button__ripple"></div>arrow_upward</button>
+    <button id="hr-down-button" class="mdc-icon-button material-icons"><div class="mdc-icon-button__ripple"></div>arrow_downward</button>
+    <hr>
+    <textarea id="log-output" style="width: 100%;" rows="10" disabled></textarea><hr>
+</body>
+</html>

web/heart_rate_monitor/heart_rate_monitor.js

@@ -0,0 +1,30 @@
+import {setupSimpleApp} from '../bumble.js';
+
+const logOutput = document.querySelector('#log-output');
+function logToOutput(message) {
+    console.log(message);
+    logOutput.value += message + '\n';
+}
+
+let heartRate = 60;
+const heartRateText = document.querySelector('#hr-value')
+
+function setHeartRate(newHeartRate) {
+    heartRate = newHeartRate;
+    heartRateText.innerHTML = heartRate;
+    app.set_heart_rate(heartRate);
+}
+
+// Setup the UI
+const bumbleControls = document.querySelector('#bumble-controls');
+document.querySelector('#hr-up-button').addEventListener('click', () => {
+    setHeartRate(heartRate + 1);
+})
+document.querySelector('#hr-down-button').addEventListener('click', () => {
+    setHeartRate(heartRate - 1);
+})
+
+// Setup the app
+const app = await setupSimpleApp('heart_rate_monitor.py', bumbleControls, logToOutput);
+logToOutput('Click the Bluetooth button to start');
+

web/heart_rate_monitor/heart_rate_monitor.py

@@ -0,0 +1,119 @@
+# 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 struct
+
+from bumble.core import AdvertisingData
+from bumble.device import Device
+from bumble.hci import HCI_Reset_Command
+from bumble.profiles.device_information_service import DeviceInformationService
+from bumble.profiles.heart_rate_service import HeartRateService
+from bumble.utils import AsyncRunner
+
+
+# -----------------------------------------------------------------------------
+class HeartRateMonitor:
+    def __init__(self, hci_source, hci_sink):
+        self.heart_rate = 60
+
+        self.device = Device.with_hci(
+            'Bumble', 'F0:F1:F2:F3:F4:F5', hci_source, hci_sink
+        )
+
+        device_information_service = DeviceInformationService(
+            manufacturer_name='ACME',
+            model_number='HR-102',
+            serial_number='7654321',
+            hardware_revision='1.1.3',
+            software_revision='2.5.6',
+            system_id=(0x123456, 0x8877665544),
+        )
+
+        self.heart_rate_service = HeartRateService(
+            read_heart_rate_measurement=lambda _: HeartRateService.HeartRateMeasurement(
+                heart_rate=self.heart_rate,
+                sensor_contact_detected=True,
+            ),
+            body_sensor_location=HeartRateService.BodySensorLocation.WRIST,
+            reset_energy_expended=self.reset_energy_expended,
+        )
+
+        # Notify subscribers of the current value as soon as they subscribe
+        @self.heart_rate_service.heart_rate_measurement_characteristic.on(
+            'subscription'
+        )
+        def on_subscription(_, notify_enabled, indicate_enabled):
+            if notify_enabled or indicate_enabled:
+                self.notify_heart_rate()
+
+        self.device.add_services([device_information_service, self.heart_rate_service])
+
+        self.device.advertising_data = bytes(
+            AdvertisingData(
+                [
+                    (
+                        AdvertisingData.FLAGS,
+                        bytes(
+                            [
+                                AdvertisingData.LE_GENERAL_DISCOVERABLE_MODE_FLAG
+                                | AdvertisingData.BR_EDR_NOT_SUPPORTED_FLAG
+                            ]
+                        ),
+                    ),
+                    (
+                        AdvertisingData.COMPLETE_LOCAL_NAME,
+                        bytes('Bumble Heart', 'utf-8'),
+                    ),
+                    (
+                        AdvertisingData.INCOMPLETE_LIST_OF_16_BIT_SERVICE_CLASS_UUIDS,
+                        bytes(self.heart_rate_service.uuid),
+                    ),
+                    (AdvertisingData.APPEARANCE, struct.pack('<H', 0x0340)),
+                ]
+            )
+        )
+
+    async def start(self):
+        print('### Starting Monitor')
+        await self.device.power_on()
+        await self.device.start_advertising(auto_restart=True)
+        print('### Monitor started')
+
+    async def stop(self):
+        # TODO: replace this once a proper reset is implemented in the lib.
+        await self.device.host.send_command(HCI_Reset_Command())
+        await self.device.power_off()
+        print('### Monitor stopped')
+
+    def notify_heart_rate(self):
+        AsyncRunner.spawn(
+            self.device.notify_subscribers(
+                self.heart_rate_service.heart_rate_measurement_characteristic
+            )
+        )
+
+    def set_heart_rate(self, heart_rate):
+        self.heart_rate = heart_rate
+        self.notify_heart_rate()
+
+    def reset_energy_expended(self, _):
+        print('<<< Reset Energy Expended')
+
+
+# -----------------------------------------------------------------------------
+def main(hci_source, hci_sink):
+    return HeartRateMonitor(hci_source, hci_sink)

web/scanner/scanner.css

@@ -0,0 +1,3 @@
+body {
+    font-family: monospace;
+}

web/scanner/scanner.html

@@ -1,129 +1,21 @@
+<!DOCTYPE html>
 <html>
-
 <head>
-  <script src="https://cdn.jsdelivr.net/pyodide/v0.23.2/full/pyodide.js"></script>
-  <style>
-    body {
-      font-family: monospace;
-    }
-
-    table, th, td {
-      padding: 2px;
-      white-space: pre;
-      border: 1px solid black;
-      border-collapse: collapse;
-    }
+  <link rel="stylesheet" href="https://fonts.googleapis.com/icon?family=Material+Icons">
+  <link rel="stylesheet" href="scanner.css">
+  <script src="https://cdn.jsdelivr.net/pyodide/v0.24.1/full/pyodide.js"></script>
+  <script type="module" src="../ui.js"></script>
+  <script type="module" src="scanner.js"></script>
+</style>
   </style>
 </head>
-
 <body>
-  <button id="connectButton" disabled>Connect</button>
-  <br />
-  <br />
-  <div>Log Output</div><br>
-  <textarea id="output" style="width: 100%;" rows="10" disabled></textarea>
-  <div id="scanTableContainer"><table></table></div>
+    <script type="module">
+        import {LitElement, html} from 'https://cdn.jsdelivr.net/gh/lit/dist@2/core/lit-core.min.js';
+    </script>
 
-  <script type="module">
-    import { loadBumble, connectWebSocketTransport } from "../bumble.js"
-    let pyodide;
-    let output;
-
-    function logToOutput(s) {
-      output.value += s + "\n";
-      console.log(s);
-    }
-
-    async function run() {
-      const params = (new URL(document.location)).searchParams;
-      const hciWsUrl = params.get("hci") || "ws://localhost:9922/hci";
-
-      try {
-        // Create a WebSocket HCI transport
-        let transport
-        try {
-          transport = await connectWebSocketTransport(pyodide, hciWsUrl);
-        } catch (error) {
-          logToOutput(error);
-          return;
-        }
-
-        // Run the scanner example
-        const script = await (await fetch("scanner.py")).text();
-        await pyodide.runPythonAsync(script);
-        const pythonMain = pyodide.globals.get("main");
-        logToOutput("Starting scanner...");
-        await pythonMain(transport.packet_source, transport.packet_sink, onScanUpdate);
-        logToOutput("Scanner running");
-      } catch (err) {
-        logToOutput(err);
-      }
-    }
-
-    function onScanUpdate(scanEntries) {
-      scanEntries = scanEntries.toJs();
-
-      const scanTable = document.createElement("table");
-
-      const tableHeader = document.createElement("tr");
-      for (const name of ["Address", "Address Type", "RSSI", "Data"]) {
-        const header = document.createElement("th");
-        header.appendChild(document.createTextNode(name));
-        tableHeader.appendChild(header);
-      }
-      scanTable.appendChild(tableHeader);
-
-      scanEntries.forEach(entry => {
-        const row = document.createElement("tr");
-
-        const addressCell = document.createElement("td");
-        addressCell.appendChild(document.createTextNode(entry.address));
-        row.appendChild(addressCell);
-
-        const addressTypeCell = document.createElement("td");
-        addressTypeCell.appendChild(document.createTextNode(entry.address_type));
-        row.appendChild(addressTypeCell);
-
-        const rssiCell = document.createElement("td");
-        rssiCell.appendChild(document.createTextNode(entry.rssi));
-        row.appendChild(rssiCell);
-
-        const dataCell = document.createElement("td");
-        dataCell.appendChild(document.createTextNode(entry.data));
-        row.appendChild(dataCell);
-
-        scanTable.appendChild(row);
-      });
-
-      const scanTableContainer = document.getElementById("scanTableContainer");
-      scanTableContainer.replaceChild(scanTable, scanTableContainer.firstChild);
-
-      return true;
-    }
-
-    async function main() {
-      output = document.getElementById("output");
-
-      // Load pyodide
-      logToOutput("Loading Pyodide");
-      pyodide = await loadPyodide();
-
-      // Load Bumble
-      logToOutput("Loading Bumble");
-      const params = (new URL(document.location)).searchParams;
-      const bumblePackage = params.get("package") || "bumble";
-      await loadBumble(pyodide, bumblePackage);
-
-      logToOutput("Ready!")
-
-      // Enable the Connect button
-      const connectButton = document.getElementById("connectButton");
-      connectButton.disabled = false
-      connectButton.addEventListener("click", run)
-    }
-
-    main();
-  </script>
+    <bumble-controls id="bumble-controls"></bumble-controls><hr>
+    <textarea id="log-output" style="width: 100%;" rows="10" disabled></textarea><hr>
+    <scan-list id="scan-list"></scan-list>
 </body>
-
-</html>
+</html>

web/scanner/scanner.js

@@ -0,0 +1,68 @@
+import {LitElement, html, css} from 'https://cdn.jsdelivr.net/gh/lit/dist@2/core/lit-core.min.js';
+import {setupSimpleApp} from '../bumble.js';
+
+ class ScanList extends LitElement {
+    static properties = {
+        listItems: {state: true},
+    };
+
+    static styles = css`
+        table, th, td {
+            padding: 2px;
+            white-space: pre;
+            border: 1px solid black;
+            border-collapse: collapse;
+        }
+    `;
+
+    constructor() {
+        super();
+        this.listItems = [];
+    }
+
+    render() {
+        if (this.listItems.length === 0) {
+            return '';
+        }
+        return html`
+            <table>
+                <thead>
+                    <tr>
+                        ${Object.keys(this.listItems[0]).map(i => html`<th>${i}</th>`)}
+                    </tr>
+                </thead>
+                <tbody>
+                    ${this.listItems.map(i => html`
+                    <tr>
+                        ${Object.keys(i).map(key => html`<td>${i[key]}</td>`)}
+                    </tr>
+                    `)}
+                </tbody>
+            </table>
+        `;
+    }
+}
+customElements.define('scan-list', ScanList);
+
+const logOutput = document.querySelector('#log-output');
+function logToOutput(message) {
+    console.log(message);
+    logOutput.value += message + '\n';
+}
+
+function onUpdate(scanResults) {
+    const items = scanResults.toJs({create_proxies : false}).map(entry => (
+        { address: entry.address, address_type: entry.address_type, rssi: entry.rssi, data: entry.data }
+    ));
+    scanResults.destroy();
+    scanList.listItems = items;
+}
+
+// Setup the UI
+const scanList = document.querySelector('#scan-list');
+const bumbleControls = document.querySelector('#bumble-controls');
+
+// Setup the app
+const app = await setupSimpleApp('scanner.py', bumbleControls, logToOutput);
+app.on('update', onUpdate);
+logToOutput('Click the Bluetooth button to start');

web/scanner/scanner.py

@@ -15,39 +15,59 @@
 # -----------------------------------------------------------------------------
 # Imports
 # -----------------------------------------------------------------------------
-import time
-
 from bumble.device import Device
+from bumble.hci import HCI_Reset_Command
 
 
 # -----------------------------------------------------------------------------
-class ScanEntry:
-    def __init__(self, advertisement):
-        self.address = advertisement.address.to_string(False)
-        self.address_type = ('Public', 'Random', 'Public Identity', 'Random Identity')[
-            advertisement.address.address_type
-        ]
-        self.rssi = advertisement.rssi
-        self.data = advertisement.data.to_string("\n")
+class Scanner:
+    class ScanEntry:
+        def __init__(self, advertisement):
+            self.address = advertisement.address.to_string(False)
+            self.address_type = (
+                'Public',
+                'Random',
+                'Public Identity',
+                'Random Identity',
+            )[advertisement.address.address_type]
+            self.rssi = advertisement.rssi
+            self.data = advertisement.data.to_string('\n')
 
+    def __init__(self, hci_source, hci_sink):
+        super().__init__()
+        self.device = Device.with_hci(
+            'Bumble', 'F0:F1:F2:F3:F4:F5', hci_source, hci_sink
+        )
+        self.scan_entries = {}
+        self.listeners = {}
+        self.device.on('advertisement', self.on_advertisement)
 
-# -----------------------------------------------------------------------------
-class ScannerListener(Device.Listener):
-    def __init__(self, callback):
-        self.callback = callback
-        self.entries = {}
+    async def start(self):
+        print('### Starting Scanner')
+        self.scan_entries = {}
+        self.emit_update()
+        await self.device.power_on()
+        await self.device.start_scanning()
+        print('### Scanner started')
+
+    async def stop(self):
+        # TODO: replace this once a proper reset is implemented in the lib.
+        await self.device.host.send_command(HCI_Reset_Command())
+        await self.device.power_off()
+        print('### Scanner stopped')
+
+    def emit_update(self):
+        if listener := self.listeners.get('update'):
+            listener(list(self.scan_entries.values()))
+
+    def on(self, event_name, listener):
+        self.listeners[event_name] = listener
 
     def on_advertisement(self, advertisement):
-        self.entries[advertisement.address] = ScanEntry(advertisement)
-        self.callback(list(self.entries.values()))
+        self.scan_entries[advertisement.address] = self.ScanEntry(advertisement)
+        self.emit_update()
 
 
 # -----------------------------------------------------------------------------
-async def main(hci_source, hci_sink, callback):
-    print('### Starting Scanner')
-    device = Device.with_hci('Bumble', 'F0:F1:F2:F3:F4:F5', hci_source, hci_sink)
-    device.listener = ScannerListener(callback)
-    await device.power_on()
-    await device.start_scanning()
-
-    print('### Scanner started')
+def main(hci_source, hci_sink):
+    return Scanner(hci_source, hci_sink)

web/speaker/speaker.css

@@ -11,7 +11,16 @@ body, h1, h2, h3, h4, h5, h6 {
     border: none;
     border-radius: 4px;
     padding: 8px;
-    display: inline-block;
+    display: none;
+    margin: 4px;
+}
+
+#progressText {
+    background-color: rgb(179, 208, 146);
+    border: none;
+    border-radius: 4px;
+    padding: 8px;
+    display: none;
     margin: 4px;
 }
 

web/speaker/speaker.html

@@ -2,13 +2,14 @@
 <html>
 <head>
   <title>Bumble Speaker</title>
-  <script src="https://cdn.jsdelivr.net/pyodide/v0.23.2/full/pyodide.js"></script>
-  <script type="module" src="speaker.js"></script>
+  <link rel="stylesheet" href="https://fonts.googleapis.com/icon?family=Material+Icons">
   <link rel="stylesheet" href="speaker.css">
+  <script src="https://cdn.jsdelivr.net/pyodide/v0.24.1/full/pyodide.js"></script>
+  <script type="module" src="speaker.js"></script>
+  <script type="module" src="../ui.js"></script>
 </head>
 <body>
   <h1><img src="logo.svg" width=100 height=100 style="vertical-align:middle" alt=""/>Bumble Virtual Speaker</h1>
-  <div id="errorText"></div>
   <div id="speaker">
     <table><tr>
       <td>
@@ -25,7 +26,8 @@
     <span id="streamStateText">IDLE</span>
     <span id="connectionStateText">NOT CONNECTED</span>
     <div id="controlsDiv">
-        <button id="audioOnButton">Audio On</button>
+      <bumble-controls id="bumble-controls"></bumble-controls>
+      <button id="audioOnButton" class="mdc-icon-button material-icons"><div class="mdc-icon-button__ripple"></div>volume_up</button>
     </div>
     <canvas id="fftCanvas" width="1024", height="300">Audio Frequencies Animation</canvas>
     <audio id="audio"></audio>

web/speaker/speaker.js

@@ -1,4 +1,4 @@
-import { loadBumble, connectWebSocketTransport } from "../bumble.js";
+import {setupSimpleApp} from '../bumble.js';
 
 (function () {
     'use strict';
@@ -8,7 +8,6 @@ import { loadBumble, connectWebSocketTransport } from "../bumble.js";
     let bytesReceivedText;
     let streamStateText;
     let connectionStateText;
-    let errorText;
     let audioOnButton;
     let mediaSource;
     let sourceBuffer;
@@ -19,15 +18,14 @@ import { loadBumble, connectWebSocketTransport } from "../bumble.js";
     let audioFrequencyData;
     let packetsReceived = 0;
     let bytesReceived = 0;
-    let audioState = "stopped";
-    let streamState = "IDLE";
+    let audioState = 'stopped';
+    let streamState = 'IDLE';
     let fftCanvas;
     let fftCanvasContext;
     let bandwidthCanvas;
     let bandwidthCanvasContext;
     let bandwidthBinCount;
     let bandwidthBins = [];
-    let pyodide;
 
     const FFT_WIDTH = 800;
     const FFT_HEIGHT = 256;
@@ -44,18 +42,16 @@ import { loadBumble, connectWebSocketTransport } from "../bumble.js";
     }
 
     function initUI() {
-        audioOnButton = document.getElementById("audioOnButton");
-        codecText = document.getElementById("codecText");
-        packetsReceivedText = document.getElementById("packetsReceivedText");
-        bytesReceivedText = document.getElementById("bytesReceivedText");
-        streamStateText = document.getElementById("streamStateText");
-        errorText = document.getElementById("errorText");
-        connectionStateText = document.getElementById("connectionStateText");
+        audioOnButton = document.getElementById('audioOnButton');
+        codecText = document.getElementById('codecText');
+        packetsReceivedText = document.getElementById('packetsReceivedText');
+        bytesReceivedText = document.getElementById('bytesReceivedText');
+        streamStateText = document.getElementById('streamStateText');
+        connectionStateText = document.getElementById('connectionStateText');
 
-        audioOnButton.onclick = () => startAudio();
+        audioOnButton.onclick = startAudio;
 
-        codecText.innerText = "AAC";
-        setErrorText("");
+        codecText.innerText = 'AAC';
 
         requestAnimationFrame(onAnimationFrame);
     }
@@ -68,62 +64,36 @@ import { loadBumble, connectWebSocketTransport } from "../bumble.js";
     }
 
     function initAudioElement() {
-        audioElement = document.getElementById("audio");
+        audioElement = document.getElementById('audio');
         audioElement.src = URL.createObjectURL(mediaSource);
         // audioElement.controls = true;
     }
 
     function initAnalyzer() {
-        fftCanvas = document.getElementById("fftCanvas");
+        fftCanvas = document.getElementById('fftCanvas');
         fftCanvas.width = FFT_WIDTH
         fftCanvas.height = FFT_HEIGHT
         fftCanvasContext = fftCanvas.getContext('2d');
-        fftCanvasContext.fillStyle = "rgb(0, 0, 0)";
+        fftCanvasContext.fillStyle = 'rgb(0, 0, 0)';
         fftCanvasContext.fillRect(0, 0, FFT_WIDTH, FFT_HEIGHT);
 
-        bandwidthCanvas = document.getElementById("bandwidthCanvas");
+        bandwidthCanvas = document.getElementById('bandwidthCanvas');
         bandwidthCanvas.width = BANDWIDTH_WIDTH
         bandwidthCanvas.height = BANDWIDTH_HEIGHT
         bandwidthCanvasContext = bandwidthCanvas.getContext('2d');
-        bandwidthCanvasContext.fillStyle = "rgb(255, 255, 255)";
+        bandwidthCanvasContext.fillStyle = 'rgb(255, 255, 255)';
         bandwidthCanvasContext.fillRect(0, 0, BANDWIDTH_WIDTH, BANDWIDTH_HEIGHT);
     }
 
     async function initBumble() {
-        // Load pyodide
-        console.log("Loading Pyodide");
-        pyodide = await loadPyodide();
-
-        // Load Bumble
-        console.log("Loading Bumble");
-        const params = (new URL(document.location)).searchParams;
-        const bumblePackage = params.get("package") || "bumble";
-        await loadBumble(pyodide, bumblePackage);
-
-        console.log("Ready!")
-
-        const hciWsUrl = params.get("hci") || "ws://localhost:9922/hci";
-        try {
-            // Create a WebSocket HCI transport
-            let transport
-            try {
-                transport = await connectWebSocketTransport(pyodide, hciWsUrl);
-            } catch (error) {
-                console.error(error);
-                setErrorText(error);
-                return;
-            }
-
-            // Run the scanner example
-            const script = await (await fetch("speaker.py")).text();
-            await pyodide.runPythonAsync(script);
-            const pythonMain = pyodide.globals.get("main");
-            console.log("Starting speaker...");
-            await pythonMain(transport.packet_source, transport.packet_sink, onEvent);
-            console.log("Speaker running");
-        } catch (err) {
-            console.log(err);
-        }
+        const bumbleControls = document.querySelector('#bumble-controls');
+        const app = await setupSimpleApp('speaker.py', bumbleControls, console.log);
+        app.on('start', onStart);
+        app.on('stop', onStop);
+        app.on('suspend', onSuspend);
+        app.on('connection', onConnection);
+        app.on('disconnection', onDisconnection);
+        app.on('audio', onAudio);
     }
 
     function startAnalyzer() {
@@ -144,15 +114,6 @@ import { loadBumble, connectWebSocketTransport } from "../bumble.js";
         bandwidthBins = [];
     }
 
-    function setErrorText(message) {
-        errorText.innerText = message;
-        if (message.length == 0) {
-            errorText.style.display = "none";
-        } else {
-            errorText.style.display = "inline-block";
-        }
-    }
-
     function setStreamState(state) {
         streamState = state;
         streamStateText.innerText = streamState;
@@ -162,7 +123,7 @@ import { loadBumble, connectWebSocketTransport } from "../bumble.js";
         // FFT
         if (audioAnalyzer !== undefined) {
             audioAnalyzer.getByteFrequencyData(audioFrequencyData);
-            fftCanvasContext.fillStyle = "rgb(0, 0, 0)";
+            fftCanvasContext.fillStyle = 'rgb(0, 0, 0)';
             fftCanvasContext.fillRect(0, 0, FFT_WIDTH, FFT_HEIGHT);
             const barCount = audioFrequencyBinCount;
             const barWidth = (FFT_WIDTH / audioFrequencyBinCount) - 1;
@@ -174,7 +135,7 @@ import { loadBumble, connectWebSocketTransport } from "../bumble.js";
         }
 
         // Bandwidth
-        bandwidthCanvasContext.fillStyle = "rgb(255, 255, 255)";
+        bandwidthCanvasContext.fillStyle = 'rgb(255, 255, 255)';
         bandwidthCanvasContext.fillRect(0, 0, BANDWIDTH_WIDTH, BANDWIDTH_HEIGHT);
         bandwidthCanvasContext.fillStyle = `rgb(100, 100, 100)`;
         for (let t = 0; t < bandwidthBins.length; t++) {
@@ -188,7 +149,7 @@ import { loadBumble, connectWebSocketTransport } from "../bumble.js";
 
     function onMediaSourceOpen() {
         console.log(this.readyState);
-        sourceBuffer = mediaSource.addSourceBuffer("audio/aac");
+        sourceBuffer = mediaSource.addSourceBuffer('audio/aac');
     }
 
     function onMediaSourceClose() {
@@ -201,41 +162,30 @@ import { loadBumble, connectWebSocketTransport } from "../bumble.js";
 
     async function startAudio() {
         try {
-            console.log("starting audio...");
+            console.log('starting audio...');
             audioOnButton.disabled = true;
-            audioState = "starting";
+            audioState = 'starting';
             await audioElement.play();
-            console.log("audio started");
-            audioState = "playing";
+            console.log('audio started');
+            audioState = 'playing';
             startAnalyzer();
         } catch (error) {
             console.error(`play failed: ${error}`);
-            audioState = "stopped";
+            audioState = 'stopped';
             audioOnButton.disabled = false;
         }
     }
 
-    async function onEvent(name, params) {
-        // Dispatch the message.
-        const handlerName = `on${name.charAt(0).toUpperCase()}${name.slice(1)}`
-        const handler = eventHandlers[handlerName];
-        if (handler !== undefined) {
-            handler(params);
-        } else {
-            console.warn(`unhandled event: ${name}`)
-        }
-    }
-
     function onStart() {
-        setStreamState("STARTED");
+        setStreamState('STARTED');
     }
 
     function onStop() {
-        setStreamState("STOPPED");
+        setStreamState('STOPPED');
     }
 
     function onSuspend() {
-        setStreamState("SUSPENDED");
+        setStreamState('SUSPENDED');
     }
 
     function onConnection(params) {
@@ -243,13 +193,13 @@ import { loadBumble, connectWebSocketTransport } from "../bumble.js";
     }
 
     function onDisconnection(params) {
-        connectionStateText.innerText = "DISCONNECTED";
+        connectionStateText.innerText = 'DISCONNECTED';
     }
 
     function onAudio(python_packet) {
         const packet = python_packet.toJs({create_proxies : false});
         python_packet.destroy();
-        if (audioState != "stopped") {
+        if (audioState != 'stopped') {
             // Queue the audio packet.
             sourceBuffer.appendBuffer(packet);
         }
@@ -265,25 +215,7 @@ import { loadBumble, connectWebSocketTransport } from "../bumble.js";
         }
     }
 
-    function onKeystoreupdate() {
-        // Sync the FS
-        pyodide.FS.syncfs(() => {
-            console.log("FS synced out")
-        });
-    }
-
-    const eventHandlers = {
-        onStart,
-        onStop,
-        onSuspend,
-        onConnection,
-        onDisconnection,
-        onAudio,
-        onKeystoreupdate
-    }
-
     window.onload = (event) => {
         init();
     }
-
 }());

web/speaker/speaker.py

@@ -47,6 +47,7 @@ from bumble.a2dp import (
 )
 from bumble.utils import AsyncRunner
 from bumble.codecs import AacAudioRtpPacket
+from bumble.hci import HCI_Reset_Command
 
 
 # -----------------------------------------------------------------------------
@@ -95,15 +96,14 @@ class Speaker:
         STARTED = 2
         SUSPENDED = 3
 
-    def __init__(self, hci_source, hci_sink, emit_event, codec, discover):
+    def __init__(self, hci_source, hci_sink, codec):
         self.hci_source = hci_source
         self.hci_sink = hci_sink
-        self.emit_event = emit_event
+        self.js_listeners = {}
         self.codec = codec
-        self.discover = discover
         self.device = None
         self.connection = None
-        self.listener = None
+        self.avdtp_listener = None
         self.packets_received = 0
         self.bytes_received = 0
         self.stream_state = Speaker.StreamState.IDLE
@@ -164,7 +164,7 @@ class Speaker:
 
     def on_key_store_update(self):
         print("Key Store updated")
-        self.emit_event('keystoreupdate', None)
+        self.emit('key_store_update')
 
     def on_bluetooth_connection(self, connection):
         print(f'Connection: {connection}')
@@ -172,15 +172,12 @@ class Speaker:
         connection.on('disconnection', self.on_bluetooth_disconnection)
         peer_name = '' if connection.peer_name is None else connection.peer_name
         peer_address = connection.peer_address.to_string(False)
-        self.emit_event(
-            'connection', {'peer_name': peer_name, 'peer_address': peer_address}
-        )
+        self.emit('connection', {'peer_name': peer_name, 'peer_address': peer_address})
 
     def on_bluetooth_disconnection(self, reason):
         print(f'Disconnection ({reason})')
         self.connection = None
-        AsyncRunner.spawn(self.advertise())
-        self.emit_event('disconnection', None)
+        self.emit('disconnection', None)
 
     def on_avdtp_connection(self, protocol):
         print('Audio Stream Open')
@@ -198,27 +195,23 @@ class Speaker:
         # Listen for close events
         protocol.on('close', self.on_avdtp_close)
 
-        # Discover all endpoints on the remote device is requested
-        if self.discover:
-            AsyncRunner.spawn(self.discover_remote_endpoints(protocol))
-
     def on_avdtp_close(self):
         print("Audio Stream Closed")
 
     def on_sink_start(self):
         print("Sink Started")
         self.stream_state = self.StreamState.STARTED
-        self.emit_event('start', None)
+        self.emit('start', None)
 
     def on_sink_stop(self):
         print("Sink Stopped")
         self.stream_state = self.StreamState.STOPPED
-        self.emit_event('stop', None)
+        self.emit('stop', None)
 
     def on_sink_suspend(self):
         print("Sink Suspended")
         self.stream_state = self.StreamState.SUSPENDED
-        self.emit_event('suspend', None)
+        self.emit('suspend', None)
 
     def on_sink_configuration(self, config):
         print("Sink Configuration:")
@@ -234,11 +227,7 @@ class Speaker:
     def on_rtp_packet(self, packet):
         self.packets_received += 1
         self.bytes_received += len(packet.payload)
-        self.emit_event("audio", self.audio_extractor.extract_audio(packet))
-
-    async def advertise(self):
-        await self.device.set_discoverable(True)
-        await self.device.set_connectable(True)
+        self.emit("audio", self.audio_extractor.extract_audio(packet))
 
     async def connect(self, address):
         # Connect to the source
@@ -257,7 +246,7 @@ class Speaker:
         print('*** Encryption on')
 
         protocol = await Protocol.connect(connection)
-        self.listener.set_server(connection, protocol)
+        self.avdtp_listener.set_server(connection, protocol)
         self.on_avdtp_connection(protocol)
 
     async def discover_remote_endpoints(self, protocol):
@@ -266,6 +255,13 @@ class Speaker:
         for endpoint in endpoints:
             print('@@@', endpoint)
 
+    def on(self, event_name, listener):
+        self.js_listeners[event_name] = listener
+
+    def emit(self, event_name, event=None):
+        if listener := self.js_listeners.get(event_name):
+            listener(event)
+
     async def run(self, connect_address):
         # Create a device
         device_config = DeviceConfiguration()
@@ -296,8 +292,8 @@ class Speaker:
         self.device.on('key_store_update', self.on_key_store_update)
 
         # Create a listener to wait for AVDTP connections
-        self.listener = Listener(Listener.create_registrar(self.device))
-        self.listener.on('connection', self.on_avdtp_connection)
+        self.avdtp_listener = Listener.for_device(self.device)
+        self.avdtp_listener.on('connection', self.on_avdtp_connection)
 
         print(f'Speaker ready to play, codec={self.codec}')
 
@@ -309,13 +305,19 @@ class Speaker:
                 print("Connection timed out")
                 return
         else:
-            # Start being discoverable and connectable
+            # We'll wait for a connection
             print("Waiting for connection...")
-            await self.advertise()
+
+    async def start(self):
+        await self.run(None)
+
+    async def stop(self):
+        # TODO: replace this once a proper reset is implemented in the lib.
+        await self.device.host.send_command(HCI_Reset_Command())
+        await self.device.power_off()
+        print('Speaker stopped')
 
 
 # -----------------------------------------------------------------------------
-async def main(hci_source, hci_sink, emit_event):
-    # logging.basicConfig(level='DEBUG')
-    speaker = Speaker(hci_source, hci_sink, emit_event, "aac", False)
-    await speaker.run(None)
+def main(hci_source, hci_sink):
+    return Speaker(hci_source, hci_sink, "aac")

web/ui.js

@@ -0,0 +1,102 @@
+import {LitElement, html} from 'https://cdn.jsdelivr.net/gh/lit/dist@2/core/lit-core.min.js';
+
+class BumbleControls extends LitElement {
+    constructor() {
+        super();
+        this.bumbleLoaded = false;
+        this.connected = false;
+    }
+
+    render() {
+        return html`
+            <link rel="stylesheet" href="https://fonts.googleapis.com/icon?family=Material+Icons">
+            <dialog id="settings-dialog" @close=${this.onSettingsDialogClose} style="font-family:sans-serif">
+                <p>WebSocket URL for HCI transport</p>
+                <form>
+                    <input id="settings-hci-url-input" type="text" size="50"></input>
+                    <button value="cancel" formmethod="dialog">Cancel</button>
+                    <button @click=${this.saveSettings}>Save</button>
+                </form>
+            </dialog>
+            <button @click=${this.openSettingsDialog} class="mdc-icon-button material-icons"><div class="mdc-icon-button__ripple"></div>settings</button>
+            <button @click=${this.connectBluetooth} ?disabled=${!this.canConnect()} class="mdc-icon-button material-icons"><div class="mdc-icon-button__ripple"></div>bluetooth</button>
+            <button @click=${this.stop} ?disabled=${!this.connected} class="mdc-icon-button material-icons"><div class="mdc-icon-button__ripple"></div>stop</button>
+        `
+    }
+
+    get settingsHciUrlInput() {
+        return this.renderRoot.querySelector('#settings-hci-url-input');
+    }
+
+    get settingsDialog() {
+        return this.renderRoot.querySelector('#settings-dialog');
+    }
+
+    canConnect() {
+        return this.bumbleLoaded && !this.connected && this.getHciUrl();
+    }
+
+    getHciUrl() {
+        // Look for a URL parameter setting first.
+        const params = (new URL(document.location)).searchParams;
+        let hciWsUrl = params.get("hci");
+        if (hciWsUrl) {
+          return hciWsUrl;
+        }
+
+        // Try to load the setting from storage.
+        hciWsUrl = localStorage.getItem("hciWsUrl");
+        if (hciWsUrl) {
+          return hciWsUrl;
+        }
+
+        // Finally, default to nothing.
+        return null;
+    }
+
+    openSettingsDialog() {
+        const hciUrl = this.getHciUrl();
+        if (hciUrl) {
+            this.settingsHciUrlInput.value = hciUrl;
+        } else {
+          // Start with default, assuming port 7681.
+          this.settingsHciUrlInput.value = "ws://localhost:7681/v1/websocket/bt"
+        }
+        this.settingsDialog.showModal();
+    }
+
+    onSettingsDialogClose() {
+        if (this.settingsDialog.returnValue === "cancel") {
+            return;
+        }
+        if (this.settingsHciUrlInput.value) {
+            localStorage.setItem("hciWsUrl", this.settingsHciUrlInput.value);
+        } else {
+            localStorage.removeItem("hciWsUrl");
+        }
+
+        this.requestUpdate();
+    }
+
+    saveSettings(event) {
+        event.preventDefault();
+        this.settingsDialog.close(this.settingsHciUrlInput.value);
+    }
+
+    async connectBluetooth() {
+        this.connected = await this.connector(this.getHciUrl());
+        this.requestUpdate();
+    }
+
+    async stop() {
+        await this.stopper();
+        this.connected = false;
+        this.requestUpdate();
+    }
+
+    onBumbleLoaded() {
+        this.bumbleLoaded = true;
+        this.requestUpdate();
+    }
+}
+customElements.define('bumble-controls', BumbleControls);