MCUXpresso SDK Documentation

Version: 26.03.00-pvw1 25.12.00 25.12.00-pvw2 25.12.00-pvw1 25.09.00 latest

Open on Repo Open an Issue

Source (.md/.rst) Page PDF (.pdf)

Application common modules

While the CS APIs are available to applications and can be used directly, common application modules are also provided. These modules, detailed below, offer a simplified API for performing distance measurements and allow for quick integration into existing applications.

app_localization common module

Introduction

The app_localization common module allows for quick integration of Channel Sounding functionality in a Bluetooth LE application.

Integration

All the APIs referenced in this section are available in the app_localization application common module.

Perform the following steps for integration into the application. Unless specified, each step applies to both the CS Initiator and the CS Reflector:

1. Add the following components to the application project via Kconfig:

   • CONFIG_MCUX_COMPONENT_middleware.wireless.lcl=y

   • CONFIG_MCUX_COMPONENT_middleware.wireless.ble_host_CS=y

   • CONFIG_MCUX_COMPONENT_middleware.wireless.ble_host_CS_component_lib=y

2. Begin the initialization of the common module by calling AppLocalization_Init(). One of the parameters of this API is the application callback where events will be received from the app_localization module.

3. Complete the initialization of the common module by calling AppLocalization_HostInitHandler() after the Host stack has been initialized.

4. The CS Config depends on the Bluetooth LE connection interval. Upon connection with the peer, the CS Config is retrieved by calling AppLocalization_ReadConfig() and updated by calling AppLocalization_WriteConfig().

5. If the application is the Ranging Requester, that is, it will run the distance measurement algorithm, the connection interval must also be saved by calling the function AppLocalization_SetConnectionInterval(). This is required by the algorithm.

6. Once the Ranging Requester has discovered and subscribed to the Ranging Service on the Ranging Responder (as detailed in the section below), the CS procedure can begin. The first step is to call AppLocalization_Config().

7. Upon receiving the gConfigComplete_c or the gLocalConfigWritten_c events, only the device who has the GAP Central role must call AppLocalization_SecurityEnable().

8. Upon receiving the gCsSecurityEnabled_c event, only one device must call AppLocalization_SetProcedureParameters().

9. Upon receiving the gSetProcParamsComplete_c event, the device from step 8 must call AppLocalization_StartMeasurement().

10. From this point onwards, the application will receive events informing it of the status of the distance measurement procedure, such as:

    • gDistanceMeastStarted_c - the CS Procedure has started

    • gLocalMeasurementComplete_c - the CS Procedure is complete and local data is available

    • various error events

11. Upon peer disconnection, cleanup should be performed by calling AppLocalization_ResetPeer().

app_localization_algo common module

Introduction

