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