BLUFI API¶
Overview¶
BLUFI is a profile based GATT to config ESP32 WIFI 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 Example¶
Check bluetooth/bluedroid/ble folder in ESP-IDF examples, which contains the following application:
- This is the BLUFI demo. This demo can set ESP32’s wifi to softap/station/softap&station mode and config wifi connections - bluetooth/bluedroid/ble/blufi
API Reference¶
Functions¶
-
esp_err_t
esp_blufi_register_callbacks
(esp_blufi_callbacks_t *callbacks)¶ This function is called to receive blufi callback event.
- Return
- ESP_OK - success, other - failed
- Parameters
callbacks
: callback functions
-
esp_err_t
esp_blufi_profile_init
(void)¶ This function is called to initialize blufi_profile.
- Return
- ESP_OK - success, other - failed
-
esp_err_t
esp_blufi_profile_deinit
(void)¶ This function is called to de-initialize blufi_profile.
- Return
- 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.
- Return
- ESP_OK - success, other - failed
- Parameters
opmode
: : wifi opmodesta_conn_state
: : station is already in connection or notsoftap_conn_num
: : softap connection numberextra_info
: : extra information, such as sta_ssid, softap_ssid and etc.
-
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.
- Return
- ESP_OK - success, other - failed
- Parameters
apCount
: : wifi list countlist
: : wifi list
-
uint16_t
esp_blufi_get_version
(void)¶ Get BLUFI profile version.
- Return
- Most 8bit significant is Great version, Least 8bit is Sub version
-
esp_err_t
esp_blufi_close
(esp_gatt_if_t gatts_if, uint16_t conn_id)¶ Close a connection a remote device.
- Return
- ESP_OK : success
- other : failed
- Parameters
gatts_if
: GATT server access interfaceconn_id
: connection ID to be closed.
-
esp_err_t
esp_blufi_send_error_info
(esp_blufi_error_state_t state)¶ This function is called to send blufi error information.
- Return
- ESP_OK - success, other - failed
- Parameters
state
: : error state
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_bd_addr_t
remote_bda
¶ Blufi Remote bluetooth device address
-
uint8_t
server_if
¶ server interface
-
uint16_t
conn_id
¶ Connection id
-
esp_bd_addr_t
-
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
-
struct
blufi_disconnect_evt_param
¶ - #include <esp_blufi_api.h>
ESP_BLUFI_EVENT_DISCONNECT.
Public Members
-
esp_bd_addr_t
remote_bda
¶ Blufi Remote bluetooth device address
-
esp_bd_addr_t
-
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
-
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
-
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
-
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
-
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
-
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
-
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
blufi_set_wifi_mode_evt_param
¶ - #include <esp_blufi_api.h>
ESP_BLUFI_EVENT_SET_WIFI_MODE.
Public Members
-
wifi_mode_t
op_mode
¶ Wifi operation mode
-
wifi_mode_t
-
struct esp_blufi_cb_param_t::blufi_init_finish_evt_param
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
-
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
Type Definitions¶
-
typedef void (*
esp_blufi_event_cb_t
)(esp_blufi_cb_event_t event, esp_blufi_cb_param_t *param)¶ BLUFI event callback function type.
- Parameters
event
: : Event typeparam
: : 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.
- Parameters
data
: : data from phonelen
: : length of data from phoneoutput_data
: : data want to send to phoneoutput_len
: : length of data want to send to phone
-
typedef int (*
esp_blufi_encrypt_func_t
)(uint8_t iv8, uint8_t *crypt_data, int cyprt_len)¶ BLUFI encrypt the data after negotiate a share key.
- Return
- Nonnegative number is encrypted length, if error, return negative number;
- Parameters
iv8
: : initial vector(8bit), normally, blufi core will input packet sequence numbercrypt_data
: : plain text and encrypted data, the encrypt function must support autochthonous encryptcrypt_len
: : length of plain text
-
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.
- Return
- Nonnegative number is decrypted length, if error, return negative number;
- Parameters
iv8
: : initial vector(8bit), normally, blufi core will input packet sequence numbercrypt_data
: : encrypted data and plain text, the encrypt function must support autochthonous decryptcrypt_len
: : length of encrypted text
-
typedef uint16_t (*
esp_blufi_checksum_func_t
)(uint8_t iv8, uint8_t *data, int len)¶ BLUFI checksum.
- Parameters
iv8
: : initial vector(8bit), normally, blufi core will input packet sequence numberdata
: : data need to checksumlen
: : length of data
Enumerations¶
-
enum
esp_blufi_cb_event_t
¶ Values:
-
ESP_BLUFI_EVENT_INIT_FINISH
= 0¶
-
ESP_BLUFI_EVENT_DEINIT_FINISH
¶
-
ESP_BLUFI_EVENT_SET_WIFI_OPMODE
¶
-
ESP_BLUFI_EVENT_BLE_CONNECT
¶
-
ESP_BLUFI_EVENT_BLE_DISCONNECT
¶
-
ESP_BLUFI_EVENT_REQ_CONNECT_TO_AP
¶
-
ESP_BLUFI_EVENT_REQ_DISCONNECT_FROM_AP
¶
-
ESP_BLUFI_EVENT_GET_WIFI_STATUS
¶
-
ESP_BLUFI_EVENT_DEAUTHENTICATE_STA
¶
-
ESP_BLUFI_EVENT_RECV_STA_BSSID
¶
-
ESP_BLUFI_EVENT_RECV_STA_SSID
¶
-
ESP_BLUFI_EVENT_RECV_STA_PASSWD
¶
-
ESP_BLUFI_EVENT_RECV_SOFTAP_SSID
¶
-
ESP_BLUFI_EVENT_RECV_SOFTAP_PASSWD
¶
-
ESP_BLUFI_EVENT_RECV_SOFTAP_MAX_CONN_NUM
¶
-
ESP_BLUFI_EVENT_RECV_SOFTAP_AUTH_MODE
¶
-
ESP_BLUFI_EVENT_RECV_SOFTAP_CHANNEL
¶
-
ESP_BLUFI_EVENT_RECV_USERNAME
¶
-
ESP_BLUFI_EVENT_RECV_CA_CERT
¶
-
ESP_BLUFI_EVENT_RECV_CLIENT_CERT
¶
-
ESP_BLUFI_EVENT_RECV_SERVER_CERT
¶
-
ESP_BLUFI_EVENT_RECV_CLIENT_PRIV_KEY
¶
-
ESP_BLUFI_EVENT_RECV_SERVER_PRIV_KEY
¶
-
ESP_BLUFI_EVENT_RECV_SLAVE_DISCONNECT_BLE
¶
-
ESP_BLUFI_EVENT_GET_WIFI_LIST
¶
-
ESP_BLUFI_EVENT_REPORT_ERROR
¶
-
ESP_BLUFI_EVENT_RECV_CUSTOM_DATA
¶
-
-
enum
esp_blufi_sta_conn_state_t
¶ BLUFI config status.
Values:
-
ESP_BLUFI_STA_CONN_SUCCESS
= 0x00¶
-
ESP_BLUFI_STA_CONN_FAIL
= 0x01¶
-
-
enum
esp_blufi_init_state_t
¶ BLUFI init status.
Values:
-
ESP_BLUFI_INIT_OK
= 0¶
-
ESP_BLUFI_INIT_FAILED
¶
-
-
enum
esp_blufi_deinit_state_t
¶ BLUFI deinit status.
Values:
-
ESP_BLUFI_DEINIT_OK
= 0¶
-
ESP_BLUFI_DEINIT_FAILED
¶
-
-
enum
esp_blufi_error_state_t
¶ Values:
-
ESP_BLUFI_SEQUENCE_ERROR
= 0¶
-
ESP_BLUFI_CHECKSUM_ERROR
¶
-
ESP_BLUFI_DECRYPT_ERROR
¶
-
ESP_BLUFI_ENCRYPT_ERROR
¶
-
ESP_BLUFI_INIT_SECURITY_ERROR
¶
-
ESP_BLUFI_DH_MALLOC_ERROR
¶
-
ESP_BLUFI_DH_PARAM_ERROR
¶
-
ESP_BLUFI_READ_PARAM_ERROR
¶
-
ESP_BLUFI_MAKE_PUBLIC_ERROR
¶
-
ESP_BLUFI_DATA_FORMAT_ERROR
¶
-