Channel Sounding (CS)#
Channel Sounding.
Distances are calculated by following the steps below:
Initialize a sl_rtl_cs_libitem instance.
Set up the algorithm mode and CS parameters.
Create the estimator.
Process the CS procedure data into distance.
Get distance and/or likeliness estimates.
Modules#
sl_rtl_cs_estimator_param_value
sl_rtl_cs_step_data.__unnamed1__
Enumerations#
Typedefs#
CS library item.
Functions#
Macros#
Enumeration Documentation#
sl_rtl_cs_role#
sl_rtl_cs_role
Enumerator | |
---|---|
SL_RTL_CS_ROLE_INITIATOR | Initiator role. |
SL_RTL_CS_ROLE_REFLECTOR | Reflector role. |
sl_rtl_cs_algo_mode#
sl_rtl_cs_algo_mode
Enumerator | |
---|---|
SL_RTL_CS_ALGO_MODE_REAL_TIME_BASIC | Medium filtering, medium response, medium CPU cost. Suitable for real-time tracking. |
SL_RTL_CS_ALGO_MODE_STATIC_HIGH_ACCURACY | High filtering, high CPU cost, high accuracy. Suitable for static high-accuracy use cases. |
SL_RTL_CS_ALGO_MODE_REAL_TIME_FAST | Low filtering, low CPU and RAM cost, basic accuracy. Suitable for real-time tracking with constrained computational resources. This mode is only available for free-running procedures (procedure_count = 0). |
sl_rtl_cs_mode#
sl_rtl_cs_mode
Enumerator | |
---|---|
SL_RTL_CS_MODE_CALIBRATION | Calibration mode with no distance estimation enabled |
SL_RTL_CS_MODE_RTT | Round-trip time based estimation (RTT) |
SL_RTL_CS_MODE_PBR | Round-trip phase based estimation (PBR) |
SL_RTL_CS_MODE_NONE | No mode is set. This option is used solely to indicate the absence of a sub mode. |
sl_rtl_cs_rtt_type#
sl_rtl_cs_rtt_type
Enumerator | |
---|---|
SL_RTL_CS_RTT_TYPE_AAONLY | RTT AA Only. Currently unsupported type. |
SL_RTL_CS_RTT_TYPE_SS_32BIT | RTT with 32-bit sounding sequence. Currently unsupported type. |
SL_RTL_CS_RTT_TYPE_SS_96BIT | RTT with 96-bit sounding sequence. |
SL_RTL_CS_RTT_TYPE_RS_32BIT | RTT with 32-bit random sequence. Currently unsupported type. |
SL_RTL_CS_RTT_TYPE_RS_64BIT | RTT with 64-bit random sequence. Currently unsupported type. |
SL_RTL_CS_RTT_TYPE_RS_96BIT | RTT with 96-bit random sequence. Currently unsupported type. |
SL_RTL_CS_RTT_TYPE_RS_128BIT | RTT with 128-bit random sequence. Currently unsupported type. |
sl_rtl_cs_estimator_param_type#
sl_rtl_cs_estimator_param_type
Enumerator | |
---|---|
SL_RTL_LAST_KNOWN_DISTANCE | Last known distance from the user, if more recent than the last CS measurement. |
SL_RTL_RANGE_MIN | Minimum limit for the distance estimation range. |
SL_RTL_RANGE_MAX | Maximum limit for the distance estimation range. |
SL_RTL_REF_TX_POWER | Reference RSSI value of the TX-device at 1.0 m distance in dBm. Default value is -45.0 dBm. |
sl_rtl_cs_distance_estimate_mode#
sl_rtl_cs_distance_estimate_mode
Enumerator | |
---|---|
SL_RTL_CS_BEST_ESTIMATE | The best estimate |
SL_RTL_CS_MAIN_MODE_ESTIMATE | Estimate based only on the main mode |
SL_RTL_CS_SUB_MODE_ESTIMATE | Estimate based only on the sub mode This option is available only if a valid sub mode is set. |
sl_rtl_cs_distance_estimate_type#
sl_rtl_cs_distance_estimate_type
Enumerator | |
---|---|
SL_RTL_CS_DISTANCE_ESTIMATE_TYPE_FILTERED | Distance estimate with built-in post-filtering. Note: The post-filtering would remove any large undesired jumps in the distance reported. However, post-filtering introduces latency in distance reported. |
SL_RTL_CS_DISTANCE_ESTIMATE_TYPE_RSSI | Distance estimate based on the Packet_RSSI in the calibration (Mode 0) steps |
SL_RTL_CS_DISTANCE_ESTIMATE_TYPE_RAW | Distance estimate based solely on the most recent procedure input. |
SL_RTL_CS_DISTANCE_ESTIMATE_TYPE_VELOCITY | Provides a velocity estimate derived from PCT data. Negative velocity denotes approaching target. This feature is experimental and currently only supports specific channel maps with sl_rtl_cs_mode::SL_RTL_CS_MODE_PBR and sl_rtl_algo_mode::SL_RTL_CS_ALGO_MODE_REAL_TIME_FAST. |
sl_rtl_cs_distance_estimate_confidence_type#
sl_rtl_cs_distance_estimate_confidence_type
Enumerator | |
---|---|
SL_RTL_CS_DISTANCE_ESTIMATE_CONFIDENCE_TYPE_LIKELINESS | Likeliness of the distance estimate accuracy, ranging from 0 to 1 |
SL_RTL_CS_DISTANCE_ESTIMATE_CONFIDENCE_TYPE_BIT_ERROR_RATE | Bit error rate in the RTT random or sounding sequence, ranging from 0 to 1. Only supported for RTT types (see sl_rtl_cs_rtt_type) with random sequence (RS) or sounding sequence (SS). |
sl_rtl_cs_distance_estimate_extended_info_type#
sl_rtl_cs_distance_estimate_extended_info_type
Enumerator | |
---|---|
SL_RTL_CS_DISTANCE_ESTIMATE_EXTENDED_INFO_TYPE_PROGRESS_PERCENTAGE | Estimation progress in percentage.
|
Typedef Documentation#
sl_rtl_cs_distance_estimate_confidence_mode#
typedef sl_rtl_cs_distance_estimate_mode sl_rtl_cs_distance_estimate_confidence_mode
Function Documentation#
sl_rtl_cs_init#
enum sl_rtl_error_code sl_rtl_cs_init (sl_rtl_cs_libitem * item)
Type | Direction | Argument Name | Description |
---|---|---|---|
sl_rtl_cs_libitem * | [in] | item | Pointer to the libitem to be initialized |
Initialize the CS libitem instance.
Returns
SL_RTL_ERROR_SUCCESS if successful
sl_rtl_cs_deinit#
enum sl_rtl_error_code sl_rtl_cs_deinit (sl_rtl_cs_libitem * item)
Type | Direction | Argument Name | Description |
---|---|---|---|
sl_rtl_cs_libitem * | [in] | item | Pointer to the libitem to be deinitialized |
Deinitialize a libitem instance of the CS estimator.
Returns
SL_RTL_ERROR_SUCCESS if successful
sl_rtl_cs_set_algo_mode#
enum sl_rtl_error_code sl_rtl_cs_set_algo_mode (sl_rtl_cs_libitem * item, const sl_rtl_cs_algo_mode mode)
Type | Direction | Argument Name | Description |
---|---|---|---|
sl_rtl_cs_libitem * | [in] | item | Pointer to the initialized CS libitem |
const sl_rtl_cs_algo_mode | [in] | mode | Estimator mode as sl_rtl_cs_algo_mode |
Set the estimation algorithm mode.
Returns
SL_RTL_ERROR_SUCCESS if successful
Set the estimation mode. For example, SL_RTL_CS_ALGO_MODE_REAL_TIME_BASIC sets medium filtering. For further description of the modes, see the documentation of::sl_rtl_cs_algo_mode. CS libitem must be initialized before calling this method, or it will fail with return code SL_RTL_ERROR_NOT_INITIALIZED. This method should be called before estimator is created for CS libitem, or it will fail with error code SL_RTL_ERROR_ESTIMATOR_ALREADY_CREATED.
sl_rtl_cs_set_cs_mode#
enum sl_rtl_error_code sl_rtl_cs_set_cs_mode (sl_rtl_cs_libitem * item, const sl_rtl_cs_mode main_mode, const sl_rtl_cs_mode sub_mode)
Type | Direction | Argument Name | Description |
---|---|---|---|
sl_rtl_cs_libitem * | [in] | item | Pointer to the initialized CS libitem |
const sl_rtl_cs_mode | [in] | main_mode | main_mode as sl_rtl_cs_mode |
const sl_rtl_cs_mode | [in] | sub_mode | sub_mode as sl_rtl_cs_mode |
Set the estimation CS mode.
Returns
SL_RTL_ERROR_SUCCESS if successful
Set the desired CS mode for main and sub modes. For example, SL_RTL_CS_MODE_PBR uses round-trip phase based cs_mode. Sub mode should be set to SL_RTL_CS_MODE_NONE if only main mode is enabled in CS ranging. CS libitem must be initialized before calling this method, or it will fail with return code SL_RTL_ERROR_NOT_INITIALIZED. This method should be called before estimator is created for CS libitem, or it will fail with error code SL_RTL_ERROR_ESTIMATOR_ALREADY_CREATED.
sl_rtl_cs_set_cs_params#
enum sl_rtl_error_code sl_rtl_cs_set_cs_params (sl_rtl_cs_libitem * item, const sl_rtl_cs_params * parameters)
Type | Direction | Argument Name | Description |
---|---|---|---|
sl_rtl_cs_libitem * | [in] | item | Pointer to the initialized CS libitem |
const sl_rtl_cs_params * | [in] | parameters | cs_params as sl_rtl_cs_params |
Set the estimation CS parameters.
Returns
SL_RTL_ERROR_SUCCESS if successful
Set the parameters for the estimator. CS libitem must be initialized before calling this method, or it will fail with return code SL_RTL_ERROR_NOT_INITIALIZED. This method should be called before estimator is created for CS libitem, or it will fail with error code SL_RTL_ERROR_ESTIMATOR_ALREADY_CREATED.
sl_rtl_cs_create_estimator#
enum sl_rtl_error_code sl_rtl_cs_create_estimator (sl_rtl_cs_libitem * item)
Type | Direction | Argument Name | Description |
---|---|---|---|
sl_rtl_cs_libitem * | [in] | item | Pointer to the initialized and configured CS libitem |
Create an estimator with the given parameters after initializing the libitem.
Returns
SL_RTL_ERROR_SUCCESS if successful
CS libitem must be initialized before calling this method, or it will fail with return code SL_RTL_ERROR_NOT_INITIALIZED. This method should be called before estimator is created for CS libitem, or it will fail with error code SL_RTL_ERROR_ESTIMATOR_ALREADY_CREATED.
sl_rtl_cs_set_estimator_param#
enum sl_rtl_error_code sl_rtl_cs_set_estimator_param (sl_rtl_cs_libitem * item, const sl_rtl_cs_estimator_param * param)
Type | Direction | Argument Name | Description |
---|---|---|---|
sl_rtl_cs_libitem * | [in] | item | Pointer to the initialized and configured CS libitem |
const sl_rtl_cs_estimator_param * | [in] | param | Data structure with the CS algorithm parameter to be set |
Set CS algorithm parameters. The function can be called any time before or during the processing calls.
Returns
SL_RTL_ERROR_SUCCESS if successful
CS libitem must be initialized before calling this method, or it will fail with return code SL_RTL_ERROR_NOT_INITIALIZED. This method should be called after estimator is created for CS libitem, or it will fail with error code SL_RTL_ERROR_ESTIMATOR_NOT_CREATED.
sl_rtl_cs_process#
enum sl_rtl_error_code sl_rtl_cs_process (sl_rtl_cs_libitem * item, const uint8_t num_procedures, const sl_rtl_cs_procedure * procedure_data)
Type | Direction | Argument Name | Description |
---|---|---|---|
sl_rtl_cs_libitem * | [in] | item | Pointer to the initialized and configured CS libitem |
const uint8_t | [in] | num_procedures | Number of procedures in the procedure_data array |
const sl_rtl_cs_procedure * | [in] | procedure_data | Data structure with the completed CS procedures |
Calculate distance estimate based on CS procedures.
Returns
SL_RTL_ERROR_SUCCESS if successful and SL_RTL_ERROR_ESTIMATION_IN_PROGRESS if estimate is not yet final and more input data needs to be processed.
Calculate the distance estimate from the given procedure data. The function can be called with multiple procedures. Use sl_rtl_cs_get_distance to fetch the latest distance estimate. CS libitem must be initialized before calling this method, or it will fail with return code SL_RTL_ERROR_NOT_INITIALIZED. This method should be called after estimator is created for CS libitem, or it will fail with error code SL_RTL_ERROR_ESTIMATOR_NOT_CREATED.
sl_rtl_cs_get_distance_estimate#
enum sl_rtl_error_code sl_rtl_cs_get_distance_estimate (sl_rtl_cs_libitem * item, const sl_rtl_cs_distance_estimate_type estimate_type, const sl_rtl_cs_distance_estimate_mode estimate_mode, float * distance)
Type | Direction | Argument Name | Description |
---|---|---|---|
sl_rtl_cs_libitem * | [in] | item | Pointer to the initialized CS libitem |
const sl_rtl_cs_distance_estimate_type | [in] | estimate_type | Type of distance estimate |
const sl_rtl_cs_distance_estimate_mode | [in] | estimate_mode | Mode of distance estimate |
float * | [out] | distance | Distance out in meters. |
Get distance estimate
Returns
SL_RTL_ERROR_SUCCESS if successful
CS libitem must be initialized before calling this method, or it will fail with return code SL_RTL_ERROR_NOT_INITIALIZED. This method should be called after estimator is created for CS libitem, or it will fail with error code SL_RTL_ERROR_ESTIMATOR_NOT_CREATED.
sl_rtl_cs_get_distance_estimate_confidence#
enum sl_rtl_error_code sl_rtl_cs_get_distance_estimate_confidence (sl_rtl_cs_libitem * item, const sl_rtl_cs_distance_estimate_confidence_type confidence_type, const sl_rtl_cs_distance_estimate_confidence_mode confidence_mode, float * confidence)
Type | Direction | Argument Name | Description |
---|---|---|---|
sl_rtl_cs_libitem * | [in] | item | Pointer to the initialized CS libitem |
const sl_rtl_cs_distance_estimate_confidence_type | [in] | confidence_type | Type of confidence estimate |
const sl_rtl_cs_distance_estimate_confidence_mode | [in] | confidence_mode | Mode of confidence estimate |
float * | [out] | confidence | Confidence between 0.0 - 1.0 (unlikely - likely) of the estimated distance |
Get distance estimate confidence.
Returns
SL_RTL_ERROR_SUCCESS if successful
CS libitem must be initialized before calling this method, or it will fail with return code SL_RTL_ERROR_NOT_INITIALIZED. This method should be called after estimator is created for CS libitem, or it will fail with error code SL_RTL_ERROR_ESTIMATOR_NOT_CREATED.
sl_rtl_cs_get_distance_estimate_extended_info#
enum sl_rtl_error_code sl_rtl_cs_get_distance_estimate_extended_info (sl_rtl_cs_libitem * item, const sl_rtl_cs_distance_estimate_extended_info_type extended_info_type, float * extended_info)
Type | Direction | Argument Name | Description |
---|---|---|---|
sl_rtl_cs_libitem * | [in] | item | Pointer to the initialized CS libitem |
const sl_rtl_cs_distance_estimate_extended_info_type | [in] | extended_info_type | Type of distance estimate extended information |
float * | [out] | extended_info | Extended info value depending on the extedended_info_type selection |
Get distance estimate extended information.
Returns
SL_RTL_ERROR_SUCCESS if successful
CS libitem must be initialized before calling this method, or it will fail with return code SL_RTL_ERROR_NOT_INITIALIZED. This method should be called after estimator is created for CS libitem, or it will fail with error code SL_RTL_ERROR_ESTIMATOR_NOT_CREATED.
sl_rtl_cs_log_enable#
enum sl_rtl_error_code sl_rtl_cs_log_enable (sl_rtl_cs_libitem * item)
Type | Direction | Argument Name | Description |
---|---|---|---|
sl_rtl_cs_libitem * | [in] | item | Pointer to the CS libitem |
Enable logging for the given CS libitem.
Returns
SL_RTL_ERROR_SUCCESS if successful
CS libitem must be initialized before calling this method, or it will fail with return code SL_RTL_ERROR_NOT_INITIALIZED. This method should be called before estimator is created for CS libitem, or it will fail with error code SL_RTL_ERROR_ESTIMATOR_ALREADY_CREATED.
sl_rtl_cs_log_disable#
enum sl_rtl_error_code sl_rtl_cs_log_disable (sl_rtl_cs_libitem * item)
Type | Direction | Argument Name | Description |
---|---|---|---|
sl_rtl_cs_libitem * | [in] | item | Pointer to the CS libitem |
Disable logging for the given CS libitem.
Returns
SL_RTL_ERROR_SUCCESS if successful
CS libitem must be initialized before calling this method, or it will fail with return code SL_RTL_ERROR_NOT_INITIALIZED. This method should be called before estimator is created for CS libitem, or it will fail with error code SL_RTL_ERROR_ESTIMATOR_ALREADY_CREATED.
sl_rtl_cs_log_add_timestamp#
enum sl_rtl_error_code sl_rtl_cs_log_add_timestamp (sl_rtl_cs_libitem * item, const struct timespec timestamp)
Type | Direction | Argument Name | Description |
---|---|---|---|
sl_rtl_cs_libitem * | [in] | item | Epoch time |
const struct timespec | N/A | timestamp |
Add epoch time to RTL logging data. This function logs a timestamp entry to enhance the logging data. The timestamp should be recorded at the time of receiving the first subevent from the radio. If measurements are stopped and restarted, this function must be invoked again to log a new timestamp.
Returns
SL_RTL_ERROR_SUCCESS if successful
sl_rtl_cs_log_get_instance_id#
enum sl_rtl_error_code sl_rtl_cs_log_get_instance_id (sl_rtl_cs_libitem * item, uint8_t * instance_id)
Type | Direction | Argument Name | Description |
---|---|---|---|
sl_rtl_cs_libitem * | [in] | item | Pointer to the CS libitem |
uint8_t * | [out] | instance_id | Instance ID of the given CS libitem |
Get the instance ID of the given CS libitem.
Returns
SL_RTL_ERROR_SUCCESS if successful