Line data Source code
1 0 : /*
2 : * Copyright (c) 2020 Nordic Semiconductor ASA
3 : *
4 : * SPDX-License-Identifier: Apache-2.0
5 : */
6 :
7 : #ifndef ZEPHYR_INCLUDE_BLUETOOTH_DF_H_
8 : #define ZEPHYR_INCLUDE_BLUETOOTH_DF_H_
9 :
10 : #include <stdint.h>
11 :
12 : #include <zephyr/bluetooth/bluetooth.h>
13 : #include <zephyr/sys/util_macro.h>
14 :
15 : /** Constant Tone Extension (CTE) types. */
16 1 : enum bt_df_cte_type {
17 : /** Convenience value for purposes where non of CTE types is allowed. */
18 : BT_DF_CTE_TYPE_NONE = 0,
19 : /** Angle of Arrival mode. Antenna switching done on receiver site. */
20 : BT_DF_CTE_TYPE_AOA = BIT(0),
21 : /**
22 : * @brief Angle of Departure mode with 1 us antenna switching slots.
23 : *
24 : * Antenna switching done on transmitter site.
25 : */
26 : BT_DF_CTE_TYPE_AOD_1US = BIT(1),
27 : /**
28 : * @brief Angle of Departure mode with 2 us antenna switching slots.
29 : *
30 : * Antenna switching done on transmitter site.
31 : */
32 : BT_DF_CTE_TYPE_AOD_2US = BIT(2),
33 : /** Convenience value that collects all possible CTE types in one entry. */
34 : BT_DF_CTE_TYPE_ALL = (BT_DF_CTE_TYPE_AOA | BT_DF_CTE_TYPE_AOD_1US | BT_DF_CTE_TYPE_AOD_2US)
35 : };
36 :
37 : /** Allowed antenna switching slots: 1 us or 2 us */
38 0 : enum bt_df_antenna_switching_slot {
39 : BT_DF_ANTENNA_SWITCHING_SLOT_1US = 0x1,
40 : BT_DF_ANTENNA_SWITCHING_SLOT_2US = 0x2
41 : };
42 :
43 : /** Possible statuses of PDU that contained reported CTE. */
44 1 : enum bt_df_packet_status {
45 : /** Received PDU had CRC OK */
46 : BT_DF_CTE_CRC_OK = 0x0,
47 : /** Received PDU had incorrect CRC, but Radio peripheral
48 : * was able to parse CTEInfo field of the PDU and process
49 : * sampling of CTE.
50 : */
51 : BT_DF_CTE_CRC_ERR_CTE_BASED_TIME = 0x1,
52 : /** Received PDU had incorrect CRC, but Radio peripheral
53 : * was able to process sampling of CTE in some other way.
54 : */
55 : BT_DF_CTE_CRC_ERR_CTE_BASED_OTHER = 0x2,
56 : /** There were no sufficient resources to sample CTE. */
57 : BT_DF_CTE_INSUFFICIENT_RESOURCES = 0xFF
58 : };
59 :
60 : /** @brief Constant Tone Extension parameters for connectionless
61 : * transmission.
62 : *
63 : * The structure holds information required to setup CTE transmission
64 : * in periodic advertising.
65 : */
66 1 : struct bt_df_adv_cte_tx_param {
67 : /** Length of CTE in 8us units. */
68 1 : uint8_t cte_len;
69 : /**
70 : * @brief CTE type.
71 : *
72 : * Allowed values are defined by @ref bt_df_cte_type, except BT_DF_CTE_TYPE_NONE and
73 : * BT_DF_CTE_TYPE_ALL.
74 : */
75 1 : uint8_t cte_type;
76 : /** Number of CTE to transmit in each periodic adv interval. */
77 1 : uint8_t cte_count;
78 : /** Number of Antenna IDs in the switch pattern. */
79 1 : uint8_t num_ant_ids;
80 : /** List of antenna IDs in the pattern. */
81 1 : uint8_t *ant_ids;
82 : };
83 :
84 : /**
85 : * @brief Constant Tone Extension parameters for connectionless reception.
86 : *
87 : * @note cte_type is a bit field that provides information about type of CTE an application
88 : * expects (@ref bt_df_cte_type). In case cte_type bit BT_DF_CTE_TYPE_AOA is not set, members:
89 : * slot_durations, num_ant_ids and ant_ids are not required and their values will be not verified
90 : * for correctness.
91 : */
92 1 : struct bt_df_per_adv_sync_cte_rx_param {
93 : /**
94 : * @brief Bitfield with allowed CTE types.
95 : *
96 : * Allowed values are defined by @ref bt_df_cte_type, except BT_DF_CTE_TYPE_NONE.
97 : */
98 1 : uint8_t cte_types;
99 : /** Antenna switching slots (@ref bt_df_antenna_switching_slot). */
100 1 : uint8_t slot_durations;
101 : /** Max number of CTEs to receive. Min is 1, max is 10, 0 means receive continuously. */
102 1 : uint8_t max_cte_count;
103 : /** Length of antenna switch pattern. */
104 1 : uint8_t num_ant_ids;
105 : /** Antenna switch pattern. */
106 1 : const uint8_t *ant_ids;
107 : };
108 :
109 0 : enum bt_df_iq_sample {
110 : /** Reported IQ samples have 8 bits signed integer format. Size defined in BT Core 5.3
111 : * Vol 4, Part E sections 7.7.65.21 and 7.7.65.22.
112 : */
113 : BT_DF_IQ_SAMPLE_8_BITS_INT,
114 : /** Reported IQ samples have 16 bits signed integer format. Vendor specific extension. */
115 : BT_DF_IQ_SAMPLE_16_BITS_INT,
116 : };
117 :
118 0 : struct bt_df_per_adv_sync_iq_samples_report {
119 : /** Channel index used to receive PDU with CTE that was sampled. */
120 1 : uint8_t chan_idx;
121 : /** The RSSI of the PDU with CTE (excluding CTE). Range: -1270 to +200. Units: 0.1 dBm. */
122 1 : int16_t rssi;
123 : /** Id of antenna used to measure the RSSI. */
124 1 : uint8_t rssi_ant_id;
125 : /** Type of CTE (@ref bt_df_cte_type). */
126 1 : uint8_t cte_type;
127 : /** Duration of slots when received CTE type is AoA (@ref bt_df_antenna_switching_slot). */
128 1 : uint8_t slot_durations;
129 : /** Status of received PDU with CTE (@ref bt_df_packet_status). */
130 1 : uint8_t packet_status;
131 : /** Value of the paEventCounter of the AUX_SYNC_IND PDU. */
132 1 : uint16_t per_evt_counter;
133 : /** Number of IQ samples in report. */
134 1 : uint8_t sample_count;
135 : /** Type of IQ samples provided in a report. */
136 1 : enum bt_df_iq_sample sample_type;
137 : /** Pointer to IQ samples data. */
138 : union {
139 0 : struct bt_hci_le_iq_sample const *sample;
140 0 : struct bt_hci_le_iq_sample16 const *sample16;
141 1 : };
142 : };
143 :
144 0 : struct bt_df_conn_cte_rx_param {
145 : /**
146 : * @brief Bitfield with allowed CTE types.
147 : *
148 : * Allowed values are defined by @ref bt_df_cte_type, except BT_DF_CTE_TYPE_NONE.
149 : */
150 1 : uint8_t cte_types;
151 : /** Antenna switching slots (@ref bt_df_antenna_switching_slot). */
152 1 : uint8_t slot_durations;
153 : /** Length of antenna switch pattern. */
154 1 : uint8_t num_ant_ids;
155 : /** Antenna switch pattern. */
156 1 : const uint8_t *ant_ids;
157 : };
158 :
159 0 : enum bt_df_conn_iq_report_err {
160 : /** IQ samples report received successfully. */
161 : BT_DF_IQ_REPORT_ERR_SUCCESS,
162 : /** Received PDU without CTE. No valid data in report. */
163 : BT_DF_IQ_REPORT_ERR_NO_CTE,
164 : /** Peer rejected CTE request. No valid data in report. */
165 : BT_DF_IQ_REPORT_ERR_PEER_REJECTED,
166 : };
167 :
168 0 : struct bt_df_conn_iq_samples_report {
169 : /** Report receive failed reason. */
170 1 : enum bt_df_conn_iq_report_err err;
171 : /** PHY that was used to receive PDU with CTE that was sampled. */
172 1 : uint8_t rx_phy;
173 : /** Channel index used to receive PDU with CTE that was sampled. */
174 1 : uint8_t chan_idx;
175 : /** The RSSI of the PDU with CTE (excluding CTE). Range: -1270 to +200. Units: 0.1 dBm. */
176 1 : int16_t rssi;
177 : /** Id of antenna used to measure the RSSI. */
178 1 : uint8_t rssi_ant_id;
179 : /** Type of CTE (@ref bt_df_cte_type). */
180 1 : uint8_t cte_type;
181 : /** Duration of slots when received CTE type is AoA (@ref bt_df_antenna_switching_slot). */
182 1 : uint8_t slot_durations;
183 : /** Status of received PDU with CTE (@ref bt_df_packet_status). */
184 1 : uint8_t packet_status;
185 : /** Value of connection event counter when the CTE was received and sampled. */
186 1 : uint16_t conn_evt_counter;
187 : /** Type of IQ samples provided in a report. */
188 1 : enum bt_df_iq_sample sample_type;
189 : /** Number of IQ samples in report. */
190 1 : uint8_t sample_count;
191 : /** Pointer to IQ samples data. */
192 : union {
193 0 : struct bt_hci_le_iq_sample const *sample;
194 0 : struct bt_hci_le_iq_sample16 const *sample16;
195 1 : };
196 : };
197 : /** Constant Tone Extension parameters for CTE transmission in connected mode. */
198 1 : struct bt_df_conn_cte_tx_param {
199 : /**
200 : * Bitfield with allowed CTE types (@ref bt_df_cte_type. All enum members may be used except
201 : * BT_DF_CTE_TYPE_NONE).
202 : */
203 1 : uint8_t cte_types;
204 : /** Number of antenna switch pattern. */
205 1 : uint8_t num_ant_ids;
206 : /** Antenna switch pattern. */
207 1 : const uint8_t *ant_ids;
208 : };
209 :
210 0 : struct bt_df_conn_cte_req_params {
211 : /**
212 : * @brief Requested interval for initiating the CTE Request procedure.
213 : *
214 : * Value 0x0 means, run the procedure once. Other values are intervals in number of
215 : * connection events, to run the command periodically.
216 : */
217 1 : uint16_t interval;
218 : /** Requested length of the CTE in 8 us units. */
219 1 : uint8_t cte_length;
220 : /**
221 : * @brief Requested type of the CTE.
222 : *
223 : * Allowed values are defined by @ref bt_df_cte_type, except BT_DF_CTE_TYPE_NONE and
224 : * BT_DF_CTE_TYPE_ALL.
225 : */
226 1 : uint8_t cte_type;
227 : };
228 :
229 : /**
230 : * @brief Set or update the Constant Tone Extension parameters for periodic advertising set.
231 : *
232 : * @param[in] adv Advertising set object.
233 : * @param[in] params Constant Tone Extension parameters.
234 : *
235 : * @return Zero on success or (negative) error code otherwise.
236 : */
237 1 : int bt_df_set_adv_cte_tx_param(struct bt_le_ext_adv *adv,
238 : const struct bt_df_adv_cte_tx_param *params);
239 :
240 : /**
241 : * @brief Enable transmission of Constant Tone Extension for the given advertising set.
242 : *
243 : * Transmission of Constant Tone Extension may be enabled only after setting periodic advertising
244 : * parameters (@ref bt_le_per_adv_set_param) and Constant Tone Extension parameters
245 : * (@ref bt_df_set_adv_cte_tx_param).
246 : *
247 : * @param[in] adv Advertising set object.
248 : *
249 : * @return Zero on success or (negative) error code otherwise.
250 : */
251 1 : int bt_df_adv_cte_tx_enable(struct bt_le_ext_adv *adv);
252 :
253 : /**
254 : * @brief Disable transmission of Constant Tone Extension for the given advertising set.
255 : *
256 : * @param[in] adv Advertising set object.
257 : *
258 : * @return Zero on success or (negative) error code otherwise.
259 : */
260 1 : int bt_df_adv_cte_tx_disable(struct bt_le_ext_adv *adv);
261 :
262 : /**
263 : * @brief Enable receive and sampling of Constant Tone Extension for the given sync set.
264 : *
265 : * Receive and sampling of Constant Tone Extension may be enabled only after periodic advertising
266 : * sync is established.
267 : *
268 : * @param sync Periodic advertising sync object.
269 : * @param params CTE receive and sampling parameters.
270 : *
271 : * @return Zero on success or (negative) error code otherwise.
272 : */
273 1 : int bt_df_per_adv_sync_cte_rx_enable(struct bt_le_per_adv_sync *sync,
274 : const struct bt_df_per_adv_sync_cte_rx_param *params);
275 :
276 : /**
277 : * @brief Disable receive and sampling of Constant Tone Extension for the given sync set.
278 : *
279 : * @param sync Periodic advertising sync object.
280 : *
281 : * @return Zero on success or (negative) error code otherwise.
282 : */
283 1 : int bt_df_per_adv_sync_cte_rx_disable(struct bt_le_per_adv_sync *sync);
284 :
285 : /**
286 : * @brief Enable receive and sampling of Constant Tone Extension for the connection object.
287 : *
288 : * @param conn Connection object.
289 : * @param params CTE receive and sampling parameters.
290 : *
291 : * @return Zero in case of success, other value in case of failure.
292 : */
293 1 : int bt_df_conn_cte_rx_enable(struct bt_conn *conn, const struct bt_df_conn_cte_rx_param *params);
294 :
295 : /**
296 : * @brief Disable receive and sampling of Constant Tone Extension for the connection object.
297 : *
298 : * @param conn Connection object.
299 : *
300 : * @return Zero in case of success, other value in case of failure.
301 : */
302 1 : int bt_df_conn_cte_rx_disable(struct bt_conn *conn);
303 :
304 : /**
305 : * @brief Set Constant Tone Extension transmission parameters for a connection.
306 : *
307 : * The function is available if @kconfig{CONFIG_BT_DF_CONNECTION_CTE_TX} is enabled.
308 : *
309 : * @note If neither BT_DF_CTE_TYPE_AOD_1US or BT_DF_CTE_TYPE_AOD_2US are set
310 : * in the bitfield, then the bt_df_conn_cte_tx_param.num_ant_ids and
311 : * bt_df_conn_cte_tx_param.ant_ids parameters will be ignored.
312 : *
313 : * @param conn Connection object.
314 : * @param params CTE transmission parameters.
315 : *
316 : * @return Zero in case of success, other value in case of failure.
317 : */
318 1 : int bt_df_set_conn_cte_tx_param(struct bt_conn *conn, const struct bt_df_conn_cte_tx_param *params);
319 :
320 : /**
321 : * @brief Enable Constant Tone Extension request procedure for a connection.
322 : *
323 : * The function is available if @kconfig{CONFIG_BT_DF_CONNECTION_CTE_REQ} is enabled.
324 : *
325 : * @param conn Connection object.
326 : * @param params CTE receive and sampling parameters.
327 : *
328 : * @return Zero in case of success, other value in case of failure.
329 : */
330 1 : int bt_df_conn_cte_req_enable(struct bt_conn *conn, const struct bt_df_conn_cte_req_params *params);
331 :
332 : /**
333 : * @brief Disable Constant Tone Extension request procedure for a connection.
334 : *
335 : * The function is available if @kconfig{CONFIG_BT_DF_CONNECTION_CTE_REQ} is enabled.
336 : *
337 : * @param conn Connection object.
338 : *
339 : * @return Zero in case of success, other value in case of failure.
340 : */
341 1 : int bt_df_conn_cte_req_disable(struct bt_conn *conn);
342 :
343 : /**
344 : * @brief Enable Constant Tone Extension response procedure for a connection.
345 : *
346 : * The function is available if @kconfig{CONFIG_BT_DF_CONNECTION_CTE_RSP} is enabled.
347 : *
348 : * @param conn Connection object.
349 : *
350 : * @return Zero in case of success, other value in case of failure.
351 : */
352 1 : int bt_df_conn_cte_rsp_enable(struct bt_conn *conn);
353 :
354 : /**
355 : * @brief Disable Constant Tone Extension response procedure for a connection.
356 : *
357 : * The function is available if @kconfig{CONFIG_BT_DF_CONNECTION_CTE_RSP} is enabled.
358 : *
359 : * @param conn Connection object.
360 : *
361 : * @return Zero in case of success, other value in case of failure.
362 : */
363 1 : int bt_df_conn_cte_rsp_disable(struct bt_conn *conn);
364 :
365 : #endif /* ZEPHYR_INCLUDE_BLUETOOTH_DF_H_ */
|
