docs/en/api-guides/ble/blufi.rst
:link_to_translation:zh_CN:[中文]
The BluFi for {IDF_TARGET_NAME} is a Wi-Fi network configuration function via Bluetooth channel. It provides a secure protocol to pass Wi-Fi configuration and credentials to {IDF_TARGET_NAME}. Using this information, {IDF_TARGET_NAME} can then connect to an AP or establish a SoftAP.
Fragmenting, data encryption, and checksum verification in the BluFi layer are the key elements of this process.
You can customize symmetric encryption, asymmetric encryption, and checksum support customization. Here we use the DH algorithm for key negotiation, 128-AES algorithm for data encryption, and CRC16 algorithm for checksum verification.
.. note::
BluFi is currently in maintenance mode, and no new features are planned.
For new projects or when adding Wi-Fi provisioning, we recommend using the network_provisioning_ component, which offers a modern, secure, and actively maintained solution.
This section provides a step-by-step guide to configuring Wi-Fi on an {IDF_TARGET_NAME} device using the EspBlufi app.
Prerequisites ^^^^^^^^^^^^^
Hardware:
Software:
BluFi example: :example:bluetooth/blufi (to be flashed into {IDF_TARGET_NAME})
Mobile App: EspBlufi
EspBlufi For Android <https://github.com/EspressifApp/EspBlufiForAndroid>_EspBlufi For iOS <https://github.com/EspressifApp/EspBlufiForiOS>_For detailed instructions on flashing BluFi example, please refer to ESP-IDF :doc:../../get-started/index documentation.
Configuring Wi-Fi via the EspBlufi App ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Setting {IDF_TARGET_NAME} to Station Mode #########################################
Power on {IDF_TARGET_NAME}
Connect {IDF_TARGET_NAME} to your computer. The following log will be output to the serial port tool:
.. figure:: ../../../_static/blufi-init-finish.png :align: center :width: 70%
Connect via EspBlufi
Grant Wi-Fi, Bluetooth, and location permissions on your mobile phone.
Open the EspBlufi app, and refresh the interface by swiping down. The nearby Bluetooth-enabled devices will be displayed.
.. figure:: ../../../_static/espblufi-interface.jpg :align: center :scale: 20% :alt: EspBlufi Interface
EspBlufi Interface
Click on the {IDF_TARGET_NAME} device, and click Connect to establish a Bluetooth connection. A successful connection will display the following interface:
.. figure:: ../../../_static/interface-success-connection.jpg :align: center :scale: 20% :alt: Successful Connection
Successful Connection
Meanwhile, the following log will be output to the serial port tool:
.. figure:: ../../../_static/blufi-ble-connect.png :align: center :width: 80%
.. note::
If the Networking button is missing or unresponsive, restart {IDF_TARGET_NAME} and ensure Bluetooth permissions are granted.
Configure Wi-Fi
Click on the Networking button to open the network configuration menu:
.. figure:: ../../../_static/network-config-interface.jpg :align: center :scale: 20% :alt: Network Configuration Interface
Network Configuration Interface
Select a device mode from the dropdown list. BluFi supports the following three modes:
.. figure:: ../../../_static/select-device-mode.jpg :align: center :scale: 20% :alt: Selecting Device Mode
Selecting Device Mode
Select Station mode, click on the refresh button, and choose a Wi-FI SSID. Then, enter the password.
.. figure:: ../../../_static/config-station-mode.jpg :align: center :scale: 20% :alt: Configuring Station Mode
Configuring Station Mode
.. only:: esp32
.. note::
{IDF_TARGET_NAME} only supports 2.4 GHz Wi-Fi. Ensure you select a compatible network.
Click on the Confirm button to complete the configuration. A successful connection will display the following interface. The information marked in red in shows the Wi-Fi mode (which is Station mode in this example) and the connection information (such as the AP’s BSSID and SSID, as well as the connection status).
.. figure:: ../../../_static/station-connection-info.jpg :align: center :scale: 20% :alt: Station Connection Information
Station Connection Information
Meanwhile, the following log will be output to the serial port tool:
.. figure:: ../../../_static/station-connection-log.png :align: center :width: 80%
Setting {IDF_TARGET_NAME} as a SoftAP #####################################
Connect via EspBlufi
Power on the module. Connect the EspBlufi app to {IDF_TARGET_NAME} via Bluetooth.
In the network configuration menu, select SoftAP mode:
.. figure:: ../../../_static/select-softap-mode.jpg :align: center :scale: 20% :alt: Selecting SoftAP Mode
Selecting SoftAP Mode
Configure SoftAP
Select the security encryption mode, channel, and maximum number of Stations to be connected.
Enter the SoftAP’s SSID and password.
Click on the Confirm button to complete the configuration.
.. figure:: ../../../_static/config-softap-mode.jpg :align: center :scale: 20% :alt: Configuring SoftAP Mode
Configuring SoftAP Mode
Verify SoftAP
A successful SoftAP configuration will display the following interface, showing the current Wi-Fi mode and connection status:
.. figure:: ../../../_static/softap-connection-info.jpg :align: center :scale: 20% :alt: SoftAP Connection Information
SoftAP Connection Information
Meanwhile, the following log will be output to the serial port tool:
.. figure:: ../../../_static/softap-connection-log.png :align: center :width: 70%
Connect to SoftAP
Enable Wi-Fi on your mobile phone. The configured SoftAP will appear in the network list:
.. figure:: ../../../_static/configured-softap.png :align: center :height: 370 :alt: The Configured SoftAP
The Configured SoftAP
Connect to the SoftAP. A successful connection will be indicated as follows:
.. figure:: ../../../_static/wifi-connection-prompt.png :align: center :height: 370 :alt: Wi-Fi Connection Prompt
Wi-Fi Connection Prompt
Meanwhile, the following log will be output to the serial port tool:
.. figure:: ../../../_static/wifi-connection-log.png :align: center :width: 80%
The {IDF_TARGET_NAME} device is now successfully connected to Wi-Fi using Bluetooth networking.
The BluFi networking flow includes the configuration of the SoftAP and Station.
The following uses Station as an example to illustrate the core parts of the procedure, including broadcast, connection, service discovery, negotiation of the shared key, data transmission, and connection status backhaul.
Set the {IDF_TARGET_NAME} into GATT Server mode and then it will send broadcasts with specific advertising data. You can customize this broadcast as needed, which is not a part of the BluFi Profile.
Use the App installed on the mobile phone to search for this particular broadcast. The mobile phone will connect to {IDF_TARGET_NAME} as the GATT Client once the broadcast is confirmed. The App used during this part is up to you.
After the GATT connection is successfully established, the mobile phone will send a data frame for key negotiation to {IDF_TARGET_NAME} (see the section :ref:frame_formats for details).
After {IDF_TARGET_NAME} receives the data frame of key negotiation, it will parse the content according to the user-defined negotiation method.
The mobile phone works with {IDF_TARGET_NAME} for key negotiation using the encryption algorithms, such as DH, RSA, or ECC.
After the negotiation process is completed, the mobile phone will send a control frame for security-mode setup to {IDF_TARGET_NAME}.
When receiving this control frame, {IDF_TARGET_NAME} will be able to encrypt and decrypt the communication data using the shared key and the security configuration.
The mobile phone sends the data frame defined in the section of :ref:frame_formats,with the Wi-Fi configuration information to {IDF_TARGET_NAME}, including SSID, password, etc.
The mobile phone sends a control frame of Wi-Fi connection request to {IDF_TARGET_NAME}. When receiving this control frame, {IDF_TARGET_NAME} will regard the communication of essential information as done and get ready to connect to the Wi-Fi.
After connecting to the Wi-Fi, {IDF_TARGET_NAME} will send a control frame of Wi-Fi connection status report to the mobile phone. At this point, the networking procedure is completed.
.. note::
1. After {IDF_TARGET_NAME} receives the control frame of security-mode configuration, it will execute the operations in accordance with the defined security mode.
2. The data lengths before and after symmetric encryption/decryption must stay the same. It also supports in-place encryption and decryption.
.. seqdiag:: :caption: BluFi Flow Chart :align: center
seqdiag blufi {
activation = none;
node_width = 80;
node_height = 60;
edge_length = 380;
span_height = 10;
default_fontsize = 12;
Phone <- {IDF_TARGET_NAME} [label="Advertising"];
Phone -> {IDF_TARGET_NAME} [label="Create GATT connection"];
Phone -> {IDF_TARGET_NAME} [label="Negotiate key procedure"];
Phone <- {IDF_TARGET_NAME} [label="Negotiate key procedure"];
Phone -> {IDF_TARGET_NAME} [label="CTRL: Set {IDF_TARGET_NAME} to Phone Security mode"];
Phone -> {IDF_TARGET_NAME} [label="DATA: SSID"];
Phone -> {IDF_TARGET_NAME} [label="DATA: Password"];
Phone -> {IDF_TARGET_NAME} [label="DATA: Other information, such as CA certification"];
Phone -> {IDF_TARGET_NAME} [label="CTRL: Connect to AP"];
Phone <- {IDF_TARGET_NAME} [label="DATA: Connection State Report"];
}
.. _frame_formats:
The frame formats for the communication between the mobile phone App and {IDF_TARGET_NAME} are defined as follows:
The frame format with no fragment:
.. list-table:: :header-rows: 1 :widths: 25 25
If the frag frame bit in the Frame Control field is enabled, there would be a 2-byte Total Content Length field in the Data field. This Total Content Length field indicates the length of the remaining part of the frame and also tells the remote how much memory needs to be allocated.
The frame format with fragments:
.. list-table:: :header-rows: 1 :widths: 25 25
Normally, the control frame does not contain data bits, except for ACK Frame.
The format of ACK Frame:
.. list-table:: :header-rows: 1 :widths: 25 25
Type
Type field takes 1 byte and is divided into Type and Subtype. Type uses the lower two bits, indicating whether the frame is a data frame or a control frame. Subtype uses the upper six bits, indicating the specific meaning of this data frame or control frame.
The control frame is not encrypted for the time being and supports to be verified.
The data frame supports to be encrypted and verified.
1.1 Control Frame (Binary: 0x0 b'00)
.. list-table:: :header-rows: 1 :widths: 5 15 20 30
0x1 (b’000001)
Set the ESP device to the security mode.
To inform the ESP device of the security mode to use when sending data, which is allowed to be reset multiple times during the process. Each setting affects the subsequent security mode used.
If it is not set, the ESP device will send the control frame and data frame with no checksum and encryption by default. The data transmission from the mobile phone to the ESP device is controlled by this control frame.
The data field consumes a byte. The higher four bits are for the security mode setting of the control frame, and the lower four bits are for the security mode setting of the data frame.
0x2 (b’000010)
Set the opmode of Wi-Fi.
The frame contains opmode settings for configuring the Wi-Fi mode of the ESP device.
data[0] is for opmode settings, including:
Please set the SSID/Password/Max Connection Number of the AP mode in the first place if an AP gets involved.
1.2 Data Frame (Binary: 0x1 b'01)
.. list-table:: :header-rows: 1 :widths: 5 15 20 30
0x7 (b’000111)
Set the authentication mode for SoftAP mode.
data[0]：
When the transmission direction is from the ESP device to the mobile phone, it means to provide the mobile phone with the needed information.
0xf (b’001111)
Wi-Fi Connection State Report
To notify the phone of the ESP device’s Wi-Fi status, including STA status and SoftAP status. It is for the STA device to connect to the mobile phone or the SoftAP. However, when the mobile phone receives the Wi-Fi status, it can reply to other frames in addition to this frame.
data[0] represents opmode, including:
data[1]: connection state of the STA device. 0x0 indicates a connection state with IP address, 0x1 represent a disconnected state, 0x2 indicates a connecting state, and 0x3 indicates a connection state but no IP address.
data[2]: connection state of SoftAP. That is, how many STA devices have been connected.
data[3] and the subsequent is in accordance with the format of SSID/BSSID information. If device is in connecting state, maximum Wi-Fi reconnecting time would be included here. If device is in disconnected state, Wi-Fi connection end reason and RSSI would be included here.
wifi_err_reason_t.-128... note::
Note 1: The length of the data depends on the data length field. When the transmission direction is from the ESP device to the mobile phone, it means to provide the mobile phone with the needed information.
Note 2: The length of the data depends on the data length field. The frame supports to be fragmented if the data length is not long enough.
Frame Control
The Frame Control field takes one byte and each bit has a different meaning.
.. list-table:: :header-rows: 1 :widths: 10 35
0x01
Indicates whether the frame is encrypted.
The encrypted part of the frame includes the full clear data before the DATA field is encrypted (no checksum). Control frame is not encrypted, so this bit is 0.
0x04
Indicates the data direction.
0x08
Indicates whether the other person is required to reply to an ACK.
0x10
Indicates whether there are subsequent data fragments.
In the case of a frag frame, the total length of the current content section + subsequent content section is given in the first two bytes of the data field (that is, the content data of the maximum support 64 K).
Sequence Number
The Sequence Number field is the field for sequence control. When a frame is sent, the value of this field is automatically incremented by 1 regardless of the type of frame, which prevents Replay Attack. The sequence would be cleared after each reconnection.
Data Length
The Data Length field indicates the length of the data field, which does not include CheckSum.
Data
Content of the Data field can be different according to various values of Type or Subtype. Please refer to the table above.
CheckSum
The CheckSum field takes two bytes, which is used to check "sequence + data length + clear text data".
Securing Data
To ensure that the transmission of the Wi-Fi SSID and password is secure, the message needs to be encrypted using symmetric encryption algorithms, such as AES, DES, and so on. Before using symmetric encryption algorithms, the devices are required to negotiate (or generate) a shared key using an asymmetric encryption algorithm (DH, RSA, ECC, etc).
Ensuring Data Integrity
To ensure data integrity, you need to add a checksum algorithm, such as SHA1, MD5, CRC, etc.
Securing Identity (Signature)
Algorithm like RSA can be used to secure identity. But for DH, it needs other algorithms as an companion for signature.
Replay Attack Prevention
It is added to the Sequence Number field and used during the checksum verification.
For the coding of {IDF_TARGET_NAME}, you can determine and develop the security processing, such as key negotiation. The mobile application sends the negotiation data to {IDF_TARGET_NAME}, and then the data will be sent to the application layer for processing. If the application layer does not process it, you can use the DH encryption algorithm provided by BluFi to negotiate the key.
The application layer needs to register several security-related functions to BluFi:
.. code-block:: c
typedef void (*esp_blufi_negotiate_data_handler_t)(uint8_t *data, int len, uint8_t **output_data, int *output_len, bool *need_free)
This function is for {IDF_TARGET_NAME} to receive normal data during negotiation. After processing is completed, the data will be transmitted using Output_data and Output_len.
BluFi will send output_data from Negotiate_data_handler after Negotiate_data_handler is called.
Here are two *, which means the length of the data to be emitted is unknown. Therefore, it requires the function to allocate itself (malloc) or point to the global variable to inform whether the memory needs to be freed by NEED_FREE.
.. code-block:: c
typedef int (* esp_blufi_encrypt_func_t)(uint8_t iv8, uint8_t *crypt_data, int crypt_len)
The data to be encrypted and decrypted must be in the same length. The IV8 is an 8-bit sequence value of frames, which can be used as a 8-bit of IV.
.. code-block:: c
typedef int (* esp_blufi_decrypt_func_t)(uint8_t iv8, uint8_t *crypt_data, int crypt_len)
The data to be encrypted and decrypted must be in the same length. The IV8 is an 8-bit sequence value of frames, which can be used as an 8-bit of IV.
.. code-block:: c
typedef uint16_t (*esp_blufi_checksum_func_t)(uint8_t iv8, uint8_t *data, int len)
This function is used to compute CheckSum and return a value of CheckSum. BluFi uses the returned value to compare the CheckSum of the frame.
Implementing Stronger Security
The default encryption and decryption logic in this example is intended for demonstration purposes only. If your application requires stronger security guarantees, consider one of the following approaches:
.. code-block:: c
esp_err_t esp_blufi_register_callbacks(esp_blufi_callbacks_t *callbacks);
network_provisioning_ component.UUID ^^^^
BluFi Service UUID: 0xFFFF, 16 bit
BluFi (the mobile > {IDF_TARGET_NAME}): 0xFF01, writable
Blufi ({IDF_TARGET_NAME} > the mobile phone): 0xFF02, readable and callable
.. _network_provisioning: https://github.com/espressif/idf-extra-components/tree/master/network_provisioning