1 /** @file 2 * @brief Bluetooth Channel Sounding handling 3 */ 4 5 /* 6 * Copyright (c) 2024 Nordic Semiconductor ASA 7 * 8 * SPDX-License-Identifier: Apache-2.0 9 */ 10 #ifndef ZEPHYR_INCLUDE_BLUETOOTH_CS_H_ 11 #define ZEPHYR_INCLUDE_BLUETOOTH_CS_H_ 12 13 /** 14 * @brief LE Channel Sounding (CS) 15 * @defgroup bt_le_cs Channel Sounding (CS) 16 * @ingroup bluetooth 17 * @{ 18 */ 19 20 #include <stdint.h> 21 #include <stdbool.h> 22 23 #include <zephyr/bluetooth/hci_types.h> 24 #include <zephyr/bluetooth/conn.h> 25 26 #ifdef __cplusplus 27 extern "C" { 28 #endif 29 30 /** 31 * @brief Macro for getting a specific channel bit in CS channel map 32 * 33 * @param[in] chmap Channel map array 34 * @param[in] bit Bit number to be accessed 35 * 36 * @return Bit value, either 1 or 0 37 */ 38 #define BT_LE_CS_CHANNEL_BIT_GET(chmap, bit) (((chmap)[(bit) / 8] >> ((bit) % 8)) & 1) 39 40 /** 41 * @brief Macro for setting a specific channel bit value in CS channel map 42 * 43 * @param[in] chmap Channel map array 44 * @param[in] bit Bit number to be accessed 45 * @param[in] val Bit value to be set, either 1 or 0 46 */ 47 #define BT_LE_CS_CHANNEL_BIT_SET_VAL(chmap, bit, val) \ 48 ((chmap)[(bit) / 8] = ((chmap)[(bit) / 8] & ~BIT((bit) % 8)) | ((val) << ((bit) % 8))) 49 50 enum bt_le_cs_sync_antenna_selection_opt { 51 /** Use antenna identifier 1 for CS_SYNC packets. */ 52 BT_LE_CS_ANTENNA_SELECTION_OPT_ONE = BT_HCI_OP_LE_CS_ANTENNA_SEL_ONE, 53 /** Use antenna identifier 2 for CS_SYNC packets. */ 54 BT_LE_CS_ANTENNA_SELECTION_OPT_TWO = BT_HCI_OP_LE_CS_ANTENNA_SEL_TWO, 55 /** Use antenna identifier 3 for CS_SYNC packets. */ 56 BT_LE_CS_ANTENNA_SELECTION_OPT_THREE = BT_HCI_OP_LE_CS_ANTENNA_SEL_THREE, 57 /** Use antenna identifier 4 for CS_SYNC packets. */ 58 BT_LE_CS_ANTENNA_SELECTION_OPT_FOUR = BT_HCI_OP_LE_CS_ANTENNA_SEL_FOUR, 59 /** Use antennas in repetitive order from 1 to 4 for CS_SYNC packets. */ 60 BT_LE_CS_ANTENNA_SELECTION_OPT_REPETITIVE = BT_HCI_OP_LE_CS_ANTENNA_SEL_REP, 61 /** No recommendation for local controller antenna selection. */ 62 BT_LE_CS_ANTENNA_SELECTION_OPT_NO_RECOMMENDATION = BT_HCI_OP_LE_CS_ANTENNA_SEL_NONE, 63 }; 64 65 /** Default CS settings in the local Controller */ 66 struct bt_le_cs_set_default_settings_param { 67 /** Enable CS initiator role. */ 68 bool enable_initiator_role; 69 /** Enable CS reflector role. */ 70 bool enable_reflector_role; 71 /** Antenna identifier to be used for CS_SYNC packets by the local controller. 72 */ 73 enum bt_le_cs_sync_antenna_selection_opt cs_sync_antenna_selection; 74 /** Maximum output power (Effective Isotropic Radiated Power) to be used 75 * for all CS transmissions. 76 * 77 * Value range is @ref BT_HCI_OP_LE_CS_MIN_MAX_TX_POWER to 78 * @ref BT_HCI_OP_LE_CS_MAX_MAX_TX_POWER. 79 */ 80 int8_t max_tx_power; 81 }; 82 83 /** CS Test CS_SYNC Antenna Identifier */ 84 enum bt_le_cs_test_cs_sync_antenna_selection { 85 BT_LE_CS_TEST_CS_SYNC_ANTENNA_SELECTION_ONE = BT_HCI_OP_LE_CS_ANTENNA_SEL_ONE, 86 BT_LE_CS_TEST_CS_SYNC_ANTENNA_SELECTION_TWO = BT_HCI_OP_LE_CS_ANTENNA_SEL_TWO, 87 BT_LE_CS_TEST_CS_SYNC_ANTENNA_SELECTION_THREE = BT_HCI_OP_LE_CS_ANTENNA_SEL_THREE, 88 BT_LE_CS_TEST_CS_SYNC_ANTENNA_SELECTION_FOUR = BT_HCI_OP_LE_CS_ANTENNA_SEL_FOUR, 89 }; 90 91 /** CS SNR control options */ 92 enum bt_le_cs_snr_control { 93 BT_LE_CS_SNR_CONTROL_18dB = BT_HCI_OP_LE_CS_SNR_18, 94 BT_LE_CS_SNR_CONTROL_21dB = BT_HCI_OP_LE_CS_SNR_21, 95 BT_LE_CS_SNR_CONTROL_24dB = BT_HCI_OP_LE_CS_SNR_24, 96 BT_LE_CS_SNR_CONTROL_27dB = BT_HCI_OP_LE_CS_SNR_27, 97 BT_LE_CS_SNR_CONTROL_30dB = BT_HCI_OP_LE_CS_SNR_30, 98 BT_LE_CS_SNR_CONTROL_NOT_USED = BT_HCI_OP_LE_CS_SNR_NOT_USED, 99 }; 100 101 /** CS Test Override 3 T_PM Tone Extension */ 102 enum bt_le_cs_test_override_3_pm_tone_ext { 103 /** Initiator and reflector tones sent without tone extension */ 104 BT_LE_CS_TEST_OVERRIDE_3_NO_TONE_EXT = BT_HCI_OP_LE_CS_TEST_TONE_EXT_NONE, 105 /** Initiator tone sent with extension, reflector tone sent without tone extension */ 106 BT_LE_CS_TEST_OVERRIDE_3_INITIATOR_TONE_EXT_ONLY = BT_HCI_OP_LE_CS_TEST_TONE_EXT_INIT, 107 /** Initiator tone sent without extension, reflector tone sent with tone extension */ 108 BT_LE_CS_TEST_OVERRIDE_3_REFLECTOR_TONE_EXT_ONLY = BT_HCI_OP_LE_CS_TEST_TONE_EXT_REFL, 109 /** Initiator and reflector tones sent with tone extension */ 110 BT_LE_CS_TEST_OVERRIDE_3_INITIATOR_AND_REFLECTOR_TONE_EXT = 111 BT_HCI_OP_LE_CS_TEST_TONE_EXT_BOTH, 112 /** Applicable for mode-2 and mode-3 only: 113 * 114 * Loop through: 115 * - @ref BT_LE_CS_TEST_OVERRIDE_3_NO_TONE_EXT 116 * - @ref BT_LE_CS_TEST_OVERRIDE_3_INITIATOR_TONE_EXT_ONLY 117 * - @ref BT_LE_CS_TEST_OVERRIDE_3_REFLECTOR_TONE_EXT_ONLY 118 * - @ref BT_LE_CS_TEST_OVERRIDE_3_INITIATOR_AND_REFLECTOR_TONE_EXT 119 */ 120 BT_LE_CS_TEST_OVERRIDE_3_REPETITIVE_TONE_EXT = BT_HCI_OP_LE_CS_TEST_TONE_EXT_REPEAT, 121 }; 122 123 /** CS Test Override 4 Tone Antenna Permutation. 124 * 125 * These values represent indices in an antenna path permutation table. 126 * 127 * Which table is applicable (and which indices are valid) 128 * depends on the maximum number of antenna paths (N_AP). 129 * 130 * If N_AP = 2, the permutation table is: 131 * 132 * +--------------------------------+------------------------------------------+ 133 * | Antenna Path Permutation Index | Antenna Path Positions After Permutation | 134 * +--------------------------------+------------------------------------------+ 135 * | 0 | A1 A2 | 136 * | 1 | A2 A1 | 137 * +--------------------------------+------------------------------------------+ 138 * 139 * If N_AP = 3, the permutation table is: 140 * 141 * +--------------------------------+------------------------------------------+ 142 * | Antenna Path Permutation Index | Antenna Path Positions After Permutation | 143 * +--------------------------------+------------------------------------------+ 144 * | 0 | A1 A2 A3 | 145 * | 1 | A2 A1 A3 | 146 * | 2 | A1 A3 A2 | 147 * | 3 | A3 A1 A2 | 148 * | 4 | A3 A2 A1 | 149 * | 5 | A2 A3 A1 | 150 * +--------------------------------+------------------------------------------+ 151 * 152 * If N_AP = 4, the permutation table is: 153 * 154 * +--------------------------------+------------------------------------------+ 155 * | Antenna Path Permutation Index | Antenna Path Positions After Permutation | 156 * +--------------------------------+------------------------------------------+ 157 * | 0 | A1 A2 A3 A4 | 158 * | 1 | A2 A1 A3 A4 | 159 * | 2 | A1 A3 A2 A4 | 160 * | 3 | A3 A1 A2 A4 | 161 * | 4 | A3 A2 A1 A4 | 162 * | 5 | A2 A3 A1 A4 | 163 * | 6 | A1 A2 A4 A3 | 164 * | 7 | A2 A1 A4 A3 | 165 * | 8 | A1 A4 A2 A3 | 166 * | 9 | A4 A1 A2 A3 | 167 * | 10 | A4 A2 A1 A3 | 168 * | 11 | A2 A4 A1 A3 | 169 * | 12 | A1 A4 A3 A2 | 170 * | 13 | A4 A1 A3 A2 | 171 * | 14 | A1 A3 A4 A2 | 172 * | 15 | A3 A1 A4 A2 | 173 * | 16 | A3 A4 A1 A2 | 174 * | 17 | A4 A3 A1 A2 | 175 * | 18 | A4 A2 A3 A1 | 176 * | 19 | A2 A4 A3 A1 | 177 * | 20 | A4 A3 A2 A1 | 178 * | 21 | A3 A4 A2 A1 | 179 * | 22 | A3 A2 A4 A1 | 180 * | 23 | A2 A3 A4 A1 | 181 * +--------------------------------+------------------------------------------+ 182 */ 183 enum bt_le_cs_test_override_4_tone_antenna_permutation { 184 BT_LE_CS_TEST_OVERRIDE_4_ANTENNA_PERMUTATION_INDEX_00 = BT_HCI_OP_LE_CS_TEST_AP_INDEX_00, 185 BT_LE_CS_TEST_OVERRIDE_4_ANTENNA_PERMUTATION_INDEX_01 = BT_HCI_OP_LE_CS_TEST_AP_INDEX_01, 186 BT_LE_CS_TEST_OVERRIDE_4_ANTENNA_PERMUTATION_INDEX_02 = BT_HCI_OP_LE_CS_TEST_AP_INDEX_02, 187 BT_LE_CS_TEST_OVERRIDE_4_ANTENNA_PERMUTATION_INDEX_03 = BT_HCI_OP_LE_CS_TEST_AP_INDEX_03, 188 BT_LE_CS_TEST_OVERRIDE_4_ANTENNA_PERMUTATION_INDEX_04 = BT_HCI_OP_LE_CS_TEST_AP_INDEX_04, 189 BT_LE_CS_TEST_OVERRIDE_4_ANTENNA_PERMUTATION_INDEX_05 = BT_HCI_OP_LE_CS_TEST_AP_INDEX_05, 190 BT_LE_CS_TEST_OVERRIDE_4_ANTENNA_PERMUTATION_INDEX_06 = BT_HCI_OP_LE_CS_TEST_AP_INDEX_06, 191 BT_LE_CS_TEST_OVERRIDE_4_ANTENNA_PERMUTATION_INDEX_07 = BT_HCI_OP_LE_CS_TEST_AP_INDEX_07, 192 BT_LE_CS_TEST_OVERRIDE_4_ANTENNA_PERMUTATION_INDEX_08 = BT_HCI_OP_LE_CS_TEST_AP_INDEX_08, 193 BT_LE_CS_TEST_OVERRIDE_4_ANTENNA_PERMUTATION_INDEX_09 = BT_HCI_OP_LE_CS_TEST_AP_INDEX_09, 194 BT_LE_CS_TEST_OVERRIDE_4_ANTENNA_PERMUTATION_INDEX_10 = BT_HCI_OP_LE_CS_TEST_AP_INDEX_10, 195 BT_LE_CS_TEST_OVERRIDE_4_ANTENNA_PERMUTATION_INDEX_11 = BT_HCI_OP_LE_CS_TEST_AP_INDEX_11, 196 BT_LE_CS_TEST_OVERRIDE_4_ANTENNA_PERMUTATION_INDEX_12 = BT_HCI_OP_LE_CS_TEST_AP_INDEX_12, 197 BT_LE_CS_TEST_OVERRIDE_4_ANTENNA_PERMUTATION_INDEX_13 = BT_HCI_OP_LE_CS_TEST_AP_INDEX_13, 198 BT_LE_CS_TEST_OVERRIDE_4_ANTENNA_PERMUTATION_INDEX_14 = BT_HCI_OP_LE_CS_TEST_AP_INDEX_14, 199 BT_LE_CS_TEST_OVERRIDE_4_ANTENNA_PERMUTATION_INDEX_15 = BT_HCI_OP_LE_CS_TEST_AP_INDEX_15, 200 BT_LE_CS_TEST_OVERRIDE_4_ANTENNA_PERMUTATION_INDEX_16 = BT_HCI_OP_LE_CS_TEST_AP_INDEX_16, 201 BT_LE_CS_TEST_OVERRIDE_4_ANTENNA_PERMUTATION_INDEX_17 = BT_HCI_OP_LE_CS_TEST_AP_INDEX_17, 202 BT_LE_CS_TEST_OVERRIDE_4_ANTENNA_PERMUTATION_INDEX_18 = BT_HCI_OP_LE_CS_TEST_AP_INDEX_18, 203 BT_LE_CS_TEST_OVERRIDE_4_ANTENNA_PERMUTATION_INDEX_19 = BT_HCI_OP_LE_CS_TEST_AP_INDEX_19, 204 BT_LE_CS_TEST_OVERRIDE_4_ANTENNA_PERMUTATION_INDEX_20 = BT_HCI_OP_LE_CS_TEST_AP_INDEX_20, 205 BT_LE_CS_TEST_OVERRIDE_4_ANTENNA_PERMUTATION_INDEX_21 = BT_HCI_OP_LE_CS_TEST_AP_INDEX_21, 206 BT_LE_CS_TEST_OVERRIDE_4_ANTENNA_PERMUTATION_INDEX_22 = BT_HCI_OP_LE_CS_TEST_AP_INDEX_22, 207 BT_LE_CS_TEST_OVERRIDE_4_ANTENNA_PERMUTATION_INDEX_23 = BT_HCI_OP_LE_CS_TEST_AP_INDEX_23, 208 /** Loop through all valid Antenna Permutation Indices starting 209 * from the lowest index. 210 */ 211 BT_LE_CS_TEST_OVERRIDE_4_ANTENNA_PERMUTATION_INDEX_LOOP = 212 BT_HCI_OP_LE_CS_TEST_AP_INDEX_LOOP, 213 }; 214 215 /** CS Test Override 7 Sounding Sequence Marker Value */ 216 enum bt_le_cs_test_override_7_ss_marker_value { 217 BT_LE_CS_TEST_OVERRIDE_7_SS_MARKER_VAL_0011 = BT_HCI_OP_LE_CS_TEST_SS_MARKER_VAL_0011, 218 BT_LE_CS_TEST_OVERRIDE_7_SS_MARKER_VAL_1100 = BT_HCI_OP_LE_CS_TEST_SS_MARKER_VAL_1100, 219 /** Loop through pattern '0011' and '1100' (in transmission order) */ 220 BT_LE_CS_TEST_OVERRIDE_7_SS_MARKER_VAL_LOOP = BT_HCI_OP_LE_CS_TEST_SS_MARKER_VAL_LOOP, 221 }; 222 223 /** CS Test Override 8 CS_SYNC Payload Pattern */ 224 enum bt_le_cs_test_override_8_cs_sync_payload_pattern { 225 /** PRBS9 payload sequence. */ 226 BT_LE_CS_TEST_OVERRIDE_8_PAYLOAD_PATTERN_PRBS9 = BT_HCI_OP_LE_CS_TEST_PAYLOAD_PRBS9, 227 /** Repeated '11110000' payload sequence. */ 228 BT_LE_CS_TEST_OVERRIDE_8_PAYLOAD_PATTERN_11110000 = BT_HCI_OP_LE_CS_TEST_PAYLOAD_11110000, 229 /** Repeated '10101010' payload sequence. */ 230 BT_LE_CS_TEST_OVERRIDE_8_PAYLOAD_PATTERN_10101010 = BT_HCI_OP_LE_CS_TEST_PAYLOAD_10101010, 231 /** PRBS15 payload sequence. */ 232 BT_LE_CS_TEST_OVERRIDE_8_PAYLOAD_PATTERN_PRBS15 = BT_HCI_OP_LE_CS_TEST_PAYLOAD_PRBS15, 233 /** Repeated '11111111' payload sequence. */ 234 BT_LE_CS_TEST_OVERRIDE_8_PAYLOAD_PATTERN_11111111 = BT_HCI_OP_LE_CS_TEST_PAYLOAD_11111111, 235 /** Repeated '00000000' payload sequence. */ 236 BT_LE_CS_TEST_OVERRIDE_8_PAYLOAD_PATTERN_00000000 = BT_HCI_OP_LE_CS_TEST_PAYLOAD_00000000, 237 /** Repeated '00001111' payload sequence. */ 238 BT_LE_CS_TEST_OVERRIDE_8_PAYLOAD_PATTERN_00001111 = BT_HCI_OP_LE_CS_TEST_PAYLOAD_00001111, 239 /** Repeated '01010101' payload sequence. */ 240 BT_LE_CS_TEST_OVERRIDE_8_PAYLOAD_PATTERN_01010101 = BT_HCI_OP_LE_CS_TEST_PAYLOAD_01010101, 241 /** Custom payload provided by the user. */ 242 BT_LE_CS_TEST_OVERRIDE_8_PAYLOAD_PATTERN_USER = BT_HCI_OP_LE_CS_TEST_PAYLOAD_USER, 243 }; 244 245 /** CS Test parameters */ 246 struct bt_le_cs_test_param { 247 /** CS mode to be used during the CS procedure. */ 248 enum bt_conn_le_cs_main_mode main_mode; 249 /** CS sub-mode to be used during the CS procedure. */ 250 enum bt_conn_le_cs_sub_mode sub_mode; 251 /** Number of main mode steps taken from the end of the last CS subevent 252 * to be repeated at the beginning of the current CS subevent directly 253 * after the last mode-0 step of that event. 254 */ 255 uint8_t main_mode_repetition; 256 /** Number of CS mode-0 steps at the beginning of the test CS subevent. */ 257 uint8_t mode_0_steps; 258 /** CS Test role */ 259 enum bt_conn_le_cs_role role; 260 /** RTT variant */ 261 enum bt_conn_le_cs_rtt_type rtt_type; 262 /** CS_SYNC PHY */ 263 enum bt_conn_le_cs_sync_phy cs_sync_phy; 264 /** Antenna identifier to be used for CS_SYNC packets. */ 265 enum bt_le_cs_test_cs_sync_antenna_selection cs_sync_antenna_selection; 266 /** CS subevent length in microseconds. 267 * 268 * Range: 1250us to 4s 269 */ 270 uint32_t subevent_len; 271 /** Gap between the start of two consecutive CS subevents (N * 0.625 ms) 272 * 273 * A value of 0 means that there is only one CS subevent. 274 */ 275 uint16_t subevent_interval; 276 /** Maximum allowed number of subevents in the procedure. 277 * 278 * A value of 0 means that this parameter is ignored. 279 */ 280 uint8_t max_num_subevents; 281 /** Desired TX power level for the CS procedure. 282 * 283 * Value range is @ref BT_HCI_OP_LE_CS_MIN_MAX_TX_POWER to 284 * @ref BT_HCI_OP_LE_CS_MAX_MAX_TX_POWER. 285 * 286 * Special values: 287 * - @ref BT_HCI_OP_LE_CS_TEST_MAXIMIZE_TX_POWER tells the controller 288 * it should use as high a transmit power as possible 289 * - @ref BT_HCI_OP_LE_CS_TEST_MINIMIZE_TX_POWER tells the controller 290 * it should use as low a transmit power as possible 291 */ 292 uint8_t transmit_power_level; 293 /** Interlude time in microseconds between the RTT packets. 294 * 295 * Valid options are: 296 * - 10 us 297 * - 20 us 298 * - 30 us 299 * - 40 us 300 * - 50 us 301 * - 60 us 302 * - 80 us 303 * - 145 us 304 */ 305 uint8_t t_ip1_time; 306 /** Interlude time in microseconds between the CS tones. 307 * 308 * Valid options are: 309 * - 10 us 310 * - 20 us 311 * - 30 us 312 * - 40 us 313 * - 50 us 314 * - 60 us 315 * - 80 us 316 * - 145 us 317 */ 318 uint8_t t_ip2_time; 319 /** Time in microseconds for frequency changes. 320 * 321 * Valid options are: 322 * - 15 us 323 * - 20 us 324 * - 30 us 325 * - 40 us 326 * - 50 us 327 * - 60 us 328 * - 80 us 329 * - 100 us 330 * - 120 us 331 * - 150 us 332 */ 333 uint8_t t_fcs_time; 334 /** Time in microseconds for the phase measurement period of the CS tones. 335 * 336 * Valid options are: 337 * - 10 us 338 * - 20 us 339 * - 40 us 340 */ 341 uint8_t t_pm_time; 342 /** Time in microseconds for the antenna switch period of the CS tones. 343 * 344 * Valid options are: 345 * - 0 us 346 * - 1 us 347 * - 2 us 348 * - 4 us 349 * - 10 us 350 */ 351 uint8_t t_sw_time; 352 /** Antenna Configuration Index used during antenna switching during 353 * the tone phases of CS steps. 354 */ 355 enum bt_conn_le_cs_tone_antenna_config_selection tone_antenna_config_selection; 356 /** Initiator SNR control options */ 357 enum bt_le_cs_snr_control initiator_snr_control; 358 /** Reflector SNR control options */ 359 enum bt_le_cs_snr_control reflector_snr_control; 360 /** Determines octets 14 and 15 of the initial value of the DRBG nonce. */ 361 uint16_t drbg_nonce; 362 363 /** Override configuration. 364 * 365 * This parameter is used to override CS parameters from the DRBG. 366 * Each bit configures a different set of parameters. 367 * 368 * All overrides are optional, except for those configured by bit 0. 369 * 370 * These are: 371 * - Bit 0 set: Override using list of channels 372 * - Bit 0 not set: Override using channel map 373 * - Bit 2 set: Override main mode steps 374 * - Bit 3 set: Override T_PM_Tone_Ext 375 * - Bit 4 set: Override tone antenna permutation 376 * - Bit 5 set: Override CS_SYNC AA 377 * - Bit 6 set: Override SS marker positions 378 * - Bit 7 set: Override SS marker value 379 * - Bit 8 set: Override CS_SYNC payload pattern and user payload 380 * - Bit 10 set: Procedure is replaced with a stable phase test 381 */ 382 uint16_t override_config; 383 384 /** override config bit 0. */ 385 struct { 386 /** Number of times the channels indicated by the channel map or channel field 387 * are cycled through for non-mode-0 steps within a CS procedure. 388 */ 389 uint8_t channel_map_repetition; 390 union { 391 struct { 392 uint8_t num_channels; 393 uint8_t *channels; 394 } set; 395 struct { 396 uint8_t channel_map[10]; 397 enum bt_conn_le_cs_chsel_type channel_selection_type; 398 enum bt_conn_le_cs_ch3c_shape ch3c_shape; 399 uint8_t ch3c_jump; 400 } not_set; 401 }; 402 } override_config_0; 403 404 /** Override config bit 2. These parameters are ignored if the bit is not set. */ 405 struct { 406 uint8_t main_mode_steps; 407 } override_config_2; 408 409 /** Override config bit 3. These parameters are ignored if the bit is not set. */ 410 struct { 411 enum bt_le_cs_test_override_3_pm_tone_ext t_pm_tone_ext; 412 } override_config_3; 413 414 /** Override config bit 4. These parameters are ignored if the bit is not set. */ 415 struct { 416 enum bt_le_cs_test_override_4_tone_antenna_permutation tone_antenna_permutation; 417 } override_config_4; 418 419 /** Override config bit 5. These parameters are ignored if the bit is not set. */ 420 struct { 421 /** Access Address used in CS_SYNC packets sent by the initiator. */ 422 uint32_t cs_sync_aa_initiator; 423 /** Access Address used in CS_SYNC packets sent by the reflector. */ 424 uint32_t cs_sync_aa_reflector; 425 } override_config_5; 426 427 /** Override config bit 6. These parameters are ignored if the bit is not set. */ 428 struct { 429 /** Bit number where the first marker in the channel sounding sequence starts. 430 * 431 * Must be between 0 and 28 when using @ref BT_CONN_LE_CS_RTT_TYPE_32_BIT_SOUNDING. 432 */ 433 uint8_t ss_marker1_position; 434 /** Bit number where the second marker in the channel sounding sequence starts. 435 * 436 * Must be between 67 and 92 when using @ref 437 * BT_CONN_LE_CS_RTT_TYPE_96_BIT_SOUNDING. 438 * 439 * A value of @ref BT_HCI_OP_LE_CS_TEST_SS_MARKER_2_POSITION_NOT_PRESENT 440 * indicates that this sounding sequence or marker is not present. 441 */ 442 uint8_t ss_marker2_position; 443 } override_config_6; 444 445 /** Override config bit 7. These parameters are ignored if the bit is not set. */ 446 struct { 447 /** Value of the Sounding Sequence marker. */ 448 enum bt_le_cs_test_override_7_ss_marker_value ss_marker_value; 449 } override_config_7; 450 451 /** Override config bit 8. These parameters are ignored if the bit is not set. */ 452 struct { 453 /** CS_SYNC payload pattern selection. */ 454 enum bt_le_cs_test_override_8_cs_sync_payload_pattern cs_sync_payload_pattern; 455 /** User payload for CS_SYNC packets. 456 * 457 * This parameter is only used when using 458 * @ref BT_LE_CS_TEST_OVERRIDE_8_PAYLOAD_PATTERN_USER 459 * 460 * The least significant bit corresponds to the most significant bit 461 * of the CS payload. When the sequence is less than 16 octets, 462 * the least significant octets shall be padded with zeros. 463 */ 464 uint8_t cs_sync_user_payload[16]; 465 } override_config_8; 466 }; 467 468 /** CS config creation context */ 469 enum bt_le_cs_create_config_context { 470 /** Write CS configuration in local Controller only */ 471 BT_LE_CS_CREATE_CONFIG_CONTEXT_LOCAL_ONLY, 472 /** Write CS configuration in both local and remote Controller using Channel Sounding 473 * Configuration procedure 474 */ 475 BT_LE_CS_CREATE_CONFIG_CONTEXT_LOCAL_AND_REMOTE 476 }; 477 478 /** CS Create Config params */ 479 struct bt_le_cs_create_config_params { 480 /** CS configuration ID */ 481 uint8_t id; 482 /** Main CS mode type */ 483 enum bt_conn_le_cs_main_mode main_mode_type; 484 /** Sub CS mode type */ 485 enum bt_conn_le_cs_sub_mode sub_mode_type; 486 /** Minimum number of CS main mode steps to be executed before a submode step is executed */ 487 uint8_t min_main_mode_steps; 488 /** Maximum number of CS main mode steps to be executed before a submode step is executed */ 489 uint8_t max_main_mode_steps; 490 /** Number of main mode steps taken from the end of the last CS subevent to be repeated 491 * at the beginning of the current CS subevent directly after the last mode-0 step of that 492 * event 493 */ 494 uint8_t main_mode_repetition; 495 /** Number of CS mode-0 steps to be included at the beginning of each CS subevent */ 496 uint8_t mode_0_steps; 497 /** CS role */ 498 enum bt_conn_le_cs_role role; 499 /** RTT type */ 500 enum bt_conn_le_cs_rtt_type rtt_type; 501 /** CS Sync PHY */ 502 enum bt_conn_le_cs_sync_phy cs_sync_phy; 503 /** The number of times the Channel_Map field will be cycled through for non-mode-0 steps 504 * within a CS procedure 505 */ 506 uint8_t channel_map_repetition; 507 /** Channel selection type */ 508 enum bt_conn_le_cs_chsel_type channel_selection_type; 509 /** User-specified channel sequence shape */ 510 enum bt_conn_le_cs_ch3c_shape ch3c_shape; 511 /** Number of channels skipped in each rising and falling sequence */ 512 uint8_t ch3c_jump; 513 /** Channel map used for CS procedure 514 * Channels n = 0, 1, 23, 24, 25, 77, and 78 are not allowed and shall be set to zero. 515 * Channel 79 is reserved for future use and shall be set to zero. 516 * At least 15 channels shall be enabled. 517 */ 518 uint8_t channel_map[10]; 519 }; 520 521 /** Callbacks for CS Test */ 522 struct bt_le_cs_test_cb { 523 /**@brief CS Test Subevent data. 524 * 525 * @param[in] Subevent results. 526 */ 527 void (*le_cs_test_subevent_data_available)(struct bt_conn_le_cs_subevent_result *data); 528 /**@brief CS Test End Complete. */ 529 void (*le_cs_test_end_complete)(void); 530 }; 531 532 /** Subevent result step */ 533 struct bt_le_cs_subevent_step { 534 /** CS step mode. */ 535 uint8_t mode; 536 /** CS step channel index. */ 537 uint8_t channel; 538 /** Length of role- and mode-specific information being reported. */ 539 uint8_t data_len; 540 /** Pointer to role- and mode-specific information. */ 541 const uint8_t *data; 542 }; 543 544 /** Sign-extended IQ value extracted from step data. */ 545 struct bt_le_cs_iq_sample { 546 int16_t i; 547 int16_t q; 548 }; 549 550 /** @brief Extract in-phase and quadrature terms from HCI-formatted PCT. 551 * 552 * Convenience function for processing 24-bit phase correction terms found 553 * in CS step data. The 12-bit signed real and imaginary components are 554 * converted to host endianness and sign-extended. 555 * 556 * @param pct 24-bit little-endian phase correction term. 557 * 558 * @return struct bt_le_cs_iq_sample containing real and imaginary terms as int16_t 559 */ 560 struct bt_le_cs_iq_sample bt_le_cs_parse_pct(const uint8_t pct[3]); 561 562 /** @brief Set all valid channel map bits 563 * 564 * This command is used to enable all valid channels in a 565 * given CS channel map 566 * 567 * @param channel_map Chanel map 568 */ 569 void bt_le_cs_set_valid_chmap_bits(uint8_t channel_map[10]); 570 571 /** @brief Read Remote Supported Capabilities 572 * 573 * This command is used to query the CS capabilities that are supported 574 * by the remote controller. 575 * 576 * @note To use this API @kconfig{CONFIG_BT_CHANNEL_SOUNDING} must be set. 577 * 578 * @param conn Connection Object. 579 * 580 * @return Zero on success or (negative) error code on failure. 581 */ 582 int bt_le_cs_read_remote_supported_capabilities(struct bt_conn *conn); 583 584 /** @brief Set Channel Sounding default settings. 585 * 586 * This command is used to set default Channel Sounding settings for this 587 * connection. 588 * 589 * @note To use this API @kconfig{CONFIG_BT_CHANNEL_SOUNDING} must be set. 590 * 591 * @param conn Connection Object. 592 * @param params Channel sounding default settings parameters. 593 * 594 * @return Zero on success or (negative) error code on failure. 595 */ 596 int bt_le_cs_set_default_settings(struct bt_conn *conn, 597 const struct bt_le_cs_set_default_settings_param *params); 598 599 /** @brief Read Remote FAE Table 600 * 601 * This command is used to read the per-channel mode-0 Frequency Actuation Error 602 * table of the remote Controller. 603 * 604 * @note To use this API @kconfig{CONFIG_BT_CHANNEL_SOUNDING} must be set. 605 * 606 * @param conn Connection Object. 607 * 608 * @return Zero on success or (negative) error code on failure. 609 */ 610 int bt_le_cs_read_remote_fae_table(struct bt_conn *conn); 611 612 /** @brief Register callbacks for the CS Test mode. 613 * 614 * Existing callbacks can be unregistered by providing NULL function 615 * pointers. 616 * 617 * @note To use this API @kconfig{CONFIG_BT_CHANNEL_SOUNDING_TEST} must be set. 618 * 619 * @param cs_test_cb Set of callbacks to be used with CS Test 620 * 621 * @return Zero on success or (negative) error code on failure. 622 */ 623 int bt_le_cs_test_cb_register(struct bt_le_cs_test_cb cs_test_cb); 624 625 /** @brief Start a CS test 626 * 627 * This command is used to start a CS test where the IUT is placed in the role 628 * of either the initiator or reflector. 629 * 630 * The first mode-0 channel in the list is used as the starting channel for 631 * the test. At the beginning of any test, the IUT in the reflector role shall 632 * listen on the first mode-0 channel until it receives the first transmission 633 * from the initiator. Similarly, with the IUT in the initiator role, the tester 634 * will start by listening on the first mode-0 channel and the IUT shall transmit 635 * on that channel for the first half of the first CS step. Thereafter, the 636 * parameters of this command describe the required transmit and receive behavior 637 * for the CS test. 638 * 639 * @note To use this API @kconfig{CONFIG_BT_CHANNEL_SOUNDING_TEST} must be set. 640 * 641 * @param params CS Test parameters 642 * 643 * @return Zero on success or (negative) error code on failure. 644 */ 645 int bt_le_cs_start_test(const struct bt_le_cs_test_param *params); 646 647 /** @brief Create CS configuration 648 * 649 * This command is used to create a new CS configuration or update an 650 * existing one with the config id specified. 651 * 652 * @note To use this API @kconfig{CONFIG_BT_CHANNEL_SOUNDING} must be set. 653 * 654 * @param conn Connection Object. 655 * @param params CS Create Config parameters 656 * @param context Controls whether the configuration is written to the local controller or 657 * both the local and the remote controller 658 * 659 * @return Zero on success or (negative) error code on failure. 660 */ 661 int bt_le_cs_create_config(struct bt_conn *conn, struct bt_le_cs_create_config_params *params, 662 enum bt_le_cs_create_config_context context); 663 664 /** @brief Create CS configuration 665 * 666 * This command is used to remove a CS configuration from the local controller 667 * identified by the config_id 668 * 669 * @note To use this API @kconfig{CONFIG_BT_CHANNEL_SOUNDING} must be set. 670 * 671 * @param conn Connection Object. 672 * @param config_id CS Config ID 673 * 674 * @return Zero on success or (negative) error code on failure. 675 */ 676 int bt_le_cs_remove_config(struct bt_conn *conn, uint8_t config_id); 677 678 /** @brief Stop ongoing CS Test 679 * 680 * This command is used to stop any CS test that is in progress. 681 * 682 * The controller is expected to finish reporting any subevent results 683 * before completing this termination. 684 * 685 * @note To use this API @kconfig{CONFIG_BT_CHANNEL_SOUNDING_TEST} must be set. 686 * 687 * @return Zero on success or (negative) error code on failure. 688 */ 689 int bt_le_cs_stop_test(void); 690 691 /** @brief Parse CS Subevent Step Data 692 * 693 * A helper for parsing HCI-formatted step data found in channel sounding subevent results. 694 * 695 * A typical use-case is filtering out data which does not meet certain packet quality or NADM 696 * requirements. 697 * 698 * @warning This function will consume the data when parsing. 699 * 700 * @param step_data_buf Pointer to a buffer containing the step data. 701 * @param func Callback function which will be called for each step data found. 702 * The callback should return true to continue parsing, or false to stop. 703 * @param user_data User data to be passed to the callback. 704 */ 705 void bt_le_cs_step_data_parse(struct net_buf_simple *step_data_buf, 706 bool (*func)(struct bt_le_cs_subevent_step *step, void *user_data), 707 void *user_data); 708 709 /** @brief CS Security Enable 710 * 711 * This command is used to start or restart the Channel Sounding Security 712 * Start procedure in the local Controller for the ACL connection identified 713 * in the conn parameter. 714 * 715 * @note To use this API @kconfig{CONFIG_BT_CHANNEL_SOUNDING} must be set. 716 * 717 * @param conn Connection Object. 718 * 719 * @return Zero on success or (negative) error code on failure. 720 */ 721 int bt_le_cs_security_enable(struct bt_conn *conn); 722 723 struct bt_le_cs_procedure_enable_param { 724 uint8_t config_id; 725 enum bt_conn_le_cs_procedure_enable_state enable; 726 }; 727 728 /** @brief CS Procedure Enable 729 * 730 * This command is used to enable or disable the scheduling of CS procedures 731 * by the local Controller, with the remote device identified in the conn 732 * parameter. 733 * 734 * @note To use this API @kconfig{CONFIG_BT_CHANNEL_SOUNDING} must be set. 735 * 736 * @param conn Connection Object. 737 * @param params Parameters for the CS Procedure Enable command. 738 * 739 * @return Zero on success or (negative) error code on failure. 740 */ 741 int bt_le_cs_procedure_enable(struct bt_conn *conn, 742 const struct bt_le_cs_procedure_enable_param *params); 743 744 enum bt_le_cs_procedure_phy { 745 BT_LE_CS_PROCEDURE_PHY_1M = BT_HCI_OP_LE_CS_PROCEDURE_PHY_1M, 746 BT_LE_CS_PROCEDURE_PHY_2M = BT_HCI_OP_LE_CS_PROCEDURE_PHY_2M, 747 BT_LE_CS_PROCEDURE_PHY_CODED_S8 = BT_HCI_OP_LE_CS_PROCEDURE_PHY_CODED_S8, 748 BT_LE_CS_PROCEDURE_PHY_CODED_S2 = BT_HCI_OP_LE_CS_PROCEDURE_PHY_CODED_S2, 749 }; 750 751 #define BT_LE_CS_PROCEDURE_PREFERRED_PEER_ANTENNA_1 BIT(0) 752 #define BT_LE_CS_PROCEDURE_PREFERRED_PEER_ANTENNA_2 BIT(1) 753 #define BT_LE_CS_PROCEDURE_PREFERRED_PEER_ANTENNA_3 BIT(2) 754 #define BT_LE_CS_PROCEDURE_PREFERRED_PEER_ANTENNA_4 BIT(3) 755 756 struct bt_le_cs_set_procedure_parameters_param { 757 /* The ID associated with the desired configuration (0 to 3) */ 758 uint8_t config_id; 759 760 /* Max. duration for each CS procedure, where T = N * 0.625 ms (0x0001 to 0xFFFF) */ 761 uint16_t max_procedure_len; 762 763 /* Min. number of connection events between consecutive CS procedures (0x0001 to 0xFFFF) */ 764 uint16_t min_procedure_interval; 765 766 /* Max. number of connection events between consecutive CS procedures (0x0001 to 0xFFFF) */ 767 uint16_t max_procedure_interval; 768 769 /* Max. number of procedures to be scheduled (0x0000 for no limit; otherwise 0x0001 770 * to 0xFFFF) 771 */ 772 uint16_t max_procedure_count; 773 774 /* Min. suggested duration for each CS subevent in microseconds (1250 us to 4 s) */ 775 uint32_t min_subevent_len; 776 777 /* Max. suggested duration for each CS subevent in microseconds (1250 us to 4 s) */ 778 uint32_t max_subevent_len; 779 780 /* Antenna configuration index */ 781 enum bt_conn_le_cs_tone_antenna_config_selection tone_antenna_config_selection; 782 783 /* Phy */ 784 enum bt_le_cs_procedure_phy phy; 785 786 /* Transmit power delta, in signed dB, to indicate the recommended difference between the 787 * remote device's power level for the CS tones and RTT packets and the existing power 788 * level for the Phy indicated by the Phy parameter (0x80 for no recommendation) 789 */ 790 int8_t tx_power_delta; 791 792 /* Preferred peer antenna (Bitmask of BT_LE_CS_PROCEDURE_PREFERRED_PEER_ANTENNA_*) */ 793 uint8_t preferred_peer_antenna; 794 795 /* Initiator SNR control adjustment */ 796 enum bt_le_cs_snr_control snr_control_initiator; 797 798 /* Reflector SNR control adjustment */ 799 enum bt_le_cs_snr_control snr_control_reflector; 800 }; 801 802 /** @brief CS Set Procedure Parameters 803 * 804 * This command is used to set the parameters for the scheduling of one 805 * or more CS procedures by the local controller. 806 * 807 * @note To use this API @kconfig{CONFIG_BT_CHANNEL_SOUNDING} must be set. 808 * 809 * @param conn Connection Object. 810 * @param params Parameters for the CS Set Procedure Parameters command. 811 * 812 * @return Zero on success or (negative) error code on failure. 813 */ 814 int bt_le_cs_set_procedure_parameters(struct bt_conn *conn, 815 const struct bt_le_cs_set_procedure_parameters_param *params); 816 817 /** @brief CS Set Channel Classification 818 * 819 * This command is used to update the channel classification based on 820 * its local information. 821 * 822 * The nth bitfield (in the range 0 to 78) contains the value for the CS 823 * channel index n. Channel Enabled = 1; Channel Disabled = 0. 824 * 825 * Channels n = 0, 1, 23, 24, 25, 77, and 78 shall be reserved for future 826 * use and shall be set to zero. At least 15 channels shall be enabled. 827 * 828 * The most significant bit (bit 79) is reserved for future use. 829 * 830 * @note To use this API, @kconfig{CONFIG_BT_CHANNEL_SOUNDING} must be set. 831 * 832 * @param channel_classification Bit fields 833 * 834 * @return Zero on success or (negative) error code on failure. 835 */ 836 int bt_le_cs_set_channel_classification(uint8_t channel_classification[10]); 837 838 /** @brief CS Read Local Supported Capabilities 839 * 840 * This command is used to read the CS capabilities that are supported 841 * by the local Controller. 842 * 843 * @note To use this API @kconfig{CONFIG_BT_CHANNEL_SOUNDING} must be set. 844 * 845 * @param ret Return values for the CS Procedure Enable command. 846 * 847 * @return Zero on success or (negative) error code on failure. 848 */ 849 int bt_le_cs_read_local_supported_capabilities(struct bt_conn_le_cs_capabilities *ret); 850 851 /** @brief CS Write Cached Remote Supported Capabilities 852 * 853 * This command is used to write the cached copy of the CS capabilities 854 * that are supported by the remote Controller for the connection 855 * identified. 856 * 857 * @note To use this API @kconfig{CONFIG_BT_CHANNEL_SOUNDING} must be set. 858 * 859 * @param conn Connection Object. 860 * @param params Parameters for the CS Write Cached Remote Supported Capabilities command. 861 * 862 * @return Zero on success or (negative) error code on failure. 863 */ 864 int bt_le_cs_write_cached_remote_supported_capabilities( 865 struct bt_conn *conn, const struct bt_conn_le_cs_capabilities *params); 866 867 /** @brief CS Write Cached Remote FAE Table 868 * 869 * This command is used to write a cached copy of the per-channel mode-0 870 * Frequency Actuation Error table of the remote device in the local Controller. 871 * 872 * @note To use this API @kconfig{CONFIG_BT_CHANNEL_SOUNDING} must be set. 873 * 874 * @param conn Connection Object. 875 * @param remote_fae_table Per-channel mode-0 FAE table of the local Controller 876 * 877 * @return Zero on success or (negative) error code on failure. 878 */ 879 int bt_le_cs_write_cached_remote_fae_table(struct bt_conn *conn, int8_t remote_fae_table[72]); 880 881 #ifdef __cplusplus 882 } 883 #endif 884 885 /** 886 * @} 887 */ 888 889 #endif /* ZEPHYR_INCLUDE_BLUETOOTH_CS_H_ */ 890
