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 CS capability exchange procedure should take place. This is done by calling sl_bt_cs_read_remote_supported_capabilities(). If no capability exchange has been initiated for the connection by the host and if there is no cached copy of the capabilties of the remote device, then the controller will intiate the CS capability exchange procedure.

• 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:

In the logs:

• Measurement result: The estimated distance value using CS.

• Likeliness: The probability that the CS distance estimate is correct. High values (close to 1) typically indicate accurate estimates, while low values (closer to 0) suggest a higher likelihood of error.

• RSSI distance: The RSSI based distance estimation.

• CS bit error rate: The number of bit errors detected (valid only in RTT mode). 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.

Configuring the Antenna Offset#

For Silicon Labs development boards (Ex: BRD4198A), the distance offset caused by the antenna group delay is already calibrated and configured in the sample applications.

For custom boards, the default value of SL_RAIL_UTIL_CS_ANTENNA_OFFSET_WIRELESS_CM is configured to 0. The antenna offset must be determined by following the wireless distance calibration procedure as described in Section 4 of AN1493. It can then be configured in config/sl_rail_util_cs_antenna_offset_config.h.

// <a.1 SL_RAIL_UTIL_CS_ANTENNA_OFFSET_WIRELESS_CM> Antenna wireless offset array in centimeters <-32768..32767>
// <d> { 0 }
#define SL_RAIL_UTIL_CS_ANTENNA_OFFSET_WIRELESS_CM        { 0 }

Changing the CS Mode#

By default, the initiator uses the PBR mode. To switch to RTT mode, modify CS_INITIATOR_DEFAULT_CS_MODE in config/cs_initiator_config.h and set it to 1.

// <1=> RTT
// <2=> PBR
#define CS_INITIATOR_DEFAULT_CS_MODE                 2

Changing Connection Interval#

By default, the connection event interval is set to 7.5 ms. This setting can be changed in the config/cs_initiator_config.h. The connection interval is defined in units of 1.25ms, and ranges between 6 and 3200. The true value in ms is Value x 1.25 ms.

// <i> Default: 6
#define CS_INITIATOR_DEFAULT_MIN_CONNECTION_INTERVAL         6

// <i> Default: 6
#define CS_INITIATOR_DEFAULT_MAX_CONNECTION_INTERVAL         6

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.

#ifndef CS_INITIATOR_DEFAULT_MIN_PROCEDURE_INTERVAL
#define CS_INITIATOR_DEFAULT_MIN_PROCEDURE_INTERVAL                     (30)
#endif

#ifndef CS_INITIATOR_DEFAULT_MAX_PROCEDURE_INTERVAL
#define CS_INITIATOR_DEFAULT_MAX_PROCEDURE_INTERVAL                     (30)
#endi

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

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 setting can be altered in config/cs_initiator_config.h.

// <0=> Free running
// <1=> Start new procedure after one finished
// <i> Default: 1
#define CS_INITIATOR_DEFAULT_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/cs_initiator_config.h file.

// <i> Default: 20
#define CS_INITIATOR_DEFAULT_MAX_TX_POWER  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 file.

#ifndef CS_INITIATOR_RTL_LOG
#define CS_INITIATOR_RTL_LOG                          (1)
#endif

Changing 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/cs_initiator_config.h file.

// <SL_RTL_CS_ALGO_MODE_REAL_TIME_BASIC=> Real time basic
// <SL_RTL_CS_ALGO_MODE_STATIC_HIGH_ACCURACY=> Static high accuracy
// <i> Default: SL_RTL_CS_ALGO_MODE_REAL_TIME_BASIC
#define CS_INITIATOR_DEFAULT_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.

Changing Number of Channels#

The standard defines 79 RF channels with 1 MHz spacing in the 2.4 GHz band, with channel indices ranging from 0 to 78. The allowed range for channel sounding usage is a minimum of 15 channels and a maximum of 72 channels. Channels with indices 0, 1, 23, 24, 25, 77 and 78 are excluded due to overlap with primary advertising channels.

By default, the examples use all the allowed channels. However, this can be adjusted if using fewer channels is necessary to prioritize speed and energy efficiency over the highest possible accuracy.

The channel map can be set by selecting the desired preset value to CS_INITIATOR_DEFAULT_CHANNEL_MAP_PRESET in config/cs_initiator_config.h.

// <CS_CHANNEL_MAP_PRESET_LOW=> Low
// <CS_CHANNEL_MAP_PRESET_MEDIUM=> Medium
// <CS_CHANNEL_MAP_PRESET_HIGH=> High
// <CS_CHANNEL_MAP_PRESET_CUSTOM=> Custom
// <i> Default: CS_CHANNEL_MAP_PRESET_HIGH
#define CS_INITIATOR_DEFAULT_CHANNEL_MAP_PRESET          CS_CHANNEL_MAP_PRESET_HIGH

The table below summarizes the supported channel map preset values defined in the cs_channel_map_preset_t enum type.

Each hex byte array represents a channel map, where each bit in a byte corresponds to one channel. A 1 indicates that the channel is enabled, while a 0 indicates it is disabled. The bytes are arranged in big-endian order, while the bits within each byte are in little-endian order.

In general:

• A higher number of channels enhances the robustness of distance estimation by reducing large outliers.

• Larger channel spacing reduces the maximum possible range that can be measured due to aliasing effect. For more details, refer to Channel Sounding Fundamentals.

If CS_CHANNEL_MAP_PRESET_CUSTOM is chosen, the application will use CS_CUSTOM_CHANNEL_MAP, which is defined in config/cs_initiator_config.h.

By default, custom preset enables all the 72 channels. You can customize it by modfying CS_CUSTOM_CHANNEL_MAP array. However, the custom channel map has certain limitations, and you must configure it with these limitations in mind:

• A custom channel map can be between channel 2 and channel 22, and must contain minimum 20 channels with 1MHz spacing, i.e no channel can be skipped.

• A custom channel map can be between channel 26 and channel 76, and must contain minimum 20 channels with 1MHz spacing, i.e no channel can be skipped.

• A custom channel map can be the same as CS_CHANNEL_MAP_PRESET_HIGH.

// <i> Default: { 0xFC, 0xFF, 0x7F, 0xFC, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0x1F }
#define CS_CUSTOM_CHANNEL_MAP                        { 0xFC, 0xFF, 0x7F, 0xFC, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0x1F }

The CS Initiator component uses the sl_rtl_util_validate_bluetooth_cs_channel_map() API to validate a custom channel map. If the requirements are not met, the application closes the connection and terminates with the error code 0x24: CS_ERROR_EVENT_INITIATOR_FAILED_TO_GET_CHANNEL_MAP.

Note that, for RTT, only the CS_CHANNEL_MAP_PRESET_HIGH is currently supported.

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.