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:

  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 Examples

  • bluetooth/blufi how to use the Blufi function to configure the Wi-Fi connection to an AP via a Bluetooth channel on ESP32-C2.

API Reference

Header File

  • components/bt/common/api/include/api/esp_blufi_api.h

  • 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 on bt, 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.

参数:

callbacks -- [in] callback functions

返回:

ESP_OK - success, other - failed

esp_err_t esp_blufi_profile_init(void)

This function is called to initialize blufi_profile.

返回:

ESP_OK - success, other - failed

esp_err_t esp_blufi_profile_deinit(void)

This function is called to de-initialize blufi_profile.

返回:

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.

参数:

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

参数:

  • apCount -- : wifi list count

  • list -- : wifi list

返回:

ESP_OK - success, other - failed

uint16_t esp_blufi_get_version(void)

Get BLUFI profile version.

返回:

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.

参数:

state -- : error state

返回:

ESP_OK - success, other - failed

esp_err_t esp_blufi_send_custom_data(uint8_t *data, uint32_t data_len)

This function is called to custom data.

参数:

  • data -- : custom data value

  • data_len -- : the length of custom data

返回:

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

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.

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

BLUFI init status.

Values:

enumerator ESP_BLUFI_INIT_OK
enumerator ESP_BLUFI_INIT_FAILED
enum esp_blufi_deinit_state_t

BLUFI deinit status.

Values:

enumerator ESP_BLUFI_DEINIT_OK
enumerator ESP_BLUFI_DEINIT_FAILED
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

此文档对您有帮助吗？