Throughput Tester Example (NCP Mode)#

Background#

This code example has a related User's Guide, here: Throughput with Bluetooth Low Energy Technology

Description#

With the throughput tester example application, you can measure the Bluetooth connection bitrate of the EFR32/BGM device running the Silicon Labs Bluetooth Low Energy stack. Both acknowledged and unacknowledged operations can be tested, using indications and notifications respectively. The example can also serve as a basis for testing Coded PHY and/or range.

Throughput tester measures the data throughput between a slave and a master device and reports the bps and GATT operation count values. The slave device functions as a GATT server and sends data to the client (master). The SoC type example application implements both roles in the same firmware, which enables using the same firmware for both the master and slave device and testing throughput between two radio boards, or against another third-party device such as a smart phone. The master role is also implemented as an NCP project, which makes it possible to conduct a throughput test from a PC.

This example demonstrates the NCP application used to control the master side of the throughput test. To implement the slave side please use the SoC type example application.

How it works#

The NCP host application is a PC application that controls an EFR32 device programmed with a ncp-target image. It has 4 important files: main.c, app.c, app.h and uart_win.c (the last one located at examples_ncp_host\common\uart).

app.h defines the structure TestParameters_t, which is used for storing given command line parameters. It also contains two enumerated types Action_t and State_t, which are states of the discovery process and main program respectively.

uart_win.c defines a speedTab[] array of structs that contain the baud rate options for the UART. To test throughputs higher than ~500 kbps, the cable connection between the NCP target device and your PC becomes a bottleneck. The default baud rate for the WSTK is 115200. This can be configured up to 921600 from the Simplicity Studio Console. An external USB-to-UART converter, which supports higher baud rates, can be used. See Example Test Results section for details on this setup.

main.c contains the main loop of the application. It first initializes serial communication with the NCP target kit connected to your PC. At this point, the command line parameters are parsed with the parse_commands function and assigned to the fields of structure params. The application then enters the main while-loop, where it delegates the handling of incoming events to app_handle_events function (in app.c). main.c also has an interrupt handler function, handle_user_input, for catching the CTRL+C keyboard interrupt. On keyboard interrupt, the user has the choice to run the test again in fixed modes. In free mode, the program resets the NCP target device and exits immediately.

app.c contains the app_handle_events function, which is the “brain” of the application. It has a simple state machine as in the SoC firmware. The states, represented by State_t, and their core functionalities are:

Just as the SoC firmware, the app_handle_events has another switch-statement at the end for handling “universal” events, such as the software timer timeout and parameter changes.

Return value of app_handle_events, askForInput, is related to one-shot modes, where after one test run, the user is prompted to run again or exit. This is set to 1 when in fixed modes and transmission ends.

When using the throughput tester NCP Host application, transmissions are triggered from the host side in one-shot-type fixed time and fixed data amount modes or by pushing the buttons on the slave device, as in the 2-kit use case. OS-specific functions timer_start and timer_end are used for timing on host side.

Program setup and discovery flow are better illustrated in the figure below:

Example Test Results#

Typical throughput (between 2 BG13 boards):

• 1M PHY notifications ~740 kbps, indications 20 kbps (50 ms interval)

• 2M PHY notifications ~1.3 Mbps, indications 40 kbps (25 ms interval)

• Coded PHY notifications 85 kbps, indications 5 kbps (200 ms interval)

Setting up#

Requirements:

• 2 Wireless Starter Kits (WSTK)

• Radio boards with an EFR32[B|M]x/[B|M]GMx device e.g. BRD4305C (BGM13S) or BRD4104A (EFR32BG13)

• Simplicity Studio

• [optional] USB-to-UART-converter that supports up to 2 Mbps

• [optional] jumper wires/cables

To use the NCP host application, one WSTK and radio board has to be programmed with ncp-empty-target project as it is found in the Bluetooth SDK. The other kit must run the SoC type throughput tester application. To set up a test environment follow these steps:

1. Program one device with the SoC type throughput tester application

2. Program another device with the ncp-empty-target project. Easiest way is to run the 'NCP target - Empty' demo from Simplicity Studio Launcher

3. Locate the NCP host sample apps in your Bluetooth SDK. You should find them under:

   C:\SiliconLabs\SimplicityStudio\v4\developer\sdks\gecko_sdk_suite\v2.6\app\bluetooth\examples_ncp_host (version numbers might differ)

4. Create a new folder under it, and name it e.g. to 'throughput_tester'

5. Copy the attached files into this folder (it is important to place the code exactly in this folder due to external dependencies)

6. Build the application using, for example MinGW (by running mingw32-make) or Cygwin (by running make).

7. The executable will be generated in the exe-folder

[optional part follows]

To connect to you target device you can use the virtual COM port (JLink CDC UART Port) provided by the WSTK via the USB interface. However, this puts limitation on the baudrate. To overcome this limitation, an external USB-to-UART-converter can be used. Example is given with Silicon Labs CP2104mini, which supports rates up to 2 Mbps and can therefore be used for 2M PHY throughput measurement setups.

1. Download and install the drivers for CP2104 following the quick start card

2. Make the following wiring connections with, for example, jumper wires

   CP2014 pin	WSTK EXT Header pin	WSTK EXT Header pin number
   GND	GND	1
   TX	UART_RX	14
   RX	UART_TX	12
   RTS	VCOM_CTS	3
   CTS	VCOM_RTS	5

   A figure of the setup is shown below.

1. Configure the NCP target WSTK baud rate to its maximum of 921600 through the Simplicity Studio console using the command "serial vcom config speed 921600" as shown in the figures below.

1. Modify the hal-config.h file in the ncp-empty-target project and re-flash the project:

  #define HAL_UARTNCP_BAUD_RATE (2000000) // Change from default 115200
  #define HAL_VCOM_ENABLE (0)             // Change from 1 to 0

1. The hal-config.h in the NCP target project (HAL_UARTNCP_BAUD_RATE) needs to match a speedTab[] entry in uart_win.c. An entry can be added to the array if necessary, as shown below.

1. Compile the host program with "make all" or "mingw32-make all".

Usage#

The NCP application has the following command line options:

The usage of the program with all default parameters is demonstrated by the animation below.

The test is run with the NCP target device connected to COM port 6 with default baud rate of 115200, flow control enabled. This test is a fixed time transmission of 5 seconds with 2M PHY, 25 ms connection interval, MTU of 250B and indications.

The output of the program is divided with dashes to roughly four parts:

1. Bootup, initial connection and possible PHY change

2. Service and characteristics discovery and subscriptions

3. Parameters to be used for the test displayed

4. Test results: Sent bits, time, throughput by host, GATT operation count, throughput by slave device (sender)

Host and slave reported throughput values can differ because each device keeps their own start and end time of transmission.

Source#

• app.c

• app.h

• infrastructure.h

• main.c

• makefile