BENCH TOOL
==========

The "bench" tool implements a number of different ways of measuring the
throughput and/or latency between two devices.

# General Usage

```
Usage: bumble-bench [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]
  --extended-data-length TEXT     Request a data length upon connection,
                                  specified as tx_octets/tx_time
  --rfcomm-channel INTEGER        RFComm channel to use
  --rfcomm-uuid TEXT              RFComm service UUID to use (ignored if
                                  --rfcomm-channel is not 0)
  --l2cap-psm INTEGER             L2CAP PSM to use
  --l2cap-mtu INTEGER             L2CAP MTU to use
  --l2cap-mps INTEGER             L2CAP MPS to use
  --l2cap-max-credits INTEGER     L2CAP maximum number of credits allowed for
                                  the peer
  -s, --packet-size SIZE          Packet size (client or ping role)
                                  [8<=x<=4096]
  -c, --packet-count COUNT        Packet count (client or ping role)
  -sd, --start-delay SECONDS      Start delay (client or ping role)
  --repeat N                      Repeat the run N times (client and ping
                                  roles)(0, which is the fault, to run just
                                  once)
  --repeat-delay SECONDS          Delay, in seconds, between repeats
  --pace MILLISECONDS             Wait N milliseconds between packets (0,
                                  which is the fault, to send as fast as
                                  possible)
  --linger                        Don't exit at the end of a run (server and
                                  pong roles)
  --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
  --authenticate                  Authenticate (RFComm only)
  --encrypt                       Encrypt the connection (RFComm only)
  --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
    ```