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

Build target

nRF5340 DK

PCA10095

nrf5340dk_nrf5340

nrf5340dk_nrf5340_cpuapp_ns nrf5340dk_nrf5340_cpuapp

nRF52 DK

PCA10040

nrf52dk_nrf52832

nrf52dk_nrf52832

nRF52840 DK

PCA10056

nrf52840dk_nrf52840

nrf52840dk_nrf52840

When built for an _ns build target, the sample is configured to compile and run as a non-secure application. 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.

Note

If you use nRF5340 DK, the additional configuration of the network core will be taken from the child_image directory. For more details, see Image-specific variables.

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 the nRF52840 SoC only) for long-range transmission.

By default, the following connection parameter values are used:

Default parameter values

Parameter

Value

ATT_MTU size

498 bytes

Data length

251 bytes

Connection interval

320 units (400 ms)

PHY data rate

2 Ms/s

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

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.

Note

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.

Building and running

This sample can be found under samples/bluetooth/throughput in the nRF Connect SDK folder structure.

When built as a non-secure firmware image for the _ns build target, the sample automatically includes the Trusted Firmware-M (TF-M).

To build the sample with Visual Studio Code, follow the steps listed on the Building nRF Connect SDK application quick guide page in the nRF Connect for VS Code extension documentation. See Building and programming an application for other building and programming scenarios and Testing and debugging an application for general information about testing and debugging in the nRF Connect SDK.

Testing

After programming the sample to both kits, complete following steps to test it:

  1. Connect to both kits with a terminal emulator that supports VT100/ANSI escape characters (for example, PuTTY). See How to connect with PuTTY for the required settings.

  2. Reset both kits.

  3. Press Button 1 on the kit to set the kit into central (tester) role.

  4. Press Button 2 on the other kit to set the kit into peripheral (peer) mode.

  5. 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.

  6. Type config print in the terminal to print the current configuration. Type config in 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.

  7. Type run in the terminal to start the test.

  8. 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.

  9. 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 v2.4.0-ncs1-1715-g3366927a5498  ***
Starting Bluetooth Throughput example
I: SoftDevice Controller build revision:
I: 7a 01 b4 17 68 14 99 b6 |z...h...
I: 6a d1 f2 fd fe 59 63 e3 |j....Yc.
I: 43 ca fb 5c             |C..\
I: HW Platform: Nordic Semiconductor (0x0002)
I: HW Variant: nRF52x (0x0002)
I: Firmware: Standard Bluetooth controller (0x00) Version 122.46081 Build 256825
I: Identity: D9:85:73:DC:7D:D4 (random)
I: HCI: version 5.2 (0x0b) revision 0x1154, manufacturer 0x0059
I: LMP: version 5.2 (0x0b) subver 0x1154
Bluetooth initialized

Press button 1 on the central board.
Press button 2 on the peripheral board.


