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:

  1. The event sent from profile. Then you need to do something as the event indicate.

  2. 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 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/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

  • [in] 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 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.

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 count

  • list: : 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_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

esp_err_t esp_blufi_send_custom_data(uint8_t *data, uint32_t data_len)

This function is called to custom data.

Return

ESP_OK - success, other - failed

Parameters

  • data: : custom data value

  • data_len: : the length of custom data

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

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

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

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

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

struct blufi_recv_ca_evt_param
#include <esp_blufi_api.h>

ESP_BLUFI_EVENT_RECV_CA_CERT.

Public Members

uint8_t *cert

CA certificate point

int cert_len

CA certificate length

struct blufi_recv_client_cert_evt_param
#include <esp_blufi_api.h>

ESP_BLUFI_EVENT_RECV_CLIENT_CERT

Public Members

uint8_t *cert

Client certificate point

int cert_len

Client certificate length

struct blufi_recv_client_pkey_evt_param
#include <esp_blufi_api.h>

ESP_BLUFI_EVENT_RECV_CLIENT_PRIV_KEY

Public Members

uint8_t *pkey

Client Private Key point, if Client certificate not contain Key

int pkey_len

Client Private key length

struct blufi_recv_custom_data_evt_param
#include <esp_blufi_api.h>

ESP_BLUFI_EVENT_RECV_CUSTOM_DATA.

Public Members

uint8_t *data

Custom data

uint32_t data_len

Custom data Length

struct blufi_recv_server_cert_evt_param
#include <esp_blufi_api.h>

ESP_BLUFI_EVENT_RECV_SERVER_CERT

Public Members

uint8_t *cert

Client certificate point

int cert_len

Client certificate length

struct blufi_recv_server_pkey_evt_param
#include <esp_blufi_api.h>

ESP_BLUFI_EVENT_RECV_SERVER_PRIV_KEY

Public Members

uint8_t *pkey

Client Private Key point, if Client certificate not contain Key

int pkey_len

Client Private key length

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

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

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

struct blufi_recv_softap_passwd_evt_param
#include <esp_blufi_api.h>

ESP_BLUFI_EVENT_RECV_SOFTAP_PASSWD.

Public Members

uint8_t *passwd

Password

int passwd_len

Password Length

struct blufi_recv_softap_ssid_evt_param
#include <esp_blufi_api.h>

ESP_BLUFI_EVENT_RECV_SOFTAP_SSID.

Public Members

uint8_t *ssid

SSID

int ssid_len

SSID length

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

struct blufi_recv_sta_passwd_evt_param
#include <esp_blufi_api.h>

ESP_BLUFI_EVENT_RECV_STA_PASSWD.

Public Members

uint8_t *passwd

Password

int passwd_len

Password Length

struct blufi_recv_sta_ssid_evt_param
#include <esp_blufi_api.h>

ESP_BLUFI_EVENT_RECV_STA_SSID.

Public Members

uint8_t *ssid

SSID

int ssid_len

SSID length

struct blufi_recv_username_evt_param
#include <esp_blufi_api.h>

ESP_BLUFI_EVENT_RECV_USERNAME.

Public Members

uint8_t *name

Username point

int name_len

Username length

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

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

struct esp_blufi_ap_record_t

Description of an WiFi AP.

Public Members

uint8_t ssid[33]

SSID of AP

int8_t rssi

signal strength of 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)

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.

Parameters

  • event: : Event type

  • 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.

Parameters

  • data: : data from phone

  • len: : length of data from phone

  • output_data: : data want to send to phone

  • output_len: : length of data want to send to phone

  • 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.

Return

Nonnegative number is encrypted length, if error, return negative number;

Parameters

  • iv8: : initial vector(8bit), normally, blufi core will input packet sequence number

  • crypt_data: : plain text and encrypted data, the encrypt function must support autochthonous encrypt

  • crypt_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 number

  • crypt_data: : encrypted data and plain text, the encrypt function must support autochthonous decrypt

  • crypt_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 number

  • data: : data need to checksum

  • len: : 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
ESP_BLUFI_STA_CONNECTING = 0x02
ESP_BLUFI_STA_NO_IP = 0x03
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
ESP_BLUFI_CALC_MD5_ERROR
ESP_BLUFI_WIFI_SCAN_FAIL
ESP_BLUFI_MSG_STATE_ERROR

Provide feedback about this document