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