Accurate Bluetooth Ranging Test#

Accurate Bluetooth Ranging Test.

This class provides optional test commands and events for ABR between Bluetooth devices.

Enumerations#

enum
sl_bt_cs_test_tone_extension_t {
sl_bt_cs_test_tone_extension_both_without = 0x0
sl_bt_cs_test_tone_extension_reflector_without = 0x1
sl_bt_cs_test_tone_extension_initiator_without = 0x2
sl_bt_cs_test_tone_extension_both_with = 0x3
sl_bt_cs_test_tone_extension_round_robin = 0x4
}

Defines tone extension for ABR test.

enum
sl_bt_cs_test_sounding_sequence_marker_t {
sl_bt_cs_test_sounding_sequence_marker_1 = 0x0
sl_bt_cs_test_sounding_sequence_marker_2 = 0x1
sl_bt_cs_test_sounding_sequence_marker_round_robin = 0x2
}

This defines sounding sequence marker for ABR test.

Functions#

sl_status_t
sl_bt_cs_test_start(uint8_t main_mode_type, uint8_t sub_mode_type, uint8_t main_mode_repetition, uint8_t mode_calibration_steps, uint8_t role, uint8_t rtt_type, uint8_t cs_sync_phy, uint8_t antenna_selection, const sl_bt_cs_subevent_length_t *subevent_len, uint16_t subevent_interval, int8_t tx_power, uint8_t t_ip1_time, uint8_t t_ip2_time, uint8_t t_fcs_time, uint8_t t_pm_time, uint8_t t_sw_time, uint8_t tone_antenna_config, uint8_t companion_signal_state, uint16_t drbg_nonce, uint16_t override_config, size_t override_parameters_len, const uint8_t *override_parameters)

Macros#

#define
sl_bt_cmd_cs_test_start_id 0x005a0020
#define
sl_bt_rsp_cs_test_start_id 0x005a0020

Enumeration Documentation#

sl_bt_cs_test_tone_extension_t#

sl_bt_cs_test_tone_extension_t

Defines tone extension for ABR test.

Enumerator
sl_bt_cs_test_tone_extension_both_without

(0x0) Initiator and Reflector tones sent without tone extension

sl_bt_cs_test_tone_extension_reflector_without

(0x1) Initiator tone sent with extension; Reflector tone sent without extension

sl_bt_cs_test_tone_extension_initiator_without

(0x2) Initiator tone sent without extension; Reflector tone sent with extension

sl_bt_cs_test_tone_extension_both_with

(0x3) Initiator and Reflector tones sent with extension

sl_bt_cs_test_tone_extension_round_robin

(0x4) Loop through values 0x00 to 0x03


sl_bt_cs_test_sounding_sequence_marker_t#

sl_bt_cs_test_sounding_sequence_marker_t

This defines sounding sequence marker for ABR test.

Enumerator
sl_bt_cs_test_sounding_sequence_marker_1

(0x0) Use 0b0011 as the Sounding Sequence marker

sl_bt_cs_test_sounding_sequence_marker_2

(0x1) Use 0b1100 as the Sounding Sequence marker

sl_bt_cs_test_sounding_sequence_marker_round_robin

(0x2) Loop through 0b0011 and 0b1100


Function Documentation#

sl_bt_cs_test_start#

sl_status_t sl_bt_cs_test_start (uint8_t main_mode_type, uint8_t sub_mode_type, uint8_t main_mode_repetition, uint8_t mode_calibration_steps, uint8_t role, uint8_t rtt_type, uint8_t cs_sync_phy, uint8_t antenna_selection, const sl_bt_cs_subevent_length_t * subevent_len, uint16_t subevent_interval, int8_t tx_power, uint8_t t_ip1_time, uint8_t t_ip2_time, uint8_t t_fcs_time, uint8_t t_pm_time, uint8_t t_sw_time, uint8_t tone_antenna_config, uint8_t companion_signal_state, uint16_t drbg_nonce, uint16_t override_config, size_t override_parameters_len, const uint8_t * override_parameters)
Parameters
TypeDirectionArgument NameDescription
uint8_t[in]main_mode_type

Enum sl_bt_cs_mode_t. Main mode type. Values :

  • sl_bt_cs_mode_calibration (0x0): Frequency offset and timing calibration measurement

  • 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_mode_pbr_and_rtt (0x3): PBR and RTT measurement

uint8_t[in]sub_mode_type

Enum sl_bt_cs_mode_t. Sub mode type. Values:

  • sl_bt_cs_mode_calibration (0x0): Frequency offset and timing calibration measurement

  • 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_mode_pbr_and_rtt (0x3): PBR and RTT measurement

