diff --git a/docs/en/api-guides/blufi.rst b/docs/en/api-guides/blufi.rst index d9743dba67..9d7bfb120b 100644 --- a/docs/en/api-guides/blufi.rst +++ b/docs/en/api-guides/blufi.rst @@ -4,6 +4,7 @@ BluFi Overview -------- + 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. Fragmenting, data encryption, checksum verification in the BluFi layer are the key elements of this process. @@ -12,6 +13,7 @@ You can customize symmetric encryption, asymmetric encryption and checksum suppo The BluFi Flow --------------- + 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, connection status backhaul. @@ -42,8 +44,8 @@ The following uses Station as an example to illustrate the core parts of the pro 2. The data lengths before and after symmetric encryption/decryption must stay the same. It also supports in-place encryption and decryption. -The flow chart of BluFi ------------------------ +The Flow Chart of BluFi +-------------------------- .. seqdiag:: :caption: BluFi Flow Chart @@ -78,64 +80,72 @@ The frame formats for the communication between the mobile phone App and {IDF_TA The frame format with no fragment (8 bit)： -+-----------------+----------------+ -| Description | Value | -+=================+================+ -| LSB - Type | 1 | -+-----------------+----------------+ -| Frame Control | 1 | -+-----------------+----------------+ -| Sequence Number | 1 | -+-----------------+----------------+ -| Data Length | 1 | -+-----------------+----------------+ -| Data | ${Data Length} | -+-----------------+----------------+ -| MSB - CheckSum | 2 | -+-----------------+----------------+ +.. list-table:: + :header-rows: 1 + :widths: 25 25 + + * - Description + - Value + * - Type (Least Significant Bit) + - 1 + * - Frame Control + - 1 + * - Sequence Number + - 1 + * - Data Length + - 1 + * - Data + - ${Data Length} + * - CheckSum (Most Siginificant Bit) + - 2 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. The frame format with fragments（8 bit）： -+--------------------+-------------------------------------------+ -| Description | Value | -+====================+===========================================+ -| LSB - Type | 1 | -+--------------------+-------------------------------------------+ -| FrameControl(Frag) | 1 | -+--------------------+-------------------------------------------+ -| SequenceNumber | 1 | -+--------------------+-------------------------------------------+ -| DataLength | 1 | -+--------------------+----------------------+--------------------+ -| | Total Content Length | 2 | -+ Data +----------------------+--------------------+ -| | Content | ${Data Length} - 2 | -+--------------------+----------------------+--------------------+ -| MSB - CheckSum | 2 | -+--------------------+-------------------------------------------+ +.. list-table:: + :header-rows: 1 + :widths: 25 25 + + * - Description + - Value + * - Type (Least Significant Bit) + - 1 + * - Frame Control (Frag) + - 1 + * - Sequence Number + - 1 + * - Data Length + - 1 + * - Data + - * Total Content Length: 2 + * Content: ${Data Length} - 2 + * - CheckSum (Most Siginificant Bit) + - 2 -Normally, the control frame does not contain data bits, except for Ack Frame. +Normally, the control frame does not contain data bits, except for ACK Frame. -The format of Ack Frame（8 bit）： +The format of ACK Frame（8 bit）： + +.. list-table:: + :header-rows: 1 + :widths: 25 25 + + * - Description + - Value + * - Type - ACK (Least Significant Bit) + - 1 + * - Frame Control + - 1 + * - Sequence Number + - 1 + * - Data Length + - 1 + * - Data + - Acked Sequence Number: 2 + * - CheckSum (Most Siginificant Bit) + - 2 -+------------------+--------------------------------------------+ -| Description | Value | -+------------------+--------------------------------------------+ -| LSB - Type (Ack) | 1 | -+------------------+--------------------------------------------+ -| Frame Control | 1 | -+------------------+--------------------------------------------+ -| SequenceNumber | 1 | -+------------------+--------------------------------------------+ -| DataLength | 1 | -+------------------+-----------------------+--------------------+ -+ Data + Acked Sequence Number + 2 + -| | | | -+------------------+-----------------------+--------------------+ -| MSB - CheckSum | 2 | -+------------------+--------------------------------------------+ 1. Type @@ -145,235 +155,248 @@ The format of Ack Frame（8 bit）： * The data frame supports to be encrypted and verified. - **1.1 Control Frame (0x0 b’00)** +1.1 Control Frame (Binary: 0x0 b’00) - +-------------------------+--------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------------+ - | Control Frame (Binary) | Implication | Explanation | Note | - +=========================+==============================================================+===============================================================+===============================================================+ - | 0x0 (b’000000) | Ack | The data field of the Ack frame uses the same | The data field consumes a byte and its value is | - | | | sequence value of the frame to reply to. | the same as the sequence field of the frame to reply to. | - +-------------------------+--------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------------+ - | 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. | - | | | 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. | - + + + If it is not set, ESP device will send the control frame +---------------------------------------------------------------+ - | | | and data frame with no checksum and encryption by default. | b’0000: no checksum and no encryption; | - + + + The data transmission from the mobile phone to ESP device is +---------------------------------------------------------------+ - | | | 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. | - +-------------------------+--------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------------+ - | 0x2 (b’000010) | Set the opmode of Wi-Fi. | The frame contains opmode settings for | data[0] is for opmode settings, including: | - + + + configuring for the Wi-Fi mode of ESP device. +---------------------------------------------------------------+ - | | | | 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. | - +-------------------------+--------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------------+ - | 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. | | - +-------------------------+--------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------------+ - | 0x4 (b’000100) | Disconnect ESP device from the AP. | | No data field is contained. | - +-------------------------+--------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------------+ - | 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 | - | | | | 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. | - +-------------------------+--------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------------+ - | 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. | - | | | | If there is a second STA device, then it uses data[6-11] | - | | | | and the rest can be done in the same manner. | - +-------------------------+--------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------------+ - | 0x7 (b'000111) | Get the version information. | | | - +-------------------------+--------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------------+ - | 0x8 (b’001000) | Disconnect the BLE GATT link. | | ESP device will disconnect the BLE GATT link | - | | | | after receives this command. | - +-------------------------+--------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------------+ - | 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. | - | | | | When receiving this control frame, | - | | | | ESP device will send back a follow-up frame of Wi-Fi lis | - | | | | report to the mobile phone. | - +-------------------------+--------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------------+ +.. list-table:: + :header-rows: 1 + :widths: 5 15 20 30 + + * - Control Frame + - Implication + - Explanation + - Note - **1.2 Data Frame (0x1 b’01)** + * - 0x0 (b’000000) + - ACK + - The data field of the ACK frame uses the same sequence value of the frame to reply to. + - The data field consumes a byte and its value is the same as the sequence field of the frame to reply to. + + * - 0x1 (b’000001) + - Set ESP device to the security mode. + - To inform 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. - +------------------+----------------------------------------------------+---------------------------------------------------------------+-----------------------------------------------------------------------+ - |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. | - | | | connect under the condition that the SSID is hidden. | When the transmission direction is ESP device to the mobile phone, | - | | | | 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. | - | | | | When the transmission direction is ESP device to the mobile phone, | - | | | | 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. | - | | | | When the transmission direction is ESP device to the mobile phone, | - | | | | 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. | - | | | | When the transmission direction is ESP device to the mobile phone, | - | | | | 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. | - | | | | When the transmission direction is ESP device to the mobile phone, | - | | | | 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, | - | | | | 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. | - +------------------+----------------------------------------------------+---------------------------------------------------------------+-----------------------------------------------------------------------+ - | 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 | - + + + +-----------------------------------------------------------------------+ - | | | | When the transmission direction is ESP device to the mobile phone, | - | | | | 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. | - | | | | When the transmission direction is ESP device to the mobile phone, | - | | | | 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. | - +------------------+----------------------------------------------------+---------------------------------------------------------------+-----------------------------------------------------------------------+ - | 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: | - + + + 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 | - +------------------+----------------------------------------------------+---------------------------------------------------------------+-----------------------------------------------------------------------+ - | 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 | - | | | | 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. | - +------------------+----------------------------------------------------+---------------------------------------------------------------+-----------------------------------------------------------------------+ + If it is not set, 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 ESP device is controlled by this control frame. + - The data field consumes a byte. The higher 4 bits are for the security mode setting of the control frame, and the lower 4 bits are for the security mode setting of the data frame. + + * b’0000: no checksum and no encryption; + * b’0001: with checksum but no encryption; + * b’0010: no checksum but with encryption; + * b’0011: with both checksum and encryption. + + * - 0x2 (b’000010) + - Set the opmode of Wi-Fi. + - The frame contains opmode settings for configuring the Wi-Fi mode of ESP device. + - data[0] is for opmode settings, including: + + * 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. + + * - 0x3 (b’000011) + - Connect ESP device to the AP. + - To notify ESP device that the essential information has been sent and it is allowed to connect to the AP. + - No data field is contained. + + * - 0x4 (b’000100) + - Disconnect ESP device from the AP. + - + - No data field is contained. + + * - 0x5 (b’000101) + - To get the information of ESP device’s Wi-Fi mode and it’s status. + - + - * No data field is contained. When receiving this control frame, 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. + * The types of information sent to the mobile phone is defined by the application installed on the phone. + + * - 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. If there is a second STA device, then it uses data[6-11] and the rest can be done in the same manner. + + * - 0x7 (b’000111) + - Get the version information. + - + - + + * - 0x8 (b’001000) + - Disconnect the BLE GATT link. + - + - ESP device will disconnect the BLE GATT link after receives this command. + + * - 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. When receiving this control frame, ESP device will send back a follow-up frame of Wi-Fi list report to the mobile phone. + + + +1.2 Data Frame (Binary: 0x1 b’01) + +.. list-table:: + :header-rows: 1 + :widths: 5 15 20 30 + + * - Data Frame + - Implication + - Explanation + - Note + * - 0x0 (b’000000) + - Send the negotiation data. + - The negotiation data will be sent to the callback function registered in the application layer. + - The length of the data depends on the length field. + * - 0x1 (b’000001) + - Send the BSSID for STA mode. + - 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. + * - 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 + + When the transmission direction is ESP device to the mobile phone, it means to provide the mobile phone with the needed information. + * - 0x8 (b’001000) + - Set the number of channels for SoftAP mode. + - + - data[0] represents the quantity of the supported channels, ranging from 1 to 14. When the transmission direction is ESP device to the mobile phone, 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 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[0] represents opmode, including: + + * 0x00: NULL + * 0x01: STA + * 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 version + * data[1]= sub version + * - 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 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. + +.. note:: + + - Note 1: The length of the data depends on the length field. When the transmission direction is 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 length field. The frame supports to be fragmented if the data length is not enough. 2. Frame Control Control field, takes 1 byte and each bit has a different meaning. - +--------------------+------------------------------------------------------------------------------------------------+ - | 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. | - +--------------------+------------------------------------------------------------------------------------------------+ - | | 0 means the mobile phone to ESP device; | - +--------------------+------------------------------------------------------------------------------------------------+ - | | 1 means ESP device to the mobile phone. | - +--------------------+------------------------------------------------------------------------------------------------+ - | 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 | | - +--------------------+------------------------------------------------------------------------------------------------+ + +.. list-table:: + :header-rows: 1 + :widths: 10 35 + + * - Bit + - Meaning + * - 0x01 + - Indicates whether the frame is encrypted. + + * 1 means encryption + * 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 sequence + data length + clear text. Both the control frame and the data frame can contain a check bit or not. + * - 0x04 + - Represents the data direction. + + * 0 means the mobile phone to ESP device; + * 1 means ESP device to the mobile phone. + * - 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 64 K). + * - 0x10~0x80 + - reserved 3. Sequence Control @@ -448,7 +471,7 @@ GATT Related Instructions UUID >>>>> -BluFi Service UUID: 0xFFFF，16 bit +BluFi Service UUID: 0xFFFF, 16 bit BluFi (the mobile -> {IDF_TARGET_NAME}): 0xFF01, writable diff --git a/docs/en/api-guides/build-system.rst b/docs/en/api-guides/build-system.rst index 8bc616d65e..03c0d5737f 100644 --- a/docs/en/api-guides/build-system.rst +++ b/docs/en/api-guides/build-system.rst @@ -781,16 +781,16 @@ Browse the :idf_file:`/tools/cmake/project.cmake` file and supporting functions Example Component CMakeLists ============================ -Because the build environment tries to set reasonable defaults that will work most -of the time, component ``CMakeLists.txt`` can be very small or even empty (see `Minimal Component CMakeLists`_). However, overriding `component variables`_ is usually required for some functionality. +Because the build environment tries to set reasonable defaults that will work most of the time, component ``CMakeLists.txt`` can be very small or even empty (see `Minimal Component CMakeLists`_). However, overriding `component variables`_ is usually required for some functionality. Here are some more advanced examples of component CMakeLists files. +.. _add_conditional_config: + Adding conditional configuration -------------------------------- -The configuration system can be used to conditionally compile some files -depending on the options selected in the project configuration. +The configuration system can be used to conditionally compile some files depending on the options selected in the project configuration. .. highlight:: none diff --git a/docs/zh_CN/api-guides/blufi.rst b/docs/zh_CN/api-guides/blufi.rst index 6d443d6f26..51a191bf1b 100644 --- a/docs/zh_CN/api-guides/blufi.rst +++ b/docs/zh_CN/api-guides/blufi.rst @@ -4,7 +4,8 @@ BluFi 概览 ----- -BluFi 是一款基于蓝牙通道的 Wi-Fi 网络配置功能，适用于 ESP32。它通过安全协议将 Wi-Fi 配置和证书传输到 ESP32，然后 ESP32 可基于这些信息连接到 AP 或建立 SoftAP。 + +BluFi 是一款基于蓝牙通道的 Wi-Fi 网络配置功能，适用于 {IDF_TARGET_NAME}。它通过安全协议将 Wi-Fi 的 SSID、密码等配置信息传输到 {IDF_TARGET_NAME}，然后 {IDF_TARGET_NAME} 可基于这些信息连接到 AP 或建立 SoftAP。 BluFi 流程的关键部分包括数据的分片、加密、校验和验证。 @@ -12,42 +13,39 @@ BluFi 流程的关键部分包括数据的分片、加密、校验和验证。 BluFi 流程 ---------- + BluFi 配网功能包含配置 SoftAP 和 Station 两部分。 -下面以配置 Station 为例说明配置步骤。 -BluFi 配网的配置 Station 包含广播、连接、服务发现、协商共享密钥、传输数据、回传连接状态等步骤。 +下面以配置 Station 为例说明配置步骤。BluFi 配网的配置 Station 包含广播、连接、服务发现、协商共享密钥、传输数据、回传连接状态等步骤。 -ESP32 配网流程 --------------- +1. {IDF_TARGET_NAME} 开启 GATT Server 模式，发送带有特定 *advertising data* 的广播。你可以自定义该广播，该广播不属于 BluFi Profile。 -1. ESP32 开启 GATT Server 功能，发送带有特定 *adv data* 的广播。你可以自定义该广播，该广播不属于 BluFi Profile。 +2. 使用手机 APP 搜索到该特定广播，手机作为 GATT Client 连接 {IDF_TARGET_NAME}。你可以决定使用哪款手机 APP。 -2. 使用手机 APP 搜索到该特定广播，手机作为 GATT Client 连接 ESP32。你可以决定使用哪款手机 APP。 +3. GATT 连接建立成功后，手机会向 {IDF_TARGET_NAME} 发送数据帧进行密钥协商（详情见 :ref:`frame_formats` ）。 -3. GATT 连接建立成功后，手机向 ESP32 发送“协商过程”数据帧（详情见 :ref:`frame_formats` ）。 +4. {IDF_TARGET_NAME} 收到密钥协商的数据帧后，会按照使用者自定义的协商方法来解析。 -4. ESP32 收到“协商过程”数据帧后，会按照使用者自定义的协商过程来解析。 +5. 手机与 {IDF_TARGET_NAME} 进行密钥协商。协商过程可使用 DH/RSA/ECC 等加密算法。 -5. 手机与 ESP32 进行密钥协商。协商过程可使用 DH/RSA/ECC 等加密算法进行。 +6. 协商结束后，手机端向 {IDF_TARGET_NAME} 发送控制帧，用于设置安全模式。 -6. 协商结束后，手机端向 ESP32 发送“设置安全模式”控制帧。 +7. {IDF_TARGET_NAME} 收到控制帧后，使用共享密钥以及安全配置对通信数据进行加密和解密。 -7. ESP32 收到“设置安全模式”控制帧后，使用经过协商的共享密钥以及配置的安全策略对通信数据进行加密和解密。 +8. 手机向 {IDF_TARGET_NAME} 发送 :ref:`frame_formats` 中定义的数据帧，包括 SSID、密码等 Wi-Fi 配置信息。 -8. 手机向 ESP32 发送“BluFi 传输格式”定义的 SSID、Password 等用于 Wi-Fi 连接的必要信息。 +9. 手机向 {IDF_TARGET_NAME} 发送 Wi-Fi 连接请求的控制帧。{IDF_TARGET_NAME} 收到这个控制帧之后，会认为手机已将必要的信息已经传输完毕，准备连接 Wi-Fi。 -9. 手机向 ESP32 发送“Wi-Fi 连接请求”控制帧，ESP32 收到之后，识别为手机已将必要的信息传输完毕，准备连接 Wi-Fi。 - -10. ESP32 连接到 Wi-Fi 后，发送“Wi-Fi 连接状态报告”控制帧到手机，以报告连接状态。至此配网结束。 +10. {IDF_TARGET_NAME} 连接到 Wi-Fi 后，发送 Wi-Fi 连接状态报告的控制帧到手机，以报告连接状态。至此配网结束。 .. note:: - 1. 安全模式设置可在任何时候进行，ESP32 收到安全模式的配置后，会根据安全模式指定的模式进行安全相关的操作。 + 1. {IDF_TARGET_NAME} 收到安全模式配置的控制帧后，会根据定义的安全模式进行相关操作。 2. 进行对称加密和解密时，加密和解密前后的数据长度必须一致，支持原地加密和解密。 -配网流程图 ------------ +BluFi 流程图 +--------------- .. seqdiag:: :caption: BluFi Flow Chart @@ -61,344 +59,371 @@ ESP32 配网流程 span_height = 10; default_fontsize = 12; - Phone <- ESP32 [label="广播"]; - Phone -> ESP32 [label="建立 GATT 链接"]; - Phone <- ESP32 [label="协商密钥"]; - Phone -> ESP32 [label="协商密钥"]; - Phone -> ESP32 [label="CTRL: 设置 ESP32 手机安全模式"]; - Phone -> ESP32 [label="DATA: SSID"]; - Phone -> ESP32 [label="DATA: Password"]; - Phone -> ESP32 [label="DATA: 其他信息，如 CA 认证"]; - Phone -> ESP32 [label="CTRL: 连接到 AP"]; - Phone <- ESP32 [label="DATA: 连接状态报告"]; + Phone <- {IDF_TARGET_NAME} [label="广播"]; + Phone -> {IDF_TARGET_NAME} [label="建立 GATT 链接"]; + Phone <- {IDF_TARGET_NAME} [label="协商密钥"]; + Phone -> {IDF_TARGET_NAME} [label="协商密钥"]; + Phone -> {IDF_TARGET_NAME} [label="CTRL: 设置 {IDF_TARGET_NAME} 为手机安全模式"]; + Phone -> {IDF_TARGET_NAME} [label="DATA: SSID"]; + Phone -> {IDF_TARGET_NAME} [label="DATA: Password"]; + Phone -> {IDF_TARGET_NAME} [label="DATA: 其他信息，如 CA 认证"]; + Phone -> {IDF_TARGET_NAME} [label="CTRL: 连接到 AP"]; + Phone <- {IDF_TARGET_NAME} [label="DATA: 连接状态报告"]; } .. _frame_formats: -BluFi 传输格式 --------------- +BluFi 中定义的帧格式 +---------------------------- -手机 APP 与 ESP32 之间的 BluFi 通信格式定义如下： +手机 APP 与 {IDF_TARGET_NAME} 之间的 BluFi 通信格式定义如下： -帧不分片情况下的标准格式 (8 bit)： +帧不分片情况下的格式 (8 位)： -+-----------------+----------------+ -| Description | Value | -+=================+================+ -| LSB - Type | 1 | -+-----------------+----------------+ -| Frame Control | 1 | -+-----------------+----------------+ -| Sequence Number | 1 | -+-----------------+----------------+ -| Data Length | 1 | -+-----------------+----------------+ -| Data | ${Data Length} | -+-----------------+----------------+ -| MSB - CheckSum | 2 | -+-----------------+----------------+ +.. list-table:: + :header-rows: 1 + :widths: 25 25 + + * - 描述 + - 值 + * - 类型字段（最低有效位） + - 1 + * - 帧控制字段 + - 1 + * - 序列号字段 + - 1 + * - 数据长度字段 + - 1 + * - 数据字段 + - ${Data Length} + * - 校验字段（最高有效位） + - 2 -如果 **Frame Control** 帧中的 **More Frag** 使能，则 **Total Content Length** 为数据帧中剩余部分的总长度，用于报告终端需要分配多少内存。 +如果使能 **帧控制** 位，则 **总长度** 位表示帧的剩余部分的总长度，用于报告终端需要分配多少内存。 -帧分片格式（8 bit）： +帧分片格式（8 位）： -+--------------------+-------------------------------------------+ -| Description | Value | -+====================+===========================================+ -| LSB - Type | 1 | -+--------------------+-------------------------------------------+ -| FrameControl(Frag) | 1 | -+--------------------+-------------------------------------------+ -| SequenceNumber | 1 | -+--------------------+-------------------------------------------+ -| DataLength | 1 | -+--------------------+----------------------+--------------------+ -| | Total Content Length | 2 | -+ Data +----------------------+--------------------+ -| | Content | ${Data Length} - 2 | -+--------------------+----------------------+--------------------+ -| MSB - CheckSum | 2 | -+--------------------+-------------------------------------------+ +.. list-table:: + :header-rows: 1 + :widths: 25 25 + + * - 描述 + - 值 + * - 类型字段（最低有效位） + - 1 + * - 帧控制字段（分片） + - 1 + * - 序列号字段 + - 1 + * - 数据长度字段 + - 1 + * - 数据字段 + - * Total Content Length: 2 + * Content: ${Data Length} - 2 + * - 校验字段（最高有效位） + - 2 -通常情况下，控制帧不包含数据位，Ack 帧类型除外。 +通常情况下，控制帧不包含数据位，ACK 帧类型除外。 -Ack 帧格式（8 bit）： +ACK 帧格式（8 bit）： -+------------------+--------------------------------------------+ -| Description | Value | -+------------------+--------------------------------------------+ -| LSB - Type (Ack) | 1 | -+------------------+--------------------------------------------+ -| Frame Control | 1 | -+------------------+--------------------------------------------+ -| SequenceNumber | 1 | -+------------------+--------------------------------------------+ -| DataLength | 1 | -+------------------+-----------------------+--------------------+ -+ Data + Acked Sequence Number + 2 + -| | | | -+------------------+-----------------------+--------------------+ -| MSB - CheckSum | 2 | -+------------------+--------------------------------------------+ +.. list-table:: + :header-rows: 1 + :widths: 25 25 + + * - 描述 + - 值 + * - 类型字段 - ACK（最低有效位） + - 1 + * - 帧控制字段 + - 1 + * - 序列号字段 + - 1 + * - 数据长度字段 + - 1 + * - 数据字段 + - ACK 序列号: 2 + * - 校验字段（最高有效位） + - 2 -1. Type + +1. 类型字段 - 类型域，占 1 byte。分为 Type 和 Subtype（子类型域）两部分, Type 占低 2 bit，Subtype 占高 6 bit。 + 类型字段，占 1 字节。分为类型字段和子类型字段两部分，类型字段占低 2 位，子类型字段占高 6 位。 * 控制帧，暂不进行加密，可校验； * 数据帧，可加密，可校验。 - **1.1 控制帧 (0x0 b’00)** +1.1 控制帧 (二进制：0x0 b’00) - +------------------+-----------------------------------+----------------------------------------------------------------+----------------------------------------------------------------------+ - | 控制帧 (二进制) | 含义 | 解释 | 备注 | - +==================+===================================+================================================================+======================================================================+ - | 0x0 (b’000000) | Ack | 用来回复对方发的帧， | Data 域使用1 byte Sequence 值， | - | | | Ack 帧的 Data 域使用回复对象帧的 Sequence 值。 | 与恢复对象帧的Sequence 值相同。 | - +------------------+-----------------------------------+----------------------------------------------------------------+----------------------------------------------------------------------+ - | 0x1 (b’000001) | Set ESP32 to the security mode. | 通知 ESP32 发送数据时使用的安全模式， | Data 域占用 1 byte。 | - | | | 在该过程中可设置多次，每次设置后影响后续安全模式。 | 高 4 bit 为控制帧的安全模式，低 4bit 为数据帧的安全模式。 | - + + + 在不设置的情况下，ESP32 默认控制帧和数据帧均为无校验、无加密。 +----------------------------------------------------------------------+ - | | | 手机到 ESP32 方向依赖于帧 Control 域。 | b’0000：无校验、无加密； | - + + + +----------------------------------------------------------------------+ - | | | | b’0001：有校验、无加密； | - + + + +----------------------------------------------------------------------+ - | | | | b’0010：无校验、有加密； | - + + + +----------------------------------------------------------------------+ - | | | | b’0011：有校验、有加密。 | - +------------------+-----------------------------------+----------------------------------------------------------------+----------------------------------------------------------------------+ - | 0x2 (b’000010) | Set the Wi-Fi opmode of ESP32. | 设置 ESP32 的 Wi-Fi 模式，帧包含 opmode 信息。 | data[0] 用于表示 opmode 类型，包括： | - + + + +----------------------------------------------------------------------+ - | | | | 0x00: NULL; | - + + + +----------------------------------------------------------------------+ - | | | | 0x01: STA; | - + + + +----------------------------------------------------------------------+ - | | | | 0x02: SoftAP; | - + + + +----------------------------------------------------------------------+ - | | | | 0x03: SoftAP&STA. | - + + + +----------------------------------------------------------------------+ - | | | | 如果设置有包含 AP，请尽量优先 | - | | | | 设置 AP 模式的SSID/Password/Max Conn Number 等。 | - +------------------+-----------------------------------+----------------------------------------------------------------+----------------------------------------------------------------------+ - | 0x3 (b’000011) | Connect ESP32 to the AP. | 通知 ESP32，必要的信息已经发送完毕，可以连接 AP。 | 不包含 Data 域。 | - +------------------+-----------------------------------+----------------------------------------------------------------+----------------------------------------------------------------------+ - | 0x4 (b’000100) | Disconnect ESP32 from the AP. | 通知 ESP32 断开与 AP 的连接 | 不包含 Data 域。 | - +------------------+-----------------------------------+----------------------------------------------------------------+----------------------------------------------------------------------+ - | 0x5 (b’000101) | Get the status of Wi-Fi. | 获取 ESP32 的 Wi-Fi 模式和状态等信息。 | 不包含 Data 域。 | - | | | | ESP32 收到此控制帧后，后续会通过 Wi-Fi 连接状态 | - | | | | 报告 (Wi-Fi Connection State Report) 数据帧来回复手机端当前 | - | | | | 所处的 opmode、连接状态、SSID 等信息。提供给手机端的信息由应用决定。 | - +------------------+-----------------------------------+----------------------------------------------------------------+----------------------------------------------------------------------+ - | 0x6 (b’000110) | Disconnect the STA device | 处于 SoftAP 模式时，踢掉某个 STA 设备。 | data[0~5] 为 STA 设备的 MAC 地址， | - | | from the SoftAP in SoftAP mode. | | 如有多个 STA，则 [6-11] 为第二个，依次类推。 | - +------------------+-----------------------------------+----------------------------------------------------------------+----------------------------------------------------------------------+ - | 0x7 (b'000111) | Get the version. | | | - +------------------+-----------------------------------+----------------------------------------------------------------+----------------------------------------------------------------------+ - | 0x8 (b’001000) | Tell ESP32 to disconnect | 通知 ESP32 断开蓝牙连接。 | ESP32 收到该指令后主动断开蓝牙连接。 | - | | the BLE GATT link. | | | - +------------------+-----------------------------------+----------------------------------------------------------------+----------------------------------------------------------------------+ - | 0x9 (b’001001) | Tell ESP32 to get the Wi-Fi list. | 通知 ESP32 扫描周围的 Wi-Fi 热点 | 不包含 Data 域。 | - | | | | ESP32 收到此控制帧后，会发送包含 Wi-Fi 热点 | - | | | | 报告 (Wi-Fi List Report) 的数据帧回复 | - | | | | 手机端 ESP32 周围的 Wi-Fi 热点。 | - +------------------+-----------------------------------+----------------------------------------------------------------+----------------------------------------------------------------------+ +.. list-table:: + :header-rows: 1 + :widths: 5 15 20 30 + + * - 控制帧 + - 含义 + - 解释 + - 备注 - **1.2 数据帧 (0x1 b’01)** + * - 0x0 (b’000000) + - ACK + - ACK 帧的数据字段使用回复对象帧的序列值。 + - 数据字段占用 1 字节，其序列值与回复对象帧的序列值相同。 + + * - 0x1 (b’000001) + - 将 ESP 设备设置为安全模式。 + - 通知 ESP 设备发送数据时使用的安全模式，在数据发送过程中可多次重置，每次设置后会影响后续使用的安全模式。 + + 如果不设置，ESP 设备将默认发送不带校验和加密的控制帧和数据帧。从手机到 ESP 设备的数据传输是由这个控制帧控制的。 + - 数据字段占一个字节。高 4 位用于控制帧的安全模式设置，低 4 位用于数据帧的安全模式设置。 - +---------------+----------------------------------------+------------------------------------------------+------------------------------------------------------+ - |数据帧 (二进制)| 含义 | 解释 | 备注 | - +===============+========================================+================================================+======================================================+ - | 0x0 (b’000000)| Negotiation data. | 用来发送协商数据，传输到应用层注册的回调函数。 | 数据长度与 Length 域有关。 | - +---------------+----------------------------------------+------------------------------------------------+------------------------------------------------------+ - | 0x1 (b’000001)| BSSID for STA mode. | STA 将要连接的 AP 的 BSSID（用于隐藏SSID）。 | 数据长度与 Length 域有关。 | - + + + +------------------------------------------------------+ - | | | | 当传输方向为 ESP32 到手机时， | - | | | | 表示向手机端提供信息。 | - +---------------+----------------------------------------+------------------------------------------------+------------------------------------------------------+ - | 0x2 (b’000010)| SSID for STA mode. | STA 将要连接的 AP 的 SSID。 | 数据长度与 Length 域有关。 | - + + + +------------------------------------------------------+ - | | | | 当传输方向为 ESP32 到手机时， | - | | | | 表示向手机端提供信息。 | - +---------------+----------------------------------------+------------------------------------------------+------------------------------------------------------+ - | 0x3 (b’000011)| Password for STA mode. | STA 将要连接的 AP 的密码。 | 数据长度与 Length 域有关。 | - + + + +------------------------------------------------------+ - | | | | 当传输方向为 ESP32 到手机时， | - | | | | 表示向手机端提供信息。 | - +---------------+----------------------------------------+------------------------------------------------+------------------------------------------------------+ - | 0x4 (b’000100)| SSID for SoftAP mode. | SoftAP 模式使用的 SSID。 | 数据长度与 Length 域有关。 | - + + + +------------------------------------------------------+ - | | | | 当传输方向为 ESP32 到手机时， | - | | | | 表示向手机端提供信息。 | - +---------------+----------------------------------------+------------------------------------------------+------------------------------------------------------+ - | 0x5 (b’000101)| Password for SoftAPmode. | SoftAP 模式使用的密码。 | 数据长度与 Length 域有关。 | - + + + +------------------------------------------------------+ - | | | | 当传输方向为 ESP32 到手机时， | - | | | | 表示向手机端提供信息。 | - +---------------+----------------------------------------+------------------------------------------------+------------------------------------------------------+ - | 0x6 (b’000110)| Max connection number for SoftAP mode. | AP 模式的最大连接数。 | data[0] 表示连接数的值，范围 1~4。 | - + + + +------------------------------------------------------+ - | | | | 当传输方向为 ESP32 到手机时， | - | | | | 表示向手机端提供信息。 | - +---------------+----------------------------------------+------------------------------------------------+------------------------------------------------------+ - | 0x7 (b’000111)| Authentication mode for SoftAP mode. | AP 模式的认证模式。 | data[0]： | - + + + +------------------------------------------------------+ - | | | | 0x00: OPEN; | - + + + +------------------------------------------------------+ - | | | | 0x01: WEP; | - + + + +------------------------------------------------------+ - | | | | 0x02: WPA_PSK; | - + + + +------------------------------------------------------+ - | | | | 0x03: WPA2_PSK; | - + + + +------------------------------------------------------+ - | | | | 0x04: WPA_WPA2_PSK. | - + + + +------------------------------------------------------+ - | | | | 当传输方向为 ESP32 到手机时， | - | | | | 表示向手机端提供信息。 | - +---------------+----------------------------------------+------------------------------------------------+------------------------------------------------------+ - | 0x8 (b’001000)| Channel for SoftAP mode. | SoftAP 模式的通道数量。 | data[0] 表示通道的数量，范围 1~14。 | - + + + +------------------------------------------------------+ - | | | | 当传输方向为 ESP32 到手机时， | - | | | | 表示向手机端提供信息。 | - +---------------+----------------------------------------+------------------------------------------------+------------------------------------------------------+ - | 0x9 (b’001001)| Username. | 使用企业级加密时，Client 端的用户名。 | 数据长度与 Length 域有关。 | - +---------------+----------------------------------------+------------------------------------------------+------------------------------------------------------+ - | 0xa (b’001010)| CA certification. | 进行企业级加密时使用的 CA 证书。 | 数据长度与 Length 域有关， | - | | | | 长度不够，可用分片。 | - +---------------+----------------------------------------+------------------------------------------------+------------------------------------------------------+ - | 0xb (b’001011)| Client certification. | 进行企业级加密时，Client 端的证书。 | 数据长度与 Length 域有关， | - + + +------------------------------------------------+ 长度不够，可用分片。 + - | | | 可包含或不包含私钥，由证书内容决定。 | | - +---------------+----------------------------------------+------------------------------------------------+------------------------------------------------------+ - | 0xc (b’001100)| Server certification. | 进行企业级加密时，Server 端的证书。 | 数据长度与 Length 域有关， | - + + +------------------------------------------------+ 长度不够，可用分片。 + - | | | 可包含或不包含私钥，由证书内容决定。 | | - +---------------+----------------------------------------+------------------------------------------------+------------------------------------------------------+ - | 0xd (b’001101)| Client private key. | 进行企业级加密时，Client 端的私钥。 | 数据长度与 Length 域有关， | - | | | | 长度不够，可用分片。 | - +---------------+----------------------------------------+------------------------------------------------+------------------------------------------------------+ - | 0xe (b’001110)| Server private key. | 进行企业级加密时，Server 端的私钥。 | 数据长度与 Length 域有关， | - | | | | 长度不够，可用分片。 | - +---------------+----------------------------------------+------------------------------------------------+------------------------------------------------------+ - | 0xf (b’001111)| Wi-Fi connection state report. | 通知手机 ESP32 的 Wi-Fi 状态， | data[0] 表示 opmode，包括： | - | | | 包括 STA状态和 SoftAP 状态， | | - | | | 用于手机配置 STA 连接时的通知， | | - | | | 或有 STA 连接上 SoftAP 时的通知。 | | - + + +------------------------------------------------+------------------------------------------------------+ - | | | 但收到手机询问 Wi-Fi 状态时， | 0x00: NULL； | - + + + 除了回复此帧外，还可回复其他数据帧。 +------------------------------------------------------+ - | | | | 0x01: STA; | - + + + +------------------------------------------------------+ - | | | | 0x02: SoftAP; | - + + + +------------------------------------------------------+ - | | | | 0x03: SoftAP&STA | - + + + +------------------------------------------------------+ - | | | | data[1]：STA 的连接状态， | - | | | | 0x0 表示处于连接状态， | - | | | | 其他表示处于非连接状态； | - + + + +------------------------------------------------------+ - | | | | data[2]：SoftAP 的连接状态， | - | | | | 即表示有多少 STA 已经连接。 | - + + + +------------------------------------------------------+ - | | | | data[3] 及以后：为按照本协议格式 SSID\BSSID 等信息。 | - +---------------+----------------------------------------+------------------------------------------------+------------------------------------------------------+ - | 0x10 b’010000 | Version. | | data[0]= great version | - + + + +------------------------------------------------------+ - | | | | data[1]=sub version | - +---------------+----------------------------------------+------------------------------------------------+------------------------------------------------------+ - |0x11 (b’010001)| Wi-Fi list. | 通知手机 ESP32 周围的 Wi-Fi 热点列表。 | 数据帧数据格式为 Length + RSSI + SSID, | - | | | | 数据较长时可分片发送。 | - +---------------+----------------------------------------+------------------------------------------------+------------------------------------------------------+ - |0x12 (b’010010)| Report error. | 通知手机 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. | 用户发送或者接收自定义数据。 | 数据较长时可分片发送。 | - +---------------+----------------------------------------+------------------------------------------------+------------------------------------------------------+ + * b’0000：无校验、无加密； + * b’0001：有校验、无加密； + * b’0010：无校验、有加密； + * b’0011：有校验、有加密。 + + * - 0x2 (b’000010) + - 设置 Wi-Fi 的 opmode。 + - 该帧包含设置 ESP 设备 Wi-Fi 模式 (opmode) 的设置信息。 + - data[0] 用于设置 opmode，包括： + + * 0x00: NULL + * 0x01: STA + * 0x02: SoftAP + * 0x03: SoftAP & STA + + 如果设置中包含 AP，请尽量优先设置 AP 模式的 SSID/密码/最大连接数等。 + + * - 0x3 (b’000011) + - 将 ESP 设备连接至 AP。 + - 通知 ESP 设备必要的信息已经发送完毕，可以连接至 AP。 + - 不包含数据字段。 + + * - 0x4 (b’000100) + - 断开 ESP 设备与 AP 的连接。 + - + - 不包含数据字段。 + + * - 0x5 (b’000101) + - 获取 ESP 设备的 Wi-Fi 模式和状态等信息。 + - + - * 不包含数据字段。ESP 设备收到此控制帧后，会向手机回发一个报告 Wi-Fi 连接状态的帧来告知手机端当前所处的 opmode、连接状态、SSID 等信息。 + * 提供给手机端的信息类型由手机上的应用程序决定。 + + * - 0x6 (b’000110) + - 断开 STA 设备与 SoftAP 的连接（SoftAP 模式）。 + - + - data[0~5] 为 STA 设备的 MAC 地址，如有多个 STA 设备，则第二个使用 data[6-11]，依次类推。 + + * - 0x7 (b’000111) + - 获取版本信息。 + - + - + + * - 0x8 (b’001000) + - 断开 BLE GATT 连接。 + - + - ESP 设备收到该指令后主动断开 BLE GATT 连接。 + + * - 0x9 (b’001001) + - 获取 Wi-Fi 列表。 + - 通知 ESP 设备扫描周围的 Wi-Fi 热点。 + - 不包含数据字段。 ESP 设备收到此控制帧后，会向手机回发一个包含 Wi-Fi 热点报告的帧。 + + + +1.2 数据帧 (二进制：0x1 b’01) + +.. list-table:: + :header-rows: 1 + :widths: 5 15 20 30 + + * - 数据帧 + - 含义 + - 解释 + - 备注 + * - 0x0 (b’000000) + - 发送协商数据。 + - 协商数据会发送到应用层注册的回调函数中。 + - 数据的长度取决于数据长度字段。 + * - 0x1 (b’000001) + - 发送 STA 模式的 BSSID。 + - 在 SSID 隐藏的情况下，发送 STA 设备要连接的 AP 的 BSSID。 + - 请参考备注 1。 + * - 0x2 (b’000010) + - 发送 STA 模式的 SSID + - 发送 STA 设备要连接的 AP 的 SSID。 + - 请参考备注 1。 + * - 0x3 (b’000011) + - 发送 STA 模式的密码。 + - 发送 STA 设备要连接的 AP 的密码。 + - 请参考备注 1。 + * - 0x4 (b’000100) + - 发送 SoftAP 模式的 SSID。 + - + - 请参考备注 1。 + * - 0x5 (b’000101) + - 发送 SoftAPmode 模式的密码。 + - + - 请参考备注 1。 + * - 0x6 (b’000110) + - 设置 SoftAPmode 模式的最大连接数。 + - + - data[0] 为连接数的值，范围从 1 到 4。当传输方向是 ESP 设备到手机时，表示向手机端提供所需信息。 + * - 0x7 (b’000111) + - 设置 SoftAP 的认证模式。 + - + - data[0] 包括： + + * 0x00: OPEN + * 0x01: WEP + * 0x02: WPA_PSK + * 0x03: WPA2_PSK + * 0x04: WPA_WPA2_PSK + + 当传输方向是 ESP 设备到手机时，表示向手机端提供所需信息。 + * - 0x8 (b’001000) + - 设置 SoftAP 模式的通道数量。 + - + - data[0] 代表支持的通道的数量，范围从 1 到 14。当传输方向是 ESP 设备到手机时，表示向手机端提供所需信息。 + * - 0x9 (b’001001) + - 用户名 + - 在进行企业级加密时提供 GATT 客户端的用户名。 + - 数据的长度取决于数据长度字段。 + * - 0xa (b’001010) + - CA 认证 + - 在进行企业级加密时提供 CA 认证。 + - 请参考备注 2。 + * - 0xb (b’001011) + - 客户端认证 + - 在进行企业级加密时提供客户端认证。是否包含私钥，取决于认证的内容。 + - 请参考备注 2。 + * - 0xc (b’001100) + - 服务端认证 + - 在进行企业级加密时提供服务端认证。是否包含私钥，取决于认证的内容。 + - 请参考备注 2。 + * - 0xd (b’001101) + - 客户端私钥 + - 在进行企业级加密时提供客户端私钥。 + - 请参考备注 2。 + * - 0xe (b’001110) + - 服务端私钥 + - 在进行企业级加密时提供服务端私钥。 + - 请参考备注 2。 + * - 0xf (b’001111) + - Wi-Fi 连接状态报告 + - 通知手机 ESP 设备的 Wi-Fi 状态，包括 STA 状态和 SoftAP 状态。用于 STA 设备连接手机或 SoftAP。但是，当手机接收到 Wi-Fi 状态时，除了本帧之外，还可以回复其他帧。 + - data[0] 表示 opmode，包括： + + * 0x00: NULL + * 0x01: STA + * 0x02: SoftAP + * 0x03: SoftAP & STA + + data[1]：STA 设备的连接状态，0x0 表示处于连接状态，其他表示处于非连接状态； + + data[2]：SoftAP 的连接状态，即表示有多少 STA 设备已经连接。 + + data[3]及后面的数据是按照 SSID/BSSID 格式提供的信息。 + * - 0x10 (b’010000) + - 版本 + - + - * data[0]= 主版本 + * data[1]= 子版本 + * - 0x11 (b’010001) + - Wi-Fi 热点列表 + - 将 Wi-Fi 热点列表发送给 ESP 设备 + - 数据帧的格式为 length + RSSI + SSID，数据较长时可分片发送。 + * - 0x12 (b’010010) + - 报告异常 + - 通知手机 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) + - 自定义数据 + - 用户发送或者接收自定义数据。 + - 数据较长时可分片发送。 + +.. note:: + + - 备注 1: 数据的长度取决于数据长度字段。当传输方向是 ESP 设备到手机时，表示向手机端提供所需信息。 + + - 备注 2: 数据的长度取决于数据长度字段。如果数据长度不够，该帧可用分片。 2. Frame Control - 帧控制域，占 1 byte，每个 bit 表示不同含义。 - - +----------------+-------------------------------------------------------------------------------------------------------------------------------+ - | 位 | 含义 | - +================+===============================================================================================================================+ - | 0x01 | 表示帧是否加密。 | - + +-------------------------------------------------------------------------------------------------------------------------------+ - | | 1 表示加密，0 表示未加密。 | - + +-------------------------------------------------------------------------------------------------------------------------------+ - | | 加密部分帧括完整的 DATA 域加密之前的明文（不帧含末尾的校验）。 | - + +-------------------------------------------------------------------------------------------------------------------------------+ - | | 控制帧暂不加密，故控制帧此位为 0。 | - +----------------+-------------------------------------------------------------------------------------------------------------------------------+ - | 0x02 | 表示帧 Data 域结尾是否帧含校验（例如 SHA1,MD5,CRC等）需要校验的数据域包括 sequcne + data length + 明文 data。 | - + +-------------------------------------------------------------------------------------------------------------------------------+ - | | 控制帧和数据帧都可以包含校验位或不包含。 | - +----------------+-------------------------------------------------------------------------------------------------------------------------------+ - | 0x04 | 表示数据方向。 | - + +-------------------------------------------------------------------------------------------------------------------------------+ - | | 0 表示手机发向 ESP32； | - + +-------------------------------------------------------------------------------------------------------------------------------+ - | | 1 表示 ESP32 发向手机。 | - +----------------+-------------------------------------------------------------------------------------------------------------------------------+ - | 0x08 | 表示是否要求对方回复 ack。 | - + +-------------------------------------------------------------------------------------------------------------------------------+ - | | 0 表示不要求； | - + +-------------------------------------------------------------------------------------------------------------------------------+ - | | 1 表示要求回复 ack。 | - +----------------+-------------------------------------------------------------------------------------------------------------------------------+ - | 0x10 | 表示是否有后续的数据分片。 | - + +-------------------------------------------------------------------------------------------------------------------------------+ - | | 0 表示此帧没有后续数据分片； | - + +-------------------------------------------------------------------------------------------------------------------------------+ - | | 1 表示还有后续数据分片，用来传输较长的数据。 | - + +-------------------------------------------------------------------------------------------------------------------------------+ - | | 如果是 Frag 帧，则告知当前 content 部分+后续 content 部分的总长度，位于 Data 域的前 2 字节(即最大支持 64K 的 content 数据）。 | - +----------------+-------------------------------------------------------------------------------------------------------------------------------+ - | 0x10~0x80 保留 | | - +----------------+-------------------------------------------------------------------------------------------------------------------------------+ + 帧控制字段，占 1 字节，每个位表示不同含义。 -3. Sequence Control +.. list-table:: + :header-rows: 1 + :widths: 10 35 - 序列控制域。帧发送时，无论帧的类型是什么，序列 (Sequence) 都会自动加 1，用来防止重放攻击 (Replay Attack)。每次重现连接后，序列清零。 + * - 位 + - 含义 + * - 0x01 + - 表示帧是否加密。 -4. Length + * 1 表示加密 + * 0 表示未加密 - Data 域的长度，不包含 CheckSum。 + 该帧的加密部分包括数据字段加密之前的完整明文数据（不包括校验部分）。控制帧暂不加密，故控制帧此位为 0。 + * - 0x02 + - 该数据字段表示帧尾是否包含校验位，如 SHA1、MD5、CRC 等。该数据字段包含序列 + 数据长度 + 明文。控制帧和数据帧都可以选择包含或不包含校验位。 + * - 0x04 + - 表示数据方向。 -5. Data + * 0 表示传输方向是手机到 ESP 设备 + * 1 表示传输方向是 ESP 设备到手机 + * - 0x08 + - 表示是否要求对方回复 ACK。 - 不同的 Type 或 Subtype，Data 域的含义均不同。请参考上方表格。 + * 0 表示不要求； + * 1 表示要求回复 ACK。 + * - 0x10 + - 表示是否有后续的数据分片。 -6. CheckSum + * 0 表示此帧没有后续数据分片； + * 1 表示还有后续数据分片，用来传输较长的数据。 + + 对于分片帧，在数据字段的前两个字节中会给定当前内容部分 + 随后内容部分的总长度（即最大支持 64 K 的数据内容）。 + * - 0x10~0x80 + - 保留 - 此域为 2 byte 的校验，用来校验『序列 + 数据长度 + 明文数据』。 +3. 序列控制 -ESP32 端的安全实现 ------------------- + 序列控制字段。帧发送时，无论帧的类型是什么，序列都会自动加 1，用来防止重放攻击 (Replay Attack)。每次重新连接后，序列清零。 -1. 保证数据安全 +4. 长度 - 为了保证 Wi-Fi SSID 和密码的传输过程是安全的，需要使用对称加密算法（例如 AES、DES等）对报文进行加密。在使用对称加密算法之前，需要使用非对称加密算法（DH、RSA、ECC 等）协商出（或生成出）一个共享密钥。 + 数据字段的长度，不包含校验部分。 + +5. 数据 + + 对于不同的类型或子类型，数据字段的含义均不同。请参考上方表格。 + +6. 校验 + + 此字段占两个字节，用来校验“序列 + 数据长度 + 明文数据”。 + +{IDF_TARGET_NAME} 端的安全实现 +---------------------------------- + +1. 数据安全 + + 为了保证 Wi-Fi SSID 和密码的传输过程是安全的，需要使用对称加密算法（例如 AES、DES 等）对报文进行加密。在使用对称加密算法之前，需要使用非对称加密算法（DH、RSA、ECC 等）协商出（或生成出）一个共享密钥。 2. 保证数据完整性 - 保证数据完整性，需要加入校验算法（例如 SHA1、MD5、CRC 等）。 + 为了保证数据完整性，需要加入校验算法，例如 SHA1、MD5、CRC 等。 3. 身份安全（签名） @@ -406,37 +431,39 @@ ESP32 端的安全实现 4. 防止重放攻击 (Replay Attack) - 加入帧发送序列（Sequence），并且序列参与数据校验。 + 添加其到序列字段中，并且在数据校验过程中使用。 - 在 ESP32 端的代码中，你可以决定和开发密钥协商等安全处理的流程参考上述流程图）。手机应用向 ESP32 发送协商数据，将传送给应用层处理。如果应用层不处理，可使用 BluFi 提供的 DH 加密算法来磋商密钥。应用层需向 BluFi 注册以下几个与安全相关的函数： + 在 {IDF_TARGET_NAME} 端的代码中，你可以决定和开发如密钥协商等安全处理的流程。手机应用向 {IDF_TARGET_NAME} 发送协商数据，数据会传送给应用层处理。如果应用层不处理，可使用 BluFi 提供的 DH 加密算法来协商密钥。 + + 应用层需向 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); + typedef void (*esp_blufi_negotiate_data_handler_t)(uint8_t *data, int len, uint8_t **output_data, int *output_len, bool *need_free) -该函数用来接收协商期间的正常数据 (normal data)，处理完成后，需要将待发送的数据使用 output_data 和 output_len 传出。 +该函数用来接收协商期间的正常数据 (normal data)，数据处理完成后，需要将待发送的数据使用 output_data 和 output_len 传出。 -BluFi 会在调用完 negotiate_data_handler 后，发送 negotiate_data_handler 传出的 output_data。 +BluFi 会在调用完 Negotiate_data_handler 后，发送 Negotiate_data_handler 传出的 output_data。 -这里的两个『*』，因为需要发出去的数据长度未知，所以需要函数自行分配 (malloc) 或者指向全局变量，通过 need_free 通知是否需要释放内存。 +这里的两个 “*”，因为需要发出去的数据长度未知，所以需要函数自行分配 (malloc) 或者指向全局变量，并告知是否需要通过 NEED_FREE 释放内存。 .. code-block:: c - typedef int (* esp_blufi_encrypt_func_t)(uint8_t iv8, uint8_t *crypt_data, int crypt_len); + typedef int (* esp_blufi_encrypt_func_t)(uint8_t iv8, uint8_t *crypt_data, int crypt_len) -加密和解密的数据长度必须一致。其中 iv8 为帧的 8 bit 序列 (sequence)，可作为 iv 的某 8 bit 来使用。 +加密和解密的数据长度必须一致。其中 IV8 为帧的 8 位序列，可作为 IV 的某 8 个位来使用。 .. code-block:: c - typedef int (* esp_blufi_decrypt_func_t)(uint8_t iv8, uint8_t *crypt_data, int crypt_len); + typedef int (* esp_blufi_decrypt_func_t)(uint8_t iv8, uint8_t *crypt_data, int crypt_len) -加密和解密的数据长度必须一致。其中 iv8 为帧的 8 bit 序列 (sequence)，可作为 iv 的某 8 bit 来使用。 +加密和解密的数据长度必须一致。其中 IV8 为帧的 8 位序列，可作为 IV 的某 8 个位来使用。 .. code-block:: c - typedef uint16_t (*esp_blufi_checksum_func_t)(uint8_t iv8, uint8_t *data, int len); + typedef uint16_t (*esp_blufi_checksum_func_t)(uint8_t iv8, uint8_t *data, int len) -该函数用来计算 CheckSum，返回值为 CheckSum 的值。BluFi 会使用该函数返回值与包末尾的 CheckSum 做比较。 +该函数用来进行校验，返回值为校验的值。BluFi 会使用该函数返回值与帧的校验值进行比较。 GATT 相关说明 ------------- @@ -446,6 +473,6 @@ UUID BluFi Service UUID： 0xFFFF，16 bit -BluFi （手机 -> ESP32） 特性：0xFF01，主要权限：可写 +BluFi （手机 -> {IDF_TARGET_NAME}）特性：0xFF01，主要权限：可写 -BluFi （ESP32 -> 手机） 特性：0xFF02，主要权限：可读可通知 \ No newline at end of file +BluFi （{IDF_TARGET_NAME} -> 手机）特性：0xFF02，主要权限：可读可通知 diff --git a/docs/zh_CN/api-guides/build-system.rst b/docs/zh_CN/api-guides/build-system.rst index a9c9d4c646..3265ed67c2 100644 --- a/docs/zh_CN/api-guides/build-system.rst +++ b/docs/zh_CN/api-guides/build-system.rst @@ -99,9 +99,10 @@ idf.py - ``idf.py app``，``idf.py bootloader``，``idf.py partition_table`` 仅可用于从适用的项目中构建应用程序、引导程序或分区表。 - ``idf.py app-flash`` 等匹配命令，仅将项目的特定部分烧录至 {IDF_TARGET_NAME}。 - ``idf.py -p PORT erase_flash`` 会使用 esptool.py 擦除 {IDF_TARGET_NAME} 的整个 Flash。 -- ``idf.py size`` 会打印应用程序相关的大小信息，``idf.py size-components`` 和 ``idf.py size-files`` 这两个命令相似，分别用于打印每个组件或源文件的详细信息。如果您在运行 CMake（或 ``idf.py``）时定义了变量 ``-DOUTPUT_JSON=1``，那么输出的格式会变成 JSON 而不是可读文本。 +- ``idf.py size`` 会打印应用程序相关的大小信息，``size-components`` 和 ``size-files`` 这两个命令相似，分别用于打印每个组件或源文件的详细信息。如果您在运行 CMake（或 ``idf.py``）时定义了变量 ``-DOUTPUT_JSON=1``，那么输出的格式会变成 JSON 而不是可读文本。详情请查看 ``idf.py-size``。 - ``idf.py reconfigure`` 命令会重新运行 CMake_ （即便无需重新运行）。正常使用时，并不需要运行此命令，但当源码树中添加/删除文件后或更改 CMake cache 变量时，此命令会非常有用，例如，``idf.py -DNAME='VALUE' reconfigure`` 会将 CMake cache 中的变量 ``NAME`` 的值设置为 ``VALUE``。 - ``idf.py python-clean`` 会从 IDF 目录中删除生成的 Python 字节码，Python 字节码可能会在切换 IDF 和 Python 版本时引发问题，因此建议在切换 Python 后运行该命令。 +- ``idf.py docs`` 将在浏览器中直接打开项目目标芯片和对应版本的文档链接。请使用 ``idf.py docs --help`` 查看所有选项。 同时调用多个 ``idf.py`` 命令时，命令的输入顺序并不重要，它们会按照正确的顺序依次执行，并保证每一条命令都生效（即先构建后烧录，先擦除后烧录等）。 @@ -449,7 +450,7 @@ ESP-IDF 在搜索所有待构建的组件时，会按照 ``COMPONENT_DIRS`` 指 .. highlight:: cmake -在编译特定组件的源文件时，可以使用 ``target_compile_options`` 命令来传递编译器选项:: +在编译特定组件的源文件时，可以使用 `target_compile_options`_ 函数来传递编译器选项:: target_compile_options(${COMPONENT_LIB} PRIVATE -Wno-unused-variable) @@ -650,12 +651,54 @@ Spark Plug 组件 - 将 ``COMPONENTS`` 设置为所需组件的最小列表，可以显著减少项目的构建时间。 +.. _component-circular-dependencies: + +循环依赖 +--------------------- + +一个项目中可能包含组件 A 和组件 B，而组件 A 依赖（``REQUIRES`` 或 ``PRIV_REQUIRES``）组件 B，组件 B 又依赖组件 A。这就是所谓的依赖循环或循环依赖。 + +CMake 通常会在链接器命令行上重复两次组件库名称来自动处理循环依赖。然而这种方法并不总是有效，还是可能构建失败并出现关于 “Undefined reference to ...” 的链接器错误，这通常是由于引用了循环依赖中某一组件中定义的符号。如果存在较大的循环依赖关系，即 A->B->C->D->A，这种情况极有可能发生。 + +最好的解决办法是重构组件以消除循环依赖关系。在大多数情况下，没有循环依赖的软件架构具有模块化和分层清晰的特性，并且从长远来看更容易维护。然而，移除循环依赖关系并不容易做到。 + +要绕过由循环依赖引起的链接器错误，最简单的解决方法是增加其中一个组件库的 CMake `LINK_INTERFACE_MULTIPLICITY`_ 属性。 这会让 CMake 在链接器命令行上对此库及其依赖项重复两次以上。 + +例如： + +.. code-block:: cmake + + set_property(TARGET ${COMPONENT_LIB} APPEND PROPERTY LINK_INTERFACE_MULTIPLICITY 3) + +- 这一行应该放在组件 CMakeLists.txt 文件 ``idf_component_register`` 之后。 +- 可以的话，将此行放置在因依赖其他组件而造成循环依赖的组件中。实际上，该行可以放在循环内的任何一个组件中，但建议将其放置在拥有链接器错误提示信息中显示的源文件的组件中，或是放置在定义了链接器错误提示信息中所提到的符号的组件，先从这些组件开始是个不错的选择。 +- 通常将值增加到 3（默认值是 2）就足够了，但如果不起作用，可以尝试逐步增加这个数字。 +- 注意，增加这个选项会使链接器的命令行变长，链接阶段变慢。 + +高级解决方法：未定义符号 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +如果只有一两个符号导致循环依赖，而所有其他依赖都是线性的，那么有一种替代方法可以避免链接器错误：在链接时将“反向”依赖所需的特定符号指定为未定义符号。 + +例如，如果组件 A 依赖于组件 B，但组件 B 也需要引用组件 A 的 ``reverse_ops`` （但不依赖组件 A 中的其他内容），那么你可以在组件 B 的 CMakeLists.txt 中添加如下一行，以在链接时避免这出现循环。 + +.. code-block:: cmake + + # 该符号是由“组件 A”在链接时提供 + target_link_libraries(${COMPONENT_LIB} INTERFACE "-u reverse_ops") + +- ``-u`` 参数意味着链接器将始终在链接中包含此符号，而不管依赖项顺序如何。 +- 该行应该放在组件 CMakeLists.txt 文件中的 ``idf_component_register`` 之后。 +- 如果“组件 B”不需要访问“组件 A”的任何头文件，只需链接几个符号，那么这一行可以用来代替 B 对 A 的任何 “REQUIRES”。这样则进一步简化了构建系统中的组件结构。 + +请参考 `target_link_libraries`_ 文档以了解更多关于此 CMake 函数的信息。 + .. _component-requirements-implementation: 构建系统中依赖处理的实现细节 ---------------------------- -- 在 CMake 配置进程的早期阶段会运行 ``expand_requirements.cmake`` 脚本。该脚本会对所有组件的 CMakeLists.txt 文件进行局部的运算，得到一张组件依赖关系图（此图可能会有闭环）。此图用于在构建目录中生成 ``component_depends.cmake`` 文件。 +- 在 CMake 配置进程的早期阶段会运行 ``expand_requirements.cmake`` 脚本。该脚本会对所有组件的 CMakeLists.txt 文件进行局部的运算，得到一张组件依赖关系图（:ref:`此图可能会有闭环 `）。此图用于在构建目录中生成 ``component_depends.cmake`` 文件。 - CMake 主进程会导入该文件，并以此来确定要包含到构建系统中的组件列表（内部使用的 ``BUILD_COMPONENTS`` 变量）。``BUILD_COMPONENTS`` 变量已排好序，依赖组件会排在前面。由于组件依赖关系图中可能存在闭环，因此不能保证每个组件都满足该排序规则。如果给定相同的组件集和依赖关系，那么最终的排序结果应该是确定的。 - CMake 会将 ``BUILD_COMPONENTS`` 的值以 “Component names:” 的形式打印出来。 - 然后执行构建系统中包含的每个组件的配置。 @@ -976,6 +1019,8 @@ ExternalProject 的依赖与构建清理 如若需要覆盖此文件的名称或指定多个文件，请设置 ``SDKCONFIG_DEFAULTS`` 环境变量或在顶层 CMakeLists.txt 文件中设置 ``SDKCONFIG_DEFAULTS``。在指定多个文件时，使用分号作为分隔符。未指定完整路径的文件名将以当前项目的相对路径来解析。 +一些 IDF 示例中包含了 ``sdkconfig.ci`` 文件。该文件是 CI（持续集成）测试框架的一部分，在正常构建过程中会被忽略。 + 依赖于硬件目标的 sdkconfig 默认值 --------------------------------- @@ -1583,6 +1628,7 @@ CMake 中不可用的功能 .. _target_compile_options: https://cmake.org/cmake/help/v3.5/command/target_compile_options.html .. _target_link_libraries: https://cmake.org/cmake/help/v3.5/command/target_link_libraries.html#command:target_link_libraries .. _cmake_toolchain_file: https://cmake.org/cmake/help/v3.5/variable/CMAKE_TOOLCHAIN_FILE.html +.. _LINK_INTERFACE_MULTIPLICITY: https://cmake.org/cmake/help/v3.5/prop_tgt/LINK_INTERFACE_MULTIPLICITY.html .. _quirc: https://github.com/dlbeer/quirc .. _pyenv: https://github.com/pyenv/pyenv#readme .. _virtualenv: https://virtualenv.pypa.io/en/stable/ diff --git a/docs/zh_CN/security/flash-encryption.rst b/docs/zh_CN/security/flash-encryption.rst index d9d777a0ca..e47bc0a9cf 100644 --- a/docs/zh_CN/security/flash-encryption.rst +++ b/docs/zh_CN/security/flash-encryption.rst @@ -450,7 +450,7 @@ Flash 加密设置 .. list:: - - 不要在多个设备之间重复使用同一个 flash 加密密钥。这样做意味着攻击者从一台设备上复制加密数据后，无法将其转移到第二台设备上。 + - 不要在多个设备之间重复使用同一个 flash 加密密钥，这样攻击者就无法从一台设备上复制加密数据后再将其转移到第二台设备上。 :esp32: - 在使用 ESP32 V3 时，如果生产设备不需要 UART ROM 下载模式，那么则该禁用该模式以增加设备安全性。这可以通过在应用程序启动时调用 :cpp:func:`esp_efuse_disable_rom_download_mode` 来实现。或者，可将项目 :ref:`CONFIG_ESP32_REV_MIN` 级别配置为 3（仅针对 ESP32 V3），然后选择 :ref:`CONFIG_SECURE_UART_ROM_DL_MODE` 为“永久性的禁用 ROM 下载模式（推荐）”。在早期的 ESP32 版本上无法禁用 ROM 下载模式。 :not esp32: - 如果不需要 UART ROM 下载模式，则应完全禁用该模式，或者永久设置为“安全下载模式”。安全下载模式永久性地将可用的命令限制在基本的 flash 只读和只写。默认在发布模式下第一次启动时设置为安全下载模式。要完全禁用下载模式，请选择 :ref:`CONFIG_SECURE_UART_ROM_DL_MODE` 为“永久禁用 ROM 下载模式（推荐）”或在运行时调用 :cpp:func:`esp_efuse_disable_rom_download_mode`。 - 启用 :doc:`安全启动` 作为额外的保护层，防止攻击者在启动前有选择地破坏 flash 中某部分。