Channel Sounding#

Channel Sounding.

This class provides commands and events for Channel Sounding (CS) between Bluetooth devices.

Modules#

sl_bt_evt_cs_security_enable_complete

sl_bt_evt_cs_config_complete

sl_bt_evt_cs_procedure_enable_complete

sl_bt_evt_cs_result

sl_bt_evt_cs_read_remote_supported_capabilities_complete

Enumerations#

enum
sl_bt_cs_role_t {
sl_bt_cs_role_initiator = 0x0
sl_bt_cs_role_reflector = 0x1
}

Specifies the role for the device during CS procedure.

enum
sl_bt_cs_role_status_t {
sl_bt_cs_role_status_disable = 0x0
sl_bt_cs_role_status_enable = 0x1
}

Defines the status of a given role for an CS capable device.

enum
sl_bt_cs_companion_signal_status_t {
sl_bt_cs_companion_signal_status_disable = 0x0
sl_bt_cs_companion_signal_status_enable = 0x1
}

Defines the status of a companion signal.

enum
sl_bt_cs_procedure_state_t {
sl_bt_cs_procedure_state_disabled = 0x0
sl_bt_cs_procedure_state_enabled = 0x1
}

Defines the CS procedure state for the device.

enum
sl_bt_cs_mode_t {
sl_bt_cs_mode_rtt = 0x1
sl_bt_cs_mode_pbr = 0x2
sl_bt_cs_submode_disabled = 0xff
}

Defines the different modes for CS steps.

enum
sl_bt_cs_rtt_type_t {
sl_bt_cs_rtt_type_aa_only = 0x0
sl_bt_cs_rtt_type_fractional_96_bit_sounding = 0x2
sl_bt_cs_rtt_type_fractional_32_bit_random = 0x3
sl_bt_cs_rtt_type_fractional_64_bit_random = 0x4
sl_bt_cs_rtt_type_fractional_96_bit_random = 0x5
sl_bt_cs_rtt_type_fractional_128_bit_random = 0x6
}

Defines the Round Trip Time (RTT) payload types used during the CS sequence.

enum
sl_bt_cs_channel_selection_algorithm_t {
sl_bt_cs_channel_selection_algorithm_3b = 0x0
sl_bt_cs_channel_selection_algorithm_3c = 0x1
sl_bt_cs_channel_selection_algorithm_user_shape_interleaved = 0x2
}

Specifies the CS channel selection algorithms.

enum
sl_bt_cs_ch3c_shape_t {
sl_bt_cs_ch3c_shape_hat = 0x0
sl_bt_cs_chc3_shape_interleaved = 0x1
}

Specifies the ch3c shapes.

enum
sl_bt_cs_done_status_t {
sl_bt_cs_done_status_complete = 0x0
sl_bt_cs_done_status_partial_results_continue = 0x1
sl_bt_cs_done_status_aborted = 0xf
}

Describes the current status of the procedure or subevents.

enum
sl_bt_cs_abort_reason_t {
sl_bt_cs_abort_reason_no_abort = 0x0
sl_bt_cs_abort_reason_host_request = 0x1
sl_bt_cs_abort_reason_insufficient_channels = 0x2
sl_bt_cs_abort_reason_no_map_update = 0x3
sl_bt_cs_abort_reason_busy = 0xb
sl_bt_cs_abort_reason_sync_error = 0xc
sl_bt_cs_abort_reason_scheduling_conflict = 0xd
sl_bt_cs_abort_reason_radio_failure = 0xe
sl_bt_cs_abort_reason_unspecified = 0xf
}

Describes the abort reasons for CS procedures and subevents and is represented by 4 bits in a byte.

enum
sl_bt_cs_config_state_t {
sl_bt_cs_config_state_removed = 0x0
sl_bt_cs_config_state_created = 0x1
}

Specifies the role for the device during CS procedure.

enum
sl_bt_cs_snr_control_adjustment_t {
sl_bt_cs_snr_control_adjustment_18_db = 0x0
sl_bt_cs_snr_control_adjustment_21_db = 0x1
sl_bt_cs_snr_control_adjustment_24_db = 0x2
sl_bt_cs_snr_control_adjustment_27_db = 0x3
sl_bt_cs_snr_control_adjustment_30_db = 0x4
sl_bt_cs_snr_control_adjustment_not_applied = 0xff
}

Specifies the Signal Noise Ration (SNR) used to control transmission of CS_SYNC packets.

Functions#

