rename .run to .spawn

add snoop support

apps/controller_info.py

@@ -30,6 +30,8 @@ from bumble.hci import (
     HCI_VERSION_NAMES,
     LMP_VERSION_NAMES,
     HCI_Command,
+    HCI_Command_Complete_Event,
+    HCI_Command_Status_Event,
     HCI_READ_BD_ADDR_COMMAND,
     HCI_Read_BD_ADDR_Command,
     HCI_READ_LOCAL_NAME_COMMAND,
@@ -45,11 +47,20 @@ from bumble.host import Host
 from bumble.transport import open_transport_or_link
 
 
+# -----------------------------------------------------------------------------
+def command_succeeded(response):
+    if isinstance(response, HCI_Command_Status_Event):
+        return response.status == HCI_SUCCESS
+    if isinstance(response, HCI_Command_Complete_Event):
+        return response.return_parameters.status == HCI_SUCCESS
+    return False
+
+
 # -----------------------------------------------------------------------------
 async def get_classic_info(host):
     if host.supports_command(HCI_READ_BD_ADDR_COMMAND):
         response = await host.send_command(HCI_Read_BD_ADDR_Command())
-        if response.return_parameters.status == HCI_SUCCESS:
+        if command_succeeded(response):
             print()
             print(
                 color('Classic Address:', 'yellow'), response.return_parameters.bd_addr
@@ -57,7 +68,7 @@ async def get_classic_info(host):
 
     if host.supports_command(HCI_READ_LOCAL_NAME_COMMAND):
         response = await host.send_command(HCI_Read_Local_Name_Command())
-        if response.return_parameters.status == HCI_SUCCESS:
+        if command_succeeded(response):
             print()
             print(
                 color('Local Name:', 'yellow'),
@@ -73,7 +84,7 @@ async def get_le_info(host):
         response = await host.send_command(
             HCI_LE_Read_Number_Of_Supported_Advertising_Sets_Command()
         )
-        if response.return_parameters.status == HCI_SUCCESS:
+        if command_succeeded(response):
             print(
                 color('LE Number Of Supported Advertising Sets:', 'yellow'),
                 response.return_parameters.num_supported_advertising_sets,
@@ -84,7 +95,7 @@ async def get_le_info(host):
         response = await host.send_command(
             HCI_LE_Read_Maximum_Advertising_Data_Length_Command()
         )
-        if response.return_parameters.status == HCI_SUCCESS:
+        if command_succeeded(response):
             print(
                 color('LE Maximum Advertising Data Length:', 'yellow'),
                 response.return_parameters.max_advertising_data_length,
@@ -93,7 +104,7 @@ async def get_le_info(host):
 
     if host.supports_command(HCI_LE_READ_MAXIMUM_DATA_LENGTH_COMMAND):
         response = await host.send_command(HCI_LE_Read_Maximum_Data_Length_Command())
-        if response.return_parameters.status == HCI_SUCCESS:
+        if command_succeeded(response):
             print(
                 color('Maximum Data Length:', 'yellow'),
                 (

bumble/att.py

@@ -25,12 +25,14 @@
 from __future__ import annotations
 import struct
 from pyee import EventEmitter
-from typing import Dict, Type
+from typing import Dict, Type, TYPE_CHECKING
 
 from bumble.core import UUID, name_or_number
 from bumble.hci import HCI_Object, key_with_value
 from bumble.colors import color
 
+if TYPE_CHECKING:
+    from bumble.device import Connection
 
 # -----------------------------------------------------------------------------
 # Constants
@@ -749,7 +751,25 @@ class Attribute(EventEmitter):
     def decode_value(self, value_bytes):
         return value_bytes
 
-    def read_value(self, connection):
+    def read_value(self, connection: Connection):
+        if (
+            self.permissions & self.READ_REQUIRES_ENCRYPTION
+        ) and not connection.encryption:
+            raise ATT_Error(
+                error_code=ATT_INSUFFICIENT_ENCRYPTION_ERROR, att_handle=self.handle
+            )
+        if (
+            self.permissions & self.READ_REQUIRES_AUTHENTICATION
+        ) and not connection.authenticated:
+            raise ATT_Error(
+                error_code=ATT_INSUFFICIENT_AUTHENTICATION_ERROR, att_handle=self.handle
+            )
+        if self.permissions & self.READ_REQUIRES_AUTHORIZATION:
+            # TODO: handle authorization better
+            raise ATT_Error(
+                error_code=ATT_INSUFFICIENT_AUTHORIZATION_ERROR, att_handle=self.handle
+            )
+
         if read := getattr(self.value, 'read', None):
             try:
                 value = read(connection)  # pylint: disable=not-callable
@@ -762,7 +782,25 @@ class Attribute(EventEmitter):
 
         return self.encode_value(value)
 
-    def write_value(self, connection, value_bytes):
+    def write_value(self, connection: Connection, value_bytes):
+        if (
+            self.permissions & self.WRITE_REQUIRES_ENCRYPTION
+        ) and not connection.encryption:
+            raise ATT_Error(
+                error_code=ATT_INSUFFICIENT_ENCRYPTION_ERROR, att_handle=self.handle
+            )
+        if (
+            self.permissions & self.WRITE_REQUIRES_AUTHENTICATION
+        ) and not connection.authenticated:
+            raise ATT_Error(
+                error_code=ATT_INSUFFICIENT_AUTHENTICATION_ERROR, att_handle=self.handle
+            )
+        if self.permissions & self.WRITE_REQUIRES_AUTHORIZATION:
+            # TODO: handle authorization better
+            raise ATT_Error(
+                error_code=ATT_INSUFFICIENT_AUTHORIZATION_ERROR, att_handle=self.handle
+            )
+
         value = self.decode_value(value_bytes)
 
         if write := getattr(self.value, 'write', None):

bumble/core.py

@@ -144,9 +144,12 @@ class ConnectionError(BaseError):  # pylint: disable=redefined-builtin
 class UUID:
     '''
     See Bluetooth spec Vol 3, Part B - 2.5.1 UUID
+
+    Note that this class expects and works in little-endian byte-order throughout.
+    The exception is when interacting with strings, which are in big-endian byte-order.
     '''
 
-    BASE_UUID = bytes.fromhex('00001000800000805F9B34FB')
+    BASE_UUID = bytes.fromhex('00001000800000805F9B34FB')[::-1]  # little-endian
     UUIDS: List[UUID] = []  # Registry of all instances created
 
     def __init__(self, uuid_str_or_int, name=None):
@@ -209,13 +212,20 @@ class UUID:
         return offset + 2, cls.from_bytes(uuid_as_bytes[offset : offset + 2])
 
     def to_bytes(self, force_128=False):
-        if len(self.uuid_bytes) == 16 or not force_128:
+        '''
+        Serialize UUID in little-endian byte-order
+        '''
+        if not force_128:
             return self.uuid_bytes
 
-        if len(self.uuid_bytes) == 4:
-            return self.uuid_bytes + UUID.BASE_UUID
-
-        return self.uuid_bytes + bytes([0, 0]) + UUID.BASE_UUID
+        if len(self.uuid_bytes) == 2:
+            return self.BASE_UUID + self.uuid_bytes + bytes([0, 0])
+        elif len(self.uuid_bytes) == 4:
+            return self.BASE_UUID + self.uuid_bytes
+        elif len(self.uuid_bytes) == 16:
+            return self.uuid_bytes
+        else:
+            assert False, "unreachable"
 
     def to_pdu_bytes(self):
         '''

bumble/device.py

@@ -50,6 +50,7 @@ from .hci import (
     HCI_LE_EXTENDED_CREATE_CONNECTION_COMMAND,
     HCI_LE_RAND_COMMAND,
     HCI_LE_READ_PHY_COMMAND,
+    HCI_LE_SET_PHY_COMMAND,
     HCI_MITM_NOT_REQUIRED_GENERAL_BONDING_AUTHENTICATION_REQUIREMENTS,
     HCI_MITM_NOT_REQUIRED_NO_BONDING_AUTHENTICATION_REQUIREMENTS,
     HCI_MITM_REQUIRED_GENERAL_BONDING_AUTHENTICATION_REQUIREMENTS,
@@ -534,6 +535,9 @@ class Connection(CompositeEventEmitter):
         def on_connection_parameters_update_failure(self, error):
             pass
 
+        def on_connection_data_length_change(self):
+            pass
+
         def on_connection_phy_update(self):
             pass
 
@@ -1239,6 +1243,11 @@ class Device(CompositeEventEmitter):
         # Done
         self.powered_on = True
 
+    async def power_off(self) -> None:
+        if self.powered_on:
+            await self.host.flush()
+            self.powered_on = False
+
     def supports_le_feature(self, feature):
         return self.host.supports_le_feature(feature)
 
@@ -1663,7 +1672,7 @@ class Device(CompositeEventEmitter):
                         )
                     )
                     if not phys:
-                        raise ValueError('least one supported PHY needed')
+                        raise ValueError('at least one supported PHY needed')
 
                     phy_count = len(phys)
                     initiating_phys = phy_list_to_bits(phys)
@@ -1804,7 +1813,7 @@ class Device(CompositeEventEmitter):
 
                 try:
                     return await self.abort_on('flush', pending_connection)
-                except ConnectionError as error:
+                except core.ConnectionError as error:
                     raise core.TimeoutError() from error
         finally:
             self.remove_listener('connection', on_connection)
@@ -2008,7 +2017,7 @@ class Device(CompositeEventEmitter):
         NOTE: the name of the parameters may look odd, but it just follows the names
         used in the Bluetooth spec.
         '''
-        await self.send_command(
+        result = await self.send_command(
             HCI_LE_Connection_Update_Command(
                 connection_handle=connection.handle,
                 connection_interval_min=connection_interval_min,
@@ -2017,9 +2026,10 @@ class Device(CompositeEventEmitter):
                 supervision_timeout=supervision_timeout,
                 min_ce_length=min_ce_length,
                 max_ce_length=max_ce_length,
-            ),
-            check_result=True,
+            )
         )
+        if result.status != HCI_Command_Status_Event.PENDING:
+            raise HCI_StatusError(result)
 
     async def get_connection_rssi(self, connection):
         result = await self.send_command(
@@ -2037,21 +2047,31 @@ class Device(CompositeEventEmitter):
     async def set_connection_phy(
         self, connection, tx_phys=None, rx_phys=None, phy_options=None
     ):
+        if not self.host.supports_command(HCI_LE_SET_PHY_COMMAND):
+            logger.warning('ignoring request, command not supported')
+            return
+
         all_phys_bits = (1 if tx_phys is None else 0) | (
             (1 if rx_phys is None else 0) << 1
         )
 
-        return await self.send_command(
+        result = await self.send_command(
             HCI_LE_Set_PHY_Command(
                 connection_handle=connection.handle,
                 all_phys=all_phys_bits,
                 tx_phys=phy_list_to_bits(tx_phys),
                 rx_phys=phy_list_to_bits(rx_phys),
                 phy_options=0 if phy_options is None else int(phy_options),
-            ),
-            check_result=True,
+            )
         )
 
+        if result.status != HCI_COMMAND_STATUS_PENDING:
+            logger.warning(
+                'HCI_LE_Set_PHY_Command failed: '
+                f'{HCI_Constant.error_name(result.status)}'
+            )
+            raise HCI_StatusError(result)
+
     async def set_default_phy(self, tx_phys=None, rx_phys=None):
         all_phys_bits = (1 if tx_phys is None else 0) | (
             (1 if rx_phys is None else 0) << 1
@@ -2490,7 +2510,7 @@ class Device(CompositeEventEmitter):
             self.advertising = False
 
         # Notify listeners
-        error = ConnectionError(
+        error = core.ConnectionError(
             error_code,
             transport,
             peer_address,
@@ -2563,7 +2583,7 @@ class Device(CompositeEventEmitter):
     @with_connection_from_handle
     def on_disconnection_failure(self, connection, error_code):
         logger.debug(f'*** Disconnection failed: {error_code}')
-        error = ConnectionError(
+        error = core.ConnectionError(
             error_code,
             connection.transport,
             connection.peer_address,

bumble/gatt_server.py

@@ -61,7 +61,6 @@ from .att import (
 from .gatt import (
     GATT_CHARACTERISTIC_ATTRIBUTE_TYPE,
     GATT_CLIENT_CHARACTERISTIC_CONFIGURATION_DESCRIPTOR,
-    GATT_INCLUDE_ATTRIBUTE_TYPE,
     GATT_MAX_ATTRIBUTE_VALUE_SIZE,
     GATT_PRIMARY_SERVICE_ATTRIBUTE_TYPE,
     GATT_REQUEST_TIMEOUT,
@@ -543,8 +542,6 @@ class Server(EventEmitter):
             if attribute.handle >= request.starting_handle
             and attribute.handle <= request.ending_handle
         ):
-            # TODO: check permissions
-
             this_uuid_size = len(attribute.type.to_pdu_bytes())
 
             if attributes:
@@ -638,6 +635,13 @@ class Server(EventEmitter):
         '''
 
         pdu_space_available = connection.att_mtu - 2
+
+        response = ATT_Error_Response(
+            request_opcode_in_error=request.op_code,
+            attribute_handle_in_error=request.starting_handle,
+            error_code=ATT_ATTRIBUTE_NOT_FOUND_ERROR,
+        )
+
         attributes = []
         for attribute in (
             attribute
@@ -647,10 +651,21 @@ class Server(EventEmitter):
             and attribute.handle <= request.ending_handle
             and pdu_space_available
         ):
-            # TODO: check permissions
+
+            try:
+                attribute_value = attribute.read_value(connection)
+            except ATT_Error as error:
+                # If the first attribute is unreadable, return an error
+                # Otherwise return attributes up to this point
+                if not attributes:
+                    response = ATT_Error_Response(
+                        request_opcode_in_error=request.op_code,
+                        attribute_handle_in_error=attribute.handle,
+                        error_code=error.error_code,
+                    )
+                break
 
             # Check the attribute value size
-            attribute_value = attribute.read_value(connection)
             max_attribute_size = min(connection.att_mtu - 4, 253)
             if len(attribute_value) > max_attribute_size:
                 # We need to truncate
@@ -676,11 +691,7 @@ class Server(EventEmitter):
                 length=entry_size, attribute_data_list=b''.join(attribute_data_list)
             )
         else:
-            response = ATT_Error_Response(
-                request_opcode_in_error=request.op_code,
-                attribute_handle_in_error=request.starting_handle,
-                error_code=ATT_ATTRIBUTE_NOT_FOUND_ERROR,
-            )
+            logging.debug(f"not found {request}")
 
         self.send_response(connection, response)
 
@@ -690,10 +701,17 @@ class Server(EventEmitter):
         '''
 
         if attribute := self.get_attribute(request.attribute_handle):
-            # TODO: check permissions
-            value = attribute.read_value(connection)
-            value_size = min(connection.att_mtu - 1, len(value))
-            response = ATT_Read_Response(attribute_value=value[:value_size])
+            try:
+                value = attribute.read_value(connection)
+            except ATT_Error as error:
+                response = ATT_Error_Response(
+                    request_opcode_in_error=request.op_code,
+                    attribute_handle_in_error=request.attribute_handle,
+                    error_code=error.error_code,
+                )
+            else:
+                value_size = min(connection.att_mtu - 1, len(value))
+                response = ATT_Read_Response(attribute_value=value[:value_size])
         else:
             response = ATT_Error_Response(
                 request_opcode_in_error=request.op_code,
@@ -708,29 +726,36 @@ class Server(EventEmitter):
         '''
 
         if attribute := self.get_attribute(request.attribute_handle):
-            # TODO: check permissions
-            value = attribute.read_value(connection)
-            if request.value_offset > len(value):
+            try:
+                value = attribute.read_value(connection)
+            except ATT_Error as error:
                 response = ATT_Error_Response(
                     request_opcode_in_error=request.op_code,
                     attribute_handle_in_error=request.attribute_handle,
-                    error_code=ATT_INVALID_OFFSET_ERROR,
-                )
-            elif len(value) <= connection.att_mtu - 1:
-                response = ATT_Error_Response(
-                    request_opcode_in_error=request.op_code,
-                    attribute_handle_in_error=request.attribute_handle,
-                    error_code=ATT_ATTRIBUTE_NOT_LONG_ERROR,
+                    error_code=error.error_code,
                 )
             else:
-                part_size = min(
-                    connection.att_mtu - 1, len(value) - request.value_offset
-                )
-                response = ATT_Read_Blob_Response(
-                    part_attribute_value=value[
-                        request.value_offset : request.value_offset + part_size
-                    ]
-                )
+                if request.value_offset > len(value):
+                    response = ATT_Error_Response(
+                        request_opcode_in_error=request.op_code,
+                        attribute_handle_in_error=request.attribute_handle,
+                        error_code=ATT_INVALID_OFFSET_ERROR,
+                    )
+                elif len(value) <= connection.att_mtu - 1:
+                    response = ATT_Error_Response(
+                        request_opcode_in_error=request.op_code,
+                        attribute_handle_in_error=request.attribute_handle,
+                        error_code=ATT_ATTRIBUTE_NOT_LONG_ERROR,
+                    )
+                else:
+                    part_size = min(
+                        connection.att_mtu - 1, len(value) - request.value_offset
+                    )
+                    response = ATT_Read_Blob_Response(
+                        part_attribute_value=value[
+                            request.value_offset : request.value_offset + part_size
+                        ]
+                    )
         else:
             response = ATT_Error_Response(
                 request_opcode_in_error=request.op_code,
@@ -746,7 +771,6 @@ class Server(EventEmitter):
         if request.attribute_group_type not in (
             GATT_PRIMARY_SERVICE_ATTRIBUTE_TYPE,
             GATT_SECONDARY_SERVICE_ATTRIBUTE_TYPE,
-            GATT_INCLUDE_ATTRIBUTE_TYPE,
         ):
             response = ATT_Error_Response(
                 request_opcode_in_error=request.op_code,
@@ -766,8 +790,10 @@ class Server(EventEmitter):
             and attribute.handle <= request.ending_handle
             and pdu_space_available
         ):
-            # Check the attribute value size
+            # No need to catch permission errors here, since these attributes
+            # must all be world-readable
             attribute_value = attribute.read_value(connection)
+            # Check the attribute value size
             max_attribute_size = min(connection.att_mtu - 6, 251)
             if len(attribute_value) > max_attribute_size:
                 # We need to truncate

bumble/hci.py

@@ -1421,7 +1421,11 @@ class HCI_Constant:
 # -----------------------------------------------------------------------------
 class HCI_Error(ProtocolError):
     def __init__(self, error_code):
-        super().__init__(error_code, 'hci', HCI_Constant.error_name(error_code))
+        super().__init__(
+            error_code,
+            error_namespace='hci',
+            error_name=HCI_Constant.error_name(error_code),
+        )
 
 
 # -----------------------------------------------------------------------------

bumble/l2cap.py

@@ -796,6 +796,11 @@ class Channel(EventEmitter):
         self.disconnection_result = asyncio.get_running_loop().create_future()
         return await self.disconnection_result
 
+    def abort(self):
+        if self.state == self.OPEN:
+            self.change_state(self.CLOSED)
+            self.emit('close')
+
     def send_configure_request(self):
         options = L2CAP_Control_Frame.encode_configuration_options(
             [
@@ -1105,6 +1110,10 @@ class LeConnectionOrientedChannel(EventEmitter):
         self.disconnection_result = asyncio.get_running_loop().create_future()
         return await self.disconnection_result
 
+    def abort(self):
+        if self.state == self.CONNECTED:
+            self.change_state(self.DISCONNECTED)
+
     def on_pdu(self, pdu):
         if self.sink is None:
             logger.warning('received pdu without a sink')
@@ -1492,8 +1501,12 @@ class ChannelManager:
     def on_disconnection(self, connection_handle, _reason):
         logger.debug(f'disconnection from {connection_handle}, cleaning up channels')
         if connection_handle in self.channels:
+            for _, channel in self.channels[connection_handle].items():
+                channel.abort()
             del self.channels[connection_handle]
         if connection_handle in self.le_coc_channels:
+            for _, channel in self.le_coc_channels[connection_handle].items():
+                channel.abort()
             del self.le_coc_channels[connection_handle]
         if connection_handle in self.identifiers:
             del self.identifiers[connection_handle]

bumble/rfcomm.py

@@ -852,17 +852,27 @@ class Server(EventEmitter):
         # Register ourselves with the L2CAP channel manager
         device.register_l2cap_server(RFCOMM_PSM, self.on_connection)
 
-    def listen(self, acceptor):
-        # Find a free channel number
-        for channel in range(
-            RFCOMM_DYNAMIC_CHANNEL_NUMBER_START, RFCOMM_DYNAMIC_CHANNEL_NUMBER_END + 1
-        ):
-            if channel not in self.acceptors:
-                self.acceptors[channel] = acceptor
-                return channel
+    def listen(self, acceptor, channel=0):
+        if channel:
+            if channel in self.acceptors:
+                # Busy
+                return 0
+        else:
+            # Find a free channel number
+            for candidate in range(
+                RFCOMM_DYNAMIC_CHANNEL_NUMBER_START,
+                RFCOMM_DYNAMIC_CHANNEL_NUMBER_END + 1,
+            ):
+                if candidate not in self.acceptors:
+                    channel = candidate
+                    break
 
-        # All channels used...
-        return 0
+            if channel == 0:
+                # All channels used...
+                return 0
+
+        self.acceptors[channel] = acceptor
+        return channel
 
     def on_connection(self, l2cap_channel):
         logger.debug(f'+++ new L2CAP connection: {l2cap_channel}')

bumble/utils.py

@@ -20,7 +20,7 @@ import logging
 import traceback
 import collections
 import sys
-from typing import Awaitable, TypeVar
+from typing import Awaitable, Set, TypeVar
 from functools import wraps
 from pyee import EventEmitter
 
@@ -157,6 +157,9 @@ class AsyncRunner:
     # Shared default queue
     default_queue = WorkQueue()
 
+    # Shared set of running tasks
+    running_tasks: Set[Awaitable] = set()
+
     @staticmethod
     def run_in_task(queue=None):
         """
@@ -187,6 +190,19 @@ class AsyncRunner:
 
         return decorator
 
+    @staticmethod
+    def spawn(coroutine):
+        """
+        Spawn a task to run a coroutine in a "fire and forget" mode.
+
+        Using this method instead of just calling `asyncio.create_task(coroutine)`
+        is necessary when you don't keep a reference to the task, because `asyncio`
+        only keeps weak references to alive tasks.
+        """
+        task = asyncio.create_task(coroutine)
+        AsyncRunner.running_tasks.add(task)
+        task.add_done_callback(AsyncRunner.running_tasks.remove)
+
 
 # -----------------------------------------------------------------------------
 class FlowControlAsyncPipe:

docs/mkdocs/mkdocs.yml

@@ -43,7 +43,7 @@ nav:
   - Apps & Tools:
     - Overview: apps_and_tools/index.md
     - Console: apps_and_tools/console.md
-    - Link Relay: apps_and_tools/link_relay.md
+    - Bench: apps_and_tools/bench.md
     - HCI Bridge: apps_and_tools/hci_bridge.md
     - Golden Gate Bridge: apps_and_tools/gg_bridge.md
     - Show: apps_and_tools/show.md
@@ -51,6 +51,7 @@ nav:
     - Pair: apps_and_tools/pair.md
     - Unbond: apps_and_tools/unbond.md
     - USB Probe: apps_and_tools/usb_probe.md
+    - Link Relay: apps_and_tools/link_relay.md
   - Hardware:
     - Overview: hardware/index.md
   - Platforms:
@@ -62,7 +63,7 @@ nav:
   - Examples:
     - Overview: examples/index.md
 
-copyright: Copyright 2021-2022 Google LLC
+copyright: Copyright 2021-2023 Google LLC
 
 theme:
   name: 'material'

docs/mkdocs/src/apps_and_tools/bench.md

@@ -0,0 +1,158 @@
+BENCH TOOL
+==========
+
+The "bench" tool implements a number of different ways of measuring the
+throughput and/or latency between two devices.
+
+# General Usage
+
+```
+Usage: bench.py [OPTIONS] COMMAND [ARGS]...
+
+Options:
+  --device-config FILENAME        Device configuration file
+  --role [sender|receiver|ping|pong]
+  --mode [gatt-client|gatt-server|l2cap-client|l2cap-server|rfcomm-client|rfcomm-server]
+  --att-mtu MTU                   GATT MTU (gatt-client mode)  [23<=x<=517]
+  -s, --packet-size SIZE          Packet size (server role)  [8<=x<=4096]
+  -c, --packet-count COUNT        Packet count (server role)
+  -sd, --start-delay SECONDS      Start delay (server role)
+  --help                          Show this message and exit.
+
+Commands:
+  central     Run as a central (initiates the connection)
+  peripheral  Run as a peripheral (waits for a connection)
+```
+
+## Options for the ``central`` Command
+```
+Usage: bumble-bench central [OPTIONS] TRANSPORT
+
+  Run as a central (initiates the connection)
+
+Options:
+  --peripheral ADDRESS_OR_NAME    Address or name to connect to
+  --connection-interval, --ci CONNECTION_INTERVAL
+                                  Connection interval (in ms)
+  --phy [1m|2m|coded]             PHY to use
+  --help                          Show this message and exit.
+```
+
+
+To test once device against another, one of the two devices must be running 
+the ``peripheral`` command and the other the ``central`` command. The device
+running the ``peripheral`` command will accept connections from the device
+running the ``central`` command.
+When using Bluetooth LE (all modes except for ``rfcomm-server`` and ``rfcomm-client``utils),
+the default addresses configured in the tool should be sufficient. But when using 
+Bluetooth Classic, the address of the Peripheral must be specified on the Central 
+using the ``--peripheral`` option. The address will be printed by the Peripheral when
+it starts.
+
+Independently of whether the device is the Central or Peripheral, each device selects a
+``mode`` and and ``role`` to run as. The ``mode`` and ``role`` of the Central and Peripheral
+must be compatible.
+
+Device 1 mode     | Device 2 mode
+------------------|------------------
+``gatt-client``   | ``gatt-server``
+``l2cap-client``  | ``l2cap-server``
+``rfcomm-client`` | ``rfcomm-server``
+
+Device 1 role | Device 2 role
+--------------|--------------
+``sender``    | ``receiver``
+``ping``      | ``pong``
+
+
+# Examples
+
+In the following examples, we have two USB Bluetooth controllers, one on `usb:0` and
+the other on `usb:1`, and two consoles/terminals. We will run a command in each.
+
+!!! example "GATT Throughput"
+    Using the default mode and role for the Central and Peripheral.
+
+    In the first console/terminal:
+    ```
+    $ bumble-bench peripheral usb:0
+    ```
+
+    In the second console/terminal:
+    ```
+    $ bumble-bench central usb:1
+    ```
+
+    In this default configuration, the Central runs a Sender, as a GATT client, 
+    connecting to the Peripheral running a Receiver, as a GATT server.
+
+!!! example "L2CAP Throughput"
+    In the first console/terminal:
+    ```
+    $ bumble-bench --mode l2cap-server peripheral usb:0
+    ```
+
+    In the second console/terminal:
+    ```
+    $ bumble-bench --mode l2cap-client central usb:1
+    ```
+
+!!! example "RFComm Throughput"
+    In the first console/terminal:
+    ```
+    $ bumble-bench --mode rfcomm-server peripheral usb:0
+    ```
+
+    NOTE: the BT address of the Peripheral will be printed out, use it with the
+    ``--peripheral`` option for the Central.
+
+    In this example, we use a larger packet size and packet count than the default.
+
+    In the second console/terminal:
+    ```
+    $ bumble-bench --mode rfcomm-client --packet-size 2000 --packet-count 100 central --peripheral 00:16:A4:5A:40:F2 usb:1
+    ```
+
+!!! example "Ping/Pong Latency"
+    In the first console/terminal:
+    ```
+    $ bumble-bench --role pong peripheral usb:0
+    ```
+
+    In the second console/terminal:
+    ```
+    $ bumble-bench --role ping central usb:1
+    ```
+
+!!! example "Reversed modes with GATT and custom connection interval"
+    In the first console/terminal:
+    ```
+    $ bumble-bench --mode gatt-client peripheral usb:0
+    ```
+
+    In the second console/terminal:
+    ```
+    $ bumble-bench --mode gatt-server central --ci 10 usb:1
+    ```
+
+!!! example "Reversed modes with L2CAP and custom PHY"
+    In the first console/terminal:
+    ```
+    $ bumble-bench --mode l2cap-client peripheral usb:0
+    ```
+
+    In the second console/terminal:
+    ```
+    $ bumble-bench --mode l2cap-server central --phy 2m usb:1
+    ```
+
+!!! example "Reversed roles with L2CAP"
+    In the first console/terminal:
+    ```
+    $ bumble-bench --mode l2cap-client --role sender peripheral usb:0
+    ```
+
+    In the second console/terminal:
+    ```
+    $ bumble-bench --mode l2cap-server --role receiver central usb:1
+    ```

docs/mkdocs/src/apps_and_tools/index.md

@@ -5,6 +5,7 @@ Included in the project are a few apps and tools, built on top of the core libra
 These include:
 
   * [Console](console.md) - an interactive text-based console
+  * [Bench](bench.md) - Speed and Latency benchmarking between two devices (LE and Classic)
   * [Pair](pair.md) - Pair/bond two devices (LE and Classic)
   * [Unbond](unbond.md) - Remove a previously established bond
   * [HCI Bridge](hci_bridge.md) - a HCI transport bridge to connect two HCI transports and filter/snoop the HCI packets

docs/mkdocs/src/index.md

@@ -8,8 +8,7 @@ The project initially only supported BLE (Bluetooth Low Energy), but support for
 eventually added. Support for BLE is therefore currently somewhat more advanced than for Classic.
 
 !!! warning
-    This project is still very much experimental and in an alpha state where a lot of things are still missing or broken, and what's there changes frequently.
-    Also, there are still a few hardcoded values/parameters in some of the examples and apps which need to be changed (those will eventually be command line arguments, as appropriate)
+    This project is still in an early state of development where some things are still missing or broken, and what's implemented may change and evolve frequently.
 
 Overview
 --------

setup.cfg

@@ -57,6 +57,7 @@ console_scripts =
     bumble-unbond = bumble.apps.unbond:main
     bumble-usb-probe = bumble.apps.usb_probe:main
     bumble-link-relay = bumble.apps.link_relay.link_relay:main
+    bumble-bench = bumble.apps.bench:main
 
 [options.package_data]
 * = py.typed, *.pyi