add benchmark tool and doc

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,147 @@
+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),
+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
+    ```

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