sl_status_t
sl_bt_cs_security_enable(uint8_t connection)
sl_status_t
sl_bt_cs_set_default_settings(uint8_t connection, uint8_t initiator_status, uint8_t reflector_status, uint8_t antenna_identifier, int8_t max_tx_power)
sl_status_t
sl_bt_cs_create_config(uint8_t connection, uint8_t config_id, uint8_t create_context, uint8_t main_mode_type, uint8_t sub_mode_type, uint8_t min_main_mode_steps, uint8_t max_main_mode_steps, uint8_t main_mode_repetition, uint8_t mode_calibration_steps, uint8_t role, uint8_t rtt_type, uint8_t cs_sync_phy, const sl_bt_cs_channel_map_t *channel_map, uint8_t channel_map_repetition, uint8_t channel_selection_type, uint8_t ch3c_shape, uint8_t ch3c_jump, uint8_t companion_signal_state)
sl_status_t
sl_bt_cs_remove_config(uint8_t connection, uint8_t config_id)
sl_status_t
sl_bt_cs_set_channel_classification(const sl_bt_cs_channel_map_t *channel_map)
sl_status_t
sl_bt_cs_set_procedure_parameters(uint8_t connection, uint8_t config_id, uint16_t max_procedure_len, uint16_t min_procedure_interval, uint16_t max_procedure_interval, uint16_t max_procedure_count, uint32_t min_subevent_len, uint32_t max_subevent_len, uint8_t tone_antenna_config_selection, uint8_t phy, int8_t tx_pwr_delta, uint8_t preferred_peer_antenna, uint8_t snr_control_initiator, uint8_t snr_control_reflector)
sl_status_t
sl_bt_cs_procedure_enable(uint8_t connection, uint8_t enable, uint8_t config_id)
sl_status_t
sl_bt_cs_set_antenna_configuration(size_t antenna_element_offset_len, const uint8_t *antenna_element_offset)
sl_status_t
sl_bt_cs_read_local_supported_capabilities(uint8_t *num_config, uint16_t *max_consecutive_procedures, uint8_t *num_antennas, uint8_t *max_antenna_paths, uint8_t *roles, uint8_t *optional_modes, uint8_t *rtt_capability, uint8_t *rtt_aa_only, uint8_t *rtt_sounding, uint8_t *rtt_random_payload, uint8_t *optional_cs_sync_phys, uint16_t *optional_subfeatures, uint16_t *optional_t_ip1_times, uint16_t *optional_t_ip2_times, uint16_t *optional_t_fcs_times, uint16_t *optional_t_pm_times, uint8_t *t_sw_times, uint8_t *optional_tx_snr_capability)
sl_status_t
sl_bt_cs_read_remote_supported_capabilities(uint8_t connection)

Macros#

Enumeration Documentation#

sl_bt_cs_role_t#

sl_bt_cs_role_t

Specifies the role for the device during CS procedure.

Enumerator
sl_bt_cs_role_initiator

(0x0) The device will initiate the procedure

sl_bt_cs_role_reflector

(0x1) The device will reciprocate transmission


Definition at line 11416 of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/sw/bgapi/inc/sl_bt_api.h

sl_bt_cs_role_status_t#

sl_bt_cs_role_status_t

Defines the status of a given role for an CS capable device.

Enumerator
sl_bt_cs_role_status_disable

(0x0) The given role is disabled

sl_bt_cs_role_status_enable

(0x1) The given role is enabled


Definition at line 11427 of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/sw/bgapi/inc/sl_bt_api.h

sl_bt_cs_companion_signal_status_t#

sl_bt_cs_companion_signal_status_t

Defines the status of a companion signal.

Enumerator
sl_bt_cs_companion_signal_status_disable

(0x0) The companion signal is disabled

sl_bt_cs_companion_signal_status_enable

(0x1) The companion signal is enabled


Definition at line 11436 of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/sw/bgapi/inc/sl_bt_api.h

sl_bt_cs_procedure_state_t#

sl_bt_cs_procedure_state_t

Defines the CS procedure state for the device.

Enumerator
sl_bt_cs_procedure_state_disabled

(0x0) CS procedures are disabled

sl_bt_cs_procedure_state_enabled

(0x1) CS procedures are enabled


Definition at line 11447 of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/sw/bgapi/inc/sl_bt_api.h

sl_bt_cs_mode_t#

sl_bt_cs_mode_t

Defines the different modes for CS steps.

Enumerator
sl_bt_cs_mode_rtt

(0x1) Round Trip Time (RTT) measurement

sl_bt_cs_mode_pbr

(0x2) Phase-Based Ranging (PBR) measurement

sl_bt_cs_submode_disabled

(0xff) Submode disabled for the procedure.


Definition at line 11456 of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/sw/bgapi/inc/sl_bt_api.h

sl_bt_cs_rtt_type_t#

sl_bt_cs_rtt_type_t

Defines the Round Trip Time (RTT) payload types used during the CS sequence.

Enumerator
sl_bt_cs_rtt_type_aa_only

(0x0) RTT Access Address (AA) only

sl_bt_cs_rtt_type_fractional_96_bit_sounding

(0x2) RTT Fractional with 96-bit Sounding Sequence

sl_bt_cs_rtt_type_fractional_32_bit_random

(0x3) RTT Fractional with 32-bit Random Sequence

sl_bt_cs_rtt_type_fractional_64_bit_random

(0x4) RTT Fractional with 64-bit Random Sequence

sl_bt_cs_rtt_type_fractional_96_bit_random

(0x5) RTT Fractional with 96-bit Random Sequence

sl_bt_cs_rtt_type_fractional_128_bit_random

(0x6) RTT Fractional with 128-bit Random Sequence


Definition at line 11469 of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/sw/bgapi/inc/sl_bt_api.h

sl_bt_cs_channel_selection_algorithm_t#

