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.
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.
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.
1. 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.
2. 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.
3. 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).
7. 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.
8. 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.
9. 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.
10. 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.
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.
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.
**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.
- 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.
- * No data field is contained. When receiving this control frame, the ESP device will send back a follow-up frame of Wi-Fi connection state report to the mobile phone with the information of the current opmode, connection status, SSID, and so on.
- Data[0~5] is taken as the MAC address for the STA device. If there is a second STA device, then it uses data[6-11] and the rest can be done in the same manner.
- To get the ESP device to scan the Wi-Fi access points around.
- No data field is contained. When receiving this control frame, the ESP device will send back a follow-up frame of Wi-Fi list report to the mobile phone.
- To send the BSSID of the AP for the STA device to connect under the condition that the SSID is hidden.
- Please refer to Note 1 below.
* - 0x2 (b’000010)
- Send the SSID for STA mode.
- To send the SSID of the AP for the STA device to connect.
- Please refer to Note 1 below.
* - 0x3 (b’000011)
- Send the password for STA mode.
- To send the password of the AP for the STA device to connect.
- Please refer to Note 1 below.
* - 0x4 (b’000100)
- Send the SSID for SoftAP mode.
-
- Please refer to Note 1 below.
* - 0x5 (b’000101)
- Send the password for SoftAPmode.
-
- Please refer to Note 1 below.
* - 0x6 (b’000110)
- Set the maximum connection number for SoftAP mode.
-
- data[0] represents the value of the connection number, ranging from 1 to 4. When the transmission direction is ESP device to the mobile phone, it means to provide the mobile phone with the needed information.
- data[0] represents the quantity of the supported channels, ranging from 1 to 14. When the transmission direction is from the ESP device to the mobile phone, it means to provide the mobile phone with the needed information.
- It provides the username of the GATT client when using encryption of enterprise level.
- The length of the data depends on the length field.
* - 0xa (b’001010)
- CA Certification
- It provides the CA Certification when using encryption of enterprise level.
- Please refer to Note 2 below.
* - 0xb (b’001011)
- Client Certification
- It provides the client certification when using encryption of enterprise level. Whether the private key is contained or not depends on the content of the certification.
- Please refer to Note 2 below.
* - 0xc (b’001100)
- Server Certification
- It provides the sever certification when using encryption of enterprise level. Whether the private key is contained or not depends on the content of the certification.
- Please refer to Note 2 below.
* - 0xd (b’001101)
- Client Private Key
- It provides the private key of the client when using encryption of enterprise level.
- Please refer to Note 2 below.
* - 0xe (b’001110)
- Server Private Key
- It provides the private key of the sever when using encryption of enterprise level.
- Please refer to Note 2 below.
* - 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[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[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.
- data[0] represents the maximum Wi-Fi reconnecting time.
* - 0x15 (b’010101)
- Set the Wi-Fi connection end reason.
-
- data[0] represents the Wi-Fi connection end reason, whose type shall be same with struct `wifi_err_reason_t`.
* - 0x16 (b’010110)
- Set the RSSI at Wi-Fi connection end.
-
- data[0] represents the RSSI at Wi-Fi connection end. If there is no meaningful RSSI in the connection end, this value shall be the meaningless one, which is `-128`.
- 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.
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.
- Indicates whether a frame contains a checksum (such as SHA1, MD5, CRC) for the end of the frame. Data field includes sequence, data length, and clear text. Both the control frame and the data frame can choose whether to contain a check bit or not.
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).
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.
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).
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.
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.
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.
