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_result_t

cs_intermediate_result_t

cs_result_event_t

cs_result_data_t

state_machine_event_data_t

Enumerations#

enum
cs_procedure_action_t {
CS_PROCEDURE_ACTION_CONTINUE = 0u
CS_PROCEDURE_ACTION_TRIGGER_RESET
CS_PROCEDURE_ACTION_TRIGGER_START
CS_PROCEDURE_ACTION_TRIGGER_STOP
}
enum
state_machine_event_t {
INITIATOR_EVT_INIT_STARTED = 0U
INITIATOR_EVT_INIT_COMPLETED
INITIATOR_EVT_START_PROCEDURE
INITIATOR_EVT_PROCEDURE_ENABLE_STARTING
INITIATOR_EVT_PROCEDURE_ENABLE_COMPLETED
INITIATOR_EVT_PROCEDURE_DISABLE_COMPLETED
INITIATOR_EVT_CS_RESULT
INITIATOR_EVT_CS_RESULT_CONTINUE
INITIATOR_EVT_DELETE_INSTANCE
INITIATOR_EVT_ERROR
}

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 cs_result_t *result, const sl_rtl_cs_procedure *cs_procedure, 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)
sl_status_t
cs_initiator_delete(const uint8_t conn_handle)
bool
cs_initiator_on_event(sl_bt_msg_t *evt)

Macros#

#define
CS_INITIATOR_LOG (1)
#define
CS_INITIATOR_LOG_PREFIX "[Initiator]"
#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_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_DEFAULT_ALGO_MODE SL_RTL_CS_ALGO_MODE_REAL_TIME_BASIC
#define
CS_INITIATOR_DEFAULT_CHANNEL_MAP_PRESET CS_CHANNEL_MAP_PRESET_HIGH

Enumeration Documentation#

cs_procedure_action_t#

cs_procedure_action_t
Enumerator
CS_PROCEDURE_ACTION_CONTINUE
CS_PROCEDURE_ACTION_TRIGGER_RESET
CS_PROCEDURE_ACTION_TRIGGER_START
CS_PROCEDURE_ACTION_TRIGGER_STOP

state_machine_event_t#

state_machine_event_t
Enumerator
INITIATOR_EVT_INIT_STARTED
INITIATOR_EVT_INIT_COMPLETED
INITIATOR_EVT_START_PROCEDURE
INITIATOR_EVT_PROCEDURE_ENABLE_STARTING
INITIATOR_EVT_PROCEDURE_ENABLE_COMPLETED
INITIATOR_EVT_PROCEDURE_DISABLE_COMPLETED
INITIATOR_EVT_CS_RESULT
INITIATOR_EVT_CS_RESULT_CONTINUE
INITIATOR_EVT_DELETE_INSTANCE
INITIATOR_EVT_ERROR

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
TypeDirectionArgument NameDescription
[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 cs_result_t *result, const sl_rtl_cs_procedure *cs_procedure, const void *user_data) )(const cs_result_t *result, const sl_rtl_cs_procedure *cs_procedure, const void *user_data)
Parameters
TypeDirectionArgument NameDescription
[in]result

pointer to the result structure.

[in]cs_procedure