sl_bt_cs_channel_selection_algorithm_t

Specifies the CS channel selection algorithms.

Enumerator
sl_bt_cs_channel_selection_algorithm_3b

(0x0) Use Channel Selection Algorithm #3b for non-mode 0 CS steps

sl_bt_cs_channel_selection_algorithm_3c

(0x1) Use Channel Selection Algorithm #3c for non-mode 0 CS steps

sl_bt_cs_channel_selection_algorithm_user_shape_interleaved

(0x2) Use Interleaved shape for user specified channel sequence


Definition at line 11493 of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/sw/bgapi/inc/sl_bt_api.h

sl_bt_cs_ch3c_shape_t#

sl_bt_cs_ch3c_shape_t

Specifies the ch3c shapes.

Enumerator
sl_bt_cs_ch3c_shape_hat

(0x0) Use Hat shape for user specified channel sequence

sl_bt_cs_chc3_shape_interleaved

(0x1) Use Interleaved shape for user specified channel sequence


Definition at line 11529 of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/sw/bgapi/inc/sl_bt_api.h

sl_bt_cs_done_status_t#

sl_bt_cs_done_status_t

Describes the current status of the procedure or subevents.

Enumerator
sl_bt_cs_done_status_complete

(0x0) All results complete for the CS procedure or subevent

sl_bt_cs_done_status_partial_results_continue

(0x1) Partial results with more to follow

sl_bt_cs_done_status_aborted

(0xf) Current procedure and all subsequent subevents in the procedure aborted or current subevent aborted.


Definition at line 11540 of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/sw/bgapi/inc/sl_bt_api.h

sl_bt_cs_abort_reason_t#

sl_bt_cs_abort_reason_t

Describes the abort reasons for CS procedures and subevents and is represented by 4 bits in a byte.

Enumerator
sl_bt_cs_abort_reason_no_abort

(0x0) Not aborted

sl_bt_cs_abort_reason_host_request

(0x1) Local or remote host request

sl_bt_cs_abort_reason_insufficient_channels

(0x2) Filtered channel has less than 15 channels

sl_bt_cs_abort_reason_no_map_update

(0x3) Channel map update instant has passed

sl_bt_cs_abort_reason_busy

(0xb) Controller busy with other CS Procedure

sl_bt_cs_abort_reason_sync_error

(0xc) Mode-0 packet exchanges failure

sl_bt_cs_abort_reason_scheduling_conflict

(0xd) Link Layer failed to schedule the CS procedure

sl_bt_cs_abort_reason_radio_failure

(0xe) Radio error

sl_bt_cs_abort_reason_unspecified

(0xf) Unspecified reasons for abortion


Definition at line 11561 of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/sw/bgapi/inc/sl_bt_api.h

sl_bt_cs_config_state_t#

sl_bt_cs_config_state_t

Specifies the role for the device during CS procedure.

Enumerator
sl_bt_cs_config_state_removed

(0x0) The CS device configuration is removed

sl_bt_cs_config_state_created

(0x1) The CS device configuration is created


Definition at line 11588 of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/sw/bgapi/inc/sl_bt_api.h

sl_bt_cs_snr_control_adjustment_t#

sl_bt_cs_snr_control_adjustment_t

Specifies the Signal Noise Ration (SNR) used to control transmission of CS_SYNC packets.

Enumerator
sl_bt_cs_snr_control_adjustment_18_db

(0x0) SNR control adjustment of 18 dB

sl_bt_cs_snr_control_adjustment_21_db

(0x1) SNR control adjustment of 21 dB

sl_bt_cs_snr_control_adjustment_24_db

(0x2) SNR control adjustment of 24 dB

sl_bt_cs_snr_control_adjustment_27_db

(0x3) SNR control adjustment of 27 dB

sl_bt_cs_snr_control_adjustment_30_db

(0x4) SNR control adjustment of 30 dB

sl_bt_cs_snr_control_adjustment_not_applied

(0xff) SNR control adjustment not to be applied


Definition at line 11600 of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/sw/bgapi/inc/sl_bt_api.h

Function Documentation#

sl_bt_cs_security_enable#

sl_status_t sl_bt_cs_security_enable (uint8_t connection)
Parameters
[in]connection

Connection handle

Start or restart CS security start procedure for the specified connection.

Returns

  • SL_STATUS_OK if successful. Error code otherwise.

Events


Definition at line 12345 of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/sw/bgapi/inc/sl_bt_api.h

sl_bt_cs_set_default_settings#

sl_status_t sl_bt_cs_set_default_settings (uint8_t connection, uint8_t initiator_status, uint8_t reflector_status, uint8_t antenna_identifier, int8_t max_tx_power)
Parameters
[in]connection

Connection handle

[in]initiator_status

Enum sl_bt_cs_role_status_t. Enable or disable status of the Initiator role. Values:

  • sl_bt_cs_role_status_disable (0x0): The given role is disabled

  • sl_bt_cs_role_status_enable (0x1): The given role is enabled

[in]reflector_status

Enum sl_bt_cs_role_status_t. Enable or disable status of the Reflector role. Values:

  • sl_bt_cs_role_status_disable (0x0): The given role is disabled

  • sl_bt_cs_role_status_enable (0x1): The given role is enabled

