Sample Applications#

The sample setup consists of two types of applications, the Initiator and the Reflector. The setup uses the two-way ranging scenario. This is a connection-based measurement method where the Initiator scans for the Reflector and connects to it. After a connection is established, both the Initiator and Reflector send signals and packets to measure phase and time. The Reflector sends the measured phase and time back to the Initiator using GATT service and characteristics. The Initiator then combines all the information to calculate distance.

In general, the Simplicity SDK (SiSDK) provides sample projects for the CS Initiator and CS Reflector devices that can be run in two modes of operation—SoC Mode and NCP Mode.

The sample projects for EFR32xG24 device can be found in SSv5.

SoC Mode Sample Applications#

In SoC mode, the Bluetooth stack and the application (including the RTL library) run on the SoC/EFR32xG24 device. SiSDK 2024.6.0 provides the following two Studio sample projects supporting this mode of operation.

• bt_cs_soc_initiator: Bluetooth – SoC CS Reflector

• bt_cs_soc_reflector: Bluetooth – SoC CS Initiator

The applications consist of software components aimed at handling CS and general BLE activities and interfacing with the RTL library to yield distance estimation. The diagram below depicts a high-level software architecture of the SoC CS Initiator and Reflector sample applications.

To access the projects in SSv5, in the Launcher perspective (1), select your device from the Adapter Debug window (2). In the Overview tab (3), choose the latest Simplicity SDK Suite, and then go to the EXAMPLE PROJECTS & DEMOS tab (5).

Once you are in the EXAMPLE PROJECTS & DEMOS tab, use the CS filtering keyword to see the sample applications. Click CREATE to create the project.

All the ranging applications running on the BRD4198A radio boards are also available as pre-built demos. For quick testing, you can run the demos by clicking RUN. This will flash the required bootloader and the corresponding sample application to your device.

Bluetooth – SoC CS Reflector#

The main software components of the Bluetooth SoC CS Reflector are:

• BLE Peer Manager

• CS Reflector

• CS RAS

Project Walkthrough#

The project contains the C related files under the folder <SDK_Folder>/app/bluetooth/common/.

The BLE Peer Manager is responsible for implementing the BLE peripheral roles of the Reflector device. These include configuring, starting, and stopping advertising. It accomplishes these tasks through the Bluetooth stack API calls: sl_bt_advertiser_set_timing(), sl_bt sl_bt_legacy_advertising_start(), and sl_bt_advertiser_stop(), respectively. Before advertising is started, the advertising set is created, and the advertising data is generated using sl_bt_advertiser_create_set() and sl_bt_legacy_advertiser_generate_data(), respectively. These are done in the ble_peer_manager_peripheral.c file.

The CS Reflector component is responsible for setting the maximum CS transmission power and enabling the CS Reflector role on the device for a specific connection by calling the sl_bt_cs_set_default_settings() API. This component also handles CS related events: evt_cs_security_enable_complete, which indicates that the CS Security Enable procedure has completed, evt_cs_procedure_enable_complete, which indicates the start of the CS procedure by the Initiator, and evt_cs_result, which is triggered by the local controller when a new CS result is available. These are done in the cs_reflector.c file.

The CS RAS component is responsible for parsing RAS GATT messages and creating RAS GATT responses.

Usage#

Select the Bluetooth - SoC CS Reflector sample application, and build and flash it to a device. This sample application requires the bootloader-apploader type of bootloader.

After starting up, it should be advertising with the name CS RFLCT. By default, the Reflector allows up to 4 connections. This value can be changed in the Connection software component. In multiple connection use cases, it is advised to use a longer measurement interval.

Bluetooth – SoC CS Initiator#

The main software components of the Bluetooth SoC CS Initiator are:

• BLE Peer Manager

• CS Initiator

• RTL library

• CS RAS

Project Walkthrough#

The project contains the C related files under the folder <SDK_Folder>/app/bluetooth/common/.

The BLE manager is responsible for implementing the BLE central roles of the Initiator device. This includes configuring the scanning parameters, starting/stopping the scanner, and initiating/closing a connection with a Reflector device. It achieves these by calling the Bluetooth stack APIs: sl_bt_scanner_set_parameters(), sl_bt_scanner_start()/sl_bt_scanner_stop(), sl_bt_connection_open()/sl_bt_connection_close(), respectively.

The CS Initiator component is responsible for CS related activities. These include, setting the default parameters for CS transmission power and device role using sl_bt_cs_set_default_settings(), and ensuring that the requirements for starting a CS procedure are met.

Before a CS procedure is started:

• The connection between the peer devices must be encrypted. This is done by calling sl_bt_sm_increase_security().

• The CS configuration is created and configured using sl_bt_cs_create_config() and sl_bt_cs_set_procedure_parameters () API calls, respectively.

• The CS security information is exchanged by calling sl_bt_cs_security_enable(). The Deterministic Random Bit Generator (DRBG) is seeded from security information exchanged at this step.

