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 /** Constant Tone Extension (CTE) types. */ 11 enum bt_df_cte_type { 12 /** Convenience value for purposes where non of CTE types is allowed. */ 13 BT_DF_CTE_TYPE_NONE = 0, 14 /** Angle of Arrival mode. Antenna switching done on receiver site. */ 15 BT_DF_CTE_TYPE_AOA = BIT(0), 16 /** Angle of Departure mode with 1 us antenna switching slots. 17 * Antenna switching done on transmitter site. 18 */ 19 BT_DF_CTE_TYPE_AOD_1US = BIT(1), 20 /** Angle of Departure mode with 2 us antenna switching slots. 21 * Antenna switching done on transmitter site. 22 */ 23 BT_DF_CTE_TYPE_AOD_2US = BIT(2), 24 /** Convenience value that collects all possible CTE types in one entry. */ 25 BT_DF_CTE_TYPE_ALL = (BT_DF_CTE_TYPE_AOA | BT_DF_CTE_TYPE_AOD_1US | BT_DF_CTE_TYPE_AOD_2US) 26 }; 27 28 /** Allowed antenna switching slots: 1 us or 2 us */ 29 enum bt_df_antenna_switching_slot { 30 BT_DF_ANTENNA_SWITCHING_SLOT_1US = 0x1, 31 BT_DF_ANTENNA_SWITCHING_SLOT_2US = 0x2 32 }; 33 34 /** Possible statuses of PDU that contained reported CTE. */ 35 enum bt_df_packet_status { 36 /** Received PDU had CRC OK */ 37 BT_DF_CTE_CRC_OK = 0x0, 38 /** Received PDU had incorrect CRC, but Radio peripheral 39 * was able to parse CTEInfo field of the PDU and process 40 * sampling of CTE. 41 */ 42 BT_DF_CTE_CRC_ERR_CTE_BASED_TIME = 0x1, 43 /** Received PDU had incorrect CRC, but Radio peripheral 44 * was able to process sampling of CTE in some other way. 45 */ 46 BT_DF_CTE_CRC_ERR_CTE_BASED_OTHER = 0x2, 47 /** There were no sufficient resources to sample CTE. */ 48 BT_DF_CTE_INSUFFICIENT_RESOURCES = 0xFF 49 }; 50 51 /** @brief Constant Tone Extension parameters for connectionless 52 * transmission. 53 * 54 * The structure holds information required to setup CTE transmission 55 * in periodic advertising. 56 */ 57 struct bt_df_adv_cte_tx_param { 58 /** Length of CTE in 8us units. */ 59 uint8_t cte_len; 60 /** CTE Type: AoA, AoD 1us slots, AoD 2us slots. */ 61 uint8_t cte_type; 62 /** Number of CTE to transmit in each periodic adv interval. */ 63 uint8_t cte_count; 64 /** Number of Antenna IDs in the switch pattern. */ 65 uint8_t num_ant_ids; 66 /** List of antenna IDs in the pattern. */ 67 uint8_t *ant_ids; 68 }; 69 70 /** 71 * @brief Constant Tone Extension parameters for connectionless reception. 72 * 73 * @note cte_type is a bit field that provides information about type of CTE an application 74 * expects (@ref bt_df_cte_type). In case cte_type bit BT_DF_CTE_TYPE_AOA is not set, members: 75 * slot_durations, num_ant_ids and ant_ids are not required and their values will be not verified 76 * for correctness. 77 */ 78 struct bt_df_per_adv_sync_cte_rx_param { 79 /* Bitmap with allowed CTE types (@ref bt_df_cte_type). */ 80 uint8_t cte_type; 81 /** Antenna switching slots (@ref bt_df_antenna_switching_slot). */ 82 uint8_t slot_durations; 83 /** Max number of CTEs to receive. Min is 1, max is 10, 0 means receive continuously. */ 84 uint8_t max_cte_count; 85 /** Length of antenna switch pattern. */ 86 uint8_t num_ant_ids; 87 /** Antenna switch pattern. */ 88 const uint8_t *ant_ids; 89 }; 90 91 struct bt_df_per_adv_sync_iq_samples_report { 92 /** Channel index used to receive PDU with CTE that was sampled. */ 93 uint8_t chan_idx; 94 /** The RSSI of the PDU with CTE (excluding CTE). */ 95 int16_t rssi; 96 /** Id of antenna used to measure the RSSI. */ 97 uint8_t rssi_ant_id; 98 /** Type of CTE (@ref bt_df_cte_type). */ 99 uint8_t cte_type; 100 /** Duration of slots when received CTE type is AoA (@ref bt_df_antenna_switching_slot). */ 101 uint8_t slot_durations; 102 /** Status of received PDU with CTE (@ref bt_df_packet_status). */ 103 uint8_t packet_status; 104 /** Number of IQ samples in report. */ 105 uint8_t sample_count; 106 /** Pinter to IQ samples data. */ 107 struct bt_hci_le_iq_sample const *sample; 108 }; 109 110 /** 111 * @brief Set or update the Constant Tone Extension parameters for periodic advertising set. 112 * 113 * @param[in] adv Advertising set object. 114 * @param[in] params Constant Tone Extension parameters. 115 * 116 * @return Zero on success or (negative) error code otherwise. 117 */ 118 int bt_df_set_adv_cte_tx_param(struct bt_le_ext_adv *adv, 119 const struct bt_df_adv_cte_tx_param *params); 120 121 /** 122 * @brief Enable transmission of Constant Tone Extension for the given advertising set. 123 * 124 * Transmission of Constant Tone Extension may be enabled only after setting periodic advertising 125 * parameters (@ref bt_le_per_adv_set_param) and Constant Tone Extension parameters 126 * (@ref bt_df_set_adv_cte_tx_param). 127 * 128 * @param[in] adv Advertising set object. 129 * 130 * @return Zero on success or (negative) error code otherwise. 131 */ 132 int bt_df_adv_cte_tx_enable(struct bt_le_ext_adv *adv); 133 134 /** 135 * @brief Disable transmission of Constant Tone Extension for the given advertising set. 136 * 137 * @param[in] adv Advertising set object. 138 * 139 * @return Zero on success or (negative) error code otherwise. 140 */ 141 int bt_df_adv_cte_tx_disable(struct bt_le_ext_adv *adv); 142 143 /** 144 * @brief Enable receive and sampling of Constant Tone Extension for the given sync set. 145 * 146 * Receive and sampling of Constant Tone Extension may be enabled only after periodic advertising 147 * sync is established. 148 * 149 * @param sync Periodic advertising sync object. 150 * @param params CTE receive and sampling parameters. 151 * 152 * @return Zero on success or (negative) error code otherwise. 153 */ 154 int bt_df_per_adv_sync_cte_rx_enable(struct bt_le_per_adv_sync *sync, 155 const struct bt_df_per_adv_sync_cte_rx_param *params); 156 157 /** 158 * @brief Disable receive and sampling of Constant Tone Extension for the given sync set. 159 * 160 * @param sync Periodic advertising sync object. 161 * 162 * @return Zero on success or (negative) error code otherwise. 163 */ 164 int bt_df_per_adv_sync_cte_rx_disable(struct bt_le_per_adv_sync *sync); 165 166 #endif /* ZEPHYR_INCLUDE_BLUETOOTH_DF_H_ */ 167