[in]antenna_identifier

Antenna identifier to be used for CS sync packets.

  • Range: 1 to 4

[in]max_tx_power

Maximum transmit power level to be used in all CS transmissions. Units: dBm.

  • Range: -127 to +20

Set the default CS settings for the specified connection. By default, all roles are disabled and the antenna is set to 1.

Returns

  • SL_STATUS_OK if successful. Error code otherwise.


Definition at line 12371 of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/sw/bgapi/inc/sl_bt_api.h

sl_bt_cs_create_config#

sl_status_t sl_bt_cs_create_config (uint8_t connection, uint8_t config_id, uint8_t create_context, uint8_t main_mode_type, uint8_t sub_mode_type, uint8_t min_main_mode_steps, uint8_t max_main_mode_steps, uint8_t main_mode_repetition, uint8_t mode_calibration_steps, uint8_t role, uint8_t rtt_type, uint8_t cs_sync_phy, const sl_bt_cs_channel_map_t * channel_map, uint8_t channel_map_repetition, uint8_t channel_selection_type, uint8_t ch3c_shape, uint8_t ch3c_jump, uint8_t companion_signal_state)
Parameters
[in]connection

The connection handle

[in]config_id

CS configuration identifier.

  • Range: 0 to 3

[in]create_context

Defines in which device the created configuration will be written

  • Value: 0x00. Write CS configuration in the local controller only

  • Value: 0x01. Write CS configuration in both the local and remote controller using a configuration procedure

[in]main_mode_type

Enum sl_bt_cs_mode_t. Main mode type. Values:

  • sl_bt_cs_mode_rtt (0x1): Round Trip Time (RTT) measurement

  • sl_bt_cs_mode_pbr (0x2): Phase-Based Ranging (PBR) measurement

  • sl_bt_cs_submode_disabled (0xff): Submode disabled for the procedure.

[in]sub_mode_type

Enum sl_bt_cs_mode_t. Sub mode type. Values:

  • sl_bt_cs_mode_rtt (0x1): Round Trip Time (RTT) measurement

  • sl_bt_cs_mode_pbr (0x2): Phase-Based Ranging (PBR) measurement

  • sl_bt_cs_submode_disabled (0xff): Submode disabled for the procedure.

[in]min_main_mode_steps

Minimum number of CS main mode steps to be executed prior to a sub mode step.

  • Range: 1 to 160

[in]max_main_mode_steps

Maximum number of CS main mode steps to be executed prior to a sub mode step.

  • Range: 1 to 160

[in]main_mode_repetition

Number of main mode steps taken from the end of the last CS subevent to be repeated at the beginning of the current CS subevent directly after the value r last Mode 0 step of that event.

  • Range: 0 to 3

[in]mode_calibration_steps

Number of Mode 0 steps to be included at the beginning of the test CS subevent

  • Range: 1 to 3

[in]role

Enum sl_bt_cs_role_t. Device's role during the CS procedure Values:

  • sl_bt_cs_role_initiator (0x0): The device will initiate the procedure

  • sl_bt_cs_role_reflector (0x1): The device will reciprocate transmission

[in]rtt_type

Enum sl_bt_cs_rtt_type_t. RTT payload type used in the CS procedure Values:

  • sl_bt_cs_rtt_type_aa_only (0x0): RTT Access Address (AA) only

  • sl_bt_cs_rtt_type_fractional_96_bit_sounding (0x2): RTT Fractional with 96-bit Sounding Sequence

  • sl_bt_cs_rtt_type_fractional_32_bit_random (0x3): RTT Fractional with 32-bit Random Sequence

  • sl_bt_cs_rtt_type_fractional_64_bit_random (0x4): RTT Fractional with 64-bit Random Sequence

  • sl_bt_cs_rtt_type_fractional_96_bit_random (0x5): RTT Fractional with 96-bit Random Sequence

  • sl_bt_cs_rtt_type_fractional_128_bit_random (0x6): RTT Fractional with 128-bit Random Sequence

[in]cs_sync_phy

Enum sl_bt_gap_phy_t. Used PHY for CS SYNC exchanges during a procedure Values:

  • sl_bt_gap_phy_1m (0x1): 1M PHY

[in]channel_map

A fixed length byte array of 10 bytes consisting of 79 1-bit fields.

The nth such field (in the range 0 to 78) contains the value for the CS channel index n.

  • Bit value 0: Channel n is disabled

  • Bit value 1: Channel n is enabled

The rest of most significant bits are reserved for future use and must be set to 0. Channels n = 0, 1, 23, 24, 25, 77 and 78 shall be ignored and not used for CS. At least 15 channels shall be marked as used.

[in]channel_map_repetition

Number of times the channel_map field will be cycled through for non-Mode 0 steps within an CS procedure.

  • Range: 1 to 255

[in]channel_selection_type

