1BENCH TOOL 2========== 3 4The "bench" tool implements a number of different ways of measuring the 5throughput and/or latency between two devices. 6 7# General Usage 8 9``` 10Usage: bumble-bench [OPTIONS] COMMAND [ARGS]... 11 12Options: 13 --device-config FILENAME Device configuration file 14 --role [sender|receiver|ping|pong] 15 --mode [gatt-client|gatt-server|l2cap-client|l2cap-server|rfcomm-client|rfcomm-server] 16 --att-mtu MTU GATT MTU (gatt-client mode) [23<=x<=517] 17 --extended-data-length TEXT Request a data length upon connection, 18 specified as tx_octets/tx_time 19 --rfcomm-channel INTEGER RFComm channel to use 20 --rfcomm-uuid TEXT RFComm service UUID to use (ignored if 21 --rfcomm-channel is not 0) 22 --l2cap-psm INTEGER L2CAP PSM to use 23 --l2cap-mtu INTEGER L2CAP MTU to use 24 --l2cap-mps INTEGER L2CAP MPS to use 25 --l2cap-max-credits INTEGER L2CAP maximum number of credits allowed for 26 the peer 27 -s, --packet-size SIZE Packet size (client or ping role) 28 [8<=x<=4096] 29 -c, --packet-count COUNT Packet count (client or ping role) 30 -sd, --start-delay SECONDS Start delay (client or ping role) 31 --repeat N Repeat the run N times (client and ping 32 roles)(0, which is the fault, to run just 33 once) 34 --repeat-delay SECONDS Delay, in seconds, between repeats 35 --pace MILLISECONDS Wait N milliseconds between packets (0, 36 which is the fault, to send as fast as 37 possible) 38 --linger Don't exit at the end of a run (server and 39 pong roles) 40 --help Show this message and exit. 41 42Commands: 43 central Run as a central (initiates the connection) 44 peripheral Run as a peripheral (waits for a connection) 45``` 46 47## Options for the ``central`` Command 48``` 49Usage: bumble-bench central [OPTIONS] TRANSPORT 50 51 Run as a central (initiates the connection) 52 53Options: 54 --peripheral ADDRESS_OR_NAME Address or name to connect to 55 --connection-interval, --ci CONNECTION_INTERVAL 56 Connection interval (in ms) 57 --phy [1m|2m|coded] PHY to use 58 --authenticate Authenticate (RFComm only) 59 --encrypt Encrypt the connection (RFComm only) 60 --help Show this message and exit. 61``` 62 63To test once device against another, one of the two devices must be running 64the ``peripheral`` command and the other the ``central`` command. The device 65running the ``peripheral`` command will accept connections from the device 66running the ``central`` command. 67When using Bluetooth LE (all modes except for ``rfcomm-server`` and ``rfcomm-client``utils), 68the default addresses configured in the tool should be sufficient. But when using 69Bluetooth Classic, the address of the Peripheral must be specified on the Central 70using the ``--peripheral`` option. The address will be printed by the Peripheral when 71it starts. 72 73Independently of whether the device is the Central or Peripheral, each device selects a 74``mode`` and and ``role`` to run as. The ``mode`` and ``role`` of the Central and Peripheral 75must be compatible. 76 77Device 1 mode | Device 2 mode 78------------------|------------------ 79``gatt-client`` | ``gatt-server`` 80``l2cap-client`` | ``l2cap-server`` 81``rfcomm-client`` | ``rfcomm-server`` 82 83Device 1 role | Device 2 role 84--------------|-------------- 85``sender`` | ``receiver`` 86``ping`` | ``pong`` 87 88 89# Examples 90 91In the following examples, we have two USB Bluetooth controllers, one on `usb:0` and 92the other on `usb:1`, and two consoles/terminals. We will run a command in each. 93 94!!! example "GATT Throughput" 95 Using the default mode and role for the Central and Peripheral. 96 97 In the first console/terminal: 98 ``` 99 $ bumble-bench peripheral usb:0 100 ``` 101 102 In the second console/terminal: 103 ``` 104 $ bumble-bench central usb:1 105 ``` 106 107 In this default configuration, the Central runs a Sender, as a GATT client, 108 connecting to the Peripheral running a Receiver, as a GATT server. 109 110!!! example "L2CAP Throughput" 111 In the first console/terminal: 112 ``` 113 $ bumble-bench --mode l2cap-server peripheral usb:0 114 ``` 115 116 In the second console/terminal: 117 ``` 118 $ bumble-bench --mode l2cap-client central usb:1 119 ``` 120 121!!! example "RFComm Throughput" 122 In the first console/terminal: 123 ``` 124 $ bumble-bench --mode rfcomm-server peripheral usb:0 125 ``` 126 127 NOTE: the BT address of the Peripheral will be printed out, use it with the 128 ``--peripheral`` option for the Central. 129 130 In this example, we use a larger packet size and packet count than the default. 131 132 In the second console/terminal: 133 ``` 134 $ bumble-bench --mode rfcomm-client --packet-size 2000 --packet-count 100 central --peripheral 00:16:A4:5A:40:F2 usb:1 135 ``` 136 137!!! example "Ping/Pong Latency" 138 In the first console/terminal: 139 ``` 140 $ bumble-bench --role pong peripheral usb:0 141 ``` 142 143 In the second console/terminal: 144 ``` 145 $ bumble-bench --role ping central usb:1 146 ``` 147 148!!! example "Reversed modes with GATT and custom connection interval" 149 In the first console/terminal: 150 ``` 151 $ bumble-bench --mode gatt-client peripheral usb:0 152 ``` 153 154 In the second console/terminal: 155 ``` 156 $ bumble-bench --mode gatt-server central --ci 10 usb:1 157 ``` 158 159!!! example "Reversed modes with L2CAP and custom PHY" 160 In the first console/terminal: 161 ``` 162 $ bumble-bench --mode l2cap-client peripheral usb:0 163 ``` 164 165 In the second console/terminal: 166 ``` 167 $ bumble-bench --mode l2cap-server central --phy 2m usb:1 168 ``` 169 170!!! example "Reversed roles with L2CAP" 171 In the first console/terminal: 172 ``` 173 $ bumble-bench --mode l2cap-client --role sender peripheral usb:0 174 ``` 175 176 In the second console/terminal: 177 ``` 178 $ bumble-bench --mode l2cap-server --role receiver central usb:1 179 ``` 180