BluFi API
Overview
BluFi is a profile based GATT to config ESP32 Wi-Fi to connect/disconnect AP or setup a softap and etc.
Use should concern these things:
The event sent from profile. Then you need to do something as the event indicate.
Security reference. You can write your own Security functions such as symmetrical encryption/decryption and checksum functions. Even you can define the "Key Exchange/Negotiation" procedure.
Application Examples
bluetooth/blufi how to use the Blufi function to configure the Wi-Fi connection to an AP via a Bluetooth channel on ESP32.
API Reference
Header File
This header file can be included with:
#include "esp_blufi_api.h"
This header file is a part of the API provided by the
bt
component. To declare that your component depends onbt
, add the following to your CMakeLists.txt:REQUIRES bt
or
PRIV_REQUIRES bt
Functions
-
esp_err_t esp_blufi_register_callbacks(esp_blufi_callbacks_t *callbacks)
This function is called to receive blufi callback event.
- Parameters
callbacks -- [in] callback functions
- Returns
ESP_OK - success, other - failed
-
esp_err_t esp_blufi_profile_init(void)
This function is called to initialize blufi_profile.
- Returns
ESP_OK - success, other - failed
-
esp_err_t esp_blufi_profile_deinit(void)
This function is called to de-initialize blufi_profile.
- Returns
ESP_OK - success, other - failed
-
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)
This function is called to send wifi connection report.
- Parameters
opmode -- : wifi opmode
sta_conn_state -- : station is already in connection or not
softap_conn_num -- : softap connection number
extra_info -- : extra information, such as sta_ssid, softap_ssid and etc.
- Returns
ESP_OK - success, other - failed
-
esp_err_t esp_blufi_send_wifi_list(uint16_t apCount, esp_blufi_ap_record_t *list)
This function is called to send wifi list.
- Parameters
apCount -- : wifi list count
list -- : wifi list
- Returns
ESP_OK - success, other - failed
-
uint16_t esp_blufi_get_version(void)
Get BLUFI profile version.
- Returns
Most 8bit significant is Great version, Least 8bit is Sub version
-
esp_err_t esp_blufi_send_error_info(esp_blufi_error_state_t state)
This function is called to send blufi error information.
- Parameters
state -- : error state
- Returns
ESP_OK - success, other - failed
Unions
-
union esp_blufi_cb_param_t
- #include <esp_blufi_api.h>
BLUFI callback parameters union.
Public Members
-
struct esp_blufi_cb_param_t::blufi_init_finish_evt_param init_finish
Blufi callback param of ESP_BLUFI_EVENT_INIT_FINISH
-
struct esp_blufi_cb_param_t::blufi_deinit_finish_evt_param deinit_finish
Blufi callback param of ESP_BLUFI_EVENT_DEINIT_FINISH
-
struct esp_blufi_cb_param_t::blufi_set_wifi_mode_evt_param wifi_mode
Blufi callback param of ESP_BLUFI_EVENT_INIT_FINISH
-
struct esp_blufi_cb_param_t::blufi_connect_evt_param connect
Blufi callback param of ESP_BLUFI_EVENT_CONNECT
-
struct esp_blufi_cb_param_t::blufi_disconnect_evt_param disconnect
Blufi callback param of ESP_BLUFI_EVENT_DISCONNECT
-
struct esp_blufi_cb_param_t::blufi_recv_sta_bssid_evt_param sta_bssid
Blufi callback param of ESP_BLUFI_EVENT_RECV_STA_BSSID
-
struct esp_blufi_cb_param_t::blufi_recv_sta_ssid_evt_param sta_ssid
Blufi callback param of ESP_BLUFI_EVENT_RECV_STA_SSID
-
struct esp_blufi_cb_param_t::blufi_recv_sta_passwd_evt_param sta_passwd
Blufi callback param of ESP_BLUFI_EVENT_RECV_STA_PASSWD
-
struct esp_blufi_cb_param_t::blufi_recv_softap_ssid_evt_param softap_ssid
Blufi callback param of ESP_BLUFI_EVENT_RECV_SOFTAP_SSID
-
struct esp_blufi_cb_param_t::blufi_recv_softap_passwd_evt_param softap_passwd
Blufi callback param of ESP_BLUFI_EVENT_RECV_SOFTAP_PASSWD
-
struct esp_blufi_cb_param_t::blufi_recv_softap_max_conn_num_evt_param softap_max_conn_num
Blufi callback param of ESP_BLUFI_EVENT_RECV_SOFTAP_MAX_CONN_NUM
-
struct esp_blufi_cb_param_t::blufi_recv_softap_auth_mode_evt_param softap_auth_mode
Blufi callback param of ESP_BLUFI_EVENT_RECV_SOFTAP_AUTH_MODE
-
struct esp_blufi_cb_param_t::blufi_recv_softap_channel_evt_param softap_channel
Blufi callback param of ESP_BLUFI_EVENT_RECV_SOFTAP_CHANNEL
-
struct esp_blufi_cb_param_t::blufi_recv_username_evt_param username
Blufi callback param of ESP_BLUFI_EVENT_RECV_USERNAME
-
struct esp_blufi_cb_param_t::blufi_recv_ca_evt_param ca
Blufi callback param of ESP_BLUFI_EVENT_RECV_CA_CERT
-
struct esp_blufi_cb_param_t::blufi_recv_client_cert_evt_param client_cert
Blufi callback param of ESP_BLUFI_EVENT_RECV_CLIENT_CERT
-
struct esp_blufi_cb_param_t::blufi_recv_server_cert_evt_param server_cert
Blufi callback param of ESP_BLUFI_EVENT_RECV_SERVER_CERT
-
struct esp_blufi_cb_param_t::blufi_recv_client_pkey_evt_param client_pkey
Blufi callback param of ESP_BLUFI_EVENT_RECV_CLIENT_PRIV_KEY
-
struct esp_blufi_cb_param_t::blufi_recv_server_pkey_evt_param server_pkey
Blufi callback param of ESP_BLUFI_EVENT_RECV_SERVER_PRIV_KEY
-
struct esp_blufi_cb_param_t::blufi_get_error_evt_param report_error
Blufi callback param of ESP_BLUFI_EVENT_REPORT_ERROR
-
struct esp_blufi_cb_param_t::blufi_recv_custom_data_evt_param custom_data
Blufi callback param of ESP_BLUFI_EVENT_RECV_CUSTOM_DATA
-
struct blufi_connect_evt_param
- #include <esp_blufi_api.h>
ESP_BLUFI_EVENT_CONNECT.
Public Members
-
esp_blufi_bd_addr_t remote_bda
Blufi Remote bluetooth device address
-
uint8_t server_if
server interface
-
uint16_t conn_id
Connection id
-
esp_blufi_bd_addr_t remote_bda
-
struct blufi_deinit_finish_evt_param
- #include <esp_blufi_api.h>
ESP_BLUFI_EVENT_DEINIT_FINISH.
Public Members
-
esp_blufi_deinit_state_t state
De-initial status
-
esp_blufi_deinit_state_t state
-
struct blufi_disconnect_evt_param
- #include <esp_blufi_api.h>
ESP_BLUFI_EVENT_DISCONNECT.
Public Members
-
esp_blufi_bd_addr_t remote_bda
Blufi Remote bluetooth device address
-
esp_blufi_bd_addr_t remote_bda
-
struct blufi_get_error_evt_param
- #include <esp_blufi_api.h>
ESP_BLUFI_EVENT_REPORT_ERROR.
Public Members
-
esp_blufi_error_state_t state
Blufi error state
-
esp_blufi_error_state_t state
-
struct blufi_init_finish_evt_param
- #include <esp_blufi_api.h>
ESP_BLUFI_EVENT_INIT_FINISH.
Public Members
-
esp_blufi_init_state_t state
Initial status
-
esp_blufi_init_state_t state
-
struct blufi_recv_ca_evt_param
- #include <esp_blufi_api.h>
ESP_BLUFI_EVENT_RECV_CA_CERT.
-
struct blufi_recv_client_cert_evt_param
- #include <esp_blufi_api.h>
ESP_BLUFI_EVENT_RECV_CLIENT_CERT
-
struct blufi_recv_client_pkey_evt_param
- #include <esp_blufi_api.h>
ESP_BLUFI_EVENT_RECV_CLIENT_PRIV_KEY
-
struct blufi_recv_custom_data_evt_param
- #include <esp_blufi_api.h>
ESP_BLUFI_EVENT_RECV_CUSTOM_DATA.
-
struct blufi_recv_server_cert_evt_param
- #include <esp_blufi_api.h>
ESP_BLUFI_EVENT_RECV_SERVER_CERT
-
struct blufi_recv_server_pkey_evt_param
- #include <esp_blufi_api.h>
ESP_BLUFI_EVENT_RECV_SERVER_PRIV_KEY
-
struct blufi_recv_softap_auth_mode_evt_param
- #include <esp_blufi_api.h>
ESP_BLUFI_EVENT_RECV_SOFTAP_AUTH_MODE.
Public Members
-
wifi_auth_mode_t auth_mode
Authentication mode
-
wifi_auth_mode_t auth_mode
-
struct blufi_recv_softap_channel_evt_param
- #include <esp_blufi_api.h>
ESP_BLUFI_EVENT_RECV_SOFTAP_CHANNEL.
Public Members
-
uint8_t channel
Authentication mode
-
uint8_t channel
-
struct blufi_recv_softap_max_conn_num_evt_param
- #include <esp_blufi_api.h>
ESP_BLUFI_EVENT_RECV_SOFTAP_MAX_CONN_NUM.
Public Members
-
int max_conn_num
SSID
-
int max_conn_num
-
struct blufi_recv_softap_passwd_evt_param
- #include <esp_blufi_api.h>
ESP_BLUFI_EVENT_RECV_SOFTAP_PASSWD.
-
struct blufi_recv_softap_ssid_evt_param
- #include <esp_blufi_api.h>
ESP_BLUFI_EVENT_RECV_SOFTAP_SSID.
-
struct blufi_recv_sta_bssid_evt_param
- #include <esp_blufi_api.h>
ESP_BLUFI_EVENT_RECV_STA_BSSID.
Public Members
-
uint8_t bssid[6]
BSSID
-
uint8_t bssid[6]
-
struct blufi_recv_sta_passwd_evt_param
- #include <esp_blufi_api.h>
ESP_BLUFI_EVENT_RECV_STA_PASSWD.
-
struct blufi_recv_sta_ssid_evt_param
- #include <esp_blufi_api.h>
ESP_BLUFI_EVENT_RECV_STA_SSID.
-
struct blufi_recv_username_evt_param
- #include <esp_blufi_api.h>
ESP_BLUFI_EVENT_RECV_USERNAME.
-
struct esp_blufi_cb_param_t::blufi_init_finish_evt_param init_finish
Structures
-
struct esp_blufi_extra_info_t
BLUFI extra information structure.
Public Members
-
uint8_t sta_bssid[6]
BSSID of station interface
-
bool sta_bssid_set
is BSSID of station interface set
-
uint8_t *sta_ssid
SSID of station interface
-
int sta_ssid_len
length of SSID of station interface
-
uint8_t *sta_passwd
password of station interface
-
int sta_passwd_len
length of password of station interface
-
uint8_t *softap_ssid
SSID of softap interface
-
int softap_ssid_len
length of SSID of softap interface
-
uint8_t *softap_passwd
password of station interface
-
int softap_passwd_len
length of password of station interface
-
uint8_t softap_authmode
authentication mode of softap interface
-
bool softap_authmode_set
is authentication mode of softap interface set
-
uint8_t softap_max_conn_num
max connection number of softap interface
-
bool softap_max_conn_num_set
is max connection number of softap interface set
-
uint8_t softap_channel
channel of softap interface
-
bool softap_channel_set
is channel of softap interface set
-
uint8_t sta_max_conn_retry
max retry of sta establish connection
-
bool sta_max_conn_retry_set
is max retry of sta establish connection set
-
uint8_t sta_conn_end_reason
reason of sta connection end
-
bool sta_conn_end_reason_set
is reason of sta connection end set
-
int8_t sta_conn_rssi
rssi of sta connection
-
bool sta_conn_rssi_set
is rssi of sta connection set
-
uint8_t sta_bssid[6]
-
struct esp_blufi_ap_record_t
Description of an WiFi AP.
-
struct esp_blufi_callbacks_t
BLUFI callback functions type.
Public Members
-
esp_blufi_event_cb_t event_cb
BLUFI event callback
-
esp_blufi_negotiate_data_handler_t negotiate_data_handler
BLUFI negotiate data function for negotiate share key
-
esp_blufi_encrypt_func_t encrypt_func
BLUFI encrypt data function with share key generated by negotiate_data_handler
-
esp_blufi_decrypt_func_t decrypt_func
BLUFI decrypt data function with share key generated by negotiate_data_handler
-
esp_blufi_checksum_func_t checksum_func
BLUFI check sum function (FCS)
-
esp_blufi_event_cb_t event_cb
Macros
-
ESP_BLUFI_BD_ADDR_LEN
Bluetooth address length.
Type Definitions
-
typedef uint8_t esp_blufi_bd_addr_t[ESP_BLUFI_BD_ADDR_LEN]
Bluetooth device address.
-
typedef void (*esp_blufi_event_cb_t)(esp_blufi_cb_event_t event, esp_blufi_cb_param_t *param)
BLUFI event callback function type.
- Param event
: Event type
- Param param
: Point to callback parameter, currently is union type
-
typedef void (*esp_blufi_negotiate_data_handler_t)(uint8_t *data, int len, uint8_t **output_data, int *output_len, bool *need_free)
BLUFI negotiate data handler.
- Param data
: data from phone
- Param len
: length of data from phone
- Param output_data
: data want to send to phone
- Param output_len
: length of data want to send to phone
- Param need_free
: output reporting if memory needs to be freed or not *
-
typedef int (*esp_blufi_encrypt_func_t)(uint8_t iv8, uint8_t *crypt_data, int crypt_len)
BLUFI encrypt the data after negotiate a share key.
- Param iv8
: initial vector(8bit), normally, blufi core will input packet sequence number
- Param crypt_data
: plain text and encrypted data, the encrypt function must support autochthonous encrypt
- Param crypt_len
: length of plain text
- Return
Nonnegative number is encrypted length, if error, return negative number;
-
typedef int (*esp_blufi_decrypt_func_t)(uint8_t iv8, uint8_t *crypt_data, int crypt_len)
BLUFI decrypt the data after negotiate a share key.
- Param iv8
: initial vector(8bit), normally, blufi core will input packet sequence number
- Param crypt_data
: encrypted data and plain text, the encrypt function must support autochthonous decrypt
- Param crypt_len
: length of encrypted text
- Return
Nonnegative number is decrypted length, if error, return negative number;
-
typedef uint16_t (*esp_blufi_checksum_func_t)(uint8_t iv8, uint8_t *data, int len)
BLUFI checksum.
- Param iv8
: initial vector(8bit), normally, blufi core will input packet sequence number
- Param data
: data need to checksum
- Param len
: length of data
Enumerations
-
enum esp_blufi_cb_event_t
Values:
-
enumerator ESP_BLUFI_EVENT_INIT_FINISH
-
enumerator ESP_BLUFI_EVENT_DEINIT_FINISH
-
enumerator ESP_BLUFI_EVENT_SET_WIFI_OPMODE
-
enumerator ESP_BLUFI_EVENT_BLE_CONNECT
-
enumerator ESP_BLUFI_EVENT_BLE_DISCONNECT
-
enumerator ESP_BLUFI_EVENT_REQ_CONNECT_TO_AP
-
enumerator ESP_BLUFI_EVENT_REQ_DISCONNECT_FROM_AP
-
enumerator ESP_BLUFI_EVENT_GET_WIFI_STATUS
-
enumerator ESP_BLUFI_EVENT_DEAUTHENTICATE_STA
-
enumerator ESP_BLUFI_EVENT_RECV_STA_BSSID
-
enumerator ESP_BLUFI_EVENT_RECV_STA_SSID
-
enumerator ESP_BLUFI_EVENT_RECV_STA_PASSWD
-
enumerator ESP_BLUFI_EVENT_RECV_SOFTAP_SSID
-
enumerator ESP_BLUFI_EVENT_RECV_SOFTAP_PASSWD
-
enumerator ESP_BLUFI_EVENT_RECV_SOFTAP_MAX_CONN_NUM
-
enumerator ESP_BLUFI_EVENT_RECV_SOFTAP_AUTH_MODE
-
enumerator ESP_BLUFI_EVENT_RECV_SOFTAP_CHANNEL
-
enumerator ESP_BLUFI_EVENT_RECV_USERNAME
-
enumerator ESP_BLUFI_EVENT_RECV_CA_CERT
-
enumerator ESP_BLUFI_EVENT_RECV_CLIENT_CERT
-
enumerator ESP_BLUFI_EVENT_RECV_SERVER_CERT
-
enumerator ESP_BLUFI_EVENT_RECV_CLIENT_PRIV_KEY
-
enumerator ESP_BLUFI_EVENT_RECV_SERVER_PRIV_KEY
-
enumerator ESP_BLUFI_EVENT_RECV_SLAVE_DISCONNECT_BLE
-
enumerator ESP_BLUFI_EVENT_GET_WIFI_LIST
-
enumerator ESP_BLUFI_EVENT_REPORT_ERROR
-
enumerator ESP_BLUFI_EVENT_RECV_CUSTOM_DATA
-
enumerator ESP_BLUFI_EVENT_INIT_FINISH
-
enum esp_blufi_sta_conn_state_t
BLUFI config status.
Values:
-
enumerator ESP_BLUFI_STA_CONN_SUCCESS
-
enumerator ESP_BLUFI_STA_CONN_FAIL
-
enumerator ESP_BLUFI_STA_CONNECTING
-
enumerator ESP_BLUFI_STA_NO_IP
-
enumerator ESP_BLUFI_STA_CONN_SUCCESS
-
enum esp_blufi_init_state_t
BLUFI init status.
Values:
-
enumerator ESP_BLUFI_INIT_OK
-
enumerator ESP_BLUFI_INIT_FAILED
-
enumerator ESP_BLUFI_INIT_OK
-
enum esp_blufi_deinit_state_t
BLUFI deinit status.
Values:
-
enumerator ESP_BLUFI_DEINIT_OK
-
enumerator ESP_BLUFI_DEINIT_FAILED
-
enumerator ESP_BLUFI_DEINIT_OK
-
enum esp_blufi_error_state_t
Values:
-
enumerator ESP_BLUFI_SEQUENCE_ERROR
-
enumerator ESP_BLUFI_CHECKSUM_ERROR
-
enumerator ESP_BLUFI_DECRYPT_ERROR
-
enumerator ESP_BLUFI_ENCRYPT_ERROR
-
enumerator ESP_BLUFI_INIT_SECURITY_ERROR
-
enumerator ESP_BLUFI_DH_MALLOC_ERROR
-
enumerator ESP_BLUFI_DH_PARAM_ERROR
-
enumerator ESP_BLUFI_READ_PARAM_ERROR
-
enumerator ESP_BLUFI_MAKE_PUBLIC_ERROR
-
enumerator ESP_BLUFI_DATA_FORMAT_ERROR
-
enumerator ESP_BLUFI_CALC_MD5_ERROR
-
enumerator ESP_BLUFI_WIFI_SCAN_FAIL
-
enumerator ESP_BLUFI_MSG_STATE_ERROR
-
enumerator ESP_BLUFI_SEQUENCE_ERROR