Enum sl_bt_cs_channel_selection_algorithm_t. Channel selection algorithm Values:

  • sl_bt_cs_channel_selection_algorithm_3b (0x0): Use Channel Selection Algorithm #3b for non-mode 0 CS steps

  • sl_bt_cs_channel_selection_algorithm_3c (0x1): Use Channel Selection Algorithm #3c for non-mode 0 CS steps

  • sl_bt_cs_channel_selection_algorithm_user_shape_interleaved (0x2): Use Interleaved shape for user specified channel sequence

[in]ch3c_shape

Enum sl_bt_cs_ch3c_shape_t. Ch3c shape Values:

  • sl_bt_cs_ch3c_shape_hat (0x0): Use Hat shape for user specified channel sequence

  • sl_bt_cs_chc3_shape_interleaved (0x1): Use Interleaved shape for user specified channel sequence

[in]ch3c_jump

Number of channels skipped in each rising and falling sequence.

  • Range: 2 to 8

[in]companion_signal_state

Enum sl_bt_cs_companion_signal_status_t. Companion device's signal status Values:

  • sl_bt_cs_companion_signal_status_disable (0x0): The companion signal is disabled

  • sl_bt_cs_companion_signal_status_enable (0x1): The companion signal is enabled

Create a new CS configuration in the local and remote controller. The role used in this command must be enabled prior to issuing this command using sl_bt_cs_set_default_settings command.

Returns

  • SL_STATUS_OK if successful. Error code otherwise.

Events


Definition at line 12483 of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/sw/bgapi/inc/sl_bt_api.h

sl_bt_cs_remove_config#

sl_status_t sl_bt_cs_remove_config (uint8_t connection, uint8_t config_id)
Parameters
[in]connection

Connection handle

[in]config_id

CS configuration identifier

  • Range: 0 to 3

Remove an CS configuration from the local controller.

Returns

  • SL_STATUS_OK if successful. Error code otherwise.

Events


Definition at line 12517 of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/sw/bgapi/inc/sl_bt_api.h

sl_bt_cs_set_channel_classification#

sl_status_t sl_bt_cs_set_channel_classification (const sl_bt_cs_channel_map_t * channel_map)
Parameters
[in]channel_map

A fixed length byte array of 10 bytes consisting of 79 1-bit fields.

The nth field (in the range 0 to 78) contains the value for the link layer channel index n.

  • Bit value 0: Channel n is disabled.

  • Bit value 1: Channel n is enabled.

The rest of most significant bits are reserved for future use and must be set to 0. Channels n = 0, 1, 23, 24, 25, 77 and 78 shall be ignored and not used for CS.

Update the channel classification for CS. This classification persists until overwritten with a subsequent command or until the system is reset.

Returns

  • SL_STATUS_OK if successful. Error code otherwise.


Definition at line 12541 of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/sw/bgapi/inc/sl_bt_api.h

sl_bt_cs_set_procedure_parameters#

sl_status_t sl_bt_cs_set_procedure_parameters (uint8_t connection, uint8_t config_id, uint16_t max_procedure_len, uint16_t min_procedure_interval, uint16_t max_procedure_interval, uint16_t max_procedure_count, uint32_t min_subevent_len, uint32_t max_subevent_len, uint8_t tone_antenna_config_selection, uint8_t phy, int8_t tx_pwr_delta, uint8_t preferred_peer_antenna, uint8_t snr_control_initiator, uint8_t snr_control_reflector)
Parameters
[in]connection

The connection handle

[in]config_id

CS configuration identifier.

  • Range: 0 to 3

[in]max_procedure_len

Maximum duration for each measurement procedure. Value in units of 0.625 ms.

  • Range: 1 to 65535

  • Time: N x 0.625ms. N being the input.

  • Time range: 0.625 ms to 40.959375 s.

[in]min_procedure_interval

Minimum duration in number of connection events between consecutive measurement procedure.

  • Range: 1 to 65535

[in]max_procedure_interval

Maximum duration in number of connection events between consecutive measurement procedure.

  • Range: 1 to 65535

[in]max_procedure_count

Maximum number of CS procedures to be scheduled.

  • Range: 1 to 65535

  • Value: 0x00. Procedures to continue until disabled.

[in]min_subevent_len

Minimum suggested duration for each CS subevent. Units: microseconds.

  • Range: 1 to 16777215

  • Time range: 1250 us to 4s

[in]max_subevent_len

Maximum suggested duration for each CS subevent. Units: microseconds.

  • Range: 1 to 16777215

  • Time range: 1250 us to 4s

[in]tone_antenna_config_selection

Antenna configuration index

  • Range: 0 to 7

[in]phy

Enum sl_bt_gap_phy_t. PHY on which the CS transmission will take place Values:

  • sl_bt_gap_phy_1m (0x1): 1M PHY

  • sl_bt_gap_phy_2m (0x2): 2M PHY

  • sl_bt_gap_phy_coded (0x4): Coded PHY, 125k (S=8) or 500k (S=2)

  • sl_bt_gap_phy_any (0xff): Any PHYs the device supports

[in]tx_pwr_delta

Transmit power delta. Units: dB.

  • Value: 0x80. Host does not have a recommendation for transmit power delta

[in]preferred_peer_antenna

Preferred peer-ordered antenna elements to be used by the remote device for the antenna configuration denoted by the tone antenna config selection.

  • Bit 0: Use first ordered antenna element

  • Bit 1: Use second ordered antenna element

  • Bit 2: Use third ordered antenna element

  • Bit 3: Use fourth ordered antenna element

