CS Initiator#

Channel Sounding (CS) Initiator provides an instantiable initiator (central) logic that produce its own CS results and also collects CS results from CS Reflector (peripheral) devices. Once all initiator and reflector results collected correctly it is forwarded to the RTL lib that shall produce the high-level measurement values e.g. distance, likeliness of the current distance, etc.

Modules#

cs_intermediate_result_t

cs_ranging_data_array_t

cs_ranging_data_t

Typedefs#

typedef void(*

cs_error_cb_t)(uint8_t conn_handle, cs_error_event_t evt, sl_status_t sc)

typedef void(*

cs_result_cb_t)(const uint8_t conn_handle, const uint16_t ranging_counter, const uint8_t *result, const cs_result_session_data_t *result_data, const cs_ranging_data_t *ranging_data, const void *user_data)

typedef void(*

cs_intermediate_result_cb_t)(const cs_intermediate_result_t *result, const void *user_data)

Functions#

sl_status_t

cs_initiator_create(const uint8_t conn_handle, cs_initiator_config_t *initiator_config, const rtl_config_t *rtl_config, cs_result_cb_t result_cb, cs_intermediate_result_cb_t intermediate_result_cb, cs_error_cb_t error_cb, uint8_t *instance_id)

void

cs_initiator_init(void)

sl_status_t

cs_initiator_delete(const uint8_t conn_handle)

void

cs_initiator_deinit(void)

bool

cs_initiator_on_event(sl_bt_msg_t *evt)

Macros#

#define

CS_INITIATOR_LOG (1)

#define

CS_INITIATOR_CONFIG_LOG_DATA (0)

#define

CS_INITIATOR_LOG_PREFIX "[Initiator]"

#define

CS_INITIATOR_RTL_LOG (1)

#define

CS_INITIATOR_MAX_CONNECTIONS (4)

#define

CS_INITIATOR_MAX_RANGING_DATA_SIZE (2500)

#define

CS_INITIATOR_ERROR_TIMEOUT_MS 3000

#define

CS_INITIATOR_PROCEDURE_TIMEOUT_MS 3000

#define

CS_INITIATOR_DEFAULT_CONNECTION_PERIPHERAL_LATENCY 0

#define

CS_INITIATOR_DEFAULT_TIMEOUT 200

#define

CS_INITIATOR_DEFAULT_MIN_CE_LENGTH 0

#define

CS_INITIATOR_DEFAULT_MAX_CE_LENGTH 65535

#define

CS_INITIATOR_DEFAULT_ALGO_MODE SL_RTL_CS_ALGO_MODE_REAL_TIME_FAST

#define

CS_INITIATOR_DEFAULT_CS_MAIN_MODE sl_bt_cs_mode_pbr

#define

CS_INITIATOR_DEFAULT_CS_SUB_MODE sl_bt_cs_submode_disabled

#define

CS_INITIATOR_DEFAULT_MAX_PROCEDURE_COUNT 0

#define

CS_INITIATOR_DEFAULT_PROCEDURE_SCHEDULING CS_PROCEDURE_SCHEDULING_OPTIMIZED_FOR_FREQUENCY

#define

CS_INITIATOR_DEFAULT_MIN_CONNECTION_INTERVAL 6

#define

CS_INITIATOR_DEFAULT_MAX_CONNECTION_INTERVAL 6

#define

CS_INITIATOR_DEFAULT_MIN_PROCEDURE_INTERVAL (38)

#define

CS_INITIATOR_DEFAULT_MAX_PROCEDURE_INTERVAL (38)

#define

CS_INITIATOR_DEFAULT_CHANNEL_MAP_PRESET CS_CHANNEL_MAP_PRESET_HIGH

#define

CS_CUSTOM_CHANNEL_MAP { 0xFC, 0xFF, 0x7F, 0xFC, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0x1F }

#define

CS_INITIATOR_DEFAULT_CONN_PHY sl_bt_gap_phy_2m

#define

CS_INITIATOR_DEFAULT_CS_SYNC_PHY sl_bt_gap_phy_1m

#define

CS_INITIATOR_DEFAULT_CS_TONE_ANTENNA_CONFIG_IDX_REQ CS_ANTENNA_CONFIG_INDEX_DUAL_ONLY

#define

CS_INITIATOR_DEFAULT_CS_SYNC_ANTENNA_REQ CS_SYNC_SWITCHING

#define

CS_INITIATOR_DEFAULT_PREFERRED_PEER_ANTENNA 1

#define

CS_INITIATOR_ANTENNA_OFFSET 0

#define

CS_INITIATOR_DEFAULT_MAX_TX_POWER 10

#define

CS_INITIATOR_DEFAULT_RSSI_REF_TX_POWER -40.0F

#define

CS_INITIATOR_DEFAULT_CREATE_CONTEXT 1

#define

CS_INITIATOR_DEFAULT_MODE0_STEPS 3

#define

CS_INITIATOR_DEFAULT_RTT_TYPE sl_bt_cs_rtt_type_fractional_96_bit_sounding

#define

CS_INITIATOR_DEFAULT_CHANNEL_SELECTION_TYPE sl_bt_cs_channel_selection_algorithm_3b

