1 /* 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 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 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 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 struct bt_df_adv_cte_tx_param { 64 /** Length of CTE in 8us units. */ 65 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 uint8_t cte_type; 73 /** Number of CTE to transmit in each periodic adv interval. */ 74 uint8_t cte_count; 75 /** Number of Antenna IDs in the switch pattern. */ 76 uint8_t num_ant_ids; 77 /** List of antenna IDs in the pattern. */ 78 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 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 uint8_t cte_types; 96 /** Antenna switching slots (@ref bt_df_antenna_switching_slot). */ 97 uint8_t slot_durations; 98 /** Max number of CTEs to receive. Min is 1, max is 10, 0 means receive continuously. */ 99 uint8_t max_cte_count; 100 /** Length of antenna switch pattern. */ 101 uint8_t num_ant_ids; 102 /** Antenna switch pattern. */ 103 const uint8_t *ant_ids; 104 }; 105 106 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 struct bt_df_per_adv_sync_iq_samples_report { 116 /** Channel index used to receive PDU with CTE that was sampled. */ 117 uint8_t chan_idx; 118 /** The RSSI of the PDU with CTE (excluding CTE). Range: -1270 to +200. Units: 0.1 dBm. */ 119 int16_t rssi; 120 /** Id of antenna used to measure the RSSI. */ 121 uint8_t rssi_ant_id; 122 /** Type of CTE (@ref bt_df_cte_type). */ 123 uint8_t cte_type; 124 /** Duration of slots when received CTE type is AoA (@ref bt_df_antenna_switching_slot). */ 125 uint8_t slot_durations; 126 /** Status of received PDU with CTE (@ref bt_df_packet_status). */ 127 uint8_t packet_status; 128 /** Value of the paEventCounter of the AUX_SYNC_IND PDU. */ 129 uint16_t per_evt_counter; 130 /** Number of IQ samples in report. */ 131 uint8_t sample_count; 132 /** Type of IQ samples provided in a report. */ 133 enum bt_df_iq_sample sample_type; 134 /** Pointer to IQ samples data. */ 135 union { 136 struct bt_hci_le_iq_sample const *sample; 137 struct bt_hci_le_iq_sample16 const *sample16; 138 }; 139 }; 140 141 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 uint8_t cte_types; 148 /** Antenna switching slots (@ref bt_df_antenna_switching_slot). */ 149 uint8_t slot_durations; 150 /** Length of antenna switch pattern. */ 151 uint8_t num_ant_ids; 152 /** Antenna switch pattern. */ 153 const uint8_t *ant_ids; 154 }; 155 156 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 struct bt_df_conn_iq_samples_report { 166 /** Report receive failed reason. */ 167 enum bt_df_conn_iq_report_err err; 168 /** PHY that was used to receive PDU with CTE that was sampled. */ 169 uint8_t rx_phy; 170 /** Channel index used to receive PDU with CTE that was sampled. */ 171 uint8_t chan_idx; 172 /** The RSSI of the PDU with CTE (excluding CTE). Range: -1270 to +200. Units: 0.1 dBm. */ 173 int16_t rssi; 174 /** Id of antenna used to measure the RSSI. */ 175 uint8_t rssi_ant_id; 176 /** Type of CTE (@ref bt_df_cte_type). */ 177 uint8_t cte_type; 178 /** Duration of slots when received CTE type is AoA (@ref bt_df_antenna_switching_slot). */ 179 uint8_t slot_durations; 180 /** Status of received PDU with CTE (@ref bt_df_packet_status). */ 181 uint8_t packet_status; 182 /** Value of connection event counter when the CTE was received and sampled. */ 183 uint16_t conn_evt_counter; 184 /** Type of IQ samples provided in a report. */ 185 enum bt_df_iq_sample sample_type; 186 /** Number of IQ samples in report. */ 187 uint8_t sample_count; 188 /** Pointer to IQ samples data. */ 189 union { 190 struct bt_hci_le_iq_sample const *sample; 191 struct bt_hci_le_iq_sample16 const *sample16; 192 }; 193 }; 194 /** Constant Tone Extension parameters for CTE transmission in connected mode. */ 195 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 uint8_t cte_types; 201 /** Number of antenna switch pattern. */ 202 uint8_t num_ant_ids; 203 /** Antenna switch pattern. */ 204 const uint8_t *ant_ids; 205 }; 206 207 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 uint16_t interval; 215 /** Requested length of the CTE in 8 us units. */ 216 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 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 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 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 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 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 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 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 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 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 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 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 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 int bt_df_conn_cte_rsp_disable(struct bt_conn *conn); 361 362 #endif /* ZEPHYR_INCLUDE_BLUETOOTH_DF_H_ */ 363