[in]snr_control_initiator

Enum sl_bt_cs_snr_control_adjustment_t. The Signal Noise Ratio (SNR) control adjustment for the CS_SYNC transmissions of the initiator. Values:

  • sl_bt_cs_snr_control_adjustment_18_db (0x0): SNR control adjustment of 18 dB

  • sl_bt_cs_snr_control_adjustment_21_db (0x1): SNR control adjustment of 21 dB

  • sl_bt_cs_snr_control_adjustment_24_db (0x2): SNR control adjustment of 24 dB

  • sl_bt_cs_snr_control_adjustment_27_db (0x3): SNR control adjustment of 27 dB

  • sl_bt_cs_snr_control_adjustment_30_db (0x4): SNR control adjustment of 30 dB

  • sl_bt_cs_snr_control_adjustment_not_applied (0xff): SNR control adjustment not to be applied

[in]snr_control_reflector

Enum sl_bt_cs_snr_control_adjustment_t. The Signal Noise Ratio (SNR) control adjustment for the CS_SYNC transmissions of the reflector. Values:

  • sl_bt_cs_snr_control_adjustment_18_db (0x0): SNR control adjustment of 18 dB

  • sl_bt_cs_snr_control_adjustment_21_db (0x1): SNR control adjustment of 21 dB

  • sl_bt_cs_snr_control_adjustment_24_db (0x2): SNR control adjustment of 24 dB

  • sl_bt_cs_snr_control_adjustment_27_db (0x3): SNR control adjustment of 27 dB

  • sl_bt_cs_snr_control_adjustment_30_db (0x4): SNR control adjustment of 30 dB

  • sl_bt_cs_snr_control_adjustment_not_applied (0xff): SNR control adjustment not to be applied

Set the parameters for scheduling CS procedures with the remote device.

Returns

  • SL_STATUS_OK if successful. Error code otherwise.


Definition at line 12634 of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/sw/bgapi/inc/sl_bt_api.h

sl_bt_cs_procedure_enable#

sl_status_t sl_bt_cs_procedure_enable (uint8_t connection, uint8_t enable, uint8_t config_id)
Parameters
[in]connection

The connection handle

[in]enable

Enum sl_bt_cs_procedure_state_t. Enabled or disabled CS procedure state. Values:

  • sl_bt_cs_procedure_state_disabled (0x0): CS procedures are disabled

  • sl_bt_cs_procedure_state_enabled (0x1): CS procedures are enabled

[in]config_id

CS configuration identifier

Enable or disable scheduling CS procedures with the remote device.

Returns

  • SL_STATUS_OK if successful. Error code otherwise.

Events


Definition at line 12671 of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/sw/bgapi/inc/sl_bt_api.h

sl_bt_cs_set_antenna_configuration#

sl_status_t sl_bt_cs_set_antenna_configuration (size_t antenna_element_offset_len, const uint8_t * antenna_element_offset)
Parameters
[in]antenna_element_offset_len

Length of data in antenna_element_offset

[in]antenna_element_offset

Offset of each antenna, each element is a signed 16-bit integer stored in two consecutive bytes in little-endian order. Units: 1 cm.

Set the antenna configuration for the CS feature.

Returns

  • SL_STATUS_OK if successful. Error code otherwise.


Definition at line 12688 of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/sw/bgapi/inc/sl_bt_api.h

sl_bt_cs_read_local_supported_capabilities#

sl_status_t sl_bt_cs_read_local_supported_capabilities (uint8_t * num_config, uint16_t * max_consecutive_procedures, uint8_t * num_antennas, uint8_t * max_antenna_paths, uint8_t * roles, uint8_t * optional_modes, uint8_t * rtt_capability, uint8_t * rtt_aa_only, uint8_t * rtt_sounding, uint8_t * rtt_random_payload, uint8_t * optional_cs_sync_phys, uint16_t * optional_subfeatures, uint16_t * optional_t_ip1_times, uint16_t * optional_t_ip2_times, uint16_t * optional_t_fcs_times, uint16_t * optional_t_pm_times, uint8_t * t_sw_times, uint8_t * optional_tx_snr_capability)
Parameters
[out]num_config

The number of CS configurations supported per connection.

  • Range: 1 to 4

[out]max_consecutive_procedures

The maximum number of consecutive CS procedures supported.

  • Range: 1 to 65535

  • 0x00: Fixed number of consecutive procedures and for an indefinite number of procedures until termination

[out]num_antennas

The number of antenna elements available for CS tone exchanges.

  • Range: 0x01 to 0x04

[out]max_antenna_paths

The maximum number of antenna paths supported.

  • Range: 1 to 4

[out]roles

This value is a bitmask of flags to indicate which CS roles are supported by the controller. Flags:

  • 0x01, bit 0: Initiator role

  • 0x02, bit 1: Reflector role

[out]optional_modes

This value is a bitmask of flags to indicate which Optional CS modes are supported. Flags:

  • 0x02, bit 0: Mode 3 is supported

[out]rtt_capability

