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: bench.py [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 -s, --packet-size SIZE Packet size (server role) [8<=x<=4096] 18 -c, --packet-count COUNT Packet count (server role) 19 -sd, --start-delay SECONDS Start delay (server role) 20 --help Show this message and exit. 21 22Commands: 23 central Run as a central (initiates the connection) 24 peripheral Run as a peripheral (waits for a connection) 25``` 26 27## Options for the ``central`` Command 28``` 29Usage: bumble-bench central [OPTIONS] TRANSPORT 30 31 Run as a central (initiates the connection) 32 33Options: 34 --peripheral ADDRESS_OR_NAME Address or name to connect to 35 --connection-interval, --ci CONNECTION_INTERVAL 36 Connection interval (in ms) 37 --phy [1m|2m|coded] PHY to use 38 --help Show this message and exit. 39``` 40 41 42To test once device against another, one of the two devices must be running 43the ``peripheral`` command and the other the ``central`` command. The device 44running the ``peripheral`` command will accept connections from the device 45running the ``central`` command. 46When using Bluetooth LE (all modes except for ``rfcomm-server`` and ``rfcomm-client``utils), 47the default addresses configured in the tool should be sufficient. But when using 48Bluetooth Classic, the address of the Peripheral must be specified on the Central 49using the ``--peripheral`` option. The address will be printed by the Peripheral when 50it starts. 51 52Independently of whether the device is the Central or Peripheral, each device selects a 53``mode`` and and ``role`` to run as. The ``mode`` and ``role`` of the Central and Peripheral 54must be compatible. 55 56Device 1 mode | Device 2 mode 57------------------|------------------ 58``gatt-client`` | ``gatt-server`` 59``l2cap-client`` | ``l2cap-server`` 60``rfcomm-client`` | ``rfcomm-server`` 61 62Device 1 role | Device 2 role 63--------------|-------------- 64``sender`` | ``receiver`` 65``ping`` | ``pong`` 66 67 68# Examples 69 70In the following examples, we have two USB Bluetooth controllers, one on `usb:0` and 71the other on `usb:1`, and two consoles/terminals. We will run a command in each. 72 73!!! example "GATT Throughput" 74 Using the default mode and role for the Central and Peripheral. 75 76 In the first console/terminal: 77 ``` 78 $ bumble-bench peripheral usb:0 79 ``` 80 81 In the second console/terminal: 82 ``` 83 $ bumble-bench central usb:1 84 ``` 85 86 In this default configuration, the Central runs a Sender, as a GATT client, 87 connecting to the Peripheral running a Receiver, as a GATT server. 88 89!!! example "L2CAP Throughput" 90 In the first console/terminal: 91 ``` 92 $ bumble-bench --mode l2cap-server peripheral usb:0 93 ``` 94 95 In the second console/terminal: 96 ``` 97 $ bumble-bench --mode l2cap-client central usb:1 98 ``` 99 100!!! example "RFComm Throughput" 101 In the first console/terminal: 102 ``` 103 $ bumble-bench --mode rfcomm-server peripheral usb:0 104 ``` 105 106 NOTE: the BT address of the Peripheral will be printed out, use it with the 107 ``--peripheral`` option for the Central. 108 109 In this example, we use a larger packet size and packet count than the default. 110 111 In the second console/terminal: 112 ``` 113 $ bumble-bench --mode rfcomm-client --packet-size 2000 --packet-count 100 central --peripheral 00:16:A4:5A:40:F2 usb:1 114 ``` 115 116!!! example "Ping/Pong Latency" 117 In the first console/terminal: 118 ``` 119 $ bumble-bench --role pong peripheral usb:0 120 ``` 121 122 In the second console/terminal: 123 ``` 124 $ bumble-bench --role ping central usb:1 125 ``` 126 127!!! example "Reversed modes with GATT and custom connection interval" 128 In the first console/terminal: 129 ``` 130 $ bumble-bench --mode gatt-client peripheral usb:0 131 ``` 132 133 In the second console/terminal: 134 ``` 135 $ bumble-bench --mode gatt-server central --ci 10 usb:1 136 ``` 137 138!!! example "Reversed modes with L2CAP and custom PHY" 139 In the first console/terminal: 140 ``` 141 $ bumble-bench --mode l2cap-client peripheral usb:0 142 ``` 143 144 In the second console/terminal: 145 ``` 146 $ bumble-bench --mode l2cap-server central --phy 2m usb:1 147 ``` 148 149!!! example "Reversed roles with L2CAP" 150 In the first console/terminal: 151 ``` 152 $ bumble-bench --mode l2cap-client --role sender peripheral usb:0 153 ``` 154 155 In the second console/terminal: 156 ``` 157 $ bumble-bench --mode l2cap-server --role receiver central usb:1 158 ``` 159