1 /* 2 * Copyright (c) 2022 Winner Microelectronics Co., Ltd. All rights reserved. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16 /** 17 * @file wm_ble.h 18 * 19 * @brief Bluetooth API 20 * 21 * @author WinnerMicro 22 * 23 * Copyright (c) 2020 Winner Microelectronics Co., Ltd. 24 */ 25 #ifndef WM_BLE_H 26 #define WM_BLE_H 27 28 #include "wm_bt_def.h" 29 30 /** 31 * @defgroup BT_APIs Bluetooth APIs 32 * @brief Bluetooth related APIs 33 */ 34 35 /** 36 * @addtogroup BT_APIs 37 * @{ 38 */ 39 40 /** 41 * @defgroup BLE_APIs BLE APIs 42 * @brief BLE APIs 43 */ 44 45 /** 46 * @addtogroup BLE_APIs 47 * @{ 48 */ 49 50 /** 51 * @brief initialize the application callback function 52 * 53 * @param[in] *p_callback pointer on callback function 54 * 55 * @return @ref tls_bt_status_t 56 * 57 * @note None 58 */ 59 tls_bt_status_t tls_ble_dm_init(tls_ble_dm_callback_t callback); 60 61 /** 62 * @brief start/stop ble advertisement 63 * 64 * @param[in] start 1 connectable and discoverable; 2 disconnectable and discoverable; 0 stop 65 * 66 * @return @ref tls_bt_status_t 67 * 68 * @note None 69 */ 70 tls_bt_status_t tls_ble_adv(uint8_t adv_state); 71 72 /** 73 * @brief configure the advertisment content 74 * 75 * @param[in] *data @ref btif_dm_adv_data_t 76 * 77 * @retval @ref tls_bt_status_t 78 * 79 * @note if pure_data equals to true, the filed of manufacturer equals to all fileds of advetisement data. 80 * otherwise, the filed manufacturer will be advertised in 0xFF filed. 81 * 82 */ 83 tls_bt_status_t tls_ble_set_adv_data(tls_ble_dm_adv_data_t *data); 84 85 /** 86 * @brief configure the advertisment parameters 87 * 88 * @param[in] *param @ref btif_dm_adv_param_t 89 * 90 * @retval @ref tls_bt_status_t 91 * 92 * @note None 93 */ 94 tls_bt_status_t tls_ble_set_adv_param(tls_ble_dm_adv_param_t *param); 95 96 /** 97 * @brief configure the advertisment extented parameters 98 * 99 * @param[in] *param @ref tls_ble_dm_adv_ext_param_t 100 * 101 * @retval @ref tls_bt_status_t 102 * 103 * @note if you know how to config all the parameters, you can use this function; 104 * otherwise, tls_ble_set_adv_param will be recommanded strongly; 105 */ 106 tls_bt_status_t tls_ble_set_adv_ext_param(tls_ble_dm_adv_ext_param_t *param); 107 108 /** 109 * @brief start/stop ble scan 110 * 111 * @param[in] start TRUE enable; FALSE disable 112 * 113 * @retval @ref tls_bt_status_t 114 * 115 * @note None 116 */ 117 tls_bt_status_t tls_ble_scan(bool start); 118 119 /** 120 * @brief configure the scan parameters 121 * 122 * @param[in] window scan window size 123 * @param[in] interval scan interval length 124 * @param[in] scan mode 0 passive scan; 1 active scan; 125 * 126 * @retval @ref tls_bt_status_t 127 * 128 * @note interval should greater or equals to windows, 129 * both range should be within (0x0004, 0x4000) 130 */ 131 tls_bt_status_t tls_ble_set_scan_param(int window, int interval, uint8_t scan_mode); 132 133 /** 134 * @brief enable a async process evt 135 * 136 * @param[in] id user specific definition 137 * @param[in] *p_callback callback function 138 * 139 * @return @ref tls_bt_status_t 140 * 141 * @note None 142 */ 143 tls_bt_status_t tls_dm_evt_triger(int id, tls_ble_dm_triger_callback_t callback); 144 145 /** 146 * @brief configure the max transmit unit 147 * 148 * @param[in] *bd_addr the remote device address 149 * @param[in] length range [27 - 251] 150 * 151 * @return @ref tls_bt_status_t 152 * 153 * @note None 154 */ 155 tls_bt_status_t tls_dm_set_data_length(tls_bt_addr_t *bd_addr, uint16_t length); 156 157 /** 158 * @brief configure the ble privacy 159 * 160 * @param[in] enable TRUE: using rpa/random address, updated every 15 mins 161 ** FALSE: public address 162 * 163 * @return @ref tls_bt_status_t 164 * 165 * @note None 166 */ 167 tls_bt_status_t tls_dm_set_privacy(uint8_t enable); 168 169 /** 170 * @brief update the connection parameters 171 * 172 * @param[in] *bd_addr remote device address 173 * @param[in] min_interval 174 * @param[in] max_interval 175 * @param[in] latency 176 * @param[in] timeout 177 * 178 * @return @ref tls_bt_status_t 179 * 180 * @note None 181 */ 182 tls_bt_status_t tls_ble_conn_parameter_update(const tls_bt_addr_t *bd_addr, 183 int min_interval, 184 int max_interval, 185 int latency, 186 int timeout); 187 188 /** 189 * @brief read the remote device signal strength connected 190 * 191 * @param[in] *bd_addr remote device address 192 * 193 * @return @ref tls_bt_status_t 194 * 195 * @note None 196 */ 197 tls_bt_status_t tls_dm_read_remote_rssi(const tls_bt_addr_t *bd_addr); 198 199 /** 200 * @brief config the io capabilities of local device 201 * 202 * @param[in] io_cap 203 * 204 * @return @ref tls_bt_status_t 205 * 206 * @note None 207 */ 208 209 tls_bt_status_t tls_ble_set_sec_io_cap(uint8_t io_cap); 210 211 /** 212 * @brief config the auth requirement of local device 213 * 214 * @param[in] auth_req 215 * 216 * @return @ref tls_bt_status_t 217 * 218 * @note None 219 */ 220 221 tls_bt_status_t tls_ble_set_sec_auth_req(uint8_t auth_req); 222 223 /** 224 * @brief This function is called to ensure that connection is 225 * encrypted. Should be called only on an open connection. 226 * Typically only needed for connections that first want to 227 * bring up unencrypted links, then later encrypt them. 228 229 * @param[in]sec_act - This is the security action to indicate 230 * what knid of BLE security level is required for 231 * the BLE link if the BLE is supported 232 * @param[in]bd_addr - Address of the peer device 233 * @ref tls_bt_status_t 234 * 235 * @note None 236 */ 237 238 tls_bt_status_t tls_ble_set_sec(const tls_bt_addr_t *bd_addr, uint8_t sec_act); 239 240 /** 241 * @brief only used to start/stop ble advertisement 242 * 243 * @param[in] start 1 start advertisement; 0 stop advertisement; 244 * @param[in] duration valid for start advertisement. 0 for forever, otherwise the last seconds of advertisement 245 * 246 * @return @ref tls_bt_status_t 247 * 248 * @note None 249 */ 250 251 tls_bt_status_t tls_ble_gap_adv(uint8_t start, int duration); 252 253 /** 254 * @} 255 */ 256 257 /** 258 * @} 259 */ 260 261 #endif /* WM_BLE_H */ 262 263