This value is a bitmask of flags to indicate which Round Trip Time (RTT) CS capabilities accuracy requirement in rtt_aa_only_n, rtt_sounding_n, and rtt_random_payload. Flags:

  • 0x01, bit 0: 10 ns time-of-flight (ToF) precision requirement for rtt_aa_only if set; otherwise 150 ns ToF

  • 0x02, bit 1: 10 ns ToF precision requirement for rtt_sounding if set; otherwise 150 ns ToF

  • 0x04, bit 2: 10 ns ToF precision requirement for rtt_random_payload if set; otherwise 150 ns ToF

[out]rtt_aa_only

The support status of RTT Access Address(AA) in the local controller. When supported it establishes the number of SYNC changes needed to satisfy the precision requirements.

  • Range: 1 to 255

  • 0x00: RTT AA Only is not supported

[out]rtt_sounding

The support status of RTT Sounding is supported in the local controller. When supported it establishes the number of SYNC changes needed to satisfy the precision requirements.

  • Range: 1 to 255

  • 0x00: RTT Sounding is not supported

[out]rtt_random_payload

The support status of RTT Random Payload in the local controller. When supported it establishes the number of SYNC changes needed to satisfy the precision requirements.

  • Range: 1 to 255

  • 0x00: RTT Random Payload is not supported

[out]optional_cs_sync_phys

This value is a bitmask of flags to indicate which CS_SYNC packages supported in an specific PHY. Flags:

  • 0x02, bit 1: LE 2M PHY CS_SYNC packages are supported

  • 0x04, bit 2: LE 2M 2BT PHY CS_SYNC packages are supported

[out]optional_subfeatures

This value is a bitmask of flags to indicate which Optional CS subfeatures supported is supported. Flags:

  • 0x01, bit 0: CS Companion Signal is supported

  • 0x02, bit 1: CS with zero Frequency Actuation Error relative to Mode 0 transmissions in reflector role is supported

  • 0x04, bit 2: CS Channel Selection Algorithm #3c is supported

  • 0x08, bit 3: CS phase-based ranging from a sounding sequence is supported

[out]optional_t_ip1_times

This value is a bitmask of flags to indicate which Time for Interlude Period 1 (IP1) supported is supported. Flags:

  • 0x0001, bit 0: Time durantion of 10 microseconds is supported

  • 0x0002, bit 1: Time durantion of 20 microseconds is supported

  • 0x0004, bit 2: Time durantion of 30 microseconds is supported

  • 0x0008, bit 3: Time durantion of 40 microseconds is supported

  • 0x0010, bit 4: Time durantion of 50 microseconds is supported

  • 0x0020, bit 5: Time durantion of 60 microseconds is supported

  • 0x0040, bit 6: Time durantion of 80 microseconds is supported

[out]optional_t_ip2_times

This value is a bitmask of flags to indicate which Time for Interlude Period 2 (IP2) supported is supported. Flags:

  • 0x0001, bit 0: Time duration of 10 microseconds is supported

  • 0x0002, bit 1: Time duration of 20 microseconds is supported

  • 0x0004, bit 2: Time duration of 30 microseconds is supported

  • 0x0008, bit 3: Time duration of 40 microseconds is supported

  • 0x0010, bit 4: Time duration of 50 microseconds is supported

  • 0x0020, bit 5: Time duration of 60 microseconds is supported

  • 0x0040, bit 6: Time duration of 80 microseconds is supported

[out]optional_t_fcs_times

This value is a bitmask of flags to indicate which Time for Frequency Change Spaceing (FCS) is supported. Flags:

  • 0x0001, bit 0: Time duration of 10 microseconds is supported

  • 0x0002, bit 1: Time duration of 20 microseconds is supported

  • 0x0004, bit 2: Time duration of 30 microseconds is supported

  • 0x0008, bit 3: Time duration of 40 microseconds is supported

  • 0x0010, bit 4: Time duration of 50 microseconds is supported

  • 0x0020, bit 5: Time duration of 60 microseconds is supported

  • 0x0040, bit 6: Time duration of 80 microseconds is supported

  • 0x0100, bit 7: Time duration of 100 microseconds is supported

  • 0x0200, bit 8: Time duration of 120 microseconds is supported

[out]optional_t_pm_times

This value is a bitmask of flags to indicate which Time for Phase Measurement (PM) supported is supported. Flags:

  • 0x0001, bit 0: Time duration of 10 microseconds is supported

  • 0x0002, bit 1: Time duration of 20 microseconds is supported

[out]t_sw_times

Time in microseconds for the antenna switch period of the CS tones.

  • Values: 0x02, 0x02, 0x04 and 0x0A

[out]optional_tx_snr_capability

This value is a bitmask of flags to indicate the supported SNR levels used in RTT packets. Flags:

  • 0x01, bit 0: 18 dB supported

  • 0x02, bit 1: 21 dB supported

  • 0x04, bit 2: 24 dB supported

  • 0x08, bit 3: 27 dB supported

  • 0x10, bit 4: 30 dB supported

Read the CS capabilities of the local controller.

Returns

  • SL_STATUS_OK if successful. Error code otherwise.