uint8_t[in]main_mode_repetition

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

  • Range: 0 to 3

uint8_t[in]mode_calibration_steps

Number of calibration mode steps to be included at the beginning of the test ABR subevent

  • Range: 1 to 3

uint8_t[in]role

Enum sl_bt_cs_role_t. Role during ABR 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

uint8_t[in]rtt_type

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

  • sl_bt_cs_rtt_type_coarse (0x0): RTT Coarse

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

uint8_t[in]cs_sync_phy

Enum sl_bt_gap_phy_t. Used PHY for ABR SYNC exchanges during a procedure 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

uint8_t[in]antenna_selection

Antenna Identifier to be used for RTT packets

  • Range: 1 to 4

const sl_bt_cs_subevent_length_t *[in]subevent_len

ABR subevent length in units of microseconds.

uint16_t[in]subevent_interval

Interval between the start of two consecutive ABR events. Units: 0.625 ms.

  • Value: 0x0000. Single ABR subevent

int8_t[in]tx_power

Transmit power level for the transmission. Units: dBm.

  • Range: -127 to +20

  • Value: 0x7E. Set transmitter to minimum transmit power level

  • Value: 0x7F. Set transmitter to maximum transmit power level

uint8_t[in]t_ip1_time

Idle time in microseconds between the RTT packets

  • Values: 10, 20, 30, 40, 50, 60, 80 or 145

uint8_t[in]t_ip2_time

Interlude time in microseconds between the ABR tones

  • Values: 10, 20, 30, 40, 50, 60, 80 or 145

uint8_t[in]t_fcs_time

Time in microseconds for frequency changes

  • Values: 15, 20, 30, 40, 50, 60, 80, 100, 120 or 150

uint8_t[in]t_pm_time

Time in microseconds for the phase measurement period of the ABR tones

  • Values: 10, 20 or 40

uint8_t[in]t_sw_time

Time in microseconds for the antenna switch period of the ABR tones

  • Values: 0, 1, 2, 4 or 10

uint8_t[in]tone_antenna_config

Antenna Configuration Index used during antenna switching

  • Range: 0 to 7

uint8_t[in]companion_signal_state

Enum sl_bt_cs_companion_signal_status_t. Enable or disable status of the companion signal. 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

uint16_t[in]drbg_nonce

Antenna Configuration Index used during antenna switching

  • Range: 0 to 7

uint16_t[in]override_config

Configuration of the parameters in override_parameters

  • Bit 0: The channel sequence for the subevent is determined by the values of channel map repetition, channel length, and channel parameters.

  • Bit 2: The number of main mode ABR steps to be executed before a sub mode ABR step during the ABR procedure is determined by the value of main mode steps parameter.

  • Bit 3: The transmission of tone extensions within each Mode 2 or Mode 3 step is determined by the value of T_PM_Tone_Ext parameter.

  • Bit 4: The Tone antenna permutation index for each Mode 2 or Mode 3 step is determined by the value of Tone_Antenna_Permutation parameter.

  • Bit 5: The ABR Access Address of all packets sent by the initiator is determined by ABR_SYNC_AA_Initiator parameter. The ABR Access Address of all packets sent by the reflector is determined by ABR_SYNC_AA_Reflector parameter. B

  • Bit 6: The Marker positions for each ABR SYNC packet with a marker is determined by the value of SS_Marker1_Position and SS_Marker2_Position parameters.

  • Bit 7: The Marker value for each marker within a ABR SYNC packet is determined by SS_Marker_Value parameter.

  • Bit 8: The payload of the ABR SYNC packet is determined by the value of ABR_SYNC_Payload_Pattern parameter.

  • Bit 10: Stable Phase test

size_t[in]override_parameters_len

Length of data in override_parameters

const uint8_t *[in]override_parameters

Variable set of parameters which are present dependent on the bits set in the override config parameter.

  • Bit 0: channel_map_repetition, channel_length and channel

  • Bit 2: main_mode_steps

  • Bit 3: t_pm_tone_ext

  • Bit 4: tone_antenna_permutation

  • Bit 5: aa_initiator and aa_reflector

  • Bit 6: ss_marker1_position and ss_marker2_position

  • Bit 7: ss_marker_value

  • Bit 8: ABR_SYNC_Payload_Pattern and ABR_SYNC_User_Payload

Start a single ABR procedure using the given configuration. The reflector must be initialized before starting the initiator. To stop an ongoing test, use the sl_bt_test_dtm_end command.

Returns

  • SL_STATUS_OK if successful. Error code otherwise.

Events

  • sl_bt_evt_cs_result - Triggered when local controller has results to report for every ABR subevent within the ABR procedure