The app_localization_algo module is responsible for unpacking the data resulted from the CS Procedure and the RAS transfer. The module then passes it to the distance measurement algorithm to obtain the distance in meters, which is then communicated to the application.`

Integration

The app_localization_algo is only required on the application that has the role of Ranging Requester and computes the actual distance. Perform the following steps to integrate app_localization_algo common module:

1. Add the following component to the application project via Kconfig:

   • CONFIG_MCUX_COMPONENT_middleware.wireless.lcl_algo=y

2. Pass a callback of type pfAppDisplayResult_t as the third parameter of AppLocalization_Init. This callback receives the distance measurement result, which the application displays.

3. Call the function AppLocalizationAlgo_ResetPeer upon peer disconnection to clean up algorithm-related data structures.

4. There is no other direct interaction between the application and this module. Its APIs are mostly used by the app_localization module.

Ranging Service common module

Introduction

The Ranging Service is a GATT service used to transfer the data resulted from the CS Procedure from one device (the Ranging Responder) to the other (the Ranging Requester).

Integration

Perform the following steps to integrate the Ranging Service on the application that has the role of Ranging Requester (GATT client):

1. Add the following component to the application project via Kconfig:

   • CONFIG_MCUX_COMPONENT_middleware.wireless.ble_profiles_ranging_client=y

2. Ensure the gRasRREQ_d define is present and set to 1 in the application’s app_preinclude.h file.

3. After the connection with the peer is encrypted, proceed to discover the RAS and its characteristics through the common Service Discovery module. Register a service discovery callback using BleServDisc_RegisterCallback and call BleServDisc_FindService() with the gBleSig_RangingService_d UUID as parameter. On the gServiceDiscovered_c event in the registered callback, store the handles of the RAS and its characteristics and characteristic descriptors for later use. Some handles also need to be registered with the localization component via the following APIs:

   1. RasClient_SetRasControlPointHandle

   2. RasClient_SetRasRealTimeHandle

   3. RasClient_SetRasSupportedFeatures

4. Proceed to use the regular GATT client APIs such as GattClient_ReadCharacteristicValue() and GattClient_WriteCharacteristicDescriptor() in order to read the peer’s supported RAS features and enable notifications/indications on the RAS Control Point CCCD and on either the On-Demand or Real-Time CCCDs. If you choose On-Demand as a data transfer method, you must also enable notifications/indications on the RAS Data Ready and Data Overwritten CCCDs. The client is now considered subscribed to the RAS and the CS Procedure can start by following the steps described in the sections above.

5. Depending on the RAS settings chosen by the client application, communication from the server arrives as either GATT notifications or indications. In the GATT notification or indication callback, the following APIs should be used:

   1. RasClient_StorePeerMeasurementData, when the On-Demand or Real-Time handle is notified/indicated.

   2. RasClient_ProcessRasCPRsp, when the Control Point handle is notified/indicated.

   3. RasClient_ProcessRasDataReadyIndications, when the Data Ready handle is notified/indicated.

   4. RasClient_ProcessRasDataOverwrittenIndications, when the Data Overwritten handle is notified/indicated.

Perform the following steps to integrate the Ranging Service on the application that has the role of Ranging Responder (GATT server):

1. Add the following component to the application project via Kconfig:

   • CONFIG_MCUX_COMPONENT_middleware.wireless.ble_profiles_ranging=y

2. Ensure the gRasRRSP_d and gAppRasDataTransfer_d defines are present and set to 1 in the application’s app_preinclude.h file.

3. Add the Ranging Service and its characteristics to the GATT database in the application project’s gatt_db.h file as in the excerpt below:

   PRIMARY_SERVICE(service_ranging, gBleSig_RangingService_d)
    CHARACTERISTIC(char_ras_ctrl_point, gBleSig_RasControlPoint_d, (gGattCharPropWriteWithoutRsp_c | gGattCharPropIndicate_c) )
        VALUE_VARLEN(value_ras_ctrl_point, gBleSig_RasControlPoint_d, (gPermissionFlagWritable_c | gPermissionFlagWriteWithEncryption_c ), 0x05, 0x01, 0x00)
        CCCD(cccd_ras_ctrl_point)
    CHARACTERISTIC(char_ras_stored_data, gBleSig_RasOnDemandProcData_d, (gGattCharPropNotify_c | gGattCharPropIndicate_c) )
        VALUE_VARLEN(value_ras_stored_data, gBleSig_RasOnDemandProcData_d, (gPermissionNone_c), gAttMaxNotifIndDataSize_d(gAttMaxMtu_c), 0x01, 0x00)
        CCCD(cccd_ras_stored_data)
    CHARACTERISTIC(char_ras_real_time_data, gBleSig_RasRealTimeProcData_d, (gGattCharPropNotify_c | gGattCharPropIndicate_c) )
        VALUE_VARLEN(value_ras_real_time_data, gBleSig_RasRealTimeProcData_d, (gPermissionNone_c), gAttMaxNotifIndDataSize_d(gAttMaxMtu_c), 0x01, 0x00)
        CCCD(cccd_ras_real_time_data)
    CHARACTERISTIC(char_ras_ranging_data_ready, gBleSig_RasProcDataReady_d, (gGattCharPropNotify_c | gGattCharPropIndicate_c) )
        VALUE(value_ras_ranging_data_ready, gBleSig_RasProcDataReady_d, (gPermissionNone_c), 0x02, 0x00, 0x00)
        CCCD(cccd_ras_data_ready)
    CHARACTERISTIC(char_ras_ranging_data_overwritten, gBleSig_RasprocDataOverwritten_d, (gGattCharPropNotify_c | gGattCharPropIndicate_c) )
        VALUE(value_ras_ranging_data_overwritten, gBleSig_RasprocDataOverwritten_d, (gPermissionNone_c), 0x02, 0x00, 0x00)
        CCCD(cccd_ras_data_overwritten)
    CHARACTERISTIC(char_ras_feature, gBleSig_RasFeature_d, (gGattCharPropRead_c) )
        VALUE(value_ras_feature, gBleSig_RasFeature_d, (gPermissionFlagReadable_c | gPermissionFlagReadWithEncryption_c), 4, 0x0F, 0x00, 0x00, 0x00)
   

4. Initialize RAS by calling Ras_Start() with the handles defined in the GATT database.

5. Upon the MTU Exchange procedure’s completion, call Ras_SetMtuValue() to inform the module.

6. The client’s interactions with the server are processed in the GATT server callback. Here the following APIs are used:

   1. Ras_Subscribe when the client subscribes to either On-Demand or Real-Time CCCDs.

   2. Ras_SetDataSendPreference to save the client’s preference for the data transfer (either notifications or indications).

   3. Ras_ControlPointHandler when the client writes a command to the RAS Control Point.

   4. Ras_Unsubscribe when the client unsubscribes or disconnects.

Distance Measurement Algorithm

Introduction

The SDK provides the RADE (Rapid Accurate Distance Estimator) algorithm for precise distance measurement between devices. This algorithm leverages the LCE (Localization Compute Engine) accelerator to calculate distances with high accuracy and low latency.

Integration

Perform the following steps to integrate the RADE algorithm on the distance-measuring application:

1. Add the following components to the application project via Kconfig:

   • CONFIG_MCUX_COMPONENT_middleware.wireless.genfsk_wr_lcl_algo_cm33_lce_lib=y

   • CONFIG_MCUX_PRJSEG_module.board.wireless.app_lce=y

   • CONFIG_MCUX_PRJSEG_module.board.wireless.linker_script_ble=n

   • CONFIG_MCUX_PRJSEG_module.board.wireless.linker_script_ble_loc=y

2. APP_InitLce() will be automatically called by AppLocalization_Init() during application initialization.

3. Heap areas required by the algorithm are defined and registered in app_lce_init.c.