procedure 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
TypeDirectionArgument NameDescription
[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
TypeDirectionArgument NameDescription
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
TypeDirectionArgument NameDescription
voidN/A

Create and configure initiator instances.


cs_initiator_delete#

sl_status_t cs_initiator_delete (const uint8_t conn_handle)
Parameters
TypeDirectionArgument NameDescription
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
TypeDirectionArgument NameDescription
voidN/A

Deinitialization function of CS Initiator component.


cs_initiator_on_event#

bool cs_initiator_on_event (sl_bt_msg_t * evt)
Parameters
TypeDirectionArgument NameDescription
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.


Macro Definition Documentation#

CS_INITIATOR_MAX_CONNECTIONS#

#define CS_INITIATOR_MAX_CONNECTIONS
Value:
(1)

CS_INITIATOR_MAX_SUBEVENT_PER_PROC#

#define CS_INITIATOR_MAX_SUBEVENT_PER_PROC
Value:
(6)

CS_INITIATOR_MAX_STEP_DATA_LEN#

#define CS_INITIATOR_MAX_STEP_DATA_LEN
Value:
(2048)

CS_INITIATOR_LOG#

#define CS_INITIATOR_LOG
Value:
(1)

CS_INITIATOR_LOG_PREFIX#

#define CS_INITIATOR_LOG_PREFIX
Value:
"[Initiator]"

CS_INITIATOR_RTL_LOG#

#define CS_INITIATOR_RTL_LOG
Value:
(1)

CS_INITIATOR_CS_EVENT_BUF_SIZE#

#define CS_INITIATOR_CS_EVENT_BUF_SIZE
Value:
(16)

CS_INITIATOR_DEFAULT_MIN_PROCEDURE_INTERVAL#

#define CS_INITIATOR_DEFAULT_MIN_PROCEDURE_INTERVAL
Value:
(30)

CS_INITIATOR_DEFAULT_MAX_PROCEDURE_INTERVAL#

#define CS_INITIATOR_DEFAULT_MAX_PROCEDURE_INTERVAL
Value:
(30)

CS_INITIATOR_ANTENNA_OFFSET#

#define CS_INITIATOR_ANTENNA_OFFSET
Value:
0

CS_INITIATOR_ERROR_TIMEOUT_MS#

#define CS_INITIATOR_ERROR_TIMEOUT_MS
Value:
3000

CS_INITIATOR_PROCEDURE_TIMEOUT_MS#

#define CS_INITIATOR_PROCEDURE_TIMEOUT_MS
Value:
3000

CS_CUSTOM_CHANNEL_MAP#

#define CS_CUSTOM_CHANNEL_MAP
Value:
{ 0xFC, 0xFF, 0x7F, 0xFC, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0x1F }

CS_INITIATOR_DEFAULT_CS_MODE#

#define CS_INITIATOR_DEFAULT_CS_MODE
Value:
2

CS_INITIATOR_DEFAULT_MIN_CONNECTION_INTERVAL#

#define CS_INITIATOR_DEFAULT_MIN_CONNECTION_INTERVAL
Value:
6

CS_INITIATOR_DEFAULT_MAX_CONNECTION_INTERVAL#

#define CS_INITIATOR_DEFAULT_MAX_CONNECTION_INTERVAL
Value:
6

CS_INITIATOR_DEFAULT_MAX_PROCEDURE_COUNT#

#define CS_INITIATOR_DEFAULT_MAX_PROCEDURE_COUNT
Value:
1

CS_INITIATOR_DEFAULT_CONN_PHY#

#define CS_INITIATOR_DEFAULT_CONN_PHY
Value:
sl_bt_gap_phy_2m

CS_INITIATOR_DEFAULT_CS_SYNC_PHY#

#define CS_INITIATOR_DEFAULT_CS_SYNC_PHY
Value:
sl_bt_gap_phy_1m

CS_INITIATOR_DEFAULT_MODE0_STEPS#

#define CS_INITIATOR_DEFAULT_MODE0_STEPS
Value:
3

CS_INITIATOR_DEFAULT_CS_TONE_ANTENNA_CONFIG_IDX_REQ#

#define CS_INITIATOR_DEFAULT_CS_TONE_ANTENNA_CONFIG_IDX_REQ
Value:
CS_ANTENNA_CONFIG_INDEX_DUAL_ONLY

CS_INITIATOR_DEFAULT_CS_SYNC_ANTENNA_REQ#

#define CS_INITIATOR_DEFAULT_CS_SYNC_ANTENNA_REQ
Value:
CS_SYNC_SWITCHING

CS_INITIATOR_DEFAULT_PREFERRED_PEER_ANTENNA#

#define CS_INITIATOR_DEFAULT_PREFERRED_PEER_ANTENNA
Value:
1

CS_INITIATOR_DEFAULT_MAX_TX_POWER#

#define CS_INITIATOR_DEFAULT_MAX_TX_POWER
Value:
20

CS_INITIATOR_DEFAULT_CREATE_CONTEXT#

#define CS_INITIATOR_DEFAULT_CREATE_CONTEXT
Value:
1

CS_INITIATOR_DEFAULT_RSSI_REF_TX_POWER#

#define CS_INITIATOR_DEFAULT_RSSI_REF_TX_POWER
Value:
-40.0F

CS_INITIATOR_DEFAULT_CONNECTION_PERIPHERAL_LATENCY#

#define CS_INITIATOR_DEFAULT_CONNECTION_PERIPHERAL_LATENCY
Value:
0

CS_INITIATOR_DEFAULT_TIMEOUT#

#define CS_INITIATOR_DEFAULT_TIMEOUT
Value:
200

CS_INITIATOR_DEFAULT_MIN_CE_LENGTH#

#define CS_INITIATOR_DEFAULT_MIN_CE_LENGTH
Value:
0

CS_INITIATOR_DEFAULT_MAX_CE_LENGTH#

#define CS_INITIATOR_DEFAULT_MAX_CE_LENGTH
Value:
65535

CS_INITIATOR_DEFAULT_CHANNEL_SELECTION_TYPE#

#define CS_INITIATOR_DEFAULT_CHANNEL_SELECTION_TYPE
Value:
sl_bt_cs_channel_selection_algorithm_3b

CS_INITIATOR_DEFAULT_CH3C_SHAPE#

#define CS_INITIATOR_DEFAULT_CH3C_SHAPE
Value:
sl_bt_cs_ch3c_shape_hat

CS_INITIATOR_DEFAULT_ALGO_MODE#

#define CS_INITIATOR_DEFAULT_ALGO_MODE
Value:
SL_RTL_CS_ALGO_MODE_REAL_TIME_BASIC

CS_INITIATOR_DEFAULT_CHANNEL_MAP_PRESET#

#define CS_INITIATOR_DEFAULT_CHANNEL_MAP_PRESET
Value:
CS_CHANNEL_MAP_PRESET_HIGH

CS_INITIATOR_DEFAULT_CH3C_JUMP#

#define CS_INITIATOR_DEFAULT_CH3C_JUMP
Value:
2

CS_INITIATOR_DEFAULT_MAX_PROCEDURE_DURATION#

#define CS_INITIATOR_DEFAULT_MAX_PROCEDURE_DURATION
Value:
65535

CS_INITIATOR_DEFAULT_TX_PWR_DELTA#

#define CS_INITIATOR_DEFAULT_TX_PWR_DELTA
Value:
0

CS_INITIATOR_DEFAULT_CONFIG_ID#

#define CS_INITIATOR_DEFAULT_CONFIG_ID
Value:
1

CS_INITIATOR_DEFAULT_MIN_SUBEVENT_LEN#

#define CS_INITIATOR_DEFAULT_MIN_SUBEVENT_LEN
Value:
1250

CS_INITIATOR_DEFAULT_MAX_SUBEVENT_LEN#

#define CS_INITIATOR_DEFAULT_MAX_SUBEVENT_LEN
Value:
3999999