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 | Suitable for real-time tracking. |
| SL_RTL_CS_ALGO_MODE_STATIC_HIGH_ACCURACY | Suitable for ranging between static objects with high-accuracy. |
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_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_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_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.
|
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 cs_mode)
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_rtl_cs_libitem * | [in] | item | Pointer to the initialized CS libitem |
| const sl_rtl_cs_mode | [in] | cs_mode | cs_mode as sl_rtl_cs_mode |
Set the estimation CS mode.
Returns
SL_RTL_ERROR_SUCCESS if successful
Set the desired cs_mode. For example, SL_RTL_CS_MODE_PBR uses round-trip phase based cs_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_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 procedure_count, 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] | procedure_count | 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, 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 |
| 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, 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 |
| 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, const sl_rtl_cs_log_params * log_params)
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_rtl_cs_libitem * | [in] | item | Pointer to the CS libitem |
| const sl_rtl_cs_log_params * | [in] | log_params | Pointer to the log initialisation parameters |
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.
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.
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