alex/esp-idf
alex/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf.git synced 2024-10-05 20:47:46 -04:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity
fc0eba4101
esp-idf/docs/en/api-guides/blufi.rst

456 lines
54 KiB
ReStructuredText
Raw Normal View History

Upload blufi.rst
2018-05-09 22:55:47 -04:00
BluFi
Update blufi.rst
2018-05-23 05:15:24 -04:00
^^^^^
Included missing links between English and Chinese documentation, where translation into Chinese is available
2019-01-27 13:01:34 -05:00
:link_to_translation:`zh_CN:[中文]`
Upload blufi.rst
2018-05-09 22:55:47 -04:00
Overview
Update blufi.rst
2018-05-23 05:15:24 -04:00
--------
doc: Update English pages with generic target name
2019-12-08 22:01:09 -05:00
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 the {IDF_TARGET_NAME}. Using this information {IDF_TARGET_NAME} can then e.g. connect to an AP or establish a SoftAP.
Upload blufi.rst
2018-05-09 22:55:47 -04:00
Update blufi.rst
2018-05-23 01:56:34 -04:00
Fragmenting, data encryption, checksum verification in the BluFi layer are the key elements of this process.
Upload blufi.rst
2018-05-09 22:55:47 -04:00
Update blufi.rst
2018-06-04 02:21:12 -04:00
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.
Upload blufi.rst
2018-05-09 22:55:47 -04:00
Update blufi.rst
2018-05-23 01:56:34 -04:00
The BluFi Flow
Update blufi.rst
2018-05-24 02:33:58 -04:00
---------------
Upload blufi.rst
2018-05-09 22:55:47 -04:00
The BluFi networking flow includes the configuration of the SoftAP and Station.
Update blufi.rst
2018-05-17 05:15:56 -04:00
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, connection status backhaul.
Upload blufi.rst
2018-05-09 22:55:47 -04:00
doc: Update English pages with generic target name
2019-12-08 22:01:09 -05:00
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.
Upload blufi.rst
2018-05-09 22:55:47 -04:00
doc: Update English pages with generic target name
2019-12-08 22:01:09 -05:00
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.
Upload blufi.rst
2018-05-09 22:55:47 -04:00
doc: Update English pages with generic target name
2019-12-08 22:01:09 -05:00
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).
Upload blufi.rst
2018-05-09 22:55:47 -04:00
doc: Update English pages with generic target name
2019-12-08 22:01:09 -05:00
4. After {IDF_TARGET_NAME} receives the data frame of key negotiation, it will parse the content according to the user-defined negotiation method.
Upload blufi.rst
2018-05-09 22:55:47 -04:00
doc: Update English pages with generic target name
2019-12-08 22:01:09 -05:00
5. The mobile phone works with {IDF_TARGET_NAME} for key negotiation using the encryption algorithms such as DH, RSA or ECC.
Upload blufi.rst
2018-05-09 22:55:47 -04:00
doc: Update English pages with generic target name
2019-12-08 22:01:09 -05:00
6. After the negotiation process is completed, the mobile phone will send a control frame for security-mode setup to {IDF_TARGET_NAME}.
Upload blufi.rst
2018-05-09 22:55:47 -04:00
doc: Update English pages with generic target name
2019-12-08 22:01:09 -05:00
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.
Upload blufi.rst
2018-05-09 22:55:47 -04:00
doc: Update English pages with generic target name
2019-12-08 22:01:09 -05:00
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.
Upload blufi.rst
2018-05-09 22:55:47 -04:00
doc: Update English pages with generic target name
2019-12-08 22:01:09 -05:00
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.
Upload blufi.rst
2018-05-09 22:55:47 -04:00
doc: Update English pages with generic target name
2019-12-08 22:01:09 -05:00
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，to report the connection status. At this point the networking procedure is completed.
Upload blufi.rst
2018-05-09 22:55:47 -04:00
.. note::
doc: Update English pages with generic target name
2019-12-08 22:01:09 -05:00
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.
Upload blufi.rst
2018-05-09 22:55:47 -04:00
2. The data lengths before and after symmetric encryption/decryption must stay the same. It also supports in-place encryption and decryption.
Fix the typo and tables.
2018-06-28 02:06:26 -04:00
The flow chart of BluFi
Update blufi.rst
2018-05-23 01:56:34 -04:00
-----------------------
Upload blufi.rst
2018-05-09 22:55:47 -04:00
Update blufi.rst
2018-05-23 01:56:34 -04:00
.. seqdiag::
:caption: BluFi Flow Chart
Upload blufi.rst
2018-05-09 22:55:47 -04:00
:align: center
Update blufi.rst
2018-05-23 01:56:34 -04:00
seqdiag blufi {
activation = none;
node_width = 80;
node_height = 60;
edge_length = 380;
span_height = 10;
doc: Update English pages with generic target name
2019-12-08 22:01:09 -05:00
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"];
Update blufi.rst
2018-05-23 01:56:34 -04:00
}
.. _frame_formats:
Upload blufi.rst
2018-05-09 22:55:47 -04:00
The Frame Formats Defined in BluFi
Update blufi.rst
2018-05-24 02:33:58 -04:00
-----------------------------------
Upload blufi.rst
2018-05-09 22:55:47 -04:00
doc: Update English pages with generic target name
2019-12-08 22:01:09 -05:00
The frame formats for the communication between the mobile phone App and {IDF_TARGET_NAME} are defined as follows:
Upload blufi.rst
2018-05-09 22:55:47 -04:00
The frame format with no fragment (8 bit)：
Fix the typo and tables.
2018-06-28 02:06:26 -04:00
+-----------------+----------------+
| Description | Value |
+=================+================+
| LSB - Type | 1 |
+-----------------+----------------+
| Frame Control | 1 |
+-----------------+----------------+
| Sequence Number | 1 |
+-----------------+----------------+
| Data Length | 1 |
+-----------------+----------------+
| Data | ${Data Length} |
+-----------------+----------------+
| MSB - CheckSum | 2 |
+-----------------+----------------+
Upload blufi.rst
2018-05-09 22:55:47 -04:00
Update blufi.rst
2018-05-23 01:56:34 -04:00
If the **Frame Ctrl** bit is enabled, the **Total length** bit indicates the length of remaining part of the frame. It can tell the remote how much memory needs to be alloced.
Upload blufi.rst
2018-05-09 22:55:47 -04:00
The frame format with fragments（8 bit）：
Fix the typo and tables.
2018-06-28 02:06:26 -04:00
+--------------------+-------------------------------------------+
| Description | Value |
+====================+===========================================+
| LSB - Type | 1 |
+--------------------+-------------------------------------------+
| FrameControl(Frag) | 1 |
+--------------------+-------------------------------------------+
| SequenceNumber | 1 |
+--------------------+-------------------------------------------+
| DataLength | 1 |
+--------------------+----------------------+--------------------+
| | Total Content Length | 2 |
+ Data +----------------------+--------------------+
| | Content | ${Data Length} - 2 |
+--------------------+----------------------+--------------------+
| MSB - CheckSum | 2 |
+--------------------+-------------------------------------------+
Upload blufi.rst
2018-05-09 22:55:47 -04:00
Update blufi.rst
2018-05-23 01:56:34 -04:00
Normally, the control frame does not contain data bits, except for Ack Frame.
Upload blufi.rst
2018-05-09 22:55:47 -04:00
The format of Ack Frame（8 bit）：
Fix the typo and tables.
2018-06-28 02:06:26 -04:00
+------------------+--------------------------------------------+
| Description | Value |
+------------------+--------------------------------------------+
| LSB - Type (Ack) | 1 |
+------------------+--------------------------------------------+
| Frame Control | 1 |
+------------------+--------------------------------------------+
| SequenceNumber | 1 |
+------------------+--------------------------------------------+
| DataLength | 1 |
+------------------+-----------------------+--------------------+
+ Data + Acked Sequence Number + 2 +
| | | |
+------------------+-----------------------+--------------------+
| MSB - CheckSum | 2 |
+------------------+--------------------------------------------+
Upload blufi.rst
2018-05-09 22:55:47 -04:00
1. Type
Update blufi.rst
2018-06-04 02:21:12 -04:00
The **Type** field, taking 1 byte, is divided into **Type** and **Subtype**, that Type uses the lower 2 bits and **Subtype** uses the upper 6 bits.
Upload blufi.rst
2018-05-09 22:55:47 -04:00
Update blufi.rst
2018-05-23 02:02:09 -04:00
* The control frame is not encrypted for the time being and supports to be verified;
Upload blufi.rst
2018-05-09 22:55:47 -04:00
Update blufi.rst
2018-05-23 02:02:09 -04:00
* The data frame supports to be encrypted and verified.
doc: Update English pages with generic target name
2019-12-08 22:01:09 -05:00
**1.1 Control Frame (0x0 b’00)**
Update blufi.rst
2018-05-23 01:56:34 -04:00
Update blufi.rst
2018-06-06 00:05:27 -04:00
+-------------------------+--------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------------+
component/bt: add readme doc for BLE demos - Closes:https://github.com/espressif/esp-idf/issues/3341
2019-04-26 05:24:34 -04:00
| Control Frame (Binary) | Implication | Explanation | Note |
Update blufi.rst
2018-06-06 00:05:27 -04:00
+=========================+==============================================================+===============================================================+===============================================================+
component/bt: add readme doc for BLE demos - Closes:https://github.com/espressif/esp-idf/issues/3341
2019-04-26 05:24:34 -04:00
| 0x0 (b’000000) | Ack | The data field of the Ack frame uses the same | The data field consumes a byte and its value is |
Update blufi.rst
2018-06-06 00:05:27 -04:00
| | | sequence value of the frame to reply to. | the same as the sequence field of the frame to reply to. |
+-------------------------+--------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------------+
docs: initial update of programming guide for C3 Updates "front page" content, get-started, and api-guides with C3 content Enable building and publishing of C3 docs in CI
2021-01-26 21:12:58 -05:00
| 0x1 (b’000001) | Set ESP device to the security mode. | To inform ESP device of the security mode to use | The data field consumes a byte. |
Update blufi.rst
2018-06-06 00:05:27 -04:00
| | | when sending data, which is allowed to be reset | The higher 4 bits are for the security mode setting |
| | | multiple times during the process. | of the control frame, and the lower 4 bits are for |
| | | Each setting affects the subsequent security mode used. | the security mode setting of the data frame. |
docs: initial update of programming guide for C3 Updates "front page" content, get-started, and api-guides with C3 content Enable building and publishing of C3 docs in CI
2021-01-26 21:12:58 -05:00
+ + + If it is not set, ESP device will send the control frame +---------------------------------------------------------------+
Update blufi.rst
2018-06-06 00:05:27 -04:00
| | | and data frame with no checksum and encryption by default. | b’0000: no checksum and no encryption; |
docs: initial update of programming guide for C3 Updates "front page" content, get-started, and api-guides with C3 content Enable building and publishing of C3 docs in CI
2021-01-26 21:12:58 -05:00
+ + + The data transmission from the mobile phone to ESP device is +---------------------------------------------------------------+
Update blufi.rst
2018-06-06 00:05:27 -04:00
| | | controlled by this control frame. | b’0001: with checksum but no encryption; |
+ + + +---------------------------------------------------------------+
| | | | b’0010: no checksum but with encryption; |
+ + + +---------------------------------------------------------------+
| | | | b’0011: with both checksum and encryption. |
+-------------------------+--------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------------+
component/bt: add readme doc for BLE demos - Closes:https://github.com/espressif/esp-idf/issues/3341
2019-04-26 05:24:34 -04:00
| 0x2 (b’000010) | Set the opmode of Wi-Fi. | The frame contains opmode settings for | data[0] is for opmode settings, including: |
docs: initial update of programming guide for C3 Updates "front page" content, get-started, and api-guides with C3 content Enable building and publishing of C3 docs in CI
2021-01-26 21:12:58 -05:00
+ + + configuring for the Wi-Fi mode of ESP device. +---------------------------------------------------------------+
Update blufi.rst
2018-06-06 00:05:27 -04:00
| | | | 0x00: NULL； |
+ + + +---------------------------------------------------------------+
| | | | 0x01: STA; |
+ + + +---------------------------------------------------------------+
| | | | 0x02: SoftAP; |
+ + + +---------------------------------------------------------------+
| | | | 0x03: SoftAP&STA. |
+ + + +---------------------------------------------------------------+
| | | | Please set the SSID/Password/Max Connection Number of |
| | | | the AP mode in the first place if an AP gets involved. |
+-------------------------+--------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------------+
docs: initial update of programming guide for C3 Updates "front page" content, get-started, and api-guides with C3 content Enable building and publishing of C3 docs in CI
2021-01-26 21:12:58 -05:00
| 0x3 (b’000011) | Connect ESP device to the AP. | To notify ESP device that the essential information has been | No data field is contained. |
| | | sent and it is allowed to connect to the AP. | |
Update blufi.rst
2018-06-06 00:05:27 -04:00
+-------------------------+--------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------------+
docs: initial update of programming guide for C3 Updates "front page" content, get-started, and api-guides with C3 content Enable building and publishing of C3 docs in CI
2021-01-26 21:12:58 -05:00
| 0x4 (b’000100) | Disconnect ESP device from the AP. | | No data field is contained. |
Update blufi.rst
2018-06-06 00:05:27 -04:00
+-------------------------+--------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------------+
docs: initial update of programming guide for C3 Updates "front page" content, get-started, and api-guides with C3 content Enable building and publishing of C3 docs in CI
2021-01-26 21:12:58 -05:00
| 0x5 (b’000101) | To get the information of ESP device’s Wi-Fi mode and | | No data field is contained. |
| | it's status. | | When receiving this control frame, ESP device will send back |
Update blufi.rst
2018-06-06 00:05:27 -04:00
| | | | 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. |
| | | | The types of information sent to the mobile phone is |
| | | | defined by the application installed on the phone. |
+-------------------------+--------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------------+
component/bt: add readme doc for BLE demos - Closes:https://github.com/espressif/esp-idf/issues/3341
2019-04-26 05:24:34 -04:00
| 0x6 (b’000110) | Disconnect the STA device from the SoftAP (in SoftAP mode). | | Date[0~5] is taken as the MAC address for the STA device. |
Update blufi.rst
2018-06-06 00:05:27 -04:00
| | | | If there is a second STA device, then it uses data[6-11] |
| | | | and the rest can be done in the same manner. |
+-------------------------+--------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------------+
component/bt: add readme doc for BLE demos - Closes:https://github.com/espressif/esp-idf/issues/3341
2019-04-26 05:24:34 -04:00
| 0x7 (b'000111) | Get the version information. | | |
Update blufi.rst
2018-06-06 00:05:27 -04:00
+-------------------------+--------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------------+
docs: initial update of programming guide for C3 Updates "front page" content, get-started, and api-guides with C3 content Enable building and publishing of C3 docs in CI
2021-01-26 21:12:58 -05:00
| 0x8 (b’001000) | Disconnect the BLE GATT link. | | ESP device will disconnect the BLE GATT link |
Update blufi.rst
2018-06-06 00:05:27 -04:00
| | | | after receives this command. |
+-------------------------+--------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------------+
docs: initial update of programming guide for C3 Updates "front page" content, get-started, and api-guides with C3 content Enable building and publishing of C3 docs in CI
2021-01-26 21:12:58 -05:00
| 0x9 (b’001001) | Get the Wi-Fi list. | To get ESP device to scan the Wi-Fi access points around. | No data field is contained. |
Update blufi.rst
2018-06-06 00:05:27 -04:00
| | | | When receiving this control frame, |
docs: initial update of programming guide for C3 Updates "front page" content, get-started, and api-guides with C3 content Enable building and publishing of C3 docs in CI
2021-01-26 21:12:58 -05:00
| | | | ESP device will send back a follow-up frame of Wi-Fi lis |
Update blufi.rst
2018-06-06 00:05:27 -04:00
| | | | report to the mobile phone. |
+-------------------------+--------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------------+
Update blufi.rst
2018-05-23 01:56:34 -04:00
component/bt: add readme doc for BLE demos - Closes:https://github.com/espressif/esp-idf/issues/3341
2019-04-26 05:24:34 -04:00
**1.2 Data Frame (0x1 b’01)**
+------------------+----------------------------------------------------+---------------------------------------------------------------+-----------------------------------------------------------------------+
|Data Frame(Binary)| Implication | Explanation | Note |
+==================+====================================================+===============================================================+=======================================================================+
| 0x0 (b’000000) | Send the negotiation data. | The negotiation data will be sent to the callback | The length of the data depends on the length field. |
| | | function registered in the application layer. | |
+------------------+----------------------------------------------------+---------------------------------------------------------------+-----------------------------------------------------------------------+
| 0x1 (b’000001) | Send the BSSID for STA mode. | To send the BSSID of the AP for the STA device to | The length of the data depends on the length field. |
docs: initial update of programming guide for C3 Updates "front page" content, get-started, and api-guides with C3 content Enable building and publishing of C3 docs in CI
2021-01-26 21:12:58 -05:00
| | | connect under the condition that the SSID is hidden. | When the transmission direction is ESP device to the mobile phone, |
component/bt: add readme doc for BLE demos - Closes:https://github.com/espressif/esp-idf/issues/3341
2019-04-26 05:24:34 -04:00
| | | | it means to provide the mobile phone with the needed information. |
+------------------+----------------------------------------------------+---------------------------------------------------------------+-----------------------------------------------------------------------+
| 0x2 (b’000010) | Send the SSID for STA mode. | To send the SSID of the AP for the STA device to connect. | The length of the data depends on the length field. |
docs: initial update of programming guide for C3 Updates "front page" content, get-started, and api-guides with C3 content Enable building and publishing of C3 docs in CI
2021-01-26 21:12:58 -05:00
| | | | When the transmission direction is ESP device to the mobile phone, |
component/bt: add readme doc for BLE demos - Closes:https://github.com/espressif/esp-idf/issues/3341
2019-04-26 05:24:34 -04:00
| | | | it means to provide the mobile phone with the needed information. |
+------------------+----------------------------------------------------+---------------------------------------------------------------+-----------------------------------------------------------------------+
| 0x3 (b’000011) | Send the password for STA mode. | To send the password of the AP for the STA device to connect. | The length of the data depends on the length field. |
docs: initial update of programming guide for C3 Updates "front page" content, get-started, and api-guides with C3 content Enable building and publishing of C3 docs in CI
2021-01-26 21:12:58 -05:00
| | | | When the transmission direction is ESP device to the mobile phone, |
component/bt: add readme doc for BLE demos - Closes:https://github.com/espressif/esp-idf/issues/3341
2019-04-26 05:24:34 -04:00
| | | | it means to provide the mobile phone with the needed information. |
+------------------+----------------------------------------------------+---------------------------------------------------------------+-----------------------------------------------------------------------+
| 0x4 (b’000100) | Send the SSID for SoftAP mode. | | The length of the data depends on the length field. |
docs: initial update of programming guide for C3 Updates "front page" content, get-started, and api-guides with C3 content Enable building and publishing of C3 docs in CI
2021-01-26 21:12:58 -05:00
| | | | When the transmission direction is ESP device to the mobile phone, |
component/bt: add readme doc for BLE demos - Closes:https://github.com/espressif/esp-idf/issues/3341
2019-04-26 05:24:34 -04:00
| | | | it means to provide the mobile phone with the needed information. |
+------------------+----------------------------------------------------+---------------------------------------------------------------+-----------------------------------------------------------------------+
| 0x5 (b’000101) | Send the password for SoftAPmode. | | The length of the data depends on the length field. |
docs: initial update of programming guide for C3 Updates "front page" content, get-started, and api-guides with C3 content Enable building and publishing of C3 docs in CI
2021-01-26 21:12:58 -05:00
| | | | When the transmission direction is ESP device to the mobile phone, |
component/bt: add readme doc for BLE demos - Closes:https://github.com/espressif/esp-idf/issues/3341
2019-04-26 05:24:34 -04:00
| | | | it means to provide the mobile phone with the needed information. |
+------------------+----------------------------------------------------+---------------------------------------------------------------+-----------------------------------------------------------------------+
| 0x6 (b’000110) | Set the maximum connection number for SoftAP mode. | | data[0] represents the value of the connection number, |
docs: initial update of programming guide for C3 Updates "front page" content, get-started, and api-guides with C3 content Enable building and publishing of C3 docs in CI
2021-01-26 21:12:58 -05:00
| | | | ranging from 1 to 4. When the transmission direction is ESP device |
component/bt: add readme doc for BLE demos - Closes:https://github.com/espressif/esp-idf/issues/3341
2019-04-26 05:24:34 -04:00
| | | | to the mobile phone, it means to provide the mobile phone with |
| | | | the needed information. |
+------------------+----------------------------------------------------+---------------------------------------------------------------+-----------------------------------------------------------------------+
| 0x7 (b’000111) | Set the authentication mode for the SoftAP. | | data[0]： |
+ + + +-----------------------------------------------------------------------+
| | | | 0x00: OPEN |
+ + + +-----------------------------------------------------------------------+
| | | | 0x01: WEP |
+ + + +-----------------------------------------------------------------------+
| | | | 0x02: WPA_PSK |
+ + + +-----------------------------------------------------------------------+
| | | | 0x03: WPA2_PSK |
+ + + +-----------------------------------------------------------------------+
| | | | 0x04: WPA_WPA2_PSK |
+ + + +-----------------------------------------------------------------------+
docs: initial update of programming guide for C3 Updates "front page" content, get-started, and api-guides with C3 content Enable building and publishing of C3 docs in CI
2021-01-26 21:12:58 -05:00
| | | | When the transmission direction is ESP device to the mobile phone, |
component/bt: add readme doc for BLE demos - Closes:https://github.com/espressif/esp-idf/issues/3341
2019-04-26 05:24:34 -04:00
| | | | it means to provide the mobile phone with the needed information. |
+------------------+----------------------------------------------------+---------------------------------------------------------------+-----------------------------------------------------------------------+
| 0x8 (b’001000) | Set the channel amount for SoftAP mode. | | data[0] represents the quantity of the supported channels, |
| | | | ranging from 1 to 14. |
docs: initial update of programming guide for C3 Updates "front page" content, get-started, and api-guides with C3 content Enable building and publishing of C3 docs in CI
2021-01-26 21:12:58 -05:00
| | | | When the transmission direction is ESP device to the mobile phone, |
component/bt: add readme doc for BLE demos - Closes:https://github.com/espressif/esp-idf/issues/3341
2019-04-26 05:24:34 -04:00
| | | | it means to provide the mobile phone with the needed information. |
+------------------+----------------------------------------------------+---------------------------------------------------------------+-----------------------------------------------------------------------+
| 0x9 (b’001001) | Username | It provides the username of the GATT client when using | The length of the data depends on the length field. |
| | | encryption of enterprise level. | |
+------------------+----------------------------------------------------+---------------------------------------------------------------+-----------------------------------------------------------------------+
| 0xa (b’001010) | CA Certification | It provides the CA Certification when using encryption | The length of the data depends on the length field. |
| | | of enterprise level. | The frame supports to be fragmented if the data length is not enough. |
+------------------+----------------------------------------------------+---------------------------------------------------------------+-----------------------------------------------------------------------+
| 0xb (b’001011) | Client Certification | It provides the client certification when | The length of the data depends on the length field. |
| | | using encryption of enterprise level. | The frame supports to be fragmented if the data length is not enough. |
| | | Whether the private key is contained or not | |
| | | depends on the content of the certification. | |
+------------------+----------------------------------------------------+---------------------------------------------------------------+-----------------------------------------------------------------------+
| 0xc (b’001100) | Server Certification | It provides the sever certification when using | The length of the data depends on the length field. |
| | | encryption of enterprise level. Whether the private key is | The frame supports to be fragmented if the data length is not enough. |
| | | contained or not depends on the content of the certification. | |
+------------------+----------------------------------------------------+---------------------------------------------------------------+-----------------------------------------------------------------------+
| 0xd (b’001101) | ClientPrivate Key | It provides the private key of the client when | The length of the data depends on the length field. |
| | | using encryption of enterprise level. | The frame supports to be fragmented if the data length is not enough. |
+------------------+----------------------------------------------------+---------------------------------------------------------------+-----------------------------------------------------------------------+
| 0xe (b’001110) | ServerPrivate Key | It provides the private key of the sever when | The length of the data depends on the length field. |
| | | using encryption of enterprise level. | The frame supports to be fragmented if the data length is not enough. |
+------------------+----------------------------------------------------+---------------------------------------------------------------+-----------------------------------------------------------------------+
docs: initial update of programming guide for C3 Updates "front page" content, get-started, and api-guides with C3 content Enable building and publishing of C3 docs in CI
2021-01-26 21:12:58 -05:00
| 0xf (b’001111) | Wi-Fi Connection State Report | To notify the phone of the ESP device's Wi-Fi status, | data[0] represents opmode, including: |
component/bt: add readme doc for BLE demos - Closes:https://github.com/espressif/esp-idf/issues/3341
2019-04-26 05:24:34 -04:00
+ + + including STA status and SoftAP status. +-----------------------------------------------------------------------+
| | | It is for the STA device to connect to the | 0x00: NULL |
+ + + mobile phone or the SoftAP. +-----------------------------------------------------------------------+
| | | However, when the mobile phone receives the Wi-Fi status, | 0x01: STA |
+ + + it can reply to other frames in addition to this frame. +-----------------------------------------------------------------------+
| | | | 0x02: SoftAP |
+ + + +-----------------------------------------------------------------------+
| | | | 0x03: SoftAP&STA |
+ + + +-----------------------------------------------------------------------+
| | | | data[1]：the connection state of the STA device, |
| | | | 0x0 indicates a connection state, |
| | | | and others represent a disconnected state; |
+ + + +-----------------------------------------------------------------------+
| | | | data[2]：the connection state of the 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. |
+------------------+----------------------------------------------------+---------------------------------------------------------------+-----------------------------------------------------------------------+
| 0x10 (b’010000) | Version | | data[0]= great versiondata[1]= sub version |
+------------------+----------------------------------------------------+---------------------------------------------------------------+-----------------------------------------------------------------------+
docs: initial update of programming guide for C3 Updates "front page" content, get-started, and api-guides with C3 content Enable building and publishing of C3 docs in CI
2021-01-26 21:12:58 -05:00
| 0x11 (b’010001) | Wi-Fi List | To send the Wi-Fi list to ESP device. | The format of the data frame is length + RSSI + SSID |
component/bt: add readme doc for BLE demos - Closes:https://github.com/espressif/esp-idf/issues/3341
2019-04-26 05:24:34 -04:00
| | | | and it supports to be sent into fragments |
| | | | if the data length is too long. |
+------------------+----------------------------------------------------+---------------------------------------------------------------+-----------------------------------------------------------------------+
| 0x12 (b’010010) | Report Error | To notify the mobile phone that there is an error with BluFi. | 0x00: sequence error |
+ + + +-----------------------------------------------------------------------+
| | | | 0x01: checksum error |
+ + + +-----------------------------------------------------------------------+
| | | | 0x02: decrypt error |
+ + + +-----------------------------------------------------------------------+
| | | | 0x03: encrypt error |
+ + + +-----------------------------------------------------------------------+
| | | | 0x04: init security error |
+ + + +-----------------------------------------------------------------------+
| | | | 0x05: dh malloc error |
+ + + +-----------------------------------------------------------------------+
| | | | 0x06: dh param error |
+ + + +-----------------------------------------------------------------------+
| | | | 0x07: read param error |
+ + + +-----------------------------------------------------------------------+
| | | | 0x08: make public error |
+------------------+----------------------------------------------------+---------------------------------------------------------------+-----------------------------------------------------------------------+
| 0x13 (b’010011) | Custom Data | To send or receive custom data. | The data frame supports to be sent into |
| | | | fragments if the data length is too long. |
+------------------+----------------------------------------------------+---------------------------------------------------------------+-----------------------------------------------------------------------+
Upload blufi.rst
2018-05-09 22:55:47 -04:00
2. Frame Control
Update blufi.rst
2018-06-04 02:21:12 -04:00
Control field, takes 1 byte and each bit has a different meaning.
Update blufi.rst
2018-06-05 23:58:46 -04:00
+--------------------+------------------------------------------------------------------------------------------------+
| Bit | Meaning |
+====================+================================================================================================+
| 0x01 | Indicates whether the frame is encrypted. |
+ +------------------------------------------------------------------------------------------------+
| | 1 means encryption, and 0 means unencrypted. |
+ +------------------------------------------------------------------------------------------------+
| | 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. |
+--------------------+------------------------------------------------------------------------------------------------+
| 0x02 | The data field that indicates whether a frame contains |
| | a checksum (such as SHA1,MD5,CRC, etc.) for the end of |
| | the frame data field includes SEQUCNE + data length + clear text. |
| | Both the control frame and the data frame can contain a check bit or not. |
+--------------------+------------------------------------------------------------------------------------------------+
| 0x04 | Represents the data direction. |
+--------------------+------------------------------------------------------------------------------------------------+
docs: initial update of programming guide for C3 Updates "front page" content, get-started, and api-guides with C3 content Enable building and publishing of C3 docs in CI
2021-01-26 21:12:58 -05:00
| | 0 means the mobile phone to ESP device; |
Update blufi.rst
2018-06-05 23:58:46 -04:00
+--------------------+------------------------------------------------------------------------------------------------+
docs: initial update of programming guide for C3 Updates "front page" content, get-started, and api-guides with C3 content Enable building and publishing of C3 docs in CI
2021-01-26 21:12:58 -05:00
| | 1 means ESP device to the mobile phone. |
Update blufi.rst
2018-06-05 23:58:46 -04:00
+--------------------+------------------------------------------------------------------------------------------------+
| 0x08 | Indicates whether the other person is required to reply to an ACK. |
+--------------------+------------------------------------------------------------------------------------------------+
| | 0 indicates no requirement; |
+--------------------+------------------------------------------------------------------------------------------------+
| | 1 indicates to reply Ack. |
+--------------------+------------------------------------------------------------------------------------------------+
| 0x10 | Indicates whether there are subsequent data fragments. |
+--------------------+------------------------------------------------------------------------------------------------+
| | 0 indicates that there are no subsequent data fragments for this frame; |
+--------------------+------------------------------------------------------------------------------------------------+
| | 1 indicates that there are subsequent data fragments and used to transmit longer data. |
+--------------------+------------------------------------------------------------------------------------------------+
| | In the case of a frag frame, |
| | the total length of the current content section + subsequent content section is given, |
| | in the first 2 bytes of the data field (that is, the content data of the maximum support 64K). |
+--------------------+------------------------------------------------------------------------------------------------+
| 0x10~0x80 reserved | |
+--------------------+------------------------------------------------------------------------------------------------+
Upload blufi.rst
2018-05-09 22:55:47 -04:00
3. Sequence Control
Update blufi.rst
2018-05-23 01:56:34 -04:00
Sequence control field. When a frame is sent,the value of sequence fied is automatically incremented by 1 regardless of the type of frame, which prevents Replay Attack. The sequence is cleared after each reconnection.
Upload blufi.rst
2018-05-09 22:55:47 -04:00
4. Length
Update blufi.rst
2018-05-23 02:02:09 -04:00
The length of the data field that does not include CheckSum.
Upload blufi.rst
2018-05-09 22:55:47 -04:00
5. Data
Update blufi.rst
2018-05-23 02:02:09 -04:00
The instruction of the data field is different according to various values of Type or Subtype. Please refer to the table above.
Upload blufi.rst
2018-05-09 22:55:47 -04:00
6. CheckSum
Update blufi.rst
2018-05-23 02:02:09 -04:00
This field takes 2 bytes that is used to check "sequence + data length + clear text data".
Upload blufi.rst
2018-05-09 22:55:47 -04:00
doc: Update English pages with generic target name
2019-12-08 22:01:09 -05:00
The Security Implementation of {IDF_TARGET_NAME}
------------------------------------------------
Upload blufi.rst
2018-05-09 22:55:47 -04:00
Update blufi.rst
2018-05-23 01:56:34 -04:00
1. Securing data
Upload blufi.rst
2018-05-09 22:55:47 -04:00
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).
Update blufi.rst
2018-05-23 01:56:34 -04:00
2. Ensuring data integrity
Upload blufi.rst
2018-05-09 22:55:47 -04:00
To ensure data integrity, you need to add a checksum algorithm, such as SHA1, MD5, CRC, etc.
Update blufi.rst
2018-05-23 01:56:34 -04:00
3. Securing identity (signature)
Upload blufi.rst
2018-05-09 22:55:47 -04:00
Update blufi.rst
2018-05-23 01:56:34 -04:00
Algorithm like RSA can be used to secure identity. But for DH, it needs other algorithms as an companion for signature.
Upload blufi.rst
2018-05-09 22:55:47 -04:00
Update blufi.rst
2018-05-23 01:56:34 -04:00
4. Replay attack prevention
Upload blufi.rst
2018-05-09 22:55:47 -04:00
Update blufi.rst
2018-05-23 02:02:09 -04:00
It is added to the Sequence field and used during the checksum verification.
Upload blufi.rst
2018-05-09 22:55:47 -04:00
doc: Update English pages with generic target name
2019-12-08 22:01:09 -05:00
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.
Update blufi.rst
2018-05-23 01:56:34 -04:00
The application layer needs to register several security-related functions to BluFi:
Upload blufi.rst
2018-05-09 22:55:47 -04:00
doc: Update English pages with generic target name
2019-12-08 22:01:09 -05:00
.. code-block:: c
Upload blufi.rst
2018-05-09 22:55:47 -04:00
Update blufi.rst
2018-05-23 01:56:34 -04:00
typedef void (*esp_blufi_negotiate_data_handler_t)(uint8_t *data, int len, uint8_t **output_data, int *output_len, bool *need_free)
Upload blufi.rst
2018-05-09 22:55:47 -04:00
doc: Update English pages with generic target name
2019-12-08 22:01:09 -05:00
This function is for {IDF_TARGET_NAME} to receive normal data during negotiation, and after processing is completed, the data will be transmitted using Output_data and Output_len.
Upload blufi.rst
2018-05-09 22:55:47 -04:00
Update blufi.rst
2018-05-23 01:56:34 -04:00
BluFi will send output_data from Negotiate_data_handler after Negotiate_data_handler is called.
Upload blufi.rst
2018-05-09 22:55:47 -04:00
Update blufi.rst
2018-05-23 01:56:34 -04:00
Here are two "*", because the length of the data to be emitted is unknown that requires the function to allocate itself (malloc) or point to the global variable, and to inform whether the memory needs to be freed by NEED_FREE.
Upload blufi.rst
2018-05-09 22:55:47 -04:00
Update blufi.rst
2018-05-23 01:56:34 -04:00
.. code-block:: c
Upload blufi.rst
2018-05-09 22:55:47 -04:00
docs: fix doxygen compile warnings for doxygen 1.9.1 Newer versions of doxygen will give warnings for comments in INPUT lists Delete all comment lines to fix these warnings, our folder structure stil gives an OK overview of what we are including
2021-04-08 23:57:03 -04:00
typedef int (* esp_blufi_encrypt_func_t)(uint8_t iv8, uint8_t *crypt_data, int crypt_len)
Upload blufi.rst
2018-05-09 22:55:47 -04:00
Update blufi.rst
2018-05-23 01:56:34 -04:00
The data to be encrypted and decrypted must use the same length. The IV8 is a 8 bit sequence value of frames, which can be used as a 8 bit of IV.
Upload blufi.rst
2018-05-09 22:55:47 -04:00
Update blufi.rst
2018-05-23 01:56:34 -04:00
.. code-block:: c
Upload blufi.rst
2018-05-09 22:55:47 -04:00
Update blufi.rst
2018-05-23 01:56:34 -04:00
typedef int (* esp_blufi_decrypt_func_t)(uint8_t iv8, uint8_t *crypt_data, int crypt_len)
Upload blufi.rst
2018-05-09 22:55:47 -04:00
Update blufi.rst
2018-05-23 01:56:34 -04:00
The data to be encrypted and decrypted must use the same length. The IV8 is a 8 bit sequence value of frames, which can be used as a 8 bit of IV.
Upload blufi.rst
2018-05-09 22:55:47 -04:00
Update blufi.rst
2018-05-23 01:56:34 -04:00
.. code-block:: c
Upload blufi.rst
2018-05-09 22:55:47 -04:00
Update blufi.rst
2018-05-23 01:56:34 -04:00
typedef uint16_t (*esp_blufi_checksum_func_t)(uint8_t iv8, uint8_t *data, int len)
Upload blufi.rst
2018-05-09 22:55:47 -04:00
Update blufi.rst
2018-05-23 01:56:34 -04:00
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.
Upload blufi.rst
2018-05-09 22:55:47 -04:00
GATT Related Instructions
Update blufi.rst
2018-05-23 05:15:24 -04:00
-------------------------
Upload blufi.rst
2018-05-09 22:55:47 -04:00
Update blufi.rst
2018-05-23 01:56:34 -04:00
UUID
Update blufi.rst
2018-05-23 05:15:24 -04:00
>>>>>
Upload blufi.rst
2018-05-09 22:55:47 -04:00
Update blufi.rst
2018-05-23 02:02:09 -04:00
BluFi Service UUID: 0xFFFF，16 bit
Upload blufi.rst
2018-05-09 22:55:47 -04:00
doc: Update English pages with generic target name
2019-12-08 22:01:09 -05:00
BluFi (the mobile -> {IDF_TARGET_NAME}): 0xFF01, writable
Upload blufi.rst
2018-05-09 22:55:47 -04:00
doc: Update English pages with generic target name
2019-12-08 22:01:09 -05:00
Blufi ({IDF_TARGET_NAME} -> the mobile phone): 0xFF02, readable and callable
Reference in New Issue Copy Permalink