Skip to content

Latest commit

 

History

History
179 lines (146 loc) · 6.1 KB

bench.md

File metadata and controls

179 lines (146 loc) · 6.1 KB

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-clientutils), 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
```