1 // Copyright 2015-2016 Espressif Systems (Shanghai) PTE LTD 2 // 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 #ifndef __ESP_BLUFI_API_H__ 16 #define __ESP_BLUFI_API_H__ 17 18 #include "esp_err.h" 19 #include "esp_wifi_types.h" 20 21 #ifdef __cplusplus 22 extern "C" { 23 #endif 24 25 typedef enum { 26 ESP_BLUFI_EVENT_INIT_FINISH = 0, /*<! When BLUFI init complete, this event happen */ 27 ESP_BLUFI_EVENT_DEINIT_FINISH, /*<! When BLUFI deinit complete, this event happen */ 28 ESP_BLUFI_EVENT_SET_WIFI_OPMODE, /*<! When Phone set ESP32 wifi operation mode(AP/STA/AP_STA), this event happen */ 29 ESP_BLUFI_EVENT_BLE_CONNECT, /*<! When Phone connect to ESP32 with BLE, this event happen */ 30 ESP_BLUFI_EVENT_BLE_DISCONNECT, /*<! When Phone disconnect with BLE, this event happen */ 31 ESP_BLUFI_EVENT_REQ_CONNECT_TO_AP, /*<! When Phone request ESP32's STA connect to AP, this event happen */ 32 ESP_BLUFI_EVENT_REQ_DISCONNECT_FROM_AP, /*<! When Phone request ESP32's STA disconnect from AP, this event happen */ 33 ESP_BLUFI_EVENT_GET_WIFI_STATUS, /*<! When Phone get ESP32 wifi status, this event happen */ 34 ESP_BLUFI_EVENT_DEAUTHENTICATE_STA, /*<! When Phone deauthenticate sta from SOFTAP, this event happen */ 35 /* recv data */ 36 ESP_BLUFI_EVENT_RECV_STA_BSSID, /*<! When Phone send STA BSSID to ESP32 to connect, this event happen */ 37 ESP_BLUFI_EVENT_RECV_STA_SSID, /*<! When Phone send STA SSID to ESP32 to connect, this event happen */ 38 ESP_BLUFI_EVENT_RECV_STA_PASSWD, /*<! When Phone send STA PASSWORD to ESP32 to connect, this event happen */ 39 ESP_BLUFI_EVENT_RECV_SOFTAP_SSID, /*<! When Phone send SOFTAP SSID to ESP32 to start SOFTAP, this event happen */ 40 ESP_BLUFI_EVENT_RECV_SOFTAP_PASSWD, /*<! When Phone send SOFTAP PASSWORD to ESP32 to start SOFTAP, this event happen */ 41 ESP_BLUFI_EVENT_RECV_SOFTAP_MAX_CONN_NUM, /*<! When Phone send SOFTAP max connection number to ESP32 to start SOFTAP, this event happen */ 42 ESP_BLUFI_EVENT_RECV_SOFTAP_AUTH_MODE, /*<! When Phone send SOFTAP authentication mode to ESP32 to start SOFTAP, this event happen */ 43 ESP_BLUFI_EVENT_RECV_SOFTAP_CHANNEL, /*<! When Phone send SOFTAP channel to ESP32 to start SOFTAP, this event happen */ 44 ESP_BLUFI_EVENT_RECV_USERNAME, /*<! When Phone send username to ESP32, this event happen */ 45 ESP_BLUFI_EVENT_RECV_CA_CERT, /*<! When Phone send CA certificate to ESP32, this event happen */ 46 ESP_BLUFI_EVENT_RECV_CLIENT_CERT, /*<! When Phone send Client certificate to ESP32, this event happen */ 47 ESP_BLUFI_EVENT_RECV_SERVER_CERT, /*<! When Phone send Server certificate to ESP32, this event happen */ 48 ESP_BLUFI_EVENT_RECV_CLIENT_PRIV_KEY, /*<! When Phone send Client Private key to ESP32, this event happen */ 49 ESP_BLUFI_EVENT_RECV_SERVER_PRIV_KEY, /*<! When Phone send Server Private key to ESP32, this event happen */ 50 ESP_BLUFI_EVENT_RECV_SLAVE_DISCONNECT_BLE, /*<! When Phone send Disconnect key to ESP32, this event happen */ 51 ESP_BLUFI_EVENT_GET_WIFI_LIST, /*<! When Phone send get wifi list command to ESP32, this event happen */ 52 ESP_BLUFI_EVENT_REPORT_ERROR, /*<! When Blufi report error, this event happen */ 53 ESP_BLUFI_EVENT_RECV_CUSTOM_DATA, /*<! When Phone send custom data to ESP32, this event happen */ 54 } esp_blufi_cb_event_t; 55 56 /// BLUFI config status 57 typedef enum { 58 ESP_BLUFI_STA_CONN_SUCCESS = 0x00, 59 ESP_BLUFI_STA_CONN_FAIL = 0x01, 60 } esp_blufi_sta_conn_state_t; 61 62 /// BLUFI init status 63 typedef enum { 64 ESP_BLUFI_INIT_OK = 0, 65 ESP_BLUFI_INIT_FAILED, 66 } esp_blufi_init_state_t; 67 68 /// BLUFI deinit status 69 typedef enum { 70 ESP_BLUFI_DEINIT_OK = 0, 71 ESP_BLUFI_DEINIT_FAILED, 72 } esp_blufi_deinit_state_t; 73 74 typedef enum { 75 ESP_BLUFI_SEQUENCE_ERROR = 0, 76 ESP_BLUFI_CHECKSUM_ERROR, 77 ESP_BLUFI_DECRYPT_ERROR, 78 ESP_BLUFI_ENCRYPT_ERROR, 79 ESP_BLUFI_INIT_SECURITY_ERROR, 80 ESP_BLUFI_DH_MALLOC_ERROR, 81 ESP_BLUFI_DH_PARAM_ERROR, 82 ESP_BLUFI_READ_PARAM_ERROR, 83 ESP_BLUFI_MAKE_PUBLIC_ERROR, 84 ESP_BLUFI_DATA_FORMAT_ERROR, 85 } esp_blufi_error_state_t; 86 87 /** 88 * @brief BLUFI extra information structure 89 */ 90 typedef struct { 91 //station 92 uint8_t sta_bssid[6]; /*!< BSSID of station interface */ 93 bool sta_bssid_set; /*!< is BSSID of station interface set */ 94 uint8_t *sta_ssid; /*!< SSID of station interface */ 95 int sta_ssid_len; /*!< length of SSID of station interface */ 96 uint8_t *sta_passwd; /*!< password of station interface */ 97 int sta_passwd_len; /*!< length of password of station interface */ 98 uint8_t *softap_ssid; /*!< SSID of softap interface */ 99 int softap_ssid_len; /*!< length of SSID of softap interface */ 100 uint8_t *softap_passwd; /*!< password of station interface */ 101 int softap_passwd_len; /*!< length of password of station interface */ 102 uint8_t softap_authmode; /*!< authentication mode of softap interface */ 103 bool softap_authmode_set; /*!< is authentication mode of softap interface set */ 104 uint8_t softap_max_conn_num; /*!< max connection number of softap interface */ 105 bool softap_max_conn_num_set; /*!< is max connection number of softap interface set */ 106 uint8_t softap_channel; /*!< channel of softap interface */ 107 bool softap_channel_set; /*!< is channel of softap interface set */ 108 } esp_blufi_extra_info_t; 109 110 /** @brief Description of an WiFi AP */ 111 typedef struct { 112 uint8_t ssid[33]; /**< SSID of AP */ 113 int8_t rssi; /**< signal strength of AP */ 114 } esp_blufi_ap_record_t; 115 116 /// Bluetooth address length 117 #define ESP_BD_ADDR_LEN 6 118 /// Bluetooth device address 119 typedef uint8_t esp_bd_addr_t[ESP_BD_ADDR_LEN]; 120 121 /** 122 * @brief BLUFI callback parameters union 123 */ 124 typedef union { 125 /** 126 * @brief ESP_BLUFI_EVENT_INIT_FINISH 127 */ 128 struct blufi_init_finish_evt_param { 129 esp_blufi_init_state_t state; /*!< Initial status */ 130 } init_finish; /*!< Blufi callback param of ESP_BLUFI_EVENT_INIT_FINISH */ 131 132 /** 133 * @brief ESP_BLUFI_EVENT_DEINIT_FINISH 134 */ 135 struct blufi_deinit_finish_evt_param { 136 esp_blufi_deinit_state_t state; /*!< De-initial status */ 137 } deinit_finish; /*!< Blufi callback param of ESP_BLUFI_EVENT_DEINIT_FINISH */ 138 139 /** 140 * @brief ESP_BLUFI_EVENT_SET_WIFI_MODE 141 */ 142 struct blufi_set_wifi_mode_evt_param { 143 wifi_mode_t op_mode; /*!< Wifi operation mode */ 144 } wifi_mode; /*!< Blufi callback param of ESP_BLUFI_EVENT_INIT_FINISH */ 145 146 /** 147 * @brief ESP_BLUFI_EVENT_CONNECT 148 */ 149 struct blufi_connect_evt_param { 150 esp_bd_addr_t remote_bda; /*!< Blufi Remote bluetooth device address */ 151 uint8_t server_if; /*!< server interface */ 152 uint16_t conn_id; /*!< Connection id */ 153 } connect; /*!< Blufi callback param of ESP_BLUFI_EVENT_CONNECT */ 154 155 /** 156 * @brief ESP_BLUFI_EVENT_DISCONNECT 157 */ 158 struct blufi_disconnect_evt_param { 159 esp_bd_addr_t remote_bda; /*!< Blufi Remote bluetooth device address */ 160 } disconnect; /*!< Blufi callback param of ESP_BLUFI_EVENT_DISCONNECT */ 161 162 /* ESP_BLUFI_EVENT_REQ_WIFI_CONNECT */ /* No callback param */ 163 /* ESP_BLUFI_EVENT_REQ_WIFI_DISCONNECT */ /* No callback param */ 164 165 /** 166 * @brief ESP_BLUFI_EVENT_RECV_STA_BSSID 167 */ 168 struct blufi_recv_sta_bssid_evt_param { 169 uint8_t bssid[6]; /*!< BSSID */ 170 } sta_bssid; /*!< Blufi callback param of ESP_BLUFI_EVENT_RECV_STA_BSSID */ 171 172 /** 173 * @brief ESP_BLUFI_EVENT_RECV_STA_SSID 174 */ 175 struct blufi_recv_sta_ssid_evt_param { 176 uint8_t *ssid; /*!< SSID */ 177 int ssid_len; /*!< SSID length */ 178 } sta_ssid; /*!< Blufi callback param of ESP_BLUFI_EVENT_RECV_STA_SSID */ 179 180 /** 181 * @brief 182 * ESP_BLUFI_EVENT_RECV_STA_PASSWD 183 */ 184 struct blufi_recv_sta_passwd_evt_param { 185 uint8_t *passwd; /*!< Password */ 186 int passwd_len; /*!< Password Length */ 187 } sta_passwd; /*!< Blufi callback param of ESP_BLUFI_EVENT_RECV_STA_PASSWD */ 188 189 /** 190 * @brief ESP_BLUFI_EVENT_RECV_SOFTAP_SSID 191 */ 192 struct blufi_recv_softap_ssid_evt_param { 193 uint8_t *ssid; /*!< SSID */ 194 int ssid_len; /*!< SSID length */ 195 } softap_ssid; /*!< Blufi callback param of ESP_BLUFI_EVENT_RECV_SOFTAP_SSID */ 196 197 /** 198 * @brief 199 * ESP_BLUFI_EVENT_RECV_SOFTAP_PASSWD 200 */ 201 struct blufi_recv_softap_passwd_evt_param { 202 uint8_t *passwd; /*!< Password */ 203 int passwd_len; /*!< Password Length */ 204 } softap_passwd; /*!< Blufi callback param of ESP_BLUFI_EVENT_RECV_SOFTAP_PASSWD */ 205 206 /** 207 * @brief ESP_BLUFI_EVENT_RECV_SOFTAP_MAX_CONN_NUM 208 */ 209 struct blufi_recv_softap_max_conn_num_evt_param { 210 int max_conn_num; /*!< SSID */ 211 } softap_max_conn_num; /*!< Blufi callback param of ESP_BLUFI_EVENT_RECV_SOFTAP_MAX_CONN_NUM */ 212 213 /** 214 * @brief 215 * ESP_BLUFI_EVENT_RECV_SOFTAP_AUTH_MODE 216 */ 217 struct blufi_recv_softap_auth_mode_evt_param { 218 wifi_auth_mode_t auth_mode; /*!< Authentication mode */ 219 } softap_auth_mode; /*!< Blufi callback param of ESP_BLUFI_EVENT_RECV_SOFTAP_AUTH_MODE */ 220 221 /** 222 * @brief 223 * ESP_BLUFI_EVENT_RECV_SOFTAP_CHANNEL 224 */ 225 struct blufi_recv_softap_channel_evt_param { 226 uint8_t channel; /*!< Authentication mode */ 227 } softap_channel; /*!< Blufi callback param of ESP_BLUFI_EVENT_RECV_SOFTAP_CHANNEL */ 228 229 /** 230 * @brief ESP_BLUFI_EVENT_RECV_USERNAME 231 */ 232 struct blufi_recv_username_evt_param { 233 uint8_t *name; /*!< Username point */ 234 int name_len; /*!< Username length */ 235 } username; /*!< Blufi callback param of ESP_BLUFI_EVENT_RECV_USERNAME*/ 236 237 /** 238 * @brief ESP_BLUFI_EVENT_RECV_CA_CERT 239 */ 240 struct blufi_recv_ca_evt_param { 241 uint8_t *cert; /*!< CA certificate point */ 242 int cert_len; /*!< CA certificate length */ 243 } ca; /*!< Blufi callback param of ESP_BLUFI_EVENT_RECV_CA_CERT */ 244 245 /** 246 * ESP_BLUFI_EVENT_RECV_CLIENT_CERT 247 */ 248 struct blufi_recv_client_cert_evt_param { 249 uint8_t *cert; /*!< Client certificate point */ 250 int cert_len; /*!< Client certificate length */ 251 } client_cert; /*!< Blufi callback param of ESP_BLUFI_EVENT_RECV_CLIENT_CERT */ 252 253 /** 254 * ESP_BLUFI_EVENT_RECV_SERVER_CERT 255 */ 256 struct blufi_recv_server_cert_evt_param { 257 uint8_t *cert; /*!< Client certificate point */ 258 int cert_len; /*!< Client certificate length */ 259 } server_cert; /*!< Blufi callback param of ESP_BLUFI_EVENT_RECV_SERVER_CERT */ 260 261 /** 262 * ESP_BLUFI_EVENT_RECV_CLIENT_PRIV_KEY 263 */ 264 struct blufi_recv_client_pkey_evt_param { 265 uint8_t *pkey; /*!< Client Private Key point, if Client certificate not contain Key */ 266 int pkey_len; /*!< Client Private key length */ 267 } client_pkey; /*!< Blufi callback param of ESP_BLUFI_EVENT_RECV_CLIENT_PRIV_KEY */ 268 /** 269 * ESP_BLUFI_EVENT_RECV_SERVER_PRIV_KEY 270 */ 271 struct blufi_recv_server_pkey_evt_param { 272 uint8_t *pkey; /*!< Client Private Key point, if Client certificate not contain Key */ 273 int pkey_len; /*!< Client Private key length */ 274 } server_pkey; /*!< Blufi callback param of ESP_BLUFI_EVENT_RECV_SERVER_PRIV_KEY */ 275 /** 276 * @brief 277 * ESP_BLUFI_EVENT_REPORT_ERROR 278 */ 279 struct blufi_get_error_evt_param { 280 esp_blufi_error_state_t state; /*!< Blufi error state */ 281 } report_error; /*!< Blufi callback param of ESP_BLUFI_EVENT_REPORT_ERROR */ 282 /** 283 * @brief 284 * ESP_BLUFI_EVENT_RECV_CUSTOM_DATA 285 */ 286 struct blufi_recv_custom_data_evt_param { 287 uint8_t *data; /*!< Custom data */ 288 uint32_t data_len; /*!< Custom data Length */ 289 } custom_data; /*!< Blufi callback param of ESP_BLUFI_EVENT_RECV_CUSTOM_DATA */ 290 } esp_blufi_cb_param_t; 291 292 /** 293 * @brief BLUFI event callback function type 294 * @param event : Event type 295 * @param param : Point to callback parameter, currently is union type 296 */ 297 typedef void (* esp_blufi_event_cb_t)(esp_blufi_cb_event_t event, esp_blufi_cb_param_t *param); 298 299 /* security function declare */ 300 301 /** 302 * @brief BLUFI negotiate data handler 303 * @param data : data from phone 304 * @param len : length of data from phone 305 * @param output_data : data want to send to phone 306 * @param output_len : length of data want to send to phone 307 * @param need_free : output reporting if memory needs to be freed or not * 308 */ 309 typedef void (*esp_blufi_negotiate_data_handler_t)(uint8_t *data, int len, uint8_t **output_data, int *output_len, bool *need_free); 310 311 /** 312 * @brief BLUFI encrypt the data after negotiate a share key 313 * @param iv8 : initial vector(8bit), normally, blufi core will input packet sequence number 314 * @param crypt_data : plain text and encrypted data, the encrypt function must support autochthonous encrypt 315 * @param crypt_len : length of plain text 316 * @return Nonnegative number is encrypted length, if error, return negative number; 317 */ 318 typedef int (* esp_blufi_encrypt_func_t)(uint8_t iv8, uint8_t *crypt_data, int crypt_len); 319 320 /** 321 * @brief BLUFI decrypt the data after negotiate a share key 322 * @param iv8 : initial vector(8bit), normally, blufi core will input packet sequence number 323 * @param crypt_data : encrypted data and plain text, the encrypt function must support autochthonous decrypt 324 * @param crypt_len : length of encrypted text 325 * @return Nonnegative number is decrypted length, if error, return negative number; 326 */ 327 typedef int (* esp_blufi_decrypt_func_t)(uint8_t iv8, uint8_t *crypt_data, int crypt_len); 328 329 /** 330 * @brief BLUFI checksum 331 * @param iv8 : initial vector(8bit), normally, blufi core will input packet sequence number 332 * @param data : data need to checksum 333 * @param len : length of data 334 */ 335 typedef uint16_t (*esp_blufi_checksum_func_t)(uint8_t iv8, uint8_t *data, int len); 336 337 /** 338 * @brief BLUFI callback functions type 339 */ 340 typedef struct { 341 esp_blufi_event_cb_t event_cb; /*!< BLUFI event callback */ 342 esp_blufi_negotiate_data_handler_t negotiate_data_handler; /*!< BLUFI negotiate data function for negotiate share key */ 343 esp_blufi_encrypt_func_t encrypt_func; /*!< BLUFI encrypt data function with share key generated by negotiate_data_handler */ 344 esp_blufi_decrypt_func_t decrypt_func; /*!< BLUFI decrypt data function with share key generated by negotiate_data_handler */ 345 esp_blufi_checksum_func_t checksum_func; /*!< BLUFI check sum function (FCS) */ 346 } esp_blufi_callbacks_t; 347 348 /** 349 * 350 * @brief This function is called to receive blufi callback event 351 * 352 * @param[in] callbacks: callback functions 353 * 354 * @return ESP_OK - success, other - failed 355 * 356 */ 357 esp_err_t esp_blufi_register_callbacks(esp_blufi_callbacks_t *callbacks); 358 359 /** 360 * 361 * @brief This function is called to initialize blufi_profile 362 * 363 * @return ESP_OK - success, other - failed 364 * 365 */ 366 esp_err_t esp_blufi_profile_init(void); 367 368 /** 369 * 370 * @brief This function is called to de-initialize blufi_profile 371 * 372 * @return ESP_OK - success, other - failed 373 * 374 */ 375 esp_err_t esp_blufi_profile_deinit(void); 376 377 /** 378 * 379 * @brief This function is called to send wifi connection report 380 * @param opmode : wifi opmode 381 * @param sta_conn_state : station is already in connection or not 382 * @param softap_conn_num : softap connection number 383 * @param extra_info : extra information, such as sta_ssid, softap_ssid and etc. 384 * 385 * @return ESP_OK - success, other - failed 386 * 387 */ 388 esp_err_t esp_blufi_send_wifi_conn_report(wifi_mode_t opmode, esp_blufi_sta_conn_state_t sta_conn_state, uint8_t softap_conn_num, esp_blufi_extra_info_t *extra_info); 389 390 /** 391 * 392 * @brief This function is called to send wifi list 393 * @param apCount : wifi list count 394 * @param list : wifi list 395 * 396 * @return ESP_OK - success, other - failed 397 * 398 */ 399 esp_err_t esp_blufi_send_wifi_list(uint16_t apCount, esp_blufi_ap_record_t *list); 400 401 /** 402 * 403 * @brief Get BLUFI profile version 404 * 405 * @return Most 8bit significant is Great version, Least 8bit is Sub version 406 * 407 */ 408 uint16_t esp_blufi_get_version(void); 409 410 /** 411 * 412 * @brief This function is called to send blufi error information 413 * @param state : error state 414 * 415 * @return ESP_OK - success, other - failed 416 * 417 */ 418 esp_err_t esp_blufi_send_error_info(esp_blufi_error_state_t state); 419 /** 420 * 421 * @brief This function is called to custom data 422 * @param data : custom data value 423 * @param data_len : the length of custom data 424 * 425 * @return ESP_OK - success, other - failed 426 * 427 */ 428 esp_err_t esp_blufi_send_custom_data(uint8_t *data, uint32_t data_len); 429 #ifdef __cplusplus 430 } 431 #endif 432 433 #endif /* _ESP_BLUFI_API_ */ 434