uart:~$
Central. Starting scanning
Filters matched. Address: D2:71:97:84:DE:B2 (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)

                    ^.-.^                               ^..^
                 ^-/ooooo+:.^                       ^.--:+syo/.
              ^-/oooooooooooo+:.                 ^.-:::::+yyyyyy+:^
           ^-/+oooooooooooooooooo/-^          ^.-::::::::/yyyyyyyhhs/-
        ^-:/++++oooooooooooooooooooo+:.   ^.-::::::::::::/yyyyyyyhhhhhho:^
      ^::///++++oooooooooooooooooooooooo//:::::::::::::::/yyyyyyyhhhhhddds
      -::://+++ooooooooooooooooooooooooooooo+/:::::::::::/yyyyyyyhhhhhdddd^
      -::::::/++ooooooooooooooooooooooooooooooo+/::::::::/yyyyyyyhhhhhdddd^
      -:::::::::/+ooooooooooooooooooooooooooooossso+/::::/yyyyyyyhhhhhdddd^
      -::::::::::::/+oooooooooooooooooooooooooossssssso+//yyyyyyyhhhhhdddd^
      -::::::::::::::::/+ooooooooooooooooooooooossssssssssyyyyyyyhhhhhdddd.
      -:::::::::::::::::::/+oooooooooooooooooooossssssssssyyyyyyyhhhhhdddd.
      -:::::::::::::::::::::::/+ooooooooooooooosssssssssssyyyyyyyhhhhhdddd.
      -::::::::::::::::::::::::::/+ooooooooooooossssssssssyyyyyyyhhhhhdddd.
      -::::::::::::::::::::::::::::::/+ooooooooossssssssssyyyyyyyhhhhhdddd-
      -:::::::::::::::::::::::::::::::::/+ooooosssssssssssyyyyyyyhhhhhdddd-
      -:::::::::::::::::::::::::::::::::::::/+oossssssssssyyyyyyyhhhhhdddd:
      -::::::::::::::::::::::::::::::::::::::::/+ossssssssyyyyyyyhhhhhdddd:
      -::::::::::::::::::::::::::::::::::::::::::::/osssssyyyyyyyhhhhhdddd:
      -:::::::::::::::::::::::::::::::::::::::::::::::/+ossyyyyyyhhhhhdddd:
      -:::::::::::::::::o+/:::::::::::::::::::::::::::::::+oyyyyyhhhhhdddd:
      -:::::::::::::::::ossyso/::::::::::::::::::::::::::::::/osyhhhhhdddd/
      -:::::::::::::::::ossyyyyys+:::::::::::::::::::::::::::::::+shhhdddd/
      -:::::::::::::::::ossyyyyhhhhyo/::::::::::::::::::::::::::::::/oyddd/
      .-::::::::::::::::ossyyyyhhhhddddy/-::::::::::::::::::::::::::::::+y:
        ^.-:::::::::::::ossyyyyhhhhdhs/.  ^.--:::::::::::::::::::::::::-.^
           ^.--:::::::::ossyyyyhhy+-^         ^.-::::::::::::::::::--.^
               ^.-::::::ossyyyo/.                ^^.-:::::::::::-.^
                  ^..-::oss+:^                       ^.-:::::-.^
                      ^.:.^                             ^^.^^

Done
[local] sent 1242945 bytes (1213 KB) in 7292 ms at 1363 kbps
[peer] received 1242945 bytes (1213 KB) in 2511 GATT writes at 1415583 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 v2.4.0-ncs1-1715-g3366927a5498  ***
Starting Bluetooth Throughput example
I: SoftDevice Controller build revision:
I: 7a 01 b4 17 68 14 99 b6 |z...h...
I: 6a d1 f2 fd fe 59 63 e3 |j....Yc.
I: 43 ca fb 5c             |C..\
I: HW Platform: Nordic Semiconductor (0x0002)
I: HW Variant: nRF52x (0x0002)
I: Firmware: Standard Bluetooth controller (0x00) Version 122.46081 Build 256825
I: Identity: D2:71:97:84:DE:B2 (random)
I: HCI: version 5.2 (0x0b) revision 0x1154, manufacturer 0x0059
I: LMP: version 5.2 (0x0b) subver 0x1154
Bluetooth initialized

Press button 1 on the central board.
Press button 2 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


=============================================================================
=============================================================================
=============================================================================
=============================================================================
=============================================================================
=============================================================================
=============================================================================
===========================================================
[local] received 1242945 bytes (1213 KB) in 2511 GATT writes at 1415583 bps

Dependencies

This sample uses the following nRF Connect SDK libraries:

In addition, it uses the following Zephyr libraries:

  • include/console.h

  • Kernel Services:

    • include/kernel.h

  • include/sys/printk.h

  • include/zephyr/types.h

  • Bluetooth APIs:

    • include/bluetooth/bluetooth.h

    • include/bluetooth/conn.h

    • include/bluetooth/gatt.h

    • include/bluetooth/hci.h

    • include/bluetooth/uuid.h

  • Shell:

    • 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