#define

CS_INITIATOR_DEFAULT_CH3C_SHAPE sl_bt_cs_ch3c_shape_hat

#define

CS_INITIATOR_RAS_MODE_USE_REAL_TIME_MODE 1

#define

CS_INITIATOR_RAS_REAL_TIME_INDICATION (0)

#define

CS_INITIATOR_RAS_ON_DEMAND_INDICATION (0)

#define

CS_INITIATOR_RAS_DATA_READY_NOTIFICATION (1)

#define

CS_INITIATOR_RAS_DATA_OVERWRITTEN_NOTIFICATION (1)

#define

CS_INITIATOR_DEFAULT_CH3C_JUMP 2

#define

CS_INITIATOR_DEFAULT_MAX_PROCEDURE_DURATION 65535

#define

CS_INITIATOR_DEFAULT_TX_PWR_DELTA 0

#define

CS_INITIATOR_DEFAULT_CONFIG_ID 1

#define

CS_INITIATOR_DEFAULT_MIN_SUBEVENT_LEN 1250

#define

CS_INITIATOR_DEFAULT_MAX_SUBEVENT_LEN 3999999

#define

CS_MAX_STEP_COUNT 256

Maximum number of steps.

Typedef Documentation#

cs_error_cb_t#

typedef void(* cs_error_cb_t) (uint8_t conn_handle, cs_error_event_t evt, sl_status_t sc) )(uint8_t conn_handle, cs_error_event_t evt, sl_status_t sc)

Parameters

Direction	Argument Name	Description
[in]	conn_handle	connection handle.
[in]	evt	error event.
[in]	sc	status code.

Initiator error callback type Called in case any CS initiator related error occurred.

cs_result_cb_t#

typedef void(* cs_result_cb_t) (const uint8_t conn_handle, const uint16_t ranging_counter, const uint8_t *result, const cs_result_session_data_t *result_data, const cs_ranging_data_t *ranging_data, const void *user_data) )(const uint8_t conn_handle, const uint16_t ranging_counter, const uint8_t *result, const cs_result_session_data_t *result_data, const cs_ranging_data_t *ranging_data, const void *user_data)

Parameters

Direction	Argument Name	Description
[in]	conn_handle	connection handle
[in]	ranging_counter	Ranging counter value.
[in]	result	pointer to the result array.
[in]	result_data	pointer to the result session data.
[in]	ranging_data	ranging data that the result was calculated from.
[in]	user_data	pointer to additional user data.

Initiator result callback type Called in case a CS procedure extracted successfully and based on the extracted data a distance measurement by the RTL library has been successfully performed.

cs_intermediate_result_cb_t#

typedef void(* cs_intermediate_result_cb_t) (const cs_intermediate_result_t *result, const void *user_data) )(const cs_intermediate_result_t *result, const void *user_data)

Parameters

Type	Direction	Argument Name	Description
	[in]	result	pointer to the intermediate result structure.
	[in]	user_data	pointer to additional user data.

Initiator intermediate result callback type Called only in case the static object tracking mode is active. That means not in every CS procedure the CS initiator gets a distance measurement. When the measurement is still in progress at the end of a successfully extracted CS procedure this callback will be called instead of the result callback.

Function Documentation#

cs_initiator_create#

sl_status_t cs_initiator_create (const uint8_t conn_handle, cs_initiator_config_t * initiator_config, const rtl_config_t * rtl_config, cs_result_cb_t result_cb, cs_intermediate_result_cb_t intermediate_result_cb, cs_error_cb_t error_cb, uint8_t * instance_id)

Parameters

Type	Direction	Argument Name	Description
const uint8_t	[in]	conn_handle	connection handle
cs_initiator_config_t *	[in]	initiator_config	pointer to the initiator config
const rtl_config_t *	[in]	rtl_config	pointer to the RTL library config
cs_result_cb_t	[in]	result_cb	callback for result
cs_intermediate_result_cb_t	[in]	intermediate_result_cb	callback for intermediate result
cs_error_cb_t	[in]	error_cb	callback for error
uint8_t *	[out]	instance_id	RTL library instance ID (optional)

Create CS Initiator instance for the given connection handle. Returns

status of the operation.

cs_initiator_init#

void cs_initiator_init (void )

Parameters

Type	Direction	Argument Name	Description
void	N/A

Create and configure initiator instances.

cs_initiator_delete#

sl_status_t cs_initiator_delete (const uint8_t conn_handle)

Parameters

Type	Direction	Argument Name	Description
const uint8_t	[in]	conn_handle	connection handle

Delete CS Initiator instance associated with the given connection handle. Returns

status of the operation.

cs_initiator_deinit#

void cs_initiator_deinit (void )

Parameters

Type	Direction	Argument Name	Description
void	N/A

Deinitialization function of CS Initiator component.

cs_initiator_on_event#

bool cs_initiator_on_event (sl_bt_msg_t * evt)

Parameters

Type	Direction	Argument Name	Description
sl_bt_msg_t *	[in]	evt	Event coming from the Bluetooth stack.

Bluetooth stack event handler of the initiator events. Returns

true to send the event to the host in NCP case.