After these steps, the CS procedure is started using sl_bt_cs_procedure_enable() API call.

The CS Initiator is also responsible for handling CS related events triggered by the local controller and providing the CS procedure data to the RTL library, which then calculates the distance. These are done inside cs_initiator.c file.

The CS RAS component is responsible for parsing RAS GATT messages and creating RAS GATT responses.

The RTL library is responsible for doing the actual distance estimation.

Usage#

Select the Bluetooth - SoC CS Initiator application, and build and flash it to the device. This sample application requires the bootloader-apploader type of bootloader.

The Initiator will display the measured distance on the LCD mounted on the main board. The LCD display will also show the Bit Error Rate (BER), the likelihood of the measured value, and RSSI based distance estimation. Note that the BER is applicable in RTT mode only.

The device will also send the distances via UART. Open a console application on the PC to see the logs:

Exporting Measurements to a File#

The Bluetooth—SoC CS Initiator project contains a python script log_filter.py designed to log CS measurement, RTL and/or application logs to a file. It reads data from the serial port of the Initiator device and writes the data to a JSONL and txt files.

Run the application using the following command:

python log_filter.py [-h] [-o {all,nortl,rtlonly}] [source]

Where [source] is the serial or TCP address of the Initiator device.

Channel Sounding Sequence Chart#

The following sequence diagram illustrates the message exchange between the Initiator and Reflector devices, based on the implementation of our sample applications. The diagram shows the BGAPI commands and events between the controller/LL and host of both devices, and the actual PHY PDUs exchanged between the Initiator and Reflector.

Configuration Options#

Several configuration options can be modified to meet the requirements of different use cases.

Changing the CS Mode#

By default, the Initiator uses the PBR mode. RTT mode can be selected by pressing Button 0 on the WSTK at startup. Press BTN0 on the WSTK while resetting the device to select RTT mode.

Alternatively, this setting can be changed in the config/initiator_app_config.h. Set MEASUREMENT_MODE to sl_bt_cs_mode_rtt for RTT, and sl_bt_cs_mode_pbr for PBR to explicitly define the mode at compile time.

// <i> Specify measurement mode.
// <sl_bt_cs_mode_rtt=> Round Trip Time
// <sl_bt_cs_mode_pbr=> Phase Based Ranging
// <i> Default: sl_bt_cs_mode_pbr
#define MEASUREMENT_MODE     sl_bt_cs_mode_pbr

Changing CS Procedure Parameter—CS Procedure Interval#

By default, the interval between CS measurement procedures is set to 30 for a stable setup even with multiple connections. However, if only one connection is used, this interval can be reduced to increase the refresh rate. This setting can be changed in the config/cs_initiator_config.h.

Care should be taken when adjusting the CS interval as it is defined in number of connection events between consecutive measurement procedures.

Note that the max and min CS intervals are ignored if the maximum procedure count is set to 1.

#ifndef CS_INITIATOR_MIN_INTERVAL
#define CS_INITIATOR_MIN_INTERVAL                     (30)
#endif

#ifndef CS_INITIATOR_MAX_INTERVAL
#define CS_INITIATOR_MAX_INTERVAL                     (30)
#endif

Changing CS Procedure Parameter—Maximum Procedure Count#

This defines the maximum number of CS procedure to be scheduled. If set to 0, the CS procedures continue until it is stopped. This parameter can be set in the config struct found in: <SDK_Folder>/app/bluetooth/common/sc_initiator/src/cs_initiator_configurator.c.

// Value: 0. Free running
// Value: 1. Start new procedure after one finished.
config->max_procedure_count =         1;

Changing CS Maximum TX Power#

The reference board supports a maximum TX power of 10 dBm. This value can be changed in the config struct found in: <SDK_Folder>/app/bluetooth/common/sc_initiator/src/cs_initiator_configurator.c.

// CS power
config->max_tx_power_dbm =            20;

Enabling/Disabling Algorithm Logs#

The RTL logs can be enabled or disabled in the SoC Initiator, allowing for the capture of raw IQ samples from both the Initiator and Reflector devices for post-processing. This feature is enabled by default. To disable it, set CS_INITIATOR_RTL_LOG to 0 in the config/cs_initiator_config.h.

#ifndef CS_INITIATOR_RTL_LOG
#define CS_INITIATOR_RTL_LOG                          (1)
#endif

Changing the Algorithm Mode#

In general, two algorithm modes are supported:

1. SL_RTL_CS_ALGO_MODE_REAL_TIME_BASIC: use this mode to track moving targets.

2. SL_RTL_CS_ALGO_MODE_STATIC_HIGH_ACCURACY: use this mode to estimate the distance of stationary objects.

By default, the Initiator uses the REAL_TIME mode. STATIC mode can be selected by pressing Button 1 on the WSTK at startup. Press BTN1 on the WSTK while resetting the device to select STATIC mode.

