Bluetooth: Throughput
The Bluetooth® Throughput sample uses the GATT Throughput Service to measure Bluetooth Low Energy throughput performance. You can use it to determine the maximum throughput, or to experiment with different connection parameters and check their impact on the throughput.
Requirements
The sample supports the following development kits:
Hardware platforms |
PCA |
Board name |
|
|---|---|---|---|
nRF54LV10 DK |
PCA10188 |
|
|
PCA10184 |
|
||
nRF54LC10 DK |
PCA10226 |
nrf54lc10dk |
|
PCA10156 |
|
||
PCA10156 |
|
||
PCA10156 |
|
||
PCA10175 |
|
||
PCA10095 |
|
||
PCA10040 |
|
||
PCA10056 |
|
For more security, it is recommended to use the */ns variant of the board target.
When built for this variant, the sample is configured to compile and run as a non-secure application using security by separation.
Therefore, it automatically includes Trusted Firmware-M that prepares the required peripherals and secure services to be available for the application.
You can use any two of the development kits listed above and mix different development kits.
The sample also requires a connection to a computer with a serial terminal that supports VT100/ANSI escape characters for each of the development kits.
Overview
The sample transmits data between two development kits, the tester and the peer, and measures the throughput performance. It uses the GATT Throughput Service for this. To run the tests, connect to the kit using the serial port and send shell commands. Zephyr’s Shell module is used to handle the commands.
The sample demonstrates the interaction of the following connection parameters:
- ATT_MTU size
In Bluetooth Low Energy, the default Maximum Transmission Unit (MTU) is 23 bytes. When increasing this value, longer ATT payloads can be achieved, increasing the ATT throughput.
Note
To configure the ATT_MTU size, use menuconfig and compile and program the sample again.
- Data length
In Bluetooth Low Energy, the default data length for a radio packet is 27 bytes. Data length extension allows to use larger radio packets, so that more data can be sent in one packet, increasing the throughput.
- Connection interval
The connection interval defines how often the devices must listen to the radio. When increasing this value, more packets may be sent in one interval, but if a packet is lost, the wait until the retransmission is longer.
- Physical layer (PHY) data rate
Starting with Bluetooth 5, the over-the-air data rate in Bluetooth Low Energy can exceed 1 Ms/s (mega symbols per second), which allows for faster transmission. In addition, you can use coded PHY (available on select nRF SoCs) for long-range transmission.
- Frame space
The frame space is the time between two consecutive radio packets. Starting with Bluetooth 6.0, the frame space can be configured on a BLE connection. When decreasing this value, more time is available for the radio to send and receive data, increasing the throughput.
By default, the following connection parameter values are used:
Parameter |
Value |
|---|---|
ATT_MTU size |
498 bytes |
Data length |
251 bytes |
Connection interval |
320 units (400 ms) |
PHY data rate |
2 Ms/s |
Frame space |
Minimum frame space |
Note
The minimum frame space is requested by default. This is negotiated between both devices for the minimum frame space for the current PHY.
Changing connection parameter values
To experiment with different connection parameter values, reconfigure the values using the Shell interface before running a test.
You can adjust the following parameters:
PHY
LE Data Length
LE Connection interval
Frame space
Note
In a Bluetooth Low Energy connection, the different devices negotiate the connection parameters that are used. If the configuration parameters for the devices differ, they agree on the lowest common denominator.
By default, the sample uses the fastest connection parameters. You can change them to different valid values without a need to program both kits again.
When you have set the LE Connection Interval to high values and need to change the PHY or the Data Length in the next test, the PHY Update or Data Length Update procedure can take several seconds.
User interface
- Button 1:
Set the board into a central (tester) role.
- Button 2:
Set the board into a peripheral (peer) role.
- Button 0:
Set the board into a central (tester) role.
- Button 1:
Set the board into a peripheral (peer) role.
Building and running
This sample can be found under samples/bluetooth/throughput in the nRF Connect SDK folder structure.
For more security, it is recommended to use the */ns variant of the board target (see the Requirements section above.)
When built for this variant, the sample is configured to compile and run as a non-secure application using security by separation.
Therefore, it automatically includes Trusted Firmware-M that prepares the required peripherals and secure services to be available for the application.
To build the sample, follow the instructions in Building an application for your preferred building environment. See also Programming an application for programming steps and Testing and optimization for general information about testing and debugging in the nRF Connect SDK.
Note
When building repository applications in the SDK repositories, building with sysbuild is enabled by default.
If you work with out-of-tree freestanding applications, you need to manually pass the --sysbuild parameter to every build command or configure west to always use it.
When building this sample with Sysbuild for an SoC that has a network core, the IPC radio firmware is automatically applied to the build.
The IPC radio is one of the companion components in the nRF Connect SDK and allows to use the radio peripheral from another core in a multicore device.
If needed, you can modify the IPC radio configuration in the prj.conf source file in the sample’s sysbuild/ipc_radio directory.
Testing
After programming the sample to both kits, complete following steps to test it:
Connect to both kits with a terminal emulator that supports VT100/ANSI escape characters (for example, the Serial Terminal app). See Testing and optimization for the required settings and steps.
Reset both kits.
Press Button 1 on the first development kit or type
centralin the terminal connected to the first kit to set it into the central (tester) role.Press Button 2 on the second development kit or type
peripheralin the terminal connected to the second kit to set it into the peripheral (peer) role.Observe that the kits establish a connection. The tester outputs the following information:
Type 'config' to change the configuration parameters. You can use the Tab key to autocomplete your input. Type 'run' when you are ready to run the test.
Type
config printin the terminal to print the current configuration. Typeconfigin the terminal to configure the test parameters to your choice. Use the Tab key for auto-completion and to view the options available for a parameter.Type
runin the terminal to start the test.Observe the output while the tester sends data to the peer. At the end of the test, both tester and peer display the results of the test.
Repeat the test after changing the parameters. Observe how the throughput changes for different sets of parameters.
Connect to both kits with a terminal emulator that supports VT100/ANSI escape characters (for example, the Serial Terminal app). See Testing and optimization for the required settings and steps.
Reset both kits.
Press Button 0 on the first development kit or type
centralin the terminal connected to the first kit to set it into the central (tester) role.Press Button 1 on the second development kit or type
peripheralin the terminal connected to the second kit to set it into the peripheral (peer) role.Observe that the kits establish a connection. The tester outputs the following information:
Type 'config' to change the configuration parameters. You can use the Tab key to autocomplete your input. Type 'run' when you are ready to run the test.
Type
config printin the terminal to print the current configuration. Typeconfigin the terminal to configure the test parameters to your choice. Use the Tab key for auto-completion and to view the options available for a parameter.Type
runin the terminal to start the test.Observe the output while the tester sends data to the peer. At the end of the test, both tester and peer display the results of the test.
Repeat the test after changing the parameters. Observe how the throughput changes for different sets of parameters.
Sample output
The result should look similar to the following output.
For the tester:
*** Booting Zephyr OS build v3.0.99-ncs1 ***
Starting Bluetooth Throughput sample
I: SoftDevice Controller build revision:
I: 33 78 2a 18 20 f5 61 61 |3x*. .aa
I: a6 8b 77 60 62 83 39 2a |..w`b.9*
I: 7c f1 14 e4 ||...
: HW Platform: Nordic Semiconductor (0x0002)
I: HW Variant: nRF54Lx (0x0005)
I: Firmware: Standard Bluetooth controller (0x00) Version 114.50547 Build 1092906799
I: HCI transport: SDC
I: Identity: D7:D6:AD:A2:50:62 (random)
I: HCI: version 6.2 (0x10) revision 0x107b, manufacturer 0x0059
I: LMP: version 6.2 (0x10) subver 0x107b
Bluetooth initialized
Press button 1 or type "central" on the central board.
Press button 2 or type "peripheral" on the peripheral board.
uart:~$
Central. Starting scanning
Filters matched. Address: DC:D6:E5:EE:75:9A (random) connectable: 1
Connected as central
Conn. interval is 320 units
Service discovery completed
MTU exchange pending
MTU exchange successful
Type 'config' to change the configuration parameters.
You can use the Tab key to autocomplete your input.
Type 'run' when you are ready to run the test.
run
==== Starting throughput test ====
PHY update pending
LE PHY updated: TX PHY LE 2M, RX PHY LE 2M
LE Data length update pending
LE data len updated: TX (len: 251 time: 2120) RX (len: 251 time: 2120)
Frame space update pending
Frame space updated: frame space 65 us, PHYs 0x0002, spacing types 0x0003
The test is in progress and will require around 20 seconds to complete.
Done
[local] sent 3762990 bytes (3674 KB) in 20003 ms at 1504 kbps
[peer] received 3762990 bytes (3674 KB) in 7602 GATT writes at 1524771 bps
Type 'config' to change the configuration parameters.
You can use the Tab key to autocomplete your input.
Type 'run' when you are ready to run the test.
For the peer:
*** Booting Zephyr OS build v3.0.99-ncs1 ***
Starting Bluetooth Throughput sample
I: SoftDevice Controller build revision:
I: 33 78 2a 18 20 f5 61 61 |3x*. .aa
I: a6 8b 77 60 62 83 39 2a |..w`b.9*
I: 7c f1 14 e4 ||...
I: HW Platform: Nordic Semiconductor (0x0002)
I: HW Variant: nRF54Lx (0x0005)
I: Firmware: Standard Bluetooth controller (0x00) Version 114.50547 Build 1092906799
I: HCI transport: SDC
I: Identity: DE:11:9D:70:34:D3 (random)
I: HCI: version 6.2 (0x10) revision 0x107b, manufacturer 0x0059
I: LMP: version 6.2 (0x10) subver 0x107b
Bluetooth initialized
Press button 1 or type "central" on the central board.
Press button 2 or type "peripheral" on the peripheral board.
uart:~$
Peripheral. Starting advertising
Connected as peripheral
Conn. interval is 320 units
LE PHY updated: TX PHY LE 2M, RX PHY LE 2M
Frame space updated: frame space 65 us, PHYs 0x0002, spacing types 0x0003
=============================================================================
=============================================================================
=============================================================================
=============================================================================
=============================================================================
=============================================================================
=============================================================================
===========================================================
[local] received 3762990 bytes (3674 KB) in 7602 GATT writes at 1524771 bps
Dependencies
This sample uses the following nRF Connect SDK libraries:
In addition, it uses the following Zephyr libraries:
include/console.h-
include/kernel.h
include/sys/printk.hinclude/zephyr/types.hAPI:
include/bluetooth/bluetooth.hinclude/bluetooth/conn.hinclude/bluetooth/gatt.hinclude/bluetooth/hci.hinclude/bluetooth/uuid.h
-
include/shell/shell.h
The sample also uses the following secure firmware component:
References
For more information about the connection parameters that are used in this sample, see the following chapters in the Bluetooth Core Specification:
Vol 3, Part F, 3.2.8 Exchanging MTU Size
Vol 6, Part B, 5.1.1 Connection Update Procedure
Vol 6, Part B, 5.1.9 Data Length Update Procedure
Vol 6, Part B, 5.1.10 PHY Update Procedure