# 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-S3.

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

此文档对您有帮助吗？

- 反馈已收到，谢谢！
- 如果您有其他意见，欢迎填写乐鑫文档反馈表。

- 我们重视您的反馈。
- 您可以填写乐鑫文档反馈表告诉我们如何改进该文档。