Definition at line 12809 of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/sw/bgapi/inc/sl_bt_api.h

sl_bt_cs_read_remote_supported_capabilities#

sl_status_t sl_bt_cs_read_remote_supported_capabilities (uint8_t connection)
Parameters
[in]connection

Connection handle

Read the Channel Sounding (CS) capabilities of the remote controller.

Returns

  • SL_STATUS_OK if successful. Error code otherwise.

Events


Definition at line 12842 of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/sw/bgapi/inc/sl_bt_api.h

Macro Definition Documentation#

sl_bt_cmd_cs_security_enable_id#

#define sl_bt_cmd_cs_security_enable_id
Value:
0x00590020

Definition at line 11392 of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/sw/bgapi/inc/sl_bt_api.h

sl_bt_cmd_cs_set_default_settings_id#

#define sl_bt_cmd_cs_set_default_settings_id
Value:
0x01590020

Definition at line 11393 of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/sw/bgapi/inc/sl_bt_api.h

sl_bt_cmd_cs_create_config_id#

#define sl_bt_cmd_cs_create_config_id
Value:
0x02590020

Definition at line 11394 of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/sw/bgapi/inc/sl_bt_api.h

sl_bt_cmd_cs_remove_config_id#

#define sl_bt_cmd_cs_remove_config_id
Value:
0x03590020

Definition at line 11395 of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/sw/bgapi/inc/sl_bt_api.h

sl_bt_cmd_cs_set_channel_classification_id#

#define sl_bt_cmd_cs_set_channel_classification_id
Value:
0x04590020

Definition at line 11396 of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/sw/bgapi/inc/sl_bt_api.h

sl_bt_cmd_cs_set_procedure_parameters_id#

#define sl_bt_cmd_cs_set_procedure_parameters_id
Value:
0x05590020

Definition at line 11397 of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/sw/bgapi/inc/sl_bt_api.h

sl_bt_cmd_cs_procedure_enable_id#

#define sl_bt_cmd_cs_procedure_enable_id
Value:
0x06590020

Definition at line 11398 of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/sw/bgapi/inc/sl_bt_api.h

sl_bt_cmd_cs_set_antenna_configuration_id#

#define sl_bt_cmd_cs_set_antenna_configuration_id
Value:
0x07590020

Definition at line 11399 of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/sw/bgapi/inc/sl_bt_api.h

sl_bt_cmd_cs_read_local_supported_capabilities_id#

#define sl_bt_cmd_cs_read_local_supported_capabilities_id
Value:
0x08590020

Definition at line 11400 of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/sw/bgapi/inc/sl_bt_api.h

sl_bt_cmd_cs_read_remote_supported_capabilities_id#

#define sl_bt_cmd_cs_read_remote_supported_capabilities_id
Value:
0x09590020

Definition at line 11401 of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/sw/bgapi/inc/sl_bt_api.h

sl_bt_rsp_cs_security_enable_id#

#define sl_bt_rsp_cs_security_enable_id
Value:
0x00590020

Definition at line 11402 of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/sw/bgapi/inc/sl_bt_api.h

sl_bt_rsp_cs_set_default_settings_id#

#define sl_bt_rsp_cs_set_default_settings_id
Value:
0x01590020

Definition at line 11403 of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/sw/bgapi/inc/sl_bt_api.h

sl_bt_rsp_cs_create_config_id#

#define sl_bt_rsp_cs_create_config_id
Value:
0x02590020

Definition at line 11404 of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/sw/bgapi/inc/sl_bt_api.h

sl_bt_rsp_cs_remove_config_id#

#define sl_bt_rsp_cs_remove_config_id
Value:
0x03590020

Definition at line 11405 of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/sw/bgapi/inc/sl_bt_api.h

sl_bt_rsp_cs_set_channel_classification_id#

#define sl_bt_rsp_cs_set_channel_classification_id
Value:
0x04590020

Definition at line 11406 of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/sw/bgapi/inc/sl_bt_api.h

sl_bt_rsp_cs_set_procedure_parameters_id#

#define sl_bt_rsp_cs_set_procedure_parameters_id
Value:
0x05590020

Definition at line 11407 of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/sw/bgapi/inc/sl_bt_api.h

sl_bt_rsp_cs_procedure_enable_id#

#define sl_bt_rsp_cs_procedure_enable_id
Value:
0x06590020

Definition at line 11408 of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/sw/bgapi/inc/sl_bt_api.h

sl_bt_rsp_cs_set_antenna_configuration_id#

#define sl_bt_rsp_cs_set_antenna_configuration_id
Value:
0x07590020

Definition at line 11409 of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/sw/bgapi/inc/sl_bt_api.h

sl_bt_rsp_cs_read_local_supported_capabilities_id#

#define sl_bt_rsp_cs_read_local_supported_capabilities_id
Value:
0x08590020

Definition at line 11410 of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/sw/bgapi/inc/sl_bt_api.h

sl_bt_rsp_cs_read_remote_supported_capabilities_id#

#define sl_bt_rsp_cs_read_remote_supported_capabilities_id
Value:
0x09590020

Definition at line 11411 of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/sw/bgapi/inc/sl_bt_api.h