Line data Source code
1 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 1 : #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 1 : #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 0 : 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 1 : struct bt_le_cs_set_default_settings_param {
67 : /** Enable CS initiator role. */
68 1 : bool enable_initiator_role;
69 : /** Enable CS reflector role. */
70 1 : bool enable_reflector_role;
71 : /** Antenna identifier to be used for CS_SYNC packets by the local controller.
72 : */
73 1 : 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 1 : int8_t max_tx_power;
81 : };
82 :
83 : /** CS Test CS_SYNC Antenna Identifier */
84 0 : 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 0 : 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 1 : 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 0 : 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 0 : 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 1 : 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 1 : struct bt_le_cs_test_param {
247 : /** CS mode to be used during the CS procedure. */
248 1 : enum bt_conn_le_cs_main_mode main_mode;
249 : /** CS sub-mode to be used during the CS procedure. */
250 1 : 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 1 : uint8_t main_mode_repetition;
256 : /** Number of CS mode-0 steps at the beginning of the test CS subevent. */
257 1 : uint8_t mode_0_steps;
258 : /** CS Test role */
259 1 : enum bt_conn_le_cs_role role;
260 : /** RTT variant */
261 1 : enum bt_conn_le_cs_rtt_type rtt_type;
262 : /** CS_SYNC PHY */
263 1 : enum bt_conn_le_cs_sync_phy cs_sync_phy;
264 : /** Antenna identifier to be used for CS_SYNC packets. */
265 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : uint8_t t_sw_time;
352 : /** Antenna Configuration Index used during antenna switching during
353 : * the tone phases of CS steps.
354 : */
355 1 : enum bt_conn_le_cs_tone_antenna_config_selection tone_antenna_config_selection;
356 : /** Initiator SNR control options */
357 1 : enum bt_le_cs_snr_control initiator_snr_control;
358 : /** Reflector SNR control options */
359 1 : enum bt_le_cs_snr_control reflector_snr_control;
360 : /** Determines octets 14 and 15 of the initial value of the DRBG nonce. */
361 1 : 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 1 : 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 1 : uint8_t channel_map_repetition;
390 : union {
391 : struct {
392 0 : uint8_t num_channels;
393 0 : uint8_t *channels;
394 0 : } set;
395 : struct {
396 0 : uint8_t channel_map[10];
397 0 : enum bt_conn_le_cs_chsel_type channel_selection_type;
398 0 : enum bt_conn_le_cs_ch3c_shape ch3c_shape;
399 0 : uint8_t ch3c_jump;
400 0 : } not_set;
401 : };
402 1 : } override_config_0;
403 :
404 : /** Override config bit 2. These parameters are ignored if the bit is not set. */
405 : struct {
406 0 : uint8_t main_mode_steps;
407 1 : } override_config_2;
408 :
409 : /** Override config bit 3. These parameters are ignored if the bit is not set. */
410 : struct {
411 0 : enum bt_le_cs_test_override_3_pm_tone_ext t_pm_tone_ext;
412 1 : } override_config_3;
413 :
414 : /** Override config bit 4. These parameters are ignored if the bit is not set. */
415 : struct {
416 0 : enum bt_le_cs_test_override_4_tone_antenna_permutation tone_antenna_permutation;
417 1 : } 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 1 : uint32_t cs_sync_aa_initiator;
423 : /** Access Address used in CS_SYNC packets sent by the reflector. */
424 1 : uint32_t cs_sync_aa_reflector;
425 1 : } 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 1 : 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 1 : uint8_t ss_marker2_position;
443 1 : } 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 1 : enum bt_le_cs_test_override_7_ss_marker_value ss_marker_value;
449 1 : } 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 1 : 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 1 : uint8_t cs_sync_user_payload[16];
465 1 : } override_config_8;
466 : };
467 :
468 : /** CS config creation context */
469 1 : 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 1 : struct bt_le_cs_create_config_params {
480 : /** CS configuration ID */
481 1 : uint8_t id;
482 : /** Main CS mode type */
483 1 : enum bt_conn_le_cs_main_mode main_mode_type;
484 : /** Sub CS mode type */
485 1 : 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 1 : uint8_t min_main_mode_steps;
488 : /** Maximum number of CS main mode steps to be executed before a submode step is executed */
489 1 : 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 1 : uint8_t main_mode_repetition;
495 : /** Number of CS mode-0 steps to be included at the beginning of each CS subevent */
496 1 : uint8_t mode_0_steps;
497 : /** CS role */
498 1 : enum bt_conn_le_cs_role role;
499 : /** RTT type */
500 1 : enum bt_conn_le_cs_rtt_type rtt_type;
501 : /** CS Sync PHY */
502 1 : 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 1 : uint8_t channel_map_repetition;
507 : /** Channel selection type */
508 1 : enum bt_conn_le_cs_chsel_type channel_selection_type;
509 : /** User-specified channel sequence shape */
510 1 : enum bt_conn_le_cs_ch3c_shape ch3c_shape;
511 : /** Number of channels skipped in each rising and falling sequence */
512 1 : 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 1 : uint8_t channel_map[10];
519 : };
520 :
521 : /** Callbacks for CS Test */
522 1 : struct bt_le_cs_test_cb {
523 : /**@brief CS Test Subevent data.
524 : *
525 : * @param[in] Subevent results.
526 : */
527 1 : void (*le_cs_test_subevent_data_available)(struct bt_conn_le_cs_subevent_result *data);
528 : /**@brief CS Test End Complete. */
529 1 : void (*le_cs_test_end_complete)(void);
530 : };
531 :
532 : /** Subevent result step */
533 1 : struct bt_le_cs_subevent_step {
534 : /** CS step mode. */
535 1 : uint8_t mode;
536 : /** CS step channel index. */
537 1 : uint8_t channel;
538 : /** Length of role- and mode-specific information being reported. */
539 1 : uint8_t data_len;
540 : /** Pointer to role- and mode-specific information. */
541 1 : const uint8_t *data;
542 : };
543 :
544 : /** Sign-extended IQ value extracted from step data. */
545 1 : struct bt_le_cs_iq_sample {
546 0 : int16_t i;
547 0 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : int bt_le_cs_security_enable(struct bt_conn *conn);
722 :
723 0 : struct bt_le_cs_procedure_enable_param {
724 0 : uint8_t config_id;
725 0 : 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 1 : int bt_le_cs_procedure_enable(struct bt_conn *conn,
742 : const struct bt_le_cs_procedure_enable_param *params);
743 :
744 0 : 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 0 : #define BT_LE_CS_PROCEDURE_PREFERRED_PEER_ANTENNA_1 BIT(0)
752 0 : #define BT_LE_CS_PROCEDURE_PREFERRED_PEER_ANTENNA_2 BIT(1)
753 0 : #define BT_LE_CS_PROCEDURE_PREFERRED_PEER_ANTENNA_3 BIT(2)
754 0 : #define BT_LE_CS_PROCEDURE_PREFERRED_PEER_ANTENNA_4 BIT(3)
755 :
756 0 : struct bt_le_cs_set_procedure_parameters_param {
757 : /* The ID associated with the desired configuration (0 to 3) */
758 0 : uint8_t config_id;
759 :
760 : /* Max. duration for each CS procedure, where T = N * 0.625 ms (0x0001 to 0xFFFF) */
761 0 : uint16_t max_procedure_len;
762 :
763 : /* Min. number of connection events between consecutive CS procedures (0x0001 to 0xFFFF) */
764 0 : uint16_t min_procedure_interval;
765 :
766 : /* Max. number of connection events between consecutive CS procedures (0x0001 to 0xFFFF) */
767 0 : 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 0 : uint16_t max_procedure_count;
773 :
774 : /* Min. suggested duration for each CS subevent in microseconds (1250 us to 4 s) */
775 0 : uint32_t min_subevent_len;
776 :
777 : /* Max. suggested duration for each CS subevent in microseconds (1250 us to 4 s) */
778 0 : uint32_t max_subevent_len;
779 :
780 : /* Antenna configuration index */
781 0 : enum bt_conn_le_cs_tone_antenna_config_selection tone_antenna_config_selection;
782 :
783 : /* Phy */
784 0 : 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 0 : int8_t tx_power_delta;
791 :
792 : /* Preferred peer antenna (Bitmask of BT_LE_CS_PROCEDURE_PREFERRED_PEER_ANTENNA_*) */
793 0 : uint8_t preferred_peer_antenna;
794 :
795 : /* Initiator SNR control adjustment */
796 0 : enum bt_le_cs_snr_control snr_control_initiator;
797 :
798 : /* Reflector SNR control adjustment */
799 0 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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_ */
|