Alternatively, you can change this setting in the config struct found in: <SDK_Folder>/app/bluetooth/common/sc_initiator/src/cs_initiator_configurator.c.

// RTL configuration
// Moving object tracking is enabled by default
rtl_config->algo_mode = SL_RTL_CS_ALGO_MODE_REAL_TIME_BASIC;

Important notes:

• In STATIC mode, a valid distance estimation is produced for every 100 CS procedure. Hence, extra care must be taken to the returned error code by the algorithm.

  • SL_RTL_ERROR_ESTIMATION_IN_PROGRESS is returned by sl_rtl_cs_process and sl_rtl_cs_get_distance_estimate methods when distance estimation is not ready.

  • SL_RTL_ERROR_SUCCESS is returned by sl_rtl_cs_process and sl_rtl_cs_get_distance_estimate methods when distance estimation is ready.

• In STATIC mode, the algorithm estimates distances with a resolution of 0.1 meters.

• There is currently no observable difference in the results between STATIC and REAL_TIME modes in RTT.

NCP Mode Sample Applications#

The Silicon Labs Bluetooth SDK also includes NCP sample applications that support channel Sounding. In NCP mode, the EFR32xG24 device functions as NCP target or coprocessor, working with a host controller that functions as an NCP host. The NCP host and target communicate on a serial interface using the BGAPI protocol.

Starting with version 2024.6.0, a multi-role NCP architecture is introduced for channel sounding. This architecture allows running multiple instances with similar or different roles simultaneously. To realize this architecture, the Bluetooth SDK offers:

• A Studio example project for NCP target (app/Bluetooth/example)

  • bt_cs_ncp: Bluetooth - NCP for Channel Sounding

• A host example for the NCP host (app/Bluetooth/example_host)

  • bt_cs_host: supports the multi-role NCP host

In multi-role NCP architecture, the Bluetooth stack and RTL library are run on the SoC, whereas the application is run on the host machine.

Key features of the multi-role NCP architecture:

• As the name suggests, this architecture allows multiple instances* to run with different CS roles; that is, Initiator and Reflector roles.

• The Initiator and Reflector roles are integrated on the NCP target side. As a result, the host application can act as a Reflector, an Initiator, or both.

• The distance estimation is done on the NCP target, and only the measurement results are sent to the host using CS specific BGAPI commands, thereby reducing the load on serial communication.

*Up to 4 simultaneous connections are supported. This means that the number of instances (Initiator and Reflector combined) cannot exceed 4.

NCP Interface#

The NCP provides a high-level interface to the host application. The host can configure, start a Reflector, or Initiator instance on the NCP target by calling sl_bt_user_cs_service_message_to_target().

Any asynchronous CS event triggers an sl_bt_evt_user_cs_service_message_to_host_id event on the host. The host then parses this event to extract the specific CS event, which can be:

• CS result

• CS Log data from RTL, Initiator, or Reflector

• Error events

This occurs in app.c file of bt_cs_host project.

Building the Multi-Role NCP Projects#

For the target, in Simplicity Studio Launcher perspective, select the Bluetooth - NCP for Channel Sounding, and build and flash it to the board. This sample application requires the bootloader-uart-bgapi type of bootloader. For the Host application, go to app\bluetooth\example_host\bt_cs_host. For testing purposes, you can build the application by simply calling $ make.

When you are developing, however, Silicon Labs recommends that you first generate the project using the export feature of the makefile. This feature allows copying all the SiSDK files that belong to the project into the export folder. After the project files are exported, the export directory will be your working directory that is completely detached from the SiSDK but has the same folder structure inside. With export, it is clear at glance which files belong to the project.

To generate your multi-role NCP host, open a terminal, go to app\bluetooth\example_host\bt_cs_host, and call the following command:

$ make export

A custom export folder can be also specified using the EXPORT_DIR variable.

$ make export EXPORT_DIR=/c/users/username/my_bt_cs_host

After generating the project, you can build it by:

• Navigating to the exported project directory

  • $ cd /c/users/username/my_bt_cs_host/app/bluetooth/example_host/bt_cs_host

• Running the $ make command

See the required tools and more information about building an NCP Host application here.

Running the Multi-Role NCP Host Application#

After the project is built, an executable file bt_cs_host.exe is generated inside the exe folder. Run the application using the following command:

$ ./exe/bt_cs_host.exe -t <tcp_address> | -u <serial_port> [-b <baud_rate>] [-f] [-l <log_level_filter>] [-m <cs_mode>] [-R <max_reflector_instances>] [-I <max_initiator_instances>] [-F <reflector_ble_address>] [-r] [-w] [-o] [-h]

CPC Support#

The CS Initiator sample application also supports the CPC over NCP feature. For details about how to add the CPC interface to the project refer to the NCP Application Note. This covers the basic setup of the host application on a standard Linux system. It is also possible to use OpenWRT based systems as a host. Contact Silicon Labs for a sample setup and instructions.