BLUFI API

Over概述view

BLUFI 是一个基于 GATT 的属性，用于配置 ESP32 WIFI 与 AP 的连接/断开连接，或者设置 softap 等。在使用时应当关注如下两点：

  1. 从 profile 发送的事件。你需要根据事件的指示完成某些工作。
  2. 安全引用。你可以自己写安全函数，例如对称加密/解密、校验和等函数。你甚至可以定义 “Key Exchange/Negotiation” 过程。

应用程序示例

请检查 ESP-IDF 示例中的 bluetooth 文件夹，它包含如下示例：

bluetooth/blufi

这是一个 BLUFI demo。该 demo 可以设置 ESP32 的 wifi 为 softap/station/softap&station 模式，并且可以配置 wifi 连接。

API 参考手册

宏

类型定义

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

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

枚举

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
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 = 0
enum esp_blufi_deinit_state_t

BLUFI deinit status.

Values:

ESP_BLUFI_DEINIT_OK = 0
ESP_BLUFI_DEINIT_FAILED = 0

结构体

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

警告

doxygenstruct: Cannot find class “esp_blufi_cb_param_t” in doxygen xml output for project “esp32-idf” from directory: xml/

struct esp_blufi_cb_param_t::blufi_init_finish_evt_param

ESP_BLUFI_EVENT_INIT_FINISH.

Public Members

esp_blufi_init_state_t state

Initial status

struct esp_blufi_cb_param_t::blufi_deinit_finish_evt_param

ESP_BLUFI_EVENT_DEINIT_FINISH.

Public Members

esp_blufi_deinit_state_t state

De-initial status

struct esp_blufi_cb_param_t::blufi_set_wifi_mode_evt_param

ESP_BLUFI_EVENT_SET_WIFI_MODE.

Public Members

wifi_mode_t op_mode

Wifi operation mode

struct esp_blufi_cb_param_t::blufi_connect_evt_param

ESP_BLUFI_EVENT_CONNECT.

Public Members

esp_bd_addr_t remote_bda

Blufi Remote bluetooth device address

struct esp_blufi_cb_param_t::blufi_disconnect_evt_param

ESP_BLUFI_EVENT_DISCONNECT.

Public Members

esp_bd_addr_t remote_bda

Blufi Remote bluetooth device address

struct esp_blufi_cb_param_t::blufi_recv_sta_bssid_evt_param

ESP_BLUFI_EVENT_RECV_STA_BSSID.

Public Members

uint8_t bssid[6]

BSSID

struct esp_blufi_cb_param_t::blufi_recv_sta_ssid_evt_param

ESP_BLUFI_EVENT_RECV_STA_SSID.

Public Members

uint8_t *ssid

SSID

int ssid_len

SSID length

struct esp_blufi_cb_param_t::blufi_recv_sta_passwd_evt_param

ESP_BLUFI_EVENT_RECV_STA_PASSWD.

Public Members

uint8_t *passwd

Password

int passwd_len

Password Length

struct esp_blufi_cb_param_t::blufi_recv_softap_ssid_evt_param

ESP_BLUFI_EVENT_RECV_SOFTAP_SSID.

Public Members

uint8_t *ssid

SSID

int ssid_len

SSID length

struct esp_blufi_cb_param_t::blufi_recv_softap_passwd_evt_param

ESP_BLUFI_EVENT_RECV_SOFTAP_PASSWD.

Public Members

uint8_t *passwd

Password

int passwd_len

Password Length

struct esp_blufi_cb_param_t::blufi_recv_softap_max_conn_num_evt_param

ESP_BLUFI_EVENT_RECV_SOFTAP_MAX_CONN_NUM.

Public Members

int max_conn_num

SSID

struct esp_blufi_cb_param_t::blufi_recv_softap_auth_mode_evt_param

ESP_BLUFI_EVENT_RECV_SOFTAP_AUTH_MODE.

Public Members

wifi_auth_mode_t auth_mode

Authentication mode

struct esp_blufi_cb_param_t::blufi_recv_softap_channel_evt_param

ESP_BLUFI_EVENT_RECV_SOFTAP_CHANNEL.

Public Members

uint8_t channel

Authentication mode

struct esp_blufi_cb_param_t::blufi_recv_username_evt_param

ESP_BLUFI_EVENT_RECV_USERNAME.

Public Members

uint8_t *name

Username point

int name_len

Username length

struct esp_blufi_cb_param_t::blufi_recv_ca_evt_param

ESP_BLUFI_EVENT_RECV_CA_CERT.

Public Members

uint8_t *cert

CA certificate point

int cert_len

CA certificate length

struct esp_blufi_cb_param_t::blufi_recv_client_cert_evt_param

ESP_BLUFI_EVENT_RECV_CLIENT_CERT

Public Members

uint8_t *cert

Client certificate point

int cert_len

Client certificate length

struct esp_blufi_cb_param_t::blufi_recv_server_cert_evt_param

ESP_BLUFI_EVENT_RECV_SERVER_CERT

Public Members

uint8_t *cert

Client certificate point

int cert_len

Client certificate length

struct esp_blufi_cb_param_t::blufi_recv_client_pkey_evt_param

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 esp_blufi_cb_param_t::blufi_recv_server_pkey_evt_param

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

uint16_t esp_blufi_get_version(void)

Get BLUFI profile version.

Return
Most 8bit significant is Great version, Least 8bit is Sub version