MCUXpresso SDK Documentation
Open on Repo Open an Issue
Source (.md/.rst) Page PDF (.pdf)

Localization scenarios

Localization scenarios#

Application configuration#

This section describes configuration options available for the applications. The configuration can be done either at compile time, by using macros added in the app_preinclude.h file of the respective sample, or at runtime, via shell commands. The available configurations are:

  • The Channel Sounding role can be set through the role shell command at runtime only if there are no active connections. The default role is set through the gCsDefaultRole_c define in app_preinclude.h. In the default configuration, the Anchor is in the CS Initiator role (gCsRoleInitiator_c) and the Device is in the CS Reflector role (gCsRoleReflector_c).

  • The number of Channel Sounding procedures to be run via the CS Procedure Repeat mechanism, for each triggered distance measurement. The default value can be set through the gCsProcRepeatMaxNumProcedures_c define. At runtime, the value can be changed using the setnumprocs command.

  • The ranging algorithm to run once the local and remote measurement data is available. Each of the two supported algorithms can be disabled at compile time for code size reasons. By default, both are enabled. To disable an algorithm at compile time, define its respective macro with the value 0 inside app_preinclude.h. The macros are gAppUseCDEAlgorithm_d, gAppUseRADEAlgorithm_d. At runtime, the setalgo shell command can be used to configure the algorithm that runs upon completion of the CS procedure and data transfer. Any combination of algorithms can be selected. By default, RADE is selected.

  • The timing information display feature can be activated by setting the gAppCsTimeInfo_d macro to value 1 inside app_preinclude.h. Additional timing information such as the duration of the CS config phase, CS procedure, BTCS transfer, and running of the algorithms is displayed on the console.

  • The HCI data log export can be activated by setting the gAppHciDataLogExport_d macro to value 1 in app_preinclude.h, on both the Anchor and the Device. A log of all Subevent Result and Subevent Result Continue HCI events will be printed on the second serial for each CS procedure.

For better performance and user experience, the optional LE Coded PHY advertising should be disabled by setting gAppLeCodedAdvEnable_d to 0 inside app_preinclude.h on the Anchor.

Parent topic:Localization scenarios

Localization after passive entry#

The localization process starts automatically after the Passive Entry scenario is completed. The CS Initiator performs the CS setup and starts a number of gCsProcRepeatMaxNumProcedures_c procedures. After each procedure, the Device’s local data is transmitted through BTCS to the Anchor. After the Anchor collects the data, it runs the selected algorithm(s) and displays the measured distance (meters) in the console.

The below figure shows the output of the localization process after each of the five measurements completed successfully and the distance is displayed.

Output of the localization process

Parent topic:Localization scenarios

Localization on demand and other shell commands#

Localization can also be performed on demand via the tdm shell command, which takes the device ID of the peer as an argument. The command must be executed on the device that is configured as CS Initiator. As shown in the figure below, the Device triggers the localization process, and the default 5 measurements complete successfully.

Triggering the localization process

Other available shell commands are:

  • setcsconfig: This command overwrites the default parameters for the Channel Sounding Create Config command. It takes the following parameters, in the order below:

    • peerId

    • mainModeType

    • subModeType

    • mainModeMinSteps

    • mainModeMaxSteps

    • mainModeRepetition

    • mode0Steps

    • role

    • RTTType

    • channelMap

    • channelMapRepetition

    • channelSelectionType

  • setcsproc: This command overwrites the default parameters for the Channel Sounding Set Procedure Parameters command. It takes the following parameters, in the order below:

    • peerId

    • maxProcedureDuration

    • minPeriodBetweenProcedures

    • maxPeriodBetweenProcedures

    • maxNumProcedures

    • minSubeventLen

    • maxSubeventLen

    • antCfgIndex

  • verbosity: Sets the verbosity level during the CS procedure.

  • setnumprocs: This command overwrites the default value gCsProcRepeatMaxNumProcedures_c parameter for the CS Procedure Repeat. It takes the following parameters, in the order below:

    • peerId

    • maxNumProcedures

Parent topic:Localization scenarios

BTCS L2CAP data transfer#

The CCC introduced the Bluetooth LE Channel Sounding (BTCS) measurement transfer feature. BTCS procedures are configured and executed using the Bluetooth Low Energy connection established for the Digital Key Service. The results of the BTCS procedures are transferred to the vehicle and used to estimate the distance. The data transfer is done through the L2CAP channel created during the passive entry scenario. The format of the data transferred through BTCS is defined by the CCC. The algorithms used on the receiver to estimate the distance are (RADE and CDE).

The default transfer direction enabled in the digital_key_car_anchor_cs and digital_key_device_cs is from Device to the Anchor. To reverse the transfer direction in BTCS, the following defines must be set in the app_preinclude.h file:

  • digital_key_car_anchor_cs: gAppBtcsClient_d set to 0 and gAppBtcsServer_d set to 1

  • digital_key_device_cs: gAppBtcsServer_d set to 0 and gAppBtcsClient_d set to 1

The figure below shows the car Anchor output after BTCS transfer direction is reversed.

BTCS transfer - car Anchor output

The figure below shows the Device output after BTCS is enabled.

BTCS transfer - Device output

Parent topic:Localization scenarios

Exporting HCI data#

The digital_key_car_anchor_cs and the digital_key_device_cs applications can be used for exporting HCI data. These applications allow exporting the raw HCI data of all Subevent Result and Subevent Result Continue HCI events for each CS procedure. This is achieved by enabling the gAppHciDataLogExport_d macro in the application project’s app_preinclude.h header.

This feature uses the second serial interface and therefore, Connection Handover must be disabled.

The UART wires should be connected to the board’s J1-1 and J1-2 pins, in the same way as described in Running the Connection Handover scenario. At the other end, use a UART-to-USB adapter to connect to the PC. The exported data includes the local HCI LE CS Subevent Result and LE CS Subevent Result Continue events. On the PC, custom scripts can be used to process the data. These scripts are out of the scope of this note.

The format of the data is the standard HCI data format. Refer to the Core specification definitions for more details (sections 7.7.65.44 LE CS Subevent Result event and 7.7.65.45 LE CS Subevent Result Continue event):

  • OCF (1 octet)

  • OGF (1 octet)

  • Parameter total Length (1 octet)

  • Subevent_Code (1 octet)

  • Event parameters (variable)

Parent topic:Localization scenarios

Contents