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 : #include <zephyr/net_buf.h>
26 : #include <zephyr/sys/util_macro.h>
27 :
28 : #ifdef __cplusplus
29 : extern "C" {
30 : #endif
31 :
32 : /**
33 : * @brief Macro for getting a specific channel bit in CS channel map
34 : *
35 : * @param[in] chmap Channel map array
36 : * @param[in] bit Bit number to be accessed
37 : *
38 : * @return Bit value, either 1 or 0
39 : */
40 1 : #define BT_LE_CS_CHANNEL_BIT_GET(chmap, bit) (((chmap)[(bit) / 8] >> ((bit) % 8)) & 1)
41 :
42 : /**
43 : * @brief Macro for setting a specific channel bit value in CS channel map
44 : *
45 : * @param[in] chmap Channel map array
46 : * @param[in] bit Bit number to be accessed
47 : * @param[in] val Bit value to be set, either 1 or 0
48 : */
49 1 : #define BT_LE_CS_CHANNEL_BIT_SET_VAL(chmap, bit, val) \
50 : ((chmap)[(bit) / 8] = ((chmap)[(bit) / 8] & ~BIT((bit) % 8)) | ((val) << ((bit) % 8)))
51 :
52 0 : enum bt_le_cs_sync_antenna_selection_opt {
53 : /** Use antenna identifier 1 for CS_SYNC packets. */
54 : BT_LE_CS_ANTENNA_SELECTION_OPT_ONE = BT_HCI_OP_LE_CS_ANTENNA_SEL_ONE,
55 : /** Use antenna identifier 2 for CS_SYNC packets. */
56 : BT_LE_CS_ANTENNA_SELECTION_OPT_TWO = BT_HCI_OP_LE_CS_ANTENNA_SEL_TWO,
57 : /** Use antenna identifier 3 for CS_SYNC packets. */
58 : BT_LE_CS_ANTENNA_SELECTION_OPT_THREE = BT_HCI_OP_LE_CS_ANTENNA_SEL_THREE,
59 : /** Use antenna identifier 4 for CS_SYNC packets. */
60 : BT_LE_CS_ANTENNA_SELECTION_OPT_FOUR = BT_HCI_OP_LE_CS_ANTENNA_SEL_FOUR,
61 : /** Use antennas in repetitive order from 1 to 4 for CS_SYNC packets. */
62 : BT_LE_CS_ANTENNA_SELECTION_OPT_REPETITIVE = BT_HCI_OP_LE_CS_ANTENNA_SEL_REP,
63 : /** No recommendation for local controller antenna selection. */
64 : BT_LE_CS_ANTENNA_SELECTION_OPT_NO_RECOMMENDATION = BT_HCI_OP_LE_CS_ANTENNA_SEL_NONE,
65 : };
66 :
67 : /** Default CS settings in the local Controller */
68 1 : struct bt_le_cs_set_default_settings_param {
69 : /** Enable CS initiator role. */
70 1 : bool enable_initiator_role;
71 : /** Enable CS reflector role. */
72 1 : bool enable_reflector_role;
73 : /** Antenna identifier to be used for CS_SYNC packets by the local controller.
74 : */
75 1 : enum bt_le_cs_sync_antenna_selection_opt cs_sync_antenna_selection;
76 : /** Maximum output power (Effective Isotropic Radiated Power) to be used
77 : * for all CS transmissions.
78 : *
79 : * Value range is @ref BT_HCI_OP_LE_CS_MIN_MAX_TX_POWER to
80 : * @ref BT_HCI_OP_LE_CS_MAX_MAX_TX_POWER.
81 : */
82 1 : int8_t max_tx_power;
83 : };
84 :
85 : /** CS Test CS_SYNC Antenna Identifier */
86 0 : enum bt_le_cs_test_cs_sync_antenna_selection {
87 : BT_LE_CS_TEST_CS_SYNC_ANTENNA_SELECTION_ONE = BT_HCI_OP_LE_CS_ANTENNA_SEL_ONE,
88 : BT_LE_CS_TEST_CS_SYNC_ANTENNA_SELECTION_TWO = BT_HCI_OP_LE_CS_ANTENNA_SEL_TWO,
89 : BT_LE_CS_TEST_CS_SYNC_ANTENNA_SELECTION_THREE = BT_HCI_OP_LE_CS_ANTENNA_SEL_THREE,
90 : BT_LE_CS_TEST_CS_SYNC_ANTENNA_SELECTION_FOUR = BT_HCI_OP_LE_CS_ANTENNA_SEL_FOUR,
91 : };
92 :
93 : /** CS SNR control options */
94 0 : enum bt_le_cs_snr_control {
95 : BT_LE_CS_SNR_CONTROL_18dB = BT_HCI_OP_LE_CS_SNR_18,
96 : BT_LE_CS_SNR_CONTROL_21dB = BT_HCI_OP_LE_CS_SNR_21,
97 : BT_LE_CS_SNR_CONTROL_24dB = BT_HCI_OP_LE_CS_SNR_24,
98 : BT_LE_CS_SNR_CONTROL_27dB = BT_HCI_OP_LE_CS_SNR_27,
99 : BT_LE_CS_SNR_CONTROL_30dB = BT_HCI_OP_LE_CS_SNR_30,
100 : BT_LE_CS_SNR_CONTROL_NOT_USED = BT_HCI_OP_LE_CS_SNR_NOT_USED,
101 : };
102 :
103 : /** CS Test Override 3 T_PM Tone Extension */
104 1 : enum bt_le_cs_test_override_3_pm_tone_ext {
105 : /** Initiator and reflector tones sent without tone extension */
106 : BT_LE_CS_TEST_OVERRIDE_3_NO_TONE_EXT = BT_HCI_OP_LE_CS_TEST_TONE_EXT_NONE,
107 : /** Initiator tone sent with extension, reflector tone sent without tone extension */
108 : BT_LE_CS_TEST_OVERRIDE_3_INITIATOR_TONE_EXT_ONLY = BT_HCI_OP_LE_CS_TEST_TONE_EXT_INIT,
109 : /** Initiator tone sent without extension, reflector tone sent with tone extension */
110 : BT_LE_CS_TEST_OVERRIDE_3_REFLECTOR_TONE_EXT_ONLY = BT_HCI_OP_LE_CS_TEST_TONE_EXT_REFL,
111 : /** Initiator and reflector tones sent with tone extension */
112 : BT_LE_CS_TEST_OVERRIDE_3_INITIATOR_AND_REFLECTOR_TONE_EXT =
113 : BT_HCI_OP_LE_CS_TEST_TONE_EXT_BOTH,
114 : /** Applicable for mode-2 and mode-3 only:
115 : *
116 : * Loop through:
117 : * - @ref BT_LE_CS_TEST_OVERRIDE_3_NO_TONE_EXT
118 : * - @ref BT_LE_CS_TEST_OVERRIDE_3_INITIATOR_TONE_EXT_ONLY
119 : * - @ref BT_LE_CS_TEST_OVERRIDE_3_REFLECTOR_TONE_EXT_ONLY
120 : * - @ref BT_LE_CS_TEST_OVERRIDE_3_INITIATOR_AND_REFLECTOR_TONE_EXT
121 : */
122 : BT_LE_CS_TEST_OVERRIDE_3_REPETITIVE_TONE_EXT = BT_HCI_OP_LE_CS_TEST_TONE_EXT_REPEAT,
123 : };
124 :
125 : /** CS Test Override 4 Tone Antenna Permutation.
126 : *
127 : * These values represent indices in an antenna path permutation table.
128 : *
129 : * Which table is applicable (and which indices are valid)
130 : * depends on the maximum number of antenna paths (N_AP).
131 : *
132 : * If N_AP = 2, the permutation table is:
133 : *
134 : * +--------------------------------+------------------------------------------+
135 : * | Antenna Path Permutation Index | Antenna Path Positions After Permutation |
136 : * +--------------------------------+------------------------------------------+
137 : * | 0 | A1 A2 |
138 : * | 1 | A2 A1 |
139 : * +--------------------------------+------------------------------------------+
140 : *
141 : * If N_AP = 3, the permutation table is:
142 : *
143 : * +--------------------------------+------------------------------------------+
144 : * | Antenna Path Permutation Index | Antenna Path Positions After Permutation |
145 : * +--------------------------------+------------------------------------------+
146 : * | 0 | A1 A2 A3 |
147 : * | 1 | A2 A1 A3 |
148 : * | 2 | A1 A3 A2 |
149 : * | 3 | A3 A1 A2 |
150 : * | 4 | A3 A2 A1 |
151 : * | 5 | A2 A3 A1 |
152 : * +--------------------------------+------------------------------------------+
153 : *
154 : * If N_AP = 4, the permutation table is:
155 : *
156 : * +--------------------------------+------------------------------------------+
157 : * | Antenna Path Permutation Index | Antenna Path Positions After Permutation |
158 : * +--------------------------------+------------------------------------------+
159 : * | 0 | A1 A2 A3 A4 |
160 : * | 1 | A2 A1 A3 A4 |
161 : * | 2 | A1 A3 A2 A4 |
162 : * | 3 | A3 A1 A2 A4 |
163 : * | 4 | A3 A2 A1 A4 |
164 : * | 5 | A2 A3 A1 A4 |
165 : * | 6 | A1 A2 A4 A3 |
166 : * | 7 | A2 A1 A4 A3 |
167 : * | 8 | A1 A4 A2 A3 |
168 : * | 9 | A4 A1 A2 A3 |
169 : * | 10 | A4 A2 A1 A3 |
170 : * | 11 | A2 A4 A1 A3 |
171 : * | 12 | A1 A4 A3 A2 |
172 : * | 13 | A4 A1 A3 A2 |
173 : * | 14 | A1 A3 A4 A2 |
174 : * | 15 | A3 A1 A4 A2 |
175 : * | 16 | A3 A4 A1 A2 |
176 : * | 17 | A4 A3 A1 A2 |
177 : * | 18 | A4 A2 A3 A1 |
178 : * | 19 | A2 A4 A3 A1 |
179 : * | 20 | A4 A3 A2 A1 |
180 : * | 21 | A3 A4 A2 A1 |
181 : * | 22 | A3 A2 A4 A1 |
182 : * | 23 | A2 A3 A4 A1 |
183 : * +--------------------------------+------------------------------------------+
184 : */
185 0 : enum bt_le_cs_test_override_4_tone_antenna_permutation {
186 : BT_LE_CS_TEST_OVERRIDE_4_ANTENNA_PERMUTATION_INDEX_00 = BT_HCI_OP_LE_CS_TEST_AP_INDEX_00,
187 : BT_LE_CS_TEST_OVERRIDE_4_ANTENNA_PERMUTATION_INDEX_01 = BT_HCI_OP_LE_CS_TEST_AP_INDEX_01,
188 : BT_LE_CS_TEST_OVERRIDE_4_ANTENNA_PERMUTATION_INDEX_02 = BT_HCI_OP_LE_CS_TEST_AP_INDEX_02,
189 : BT_LE_CS_TEST_OVERRIDE_4_ANTENNA_PERMUTATION_INDEX_03 = BT_HCI_OP_LE_CS_TEST_AP_INDEX_03,
190 : BT_LE_CS_TEST_OVERRIDE_4_ANTENNA_PERMUTATION_INDEX_04 = BT_HCI_OP_LE_CS_TEST_AP_INDEX_04,
191 : BT_LE_CS_TEST_OVERRIDE_4_ANTENNA_PERMUTATION_INDEX_05 = BT_HCI_OP_LE_CS_TEST_AP_INDEX_05,
192 : BT_LE_CS_TEST_OVERRIDE_4_ANTENNA_PERMUTATION_INDEX_06 = BT_HCI_OP_LE_CS_TEST_AP_INDEX_06,
193 : BT_LE_CS_TEST_OVERRIDE_4_ANTENNA_PERMUTATION_INDEX_07 = BT_HCI_OP_LE_CS_TEST_AP_INDEX_07,
194 : BT_LE_CS_TEST_OVERRIDE_4_ANTENNA_PERMUTATION_INDEX_08 = BT_HCI_OP_LE_CS_TEST_AP_INDEX_08,
195 : BT_LE_CS_TEST_OVERRIDE_4_ANTENNA_PERMUTATION_INDEX_09 = BT_HCI_OP_LE_CS_TEST_AP_INDEX_09,
196 : BT_LE_CS_TEST_OVERRIDE_4_ANTENNA_PERMUTATION_INDEX_10 = BT_HCI_OP_LE_CS_TEST_AP_INDEX_10,
197 : BT_LE_CS_TEST_OVERRIDE_4_ANTENNA_PERMUTATION_INDEX_11 = BT_HCI_OP_LE_CS_TEST_AP_INDEX_11,
198 : BT_LE_CS_TEST_OVERRIDE_4_ANTENNA_PERMUTATION_INDEX_12 = BT_HCI_OP_LE_CS_TEST_AP_INDEX_12,
199 : BT_LE_CS_TEST_OVERRIDE_4_ANTENNA_PERMUTATION_INDEX_13 = BT_HCI_OP_LE_CS_TEST_AP_INDEX_13,
200 : BT_LE_CS_TEST_OVERRIDE_4_ANTENNA_PERMUTATION_INDEX_14 = BT_HCI_OP_LE_CS_TEST_AP_INDEX_14,
201 : BT_LE_CS_TEST_OVERRIDE_4_ANTENNA_PERMUTATION_INDEX_15 = BT_HCI_OP_LE_CS_TEST_AP_INDEX_15,
202 : BT_LE_CS_TEST_OVERRIDE_4_ANTENNA_PERMUTATION_INDEX_16 = BT_HCI_OP_LE_CS_TEST_AP_INDEX_16,
203 : BT_LE_CS_TEST_OVERRIDE_4_ANTENNA_PERMUTATION_INDEX_17 = BT_HCI_OP_LE_CS_TEST_AP_INDEX_17,
204 : BT_LE_CS_TEST_OVERRIDE_4_ANTENNA_PERMUTATION_INDEX_18 = BT_HCI_OP_LE_CS_TEST_AP_INDEX_18,
205 : BT_LE_CS_TEST_OVERRIDE_4_ANTENNA_PERMUTATION_INDEX_19 = BT_HCI_OP_LE_CS_TEST_AP_INDEX_19,
206 : BT_LE_CS_TEST_OVERRIDE_4_ANTENNA_PERMUTATION_INDEX_20 = BT_HCI_OP_LE_CS_TEST_AP_INDEX_20,
207 : BT_LE_CS_TEST_OVERRIDE_4_ANTENNA_PERMUTATION_INDEX_21 = BT_HCI_OP_LE_CS_TEST_AP_INDEX_21,
208 : BT_LE_CS_TEST_OVERRIDE_4_ANTENNA_PERMUTATION_INDEX_22 = BT_HCI_OP_LE_CS_TEST_AP_INDEX_22,
209 : BT_LE_CS_TEST_OVERRIDE_4_ANTENNA_PERMUTATION_INDEX_23 = BT_HCI_OP_LE_CS_TEST_AP_INDEX_23,
210 : /** Loop through all valid Antenna Permutation Indices starting
211 : * from the lowest index.
212 : */
213 : BT_LE_CS_TEST_OVERRIDE_4_ANTENNA_PERMUTATION_INDEX_LOOP =
214 : BT_HCI_OP_LE_CS_TEST_AP_INDEX_LOOP,
215 : };
216 :
217 : /** CS Test Override 7 Sounding Sequence Marker Value */
218 0 : enum bt_le_cs_test_override_7_ss_marker_value {
219 : BT_LE_CS_TEST_OVERRIDE_7_SS_MARKER_VAL_0011 = BT_HCI_OP_LE_CS_TEST_SS_MARKER_VAL_0011,
220 : BT_LE_CS_TEST_OVERRIDE_7_SS_MARKER_VAL_1100 = BT_HCI_OP_LE_CS_TEST_SS_MARKER_VAL_1100,
221 : /** Loop through pattern '0011' and '1100' (in transmission order) */
222 : BT_LE_CS_TEST_OVERRIDE_7_SS_MARKER_VAL_LOOP = BT_HCI_OP_LE_CS_TEST_SS_MARKER_VAL_LOOP,
223 : };
224 :
225 : /** CS Test Override 8 CS_SYNC Payload Pattern */
226 1 : enum bt_le_cs_test_override_8_cs_sync_payload_pattern {
227 : /** PRBS9 payload sequence. */
228 : BT_LE_CS_TEST_OVERRIDE_8_PAYLOAD_PATTERN_PRBS9 = BT_HCI_OP_LE_CS_TEST_PAYLOAD_PRBS9,
229 : /** Repeated '11110000' payload sequence. */
230 : BT_LE_CS_TEST_OVERRIDE_8_PAYLOAD_PATTERN_11110000 = BT_HCI_OP_LE_CS_TEST_PAYLOAD_11110000,
231 : /** Repeated '10101010' payload sequence. */
232 : BT_LE_CS_TEST_OVERRIDE_8_PAYLOAD_PATTERN_10101010 = BT_HCI_OP_LE_CS_TEST_PAYLOAD_10101010,
233 : /** PRBS15 payload sequence. */
234 : BT_LE_CS_TEST_OVERRIDE_8_PAYLOAD_PATTERN_PRBS15 = BT_HCI_OP_LE_CS_TEST_PAYLOAD_PRBS15,
235 : /** Repeated '11111111' payload sequence. */
236 : BT_LE_CS_TEST_OVERRIDE_8_PAYLOAD_PATTERN_11111111 = BT_HCI_OP_LE_CS_TEST_PAYLOAD_11111111,
237 : /** Repeated '00000000' payload sequence. */
238 : BT_LE_CS_TEST_OVERRIDE_8_PAYLOAD_PATTERN_00000000 = BT_HCI_OP_LE_CS_TEST_PAYLOAD_00000000,
239 : /** Repeated '00001111' payload sequence. */
240 : BT_LE_CS_TEST_OVERRIDE_8_PAYLOAD_PATTERN_00001111 = BT_HCI_OP_LE_CS_TEST_PAYLOAD_00001111,
241 : /** Repeated '01010101' payload sequence. */
242 : BT_LE_CS_TEST_OVERRIDE_8_PAYLOAD_PATTERN_01010101 = BT_HCI_OP_LE_CS_TEST_PAYLOAD_01010101,
243 : /** Custom payload provided by the user. */
244 : BT_LE_CS_TEST_OVERRIDE_8_PAYLOAD_PATTERN_USER = BT_HCI_OP_LE_CS_TEST_PAYLOAD_USER,
245 : };
246 :
247 : /** CS Test parameters */
248 1 : struct bt_le_cs_test_param {
249 : /** CS main and sub mode to be used during the CS procedure. */
250 1 : enum bt_conn_le_cs_mode 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 and sub CS mode */
483 1 : enum bt_conn_le_cs_mode mode;
484 : /** Minimum number of CS main mode steps to be executed before a submode step is executed */
485 1 : uint8_t min_main_mode_steps;
486 : /** Maximum number of CS main mode steps to be executed before a submode step is executed */
487 1 : uint8_t max_main_mode_steps;
488 : /** Number of main mode steps taken from the end of the last CS subevent to be repeated
489 : * at the beginning of the current CS subevent directly after the last mode-0 step of that
490 : * event
491 : */
492 1 : uint8_t main_mode_repetition;
493 : /** Number of CS mode-0 steps to be included at the beginning of each CS subevent */
494 1 : uint8_t mode_0_steps;
495 : /** CS role */
496 1 : enum bt_conn_le_cs_role role;
497 : /** RTT type */
498 1 : enum bt_conn_le_cs_rtt_type rtt_type;
499 : /** CS Sync PHY */
500 1 : enum bt_conn_le_cs_sync_phy cs_sync_phy;
501 : /** The number of times the Channel_Map field will be cycled through for non-mode-0 steps
502 : * within a CS procedure
503 : */
504 1 : uint8_t channel_map_repetition;
505 : /** Channel selection type */
506 1 : enum bt_conn_le_cs_chsel_type channel_selection_type;
507 : /** User-specified channel sequence shape */
508 1 : enum bt_conn_le_cs_ch3c_shape ch3c_shape;
509 : /** Number of channels skipped in each rising and falling sequence */
510 1 : uint8_t ch3c_jump;
511 : /** Channel map used for CS procedure
512 : * Channels n = 0, 1, 23, 24, 25, 77, and 78 are not allowed and shall be set to zero.
513 : * Channel 79 is reserved for future use and shall be set to zero.
514 : * At least 15 channels shall be enabled.
515 : */
516 1 : uint8_t channel_map[10];
517 : };
518 :
519 : /** Callbacks for CS Test */
520 1 : struct bt_le_cs_test_cb {
521 : /**@brief CS Test Subevent data.
522 : *
523 : * @param[in] Subevent results.
524 : */
525 1 : void (*le_cs_test_subevent_data_available)(struct bt_conn_le_cs_subevent_result *data);
526 : /**@brief CS Test End Complete. */
527 1 : void (*le_cs_test_end_complete)(void);
528 : };
529 :
530 : /** Subevent result step */
531 1 : struct bt_le_cs_subevent_step {
532 : /** CS step mode. */
533 1 : uint8_t mode;
534 : /** CS step channel index. */
535 1 : uint8_t channel;
536 : /** Length of role- and mode-specific information being reported. */
537 1 : uint8_t data_len;
538 : /** Pointer to role- and mode-specific information. */
539 1 : const uint8_t *data;
540 : };
541 :
542 : /** Sign-extended IQ value extracted from step data. */
543 1 : struct bt_le_cs_iq_sample {
544 0 : int16_t i;
545 0 : int16_t q;
546 : };
547 :
548 : /** @brief Extract in-phase and quadrature terms from HCI-formatted PCT.
549 : *
550 : * Convenience function for processing 24-bit phase correction terms found
551 : * in CS step data. The 12-bit signed real and imaginary components are
552 : * converted to host endianness and sign-extended.
553 : *
554 : * @param pct 24-bit little-endian phase correction term.
555 : *
556 : * @return struct bt_le_cs_iq_sample containing real and imaginary terms as int16_t
557 : */
558 1 : struct bt_le_cs_iq_sample bt_le_cs_parse_pct(const uint8_t pct[3]);
559 :
560 : /** @brief Set all valid channel map bits
561 : *
562 : * This command is used to enable all valid channels in a
563 : * given CS channel map
564 : *
565 : * @param channel_map Chanel map
566 : */
567 1 : void bt_le_cs_set_valid_chmap_bits(uint8_t channel_map[10]);
568 :
569 : /** @brief Read Remote Supported Capabilities
570 : *
571 : * This command is used to query the CS capabilities that are supported
572 : * by the remote controller.
573 : *
574 : * @note To use this API @kconfig{CONFIG_BT_CHANNEL_SOUNDING} must be set.
575 : *
576 : * @param conn Connection Object.
577 : *
578 : * @return Zero on success or (negative) error code on failure.
579 : */
580 1 : int bt_le_cs_read_remote_supported_capabilities(struct bt_conn *conn);
581 :
582 : /** @brief Set Channel Sounding default settings.
583 : *
584 : * This command is used to set default Channel Sounding settings for this
585 : * connection.
586 : *
587 : * @note To use this API @kconfig{CONFIG_BT_CHANNEL_SOUNDING} must be set.
588 : *
589 : * @param conn Connection Object.
590 : * @param params Channel sounding default settings parameters.
591 : *
592 : * @return Zero on success or (negative) error code on failure.
593 : */
594 1 : int bt_le_cs_set_default_settings(struct bt_conn *conn,
595 : const struct bt_le_cs_set_default_settings_param *params);
596 :
597 : /** @brief Read Remote FAE Table
598 : *
599 : * This command is used to read the per-channel mode-0 Frequency Actuation Error
600 : * table of the remote Controller.
601 : *
602 : * If the remote controller supports a Frequency Actuation Error of zero relative
603 : * to its mode-0 transmissions in the reflector role
604 : * (see @ref bt_conn_le_cs_capabilities::cs_without_fae_supported), calling this
605 : * function is not needed and the read remote FAE table complete event will be
606 : * generated with an error code.
607 : *
608 : * @note To use this API @kconfig{CONFIG_BT_CHANNEL_SOUNDING} must be set.
609 : *
610 : * @param conn Connection Object.
611 : *
612 : * @return Zero on success or (negative) error code on failure.
613 : */
614 1 : int bt_le_cs_read_remote_fae_table(struct bt_conn *conn);
615 :
616 : /** @brief Register callbacks for the CS Test mode.
617 : *
618 : * Existing callbacks can be unregistered by providing NULL function
619 : * pointers.
620 : *
621 : * @note To use this API @kconfig{CONFIG_BT_CHANNEL_SOUNDING_TEST} must be set.
622 : *
623 : * @param cs_test_cb Set of callbacks to be used with CS Test
624 : *
625 : * @return Zero on success or (negative) error code on failure.
626 : */
627 1 : int bt_le_cs_test_cb_register(struct bt_le_cs_test_cb cs_test_cb);
628 :
629 : /** @brief Start a CS test
630 : *
631 : * This command is used to start a CS test where the IUT is placed in the role
632 : * of either the initiator or reflector.
633 : *
634 : * The first mode-0 channel in the list is used as the starting channel for
635 : * the test. At the beginning of any test, the IUT in the reflector role shall
636 : * listen on the first mode-0 channel until it receives the first transmission
637 : * from the initiator. Similarly, with the IUT in the initiator role, the tester
638 : * will start by listening on the first mode-0 channel and the IUT shall transmit
639 : * on that channel for the first half of the first CS step. Thereafter, the
640 : * parameters of this command describe the required transmit and receive behavior
641 : * for the CS test.
642 : *
643 : * @note To use this API @kconfig{CONFIG_BT_CHANNEL_SOUNDING_TEST} must be set.
644 : *
645 : * @param params CS Test parameters
646 : *
647 : * @return Zero on success or (negative) error code on failure.
648 : */
649 1 : int bt_le_cs_start_test(const struct bt_le_cs_test_param *params);
650 :
651 : /** @brief Create CS configuration
652 : *
653 : * This command is used to create a new CS configuration or update an
654 : * existing one with the config id specified.
655 : *
656 : * @note To use this API @kconfig{CONFIG_BT_CHANNEL_SOUNDING} must be set.
657 : *
658 : * @param conn Connection Object.
659 : * @param params CS Create Config parameters
660 : * @param context Controls whether the configuration is written to the local controller or
661 : * both the local and the remote controller
662 : *
663 : * @return Zero on success or (negative) error code on failure.
664 : */
665 1 : int bt_le_cs_create_config(struct bt_conn *conn, struct bt_le_cs_create_config_params *params,
666 : enum bt_le_cs_create_config_context context);
667 :
668 : /** @brief Create CS configuration
669 : *
670 : * This command is used to remove a CS configuration from the local controller
671 : * identified by the config_id
672 : *
673 : * @note To use this API @kconfig{CONFIG_BT_CHANNEL_SOUNDING} must be set.
674 : *
675 : * @param conn Connection Object.
676 : * @param config_id CS Config ID
677 : *
678 : * @return Zero on success or (negative) error code on failure.
679 : */
680 1 : int bt_le_cs_remove_config(struct bt_conn *conn, uint8_t config_id);
681 :
682 : /** @brief Stop ongoing CS Test
683 : *
684 : * This command is used to stop any CS test that is in progress.
685 : *
686 : * The controller is expected to finish reporting any subevent results
687 : * before completing this termination.
688 : *
689 : * @note To use this API @kconfig{CONFIG_BT_CHANNEL_SOUNDING_TEST} must be set.
690 : *
691 : * @return Zero on success or (negative) error code on failure.
692 : */
693 1 : int bt_le_cs_stop_test(void);
694 :
695 : /** @brief Parse CS Subevent Step Data
696 : *
697 : * A helper for parsing HCI-formatted step data found in channel sounding subevent results.
698 : *
699 : * A typical use-case is filtering out data which does not meet certain packet quality or NADM
700 : * requirements.
701 : *
702 : * @warning This function will consume the data when parsing.
703 : *
704 : * @param step_data_buf Pointer to a buffer containing the step data.
705 : * @param func Callback function which will be called for each step data found.
706 : * The callback should return true to continue parsing, or false to stop.
707 : * @param user_data User data to be passed to the callback.
708 : */
709 1 : void bt_le_cs_step_data_parse(struct net_buf_simple *step_data_buf,
710 : bool (*func)(struct bt_le_cs_subevent_step *step, void *user_data),
711 : void *user_data);
712 :
713 : /** @brief CS Security Enable
714 : *
715 : * This command is used to start or restart the Channel Sounding Security
716 : * Start procedure in the local Controller for the ACL connection identified
717 : * in the conn parameter.
718 : *
719 : * @note To use this API @kconfig{CONFIG_BT_CHANNEL_SOUNDING} must be set.
720 : *
721 : * @param conn Connection Object.
722 : *
723 : * @return Zero on success or (negative) error code on failure.
724 : */
725 1 : int bt_le_cs_security_enable(struct bt_conn *conn);
726 :
727 0 : struct bt_le_cs_procedure_enable_param {
728 0 : uint8_t config_id;
729 0 : enum bt_conn_le_cs_procedure_enable_state enable;
730 : };
731 :
732 : /** @brief CS Procedure Enable
733 : *
734 : * This command is used to enable or disable the scheduling of CS procedures
735 : * by the local Controller, with the remote device identified in the conn
736 : * parameter.
737 : *
738 : * @note To use this API @kconfig{CONFIG_BT_CHANNEL_SOUNDING} must be set.
739 : *
740 : * @param conn Connection Object.
741 : * @param params Parameters for the CS Procedure Enable command.
742 : *
743 : * @return Zero on success or (negative) error code on failure.
744 : */
745 1 : int bt_le_cs_procedure_enable(struct bt_conn *conn,
746 : const struct bt_le_cs_procedure_enable_param *params);
747 :
748 0 : enum bt_le_cs_procedure_phy {
749 : BT_LE_CS_PROCEDURE_PHY_1M = BT_HCI_OP_LE_CS_PROCEDURE_PHY_1M,
750 : BT_LE_CS_PROCEDURE_PHY_2M = BT_HCI_OP_LE_CS_PROCEDURE_PHY_2M,
751 : BT_LE_CS_PROCEDURE_PHY_CODED_S8 = BT_HCI_OP_LE_CS_PROCEDURE_PHY_CODED_S8,
752 : BT_LE_CS_PROCEDURE_PHY_CODED_S2 = BT_HCI_OP_LE_CS_PROCEDURE_PHY_CODED_S2,
753 : };
754 :
755 0 : #define BT_LE_CS_PROCEDURE_PREFERRED_PEER_ANTENNA_1 BIT(0)
756 0 : #define BT_LE_CS_PROCEDURE_PREFERRED_PEER_ANTENNA_2 BIT(1)
757 0 : #define BT_LE_CS_PROCEDURE_PREFERRED_PEER_ANTENNA_3 BIT(2)
758 0 : #define BT_LE_CS_PROCEDURE_PREFERRED_PEER_ANTENNA_4 BIT(3)
759 :
760 0 : struct bt_le_cs_set_procedure_parameters_param {
761 : /* The ID associated with the desired configuration (0 to 3) */
762 0 : uint8_t config_id;
763 :
764 : /* Max. duration for each CS procedure, where T = N * 0.625 ms (0x0001 to 0xFFFF) */
765 0 : uint16_t max_procedure_len;
766 :
767 : /* Min. number of connection events between consecutive CS procedures (0x0001 to 0xFFFF) */
768 0 : uint16_t min_procedure_interval;
769 :
770 : /* Max. number of connection events between consecutive CS procedures (0x0001 to 0xFFFF) */
771 0 : uint16_t max_procedure_interval;
772 :
773 : /* Max. number of procedures to be scheduled (0x0000 for no limit; otherwise 0x0001
774 : * to 0xFFFF)
775 : */
776 0 : uint16_t max_procedure_count;
777 :
778 : /* Min. suggested duration for each CS subevent in microseconds (1250 us to 4 s) */
779 0 : uint32_t min_subevent_len;
780 :
781 : /* Max. suggested duration for each CS subevent in microseconds (1250 us to 4 s) */
782 0 : uint32_t max_subevent_len;
783 :
784 : /* Antenna configuration index */
785 0 : enum bt_conn_le_cs_tone_antenna_config_selection tone_antenna_config_selection;
786 :
787 : /* Phy */
788 0 : enum bt_le_cs_procedure_phy phy;
789 :
790 : /* Transmit power delta, in signed dB, to indicate the recommended difference between the
791 : * remote device's power level for the CS tones and RTT packets and the existing power
792 : * level for the Phy indicated by the Phy parameter (0x80 for no recommendation)
793 : */
794 0 : int8_t tx_power_delta;
795 :
796 : /* Preferred peer antenna (Bitmask of BT_LE_CS_PROCEDURE_PREFERRED_PEER_ANTENNA_*) */
797 0 : uint8_t preferred_peer_antenna;
798 :
799 : /* Initiator SNR control adjustment */
800 0 : enum bt_le_cs_snr_control snr_control_initiator;
801 :
802 : /* Reflector SNR control adjustment */
803 0 : enum bt_le_cs_snr_control snr_control_reflector;
804 : };
805 :
806 : /** @brief CS Set Procedure Parameters
807 : *
808 : * This command is used to set the parameters for the scheduling of one
809 : * or more CS procedures by the local controller.
810 : *
811 : * @note To use this API @kconfig{CONFIG_BT_CHANNEL_SOUNDING} must be set.
812 : *
813 : * @param conn Connection Object.
814 : * @param params Parameters for the CS Set Procedure Parameters command.
815 : *
816 : * @return Zero on success or (negative) error code on failure.
817 : */
818 1 : int bt_le_cs_set_procedure_parameters(struct bt_conn *conn,
819 : const struct bt_le_cs_set_procedure_parameters_param *params);
820 :
821 : /** @brief CS Set Channel Classification
822 : *
823 : * This command is used to update the channel classification based on
824 : * its local information.
825 : *
826 : * The nth bitfield (in the range 0 to 78) contains the value for the CS
827 : * channel index n. Channel Enabled = 1; Channel Disabled = 0.
828 : *
829 : * Channels n = 0, 1, 23, 24, 25, 77, and 78 shall be reserved for future
830 : * use and shall be set to zero. At least 15 channels shall be enabled.
831 : *
832 : * The most significant bit (bit 79) is reserved for future use.
833 : *
834 : * @note To use this API, @kconfig{CONFIG_BT_CHANNEL_SOUNDING} must be set.
835 : *
836 : * @param channel_classification Bit fields
837 : *
838 : * @return Zero on success or (negative) error code on failure.
839 : */
840 1 : int bt_le_cs_set_channel_classification(uint8_t channel_classification[10]);
841 :
842 : /** @brief CS Read Local Supported Capabilities
843 : *
844 : * This command is used to read the CS capabilities that are supported
845 : * by the local Controller.
846 : *
847 : * @note To use this API @kconfig{CONFIG_BT_CHANNEL_SOUNDING} must be set.
848 : *
849 : * @param ret Return values for the CS Procedure Enable command.
850 : *
851 : * @return Zero on success or (negative) error code on failure.
852 : */
853 1 : int bt_le_cs_read_local_supported_capabilities(struct bt_conn_le_cs_capabilities *ret);
854 :
855 : /** @brief CS Write Cached Remote Supported Capabilities
856 : *
857 : * This command is used to write the cached copy of the CS capabilities
858 : * that are supported by the remote Controller for the connection
859 : * identified.
860 : *
861 : * @note To use this API @kconfig{CONFIG_BT_CHANNEL_SOUNDING} must be set.
862 : *
863 : * @param conn Connection Object.
864 : * @param params Parameters for the CS Write Cached Remote Supported Capabilities command.
865 : *
866 : * @return Zero on success or (negative) error code on failure.
867 : */
868 1 : int bt_le_cs_write_cached_remote_supported_capabilities(
869 : struct bt_conn *conn, const struct bt_conn_le_cs_capabilities *params);
870 :
871 : /** @brief CS Write Cached Remote FAE Table
872 : *
873 : * This command is used to write a cached copy of the per-channel mode-0
874 : * Frequency Actuation Error table of the remote device in the local Controller.
875 : *
876 : * If the remote controller supports a Frequency Actuation Error of zero relative
877 : * to its mode-0 transmissions in the reflector role
878 : * (see @ref bt_conn_le_cs_capabilities::cs_without_fae_supported), calling this
879 : * function is not needed. An error code will be returned.
880 : *
881 : * @note To use this API @kconfig{CONFIG_BT_CHANNEL_SOUNDING} must be set.
882 : *
883 : * @param conn Connection Object.
884 : * @param remote_fae_table Per-channel mode-0 FAE table of the local Controller
885 : *
886 : * @return Zero on success or (negative) error code on failure.
887 : */
888 1 : int bt_le_cs_write_cached_remote_fae_table(struct bt_conn *conn, int8_t remote_fae_table[72]);
889 :
890 : /** @brief Get antenna path used for the CS tone exchange
891 : * when using multiple antenna paths for mode-2 or mode-3
892 : * CS procedure.
893 : *
894 : * The function implements antenna path permutation defined in
895 : * Bluetooth Core Specification 6.0, Vol. 6, Part H, Section 4.7.5.
896 : *
897 : * @note To use this API @kconfig{CONFIG_BT_CHANNEL_SOUNDING} must be set.
898 : *
899 : * @param n_ap The number of antenna paths, range: [1, 4].
900 : * @param antenna_path_permutation_index Antenna Path Permutation Index.
901 : * @param tone_index Index of the tone in the CS step, range [0, n_ap].
902 : * tone_index = n_ap corresponds to extension slot.
903 : *
904 : * @return Antenna path used to exchange CS tones, range: [0, 3].
905 : * @return -EINVAL if arguments are invalid.
906 : */
907 1 : int bt_le_cs_get_antenna_path(uint8_t n_ap,
908 : uint8_t antenna_path_permutation_index,
909 : uint8_t tone_index);
910 :
911 : #ifdef __cplusplus
912 : }
913 : #endif
914 :
915 : /**
916 : * @}
917 : */
918 :
919 : #endif /* ZEPHYR_INCLUDE_BLUETOOTH_CS_H_ */
|
