Throughput Tester Example (NCP Mode)
This code example has a related User's Guide, here: Throughput with Bluetooth Low Energy Technology
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
app.h defines the structure
TestParameters_t, which is used for storing given command line parameters. It also contains two enumerated types
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:
|Reset variables to defaults, set max MTU size, start scanning with PHY given from command line. |
Process scan responses for device name
Set the correct connection parameters, given in the
|Wait for parameters requested in the previous state to be taken into effect, namely connection interval and PHY.|
|Discover the slave GATT database by known UUIDs: Throughput Test Service, Characteristics (|
Subscribe to notifications/indications on data characteristics and result characteristic. UUIDs are compared with the
|Count bits and operations, send confirmations to indications, depending on the mode, call |
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
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_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)
- 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:
Program one device with the SoC type throughput tester application
Program another device with the
ncp-empty-targetproject. Easiest way is to run the 'NCP target - Empty' demo from Simplicity Studio Launcher
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)
Create a new folder under it, and name it e.g. to 'throughput_tester'
Copy the attached files into this folder (it is important to place the code exactly in this folder due to external dependencies)
Build the application using, for example MinGW (by running mingw32-make) or Cygwin (by running make).
The executable will be generated in the
[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.
Download and install the drivers for CP2104 following the quick start card
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.
- 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.
- Modify the hal-config.h file in the
ncp-empty-targetproject 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
- The hal-config.h in the NCP target project (
HAL_UARTNCP_BAUD_RATE) needs to match a
speedTabentry in uart_win.c. An entry can be added to the array if necessary, as shown below.
- Compile the host program with
The NCP application has the following command line options:
|-h||Displays help text|
|-p arg||Port||Must be given e.g. COM6|
|-b arg||Baud rate with the ncp-target device||-b 115200|
|-f 1\||0||Software flow control on=1/off=0||-f 1|
|-m 1\||2\||3 [val]||Transmission mode: 1=fixed time in seconds 1-600, 2=fixed data in bytes 1kB-10MB, 3=free mode with buttons||-m 3|
|--params 1\||2\||4 [phy] [interval] [MTU size] [1\||2]||Connection parameters 4=Coded PHY (S8), connection interval 20-400 ms, MTU size 23-250 B, type of GATT operation 1=notification or 2=indication (on free mode it always subscribes to both)||--params 1 50 250 1|
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:
- Bootup, initial connection and possible PHY change
- Service and characteristics discovery and subscriptions
- Parameters to be used for the test displayed
- 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.