diff --git a/docs/conf_common.py b/docs/conf_common.py index 526e85b7f8..127aae61a3 100644 --- a/docs/conf_common.py +++ b/docs/conf_common.py @@ -15,20 +15,24 @@ from esp_docs.conf_docs import * # noqa: F403,F401 if os.environ.get('IDF_PATH') is None: raise RuntimeError('IDF_PATH should be set, run export.sh before building docs') -BT_DOCS = ['api-reference/bluetooth/bt_le.rst', - 'api-reference/bluetooth/esp_bt_defs.rst', +BT_DOCS = ['api-reference/bluetooth/esp_bt_defs.rst', 'api-reference/bluetooth/esp_bt_device.rst', 'api-reference/bluetooth/esp_bt_main.rst', 'api-reference/bluetooth/bt_common.rst', 'api-reference/bluetooth/controller_vhci.rst', - 'api-reference/bluetooth/esp_gap_ble.rst', - 'api-reference/bluetooth/esp_gatt_defs.rst', - 'api-reference/bluetooth/esp_gatts.rst', - 'api-reference/bluetooth/esp_gattc.rst', - 'api-reference/bluetooth/index.rst', - 'api-reference/bluetooth/nimble/index.rst'] + 'api-reference/bluetooth/index.rst'] -BLE_DOCS = ['migration-guides/release-5.x/5.0/bluetooth-low-energy.rst'] +BLE_DOCS = ['api-guides/ble/index.rst', + 'api-guides/ble/overview.rst', + 'api-guides/ble/ble-feature-support-status.rst', + 'api-guides/ble/host-feature-support-status.rst', + 'api-reference/bluetooth/bt_le.rst', + 'api-reference/bluetooth/esp_gap_ble.rst', + 'api-reference/bluetooth/esp_gatt_defs.rst', + 'api-reference/bluetooth/esp_gatts.rst', + 'api-reference/bluetooth/esp_gattc.rst', + 'api-reference/bluetooth/nimble/index.rst', + 'migration-guides/release-5.x/5.0/bluetooth-low-energy.rst'] BLE_MESH_DOCS = ['api-guides/esp-ble-mesh/ble-mesh-index.rst', 'api-guides/esp-ble-mesh/ble-mesh-feature-list.rst', @@ -37,7 +41,9 @@ BLE_MESH_DOCS = ['api-guides/esp-ble-mesh/ble-mesh-index.rst', 'api-guides/esp-ble-mesh/ble-mesh-faq.rst', 'api-reference/bluetooth/esp-ble-mesh.rst'] -CLASSIC_BT_DOCS = ['api-reference/bluetooth/classic_bt.rst', +CLASSIC_BT_DOCS = ['api-guides/classic-bt/index.rst', + 'api-guides/classic-bt/overview.rst', + 'api-reference/bluetooth/classic_bt.rst', 'api-reference/bluetooth/esp_a2dp.rst', 'api-reference/bluetooth/esp_avrc.rst', 'api-reference/bluetooth/esp_hidd.rst', @@ -51,7 +57,7 @@ CLASSIC_BT_DOCS = ['api-reference/bluetooth/classic_bt.rst', 'api-reference/bluetooth/esp_gap_bt.rst', 'migration-guides/release-5.x/5.0/bluetooth-classic.rst'] -BLUFI_DOCS = ['api-guides/blufi.rst', +BLUFI_DOCS = ['api-guides/ble/blufi.rst', 'api-reference/bluetooth/esp_blufi.rst'] WIFI_DOCS = ['api-guides/wifi.rst', diff --git a/docs/en/api-guides/ble/ble-feature-support-status.rst b/docs/en/api-guides/ble/ble-feature-support-status.rst new file mode 100644 index 0000000000..a585eae780 --- /dev/null +++ b/docs/en/api-guides/ble/ble-feature-support-status.rst @@ -0,0 +1,338 @@ +Major Feature Support Status +================================ + +:link_to_translation:`zh_CN:[中文]` + +The table below shows the support status of Bluetooth Low Energy major features on {IDF_TARGET_NAME}. + +|supported_def| **This feature has completed development and internal testing.** [1]_ + +|experimental_def| **This feature has been developed and is currently undergoing internal testing.** +You can explore these features for evaluation and feedback purposes but should be cautious of potential issues. + +|developing_def| **The feature is currently being actively developed, and expected to be supported by the end of YYYY/MM.** +You should anticipate future updates regarding the progress and availability of these features. +If you do have an urgent need, please contact our `customer support team `__ for a possible feature trial. + +|unsupported_def| **This feature is not supported on this chip series.** If you have related requirements, please prioritize selecting other Espressif chip series that support this feature. +If none of our chip series meet your needs, please contact `customer support team `__, and our R&D team will conduct an internal feasibility assessment for you. + +|NA_def| The feature with this label could be the following two types: + - **Host-only Feature**: The feature exists only above HCI, such as GATT Caching. It does not require the support from the Controller. + - **Controller-only Feature**: The feature exists only below HCI, and cannot be configured/enabled via Host API, such as Advertising Channel Index. It does not require the support from the Host. + +.. list-table:: + :width: 100% + :widths: auto + :header-rows: 1 + + * - .. centered:: Core Spec + - .. centered:: Major Features + - .. centered:: ESP Controller + - .. centered:: ESP-Bluedroid Host + - .. centered:: ESP-NimBLE Host + * - .. centered:: |4.2| + - LE Data Packet Length Extension + - |supported| + - |supported| + - |supported| + * - + - LE Secure Connections + - |supported| + - |supported| + - |supported| + * - + - Link Layer Privacy + - |supported| + - |supported| + - |supported| + * - + - Link Layer Extended Filter Policies + - |supported| + - |supported| + - |supported| + * - .. centered:: |5.0| + - 2 Msym/s PHY for LE + - .. only:: esp32 + + |unsupported| + .. only:: not esp32 + + |supported| + - .. only:: esp32 + + |unsupported| + .. only:: not esp32 + + |supported| + - .. only:: esp32 + + |unsupported| + .. only:: not esp32 + + |supported| + * - + - LE Long Range (Coded PHY S=2/S=8) + - .. only:: esp32 + + |unsupported| + .. only:: not esp32 + + |supported| + - .. only:: esp32 + + |unsupported| + .. only:: not esp32 + + |supported| + - .. only:: esp32 + + |unsupported| + .. only:: not esp32 + + |supported| + * - + - High Duty Cycle Non-Connectable Advertising + - .. only:: esp32 + + |unsupported| + .. only:: not esp32 + + |supported| + - .. only:: esp32 + + |unsupported| + .. only:: not esp32 + + |supported| + - .. only:: esp32 + + |unsupported| + .. only:: not esp32 + + |supported| + * - + - LE Advertising Extensions + - .. only:: esp32 + + |unsupported| + .. only:: not esp32 + + |supported| + - .. only:: esp32 + + |unsupported| + .. only:: not esp32 + + |supported| + - .. only:: esp32 + + |unsupported| + .. only:: not esp32 + + |supported| + * - + - LE Channel Selection Algorithm #2 + - .. only:: esp32 + + |unsupported| + .. only:: not esp32 + + |supported| + - .. only:: esp32 + + |unsupported| + .. only:: not esp32 + + |supported| + - .. only:: esp32 + + |unsupported| + .. only:: not esp32 + + |supported| + * - .. centered:: |5.1| + - Angle of Arrival (AoA)/Angle of Departure (AoD) + - |unsupported| + - |unsupported| + - |unsupported| + * - + - GATT Caching + - |NA| + - |experimental| + - |experimental| + * - + - Advertising Channel Index + - |unsupported| + - |NA| + - |NA| + * - + - Periodic Advertising Sync Transfer + - .. only:: esp32 or esp32c3 or esp32s3 + + |unsupported| + .. only:: esp32c6 or esp32h2 or esp32c2 or esp32c5 + + |experimental| + - .. only:: esp32 or esp32c3 or esp32s3 + + |unsupported| + .. only:: esp32c6 or esp32h2 or esp32c2 or esp32c5 + + |experimental| + - .. only:: esp32 or esp32c3 or esp32s3 + + |unsupported| + .. only:: esp32c6 or esp32h2 or esp32c2 or esp32c5 + + |experimental| + * - .. centered:: |5.2| + - LE Isochronous Channels (BIS/CIS) + - |unsupported| + - |unsupported| + - |unsupported| + * - + - Enhanced Attribute Protocol + - |NA| + - |unsupported| + - |developing202412| + * - + - LE Power Control + - .. only:: esp32 or esp32c2 + + |unsupported| + .. only:: esp32c6 or esp32h2 or esp32c3 or esp32s3 or esp32c5 + + |experimental| + - |unsupported| + - .. only:: esp32 or esp32c2 + + |unsupported| + .. only:: esp32c6 or esp32h2 or esp32c3 or esp32s3 or esp32c5 + + |developing202412| + * - .. centered:: |5.3| + - AdvDataInfo in Periodic Advertising + - .. only:: esp32 or esp32c3 or esp32s3 + + |unsupported| + .. only:: esp32c6 or esp32c2 or esp32h2 or esp32c5 + + |supported| + - .. only:: esp32 or esp32c3 or esp32s3 + + |unsupported| + .. only:: esp32c6 or esp32c2 or esp32h2 or esp32c5 + + |supported| + - .. only:: esp32 or esp32c3 or esp32s3 + + |unsupported| + .. only:: esp32c6 or esp32c2 or esp32h2 or esp32c5 + + |supported| + * - + - LE Enhanced Connection Update (Connection Subrating) + - .. only:: esp32 or esp32c6 or esp32c2 or esp32h2 or esp32c5 + + |unsupported| + .. only:: esp32c3 or esp32s3 + + |experimental| + - |unsupported| + - .. only:: esp32 or esp32c6 or esp32c2 or esp32h2 or esp32c5 + + |unsupported| + .. only:: esp32c3 or esp32s3 + + |experimental| + * - + - LE Channel Classification + - .. only:: esp32 or esp32c3 or esp32s3 or esp32c2 + + |unsupported| + .. only:: esp32c6 or esp32h2 or esp32c5 + + |experimental| + - .. only:: esp32 or esp32c3 or esp32s3 or esp32c2 + + |unsupported| + .. only:: esp32c6 or esp32h2 or esp32c5 + + |experimental| + - .. only:: esp32 or esp32c3 or esp32s3 or esp32c2 + + |unsupported| + .. only:: esp32c6 or esp32h2 or esp32c5 + + |experimental| + * - .. centered:: |5.4| + - Advertising Coding Selection + - .. only:: esp32 or esp32c6 or esp32c2 or esp32h2 or esp32c5 + + |unsupported| + .. only:: esp32c3 or esp32s3 + + |experimental| + - |unsupported| + - .. only:: esp32 or esp32c6 or esp32c2 or esp32h2 or esp32c5 + + |unsupported| + .. only:: esp32c3 or esp32s3 + + |experimental| + * - + - Encrypted Advertising Data + - |NA| + - |unsupported| + - |experimental| + * - + - LE GATT Security Levels Characteristic + - |NA| + - |unsupported| + - |developing202412| + * - + - Periodic Advertising with Responses + - |unsupported| + - |unsupported| + - |unsupported| + +.. [1] + If you would like to know the Bluetooth SIG certification information for supported features, + please consult `SIG Bluetooth Product Database `__. + +For certain features, if the majority of the development is completed on the Controller, the Host's support status will be limited by the Controller's support status. +If you want BLE Controller and Host to run on different Espressif chips, the functionality of the Host will not be limited by the Controller's support status on the chip running the Host, +please check the :doc:`ESP Host Feature Support Status Table ` . + +It is important to clarify that this document is not a binding commitment to our customers. +The above feature support status information is for general informational purposes only and is subject to change without notice. +You are encouraged to consult with our `customer support team `__ for the most up-to-date information and to verify the suitability of features for your specific needs. + + +.. |supported| image:: ../../../_static/ble/feature_status/supported.svg + :class: align-center + :width: 65px +.. |developing202412| image:: ../../../_static/ble/feature_status/developing202412.svg + :class: align-center + :width: 120px +.. |unsupported| image:: ../../../_static/ble/feature_status/unsupported.svg + :class: align-center + :width: 75px +.. |experimental| image:: ../../../_static/ble/feature_status/experimental.svg + :class: align-center + :width: 75px +.. |NA| image:: ../../../_static/ble/feature_status/NA.svg + :class: align-center + :width: 25px +.. |supported_def| image:: ../../../_static/ble/feature_status/supported.svg +.. |developing_def| image:: ../../../_static/ble/feature_status/developingYYYYMM.svg +.. |unsupported_def| image:: ../../../_static/ble/feature_status/unsupported.svg +.. |experimental_def| image:: ../../../_static/ble/feature_status/experimental.svg +.. |NA_def| image:: ../../../_static/ble/feature_status/NA.svg +.. |4.2| replace:: `4.2 `__ +.. |5.0| replace:: `5.0 `__ +.. |5.1| replace:: `5.1 `__ +.. |5.2| replace:: `5.2 `__ +.. |5.3| replace:: `5.3 `__ +.. |5.4| replace:: `5.4 `__ diff --git a/docs/en/api-guides/blufi.rst b/docs/en/api-guides/ble/blufi.rst similarity index 85% rename from docs/en/api-guides/blufi.rst rename to docs/en/api-guides/ble/blufi.rst index 852e0f671a..ce60c53f46 100644 --- a/docs/en/api-guides/blufi.rst +++ b/docs/en/api-guides/ble/blufi.rst @@ -1,9 +1,10 @@ BluFi -^^^^^ -:link_to_translation:`zh_CN:[中文]` +^^^^^^ + +:link_to_translation:`en:[English]` 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 {IDF_TARGET_NAME}. Using this information, {IDF_TARGET_NAME} can then connect to an AP or establish a SoftAP. @@ -12,7 +13,7 @@ Fragmenting, data encryption, and checksum verification in the BluFi layer are t You can customize symmetric encryption, asymmetric encryption, and checksum support customization. Here we use the DH algorithm for key negotiation, 128-AES algorithm for data encryption, and CRC16 algorithm for checksum verification. The BluFi Flow ---------------- +---------------- The BluFi networking flow includes the configuration of the SoftAP and Station. @@ -32,7 +33,7 @@ The following uses Station as an example to illustrate the core parts of the pro 7. When receiving this control frame, {IDF_TARGET_NAME} will be able to encrypt and decrypt the communication data using the shared key and the security configuration. -8. The mobile phone sends the data frame defined in the section of :ref:`frame_formats`，with the Wi-Fi configuration information to {IDF_TARGET_NAME}, including SSID, password, etc. +8. The mobile phone sends the data frame defined in the section of :ref:`frame_formats`,with the Wi-Fi configuration information to {IDF_TARGET_NAME}, including SSID, password, etc. 9. The mobile phone sends a control frame of Wi-Fi connection request to {IDF_TARGET_NAME}. When receiving this control frame, {IDF_TARGET_NAME} will regard the communication of essential information as done and get ready to connect to the Wi-Fi. @@ -45,7 +46,7 @@ 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 --------------------------- +------------------------- .. seqdiag:: :caption: BluFi Flow Chart @@ -74,39 +75,39 @@ The Flow Chart of BluFi .. _frame_formats: The Frame Formats Defined in BluFi ------------------------------------ +------------------------------------ The frame formats for the communication between the mobile phone App and {IDF_TARGET_NAME} are defined as follows: The frame format with no fragment: -.. list-table:: - :header-rows: 1 - :widths: 25 25 - +.. list-table:: + :header-rows: 1 + :widths: 25 25 + * - Field - Value (Byte) * - Type (Least Significant Bit) - 1 * - Frame Control - - 1 + - 1 * - Sequence Number - 1 * - Data Length - 1 * - Data - ${Data Length} - * - CheckSum (Most Siginificant Bit) + * - CheckSum (Most Significant Bit) - 2 If the frag frame bit in the **Frame Control** field is enabled, there would be a 2-byte **Total Content Length** field in the **Data** field. This **Total Content Length** field indicates the length of the remaining part of the frame and also tells the remote how much memory needs to be allocated. The frame format with fragments: -.. list-table:: - :header-rows: 1 - :widths: 25 25 - +.. list-table:: + :header-rows: 1 + :widths: 25 25 + * - Field - Value (Byte) * - Type (Least Significant Bit) @@ -120,17 +121,17 @@ The frame format with fragments: * - Data - * Total Content Length: 2 * Content: ${Data Length} - 2 - * - CheckSum (Most Siginificant Bit) + * - CheckSum (Most Significant Bit) - 2 Normally, the control frame does not contain data bits, except for ACK Frame. The format of ACK Frame: -.. list-table:: - :header-rows: 1 - :widths: 25 25 - +.. list-table:: + :header-rows: 1 + :widths: 25 25 + * - Field - Value (Byte) * - Type - ACK (Least Significant Bit) @@ -143,7 +144,7 @@ The format of ACK Frame: - 1 * - Data - Acked Sequence Number: 2 - * - CheckSum (Most Siginificant Bit) + * - CheckSum (Most Significant Bit) - 2 @@ -155,125 +156,125 @@ The format of ACK Frame: * The data frame supports to be encrypted and verified. -1.1 Control Frame (Binary: 0x0 b’00) +1.1 Control Frame (Binary: 0x0 b'00) + +.. list-table:: + :header-rows: 1 + :widths: 5 15 20 30 -.. list-table:: - :header-rows: 1 - :widths: 5 15 20 30 - * - Control Frame - Implication - Explanation - - Note + - Note * - 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. - + - 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 the ESP device to the security mode. - - To inform the ESP device of the security mode to use when sending data, which is allowed to be reset multiple times during the process. Each setting affects the subsequent security mode used. + - To inform the ESP device of the security mode to use when sending data, which is allowed to be reset multiple times during the process. Each setting affects the subsequent security mode used. If it is not set, the ESP device will send the control frame and data frame with no checksum and encryption by default. The data transmission from the mobile phone to the ESP device is controlled by this control frame. - The data field consumes a byte. The higher four bits are for the security mode setting of the control frame, and the lower four bits are for the security mode setting of the data frame. - * b’0000: no checksum and no encryption; - * b’0001: with checksum but no encryption; - * b’0010: no checksum but with encryption; + * 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 the ESP device. - - data[0] is for opmode settings, including: + - data[0] is for opmode settings, including: - * 0x00: NULL + * 0x00: NULL * 0x01: STA - * 0x02: SoftAP - * 0x03: SoftAP & 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 the ESP device to the AP. - To notify the ESP device that the essential information has been sent and it is allowed to connect to the AP. - - No data field is contained. - + - No data field is contained. + * - 0x4 (b’000100) - Disconnect the ESP device from the AP. - - - - No data field is contained. + - + - No data field is contained. * - 0x5 (b’000101) - To get the information of the ESP device’s Wi-Fi mode and it’s status. - - - - * No data field is contained. When receiving this control frame, the ESP device will send back a follow-up frame of Wi-Fi connection state report to the mobile phone with the information of the current opmode, connection status, SSID, and so on. - * The types of information sent to the mobile phone is defined by the application installed on the phone. + - + - * No data field is contained. When receiving this control frame, the ESP device will send back a follow-up frame of Wi-Fi connection state report to the mobile phone with the information of the current opmode, connection status, SSID, and so on. + * 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). - - - - Data[0~5] is taken as the MAC address for the STA device. If there is a second STA device, then it uses data[6-11] and the rest can be done in the same manner. - + - + - Data[0~5] is taken as the MAC address for the STA device. If there is a second STA device, then it uses data[6-11] and the rest can be done in the same manner. + * - 0x7 (b’000111) - Get the version information. - - - - + - + - * - 0x8 (b’001000) - Disconnect the BLE GATT link. - - - - The ESP device will disconnect the BLE GATT link after receives this command. + - + - The ESP device will disconnect the BLE GATT link after receives this command. * - 0x9 (b’001001) - Get the Wi-Fi list. - To get the ESP device to scan the Wi-Fi access points around. - - No data field is contained. When receiving this control frame, the ESP device will send back a follow-up frame of Wi-Fi list report to the mobile phone. + - No data field is contained. When receiving this control frame, the ESP device will send back a follow-up frame of Wi-Fi list report to the mobile phone. - -1.2 Data Frame (Binary: 0x1 b’01) -.. list-table:: - :header-rows: 1 - :widths: 5 15 20 30 - +1.2 Data Frame (Binary: 0x1 b'01) + +.. list-table:: + :header-rows: 1 + :widths: 5 15 20 30 + * - Data Frame - Implication - Explanation - - Note + - 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. + - The length of the data depends on the length field. * - 0x1 (b’000001) - Send the SSID 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. + - 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. + - 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. + - Please refer to Note 1 below. * - 0x4 (b’000100) - Send the SSID for SoftAP mode. - - - - Please refer to Note 1 below. + - + - Please refer to Note 1 below. * - 0x5 (b’000101) - Send the password for SoftAPmode. - - - - Please refer to Note 1 below. + - + - Please refer to Note 1 below. * - 0x6 (b’000110) - Set the maximum connection number for SoftAP mode. - - - - data[0] represents the value of the connection number, ranging from 1 to 4. When the transmission direction is ESP device to the mobile phone, it means to provide the mobile phone with the needed information. + - + - data[0] represents the 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 SoftAP mode. - - + - - data[0]： * 0x00: OPEN @@ -282,35 +283,35 @@ The format of ACK Frame: * 0x03: WPA2_PSK * 0x04: WPA_WPA2_PSK - When the transmission direction is from the ESP device to the mobile phone, it means to provide the mobile phone with the needed information. + When the transmission direction is from the 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 from the ESP device to the mobile phone, it means to provide the mobile phone with the needed information. + - + - data[0] represents the quantity of the supported channels, ranging from 1 to 14. When the transmission direction is from the ESP device to the mobile phone, it means to provide the mobile phone with the needed information. * - 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. + - 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. + - 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. + - 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. + - 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. + - 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. + - 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. @@ -328,13 +329,13 @@ The format of ACK Frame: data[3] and the subsequent is in accordance with the format of SSID/BSSID information. If device is in connecting state, maximum Wi-Fi reconnecting time would be included here. If device is in disconnected state, Wi-Fi connection end reason and RSSI would be included here. * - 0x10 (b’010000) - Version - - + - - * data[0]= great version - * data[1]= sub 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. It supports to be sent into fragments if the data length is too long. + - The format of the data frame is length + RSSI + SSID. 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. @@ -346,72 +347,72 @@ The format of ACK Frame: * 0x05: dh malloc error * 0x06: dh param error * 0x07: read param error - * 0x08: make public error + * 0x08: make public error * 0x09: data format error * 0x0a: calculate MD5 error * 0x0b: Wi-Fi scan 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. + - The data frame supports to be sent into fragments if the data length is too long. * - 0x14 (b’010100) - Set the maximum Wi-Fi reconnecting time. - - + - - data[0] represents the maximum Wi-Fi reconnecting time. * - 0x15 (b’010101) - Set the Wi-Fi connection end reason. - - + - - data[0] represents the Wi-Fi connection end reason, whose type shall be same with struct `wifi_err_reason_t`. * - 0x16 (b’010110) - Set the RSSI at Wi-Fi connection end. - - + - - data[0] represents the RSSI at Wi-Fi connection end. If there is no meaningful RSSI in the connection end, this value shall be the meaningless one, which is `-128`. .. note:: - - - Note 1: The length of the data depends on the data length field. When the transmission direction is from the ESP device to the mobile phone, it means to provide the mobile phone with the needed information. - - Note 2: The length of the data depends on the data length field. The frame supports to be fragmented if the data length is not long enough. + - Note 1: The length of the data depends on the data length field. When the transmission direction is from the ESP device to the mobile phone, it means to provide the mobile phone with the needed information. + + - Note 2: The length of the data depends on the data length field. The frame supports to be fragmented if the data length is not long enough. 2. Frame Control The **Frame Control** field takes one byte and each bit has a different meaning. -.. list-table:: - :header-rows: 1 - :widths: 10 35 +.. list-table:: + :header-rows: 1 + :widths: 10 35 * - Bit - - Meaning + - Meaning * - 0x01 - Indicates whether the frame is encrypted. * 1 means encrypted. * 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. + 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 - - Indicates whether a frame contains a checksum (such as SHA1, MD5, CRC) for the end of the frame. Data field includes sequence, data length, and clear text. Both the control frame and the data frame can choose whether to contain a check bit or not. + - Indicates whether a frame contains a checksum (such as SHA1, MD5, CRC) for the end of the frame. Data field includes sequence, data length, and clear text. Both the control frame and the data frame can choose whether to contain a check bit or not. * - 0x04 - Indicates the data direction. * 0 means from the mobile phone to the ESP device. - * 1 means from the ESP device to the mobile phone. + * 1 means from the ESP device to the mobile phone. * - 0x08 - Indicates whether the other person is required to reply to an ACK. * 0 indicates not required to reply to an ACK. - * 1 indicates required to reply to an ACK. + * 1 indicates required to reply to an ACK. * - 0x10 - Indicates whether there are subsequent data fragments. * 0 indicates that there is no subsequent data fragment for this frame. * 1 indicates that there are subsequent data fragments which 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 two bytes of the data field (that is, the content data of the maximum support 64 K). - * - 0x10~0x80 - - Reserved + + In the case of a frag frame, the total length of the current content section + subsequent content section is given in the first two bytes of the data field (that is, the content data of the maximum support 64 K). + * - 0x10~0x80 + - Reserved 3. Sequence Number @@ -430,7 +431,7 @@ The format of ACK Frame: The **CheckSum** field takes two bytes, which is used to check "sequence + data length + clear text data". The Security Implementation of {IDF_TARGET_NAME} ------------------------------------------------- +-------------------------------------------------- 1. Securing Data @@ -481,13 +482,13 @@ The data to be encrypted and decrypted must be in the same length. The IV8 is an 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. GATT Related Instructions -------------------------- +---------------------------- UUID >>>>> BluFi Service UUID: 0xFFFF, 16 bit -BluFi (the mobile -> {IDF_TARGET_NAME}): 0xFF01, writable +BluFi (the mobile > {IDF_TARGET_NAME}): 0xFF01, writable -Blufi ({IDF_TARGET_NAME} -> the mobile phone): 0xFF02, readable and callable +Blufi ({IDF_TARGET_NAME} > the mobile phone): 0xFF02, readable and callable diff --git a/docs/en/api-guides/ble/host-feature-support-status.rst b/docs/en/api-guides/ble/host-feature-support-status.rst new file mode 100644 index 0000000000..68ba283ba5 --- /dev/null +++ b/docs/en/api-guides/ble/host-feature-support-status.rst @@ -0,0 +1,159 @@ +:orphan: + +ESP Host Major Feature Support Status +======================================= + +:link_to_translation:`zh_CN:[中文]` + +The table below shows the support status of major features on ESP-Bluedroid and ESP-NimBLE Host. +If you plan to run the BLE Controller and Host on {IDF_TARGET_NAME} together, the functionality of the Host may be limited by the support status of the Controller, +please check the :doc:`{IDF_TARGET_NAME} Major Feature Support Status Table ` . + +|supported_def| **This feature has completed development and internal testing.** [1]_ + +|experimental_def| **This feature has been developed and is currently undergoing internal testing.** +You can explore these features for evaluation and feedback purposes but should be cautious of potential issues. + +|developing_def| **The feature is currently being actively developed, and expected to be supported by the end of YYYY/MM.** +You should anticipate future updates regarding the progress and availability of these features. +If you do have an urgent need, please contact our `customer support team `__ for a possible feature trial. + +|unsupported_def| **This feature is not supported on this Host.** If you have related requirements, please prioritize selecting other Espressif Bluetooth Host that support this feature. +If none of our chip series meet your needs, please contact `customer support team `__, and our R&D team will conduct an internal feasibility assessment for you. + +|NA_def| The feature with this label could be the following type: + - **Controller-only Feature**: The feature exists only below HCI, and cannot be configured/enabled via Host API, such as Advertising Channel Index. + It does not require the support from the Host. + +.. list-table:: + :width: 100% + :widths: auto + :header-rows: 1 + + * - .. centered:: Core Spec + - .. centered:: Major Features + - .. centered:: ESP-Bluedroid Host + - .. centered:: ESP-NimBLE Host + * - .. centered:: |4.2| + - LE Data Packet Length Extension + - |supported| + - |supported| + * - + - LE Secure Connections + - |supported| + - |supported| + * - + - Link Layer Privacy + - |supported| + - |supported| + * - + - Link Layer Extended Filter Policies + - |supported| + - |supported| + * - .. centered:: |5.0| + - 2 Msym/s PHY for LE + - |supported| + - |supported| + * - + - LE Long Range (Coded PHY S=2/S=8) + - |supported| + - |supported| + * - + - High Duty Cycle Non-Connectable Advertising + - |supported| + - |supported| + * - + - LE Advertising Extensions + - |supported| + - |supported| + * - + - LE Channel Selection Algorithm #2 + - |supported| + - |supported| + * - .. centered:: |5.1| + - Angle of Arrival (AoA)/Angle of Departure (AoD) + - |unsupported| + - |developing202412| + * - + - GATT Caching + - |experimental| + - |experimental| + * - + - Advertising Channel Index + - |NA| + - |NA| + * - + - Periodic Advertising Sync Transfer + - |supported| + - |supported| + * - .. centered:: |5.2| + - LE Isochronous Channels (BIS/CIS) + - |unsupported| + - |developing202412| + * - + - Enhanced Attribute Protocol + - |unsupported| + - |developing202412| + * - + - LE Power Control + - |unsupported| + - |developing202412| + * - .. centered:: |5.3| + - AdvDataInfo in Periodic Advertising + - |supported| + - |supported| + * - + - LE Enhanced Connection Update (Connection Subrating) + - |unsupported| + - |supported| + * - + - LE Channel Classification + - |supported| + - |supported| + * - .. centered:: |5.4| + - Advertising Coding Selection + - |unsupported| + - |supported| + * - + - Encrypted Advertising Data + - |unsupported| + - |experimental| + * - + - LE GATT Security Levels Characteristic + - |unsupported| + - |developing202412| + * - + - Periodic Advertising with Responses + - |unsupported| + - |developing202412| + +.. [1] + If you would like to know the Bluetooth SIG certification information for supported features, + please consult `SIG Bluetooth Product Database `__. + +It is important to clarify that this document is not a binding commitment to our customers. +The above feature support status information is for general informational purposes only and is subject to change without notice. +You are encouraged to consult with our `customer support team `__ for the most up-to-date information and to verify the suitability of features for your specific needs. + + +.. |supported| image:: ../../../_static/ble/feature_status/supported.svg + :class: align-center +.. |developing202412| image:: ../../../_static/ble/feature_status/developing202412.svg + :class: align-center +.. |unsupported| image:: ../../../_static/ble/feature_status/unsupported.svg + :class: align-center +.. |experimental| image:: ../../../_static/ble/feature_status/experimental.svg + :class: align-center +.. |NA| image:: ../../../_static/ble/feature_status/NA.svg + :class: align-center +.. |supported_def| image:: ../../../_static/ble/feature_status/supported.svg +.. |developing_def| image:: ../../../_static/ble/feature_status/developingYYYYMM.svg +.. |unsupported_def| image:: ../../../_static/ble/feature_status/unsupported.svg +.. |experimental_def| image:: ../../../_static/ble/feature_status/experimental.svg +.. |NA_def| image:: ../../../_static/ble/feature_status/NA.svg +.. |4.2| replace:: `4.2 `__ +.. |5.0| replace:: `5.0 `__ +.. |5.1| replace:: `5.1 `__ +.. |5.2| replace:: `5.2 `__ +.. |5.3| replace:: `5.3 `__ +.. |5.4| replace:: `5.4 `__ diff --git a/docs/en/api-guides/ble/index.rst b/docs/en/api-guides/ble/index.rst new file mode 100644 index 0000000000..226b6f73db --- /dev/null +++ b/docs/en/api-guides/ble/index.rst @@ -0,0 +1,24 @@ +####################### +Bluetooth® Low Energy +####################### + +:link_to_translation:`zh_CN:[中文]` + +********* +Overview +********* +.. toctree:: + :maxdepth: 1 + + overview + ble-feature-support-status + +********** +Profile +********** + +.. toctree:: + :maxdepth: 2 + + :SOC_BLE_MESH_SUPPORTED: ../esp-ble-mesh/ble-mesh-index + :SOC_BLUFI_SUPPORTED: blufi diff --git a/docs/en/api-guides/ble/overview.rst b/docs/en/api-guides/ble/overview.rst new file mode 100644 index 0000000000..e360d210cd --- /dev/null +++ b/docs/en/api-guides/ble/overview.rst @@ -0,0 +1,203 @@ +Introduction +============= + +:link_to_translation:`zh_CN:[中文]` + +This document provides an architecture overview of the Bluetooth Low Energy (Bluetooth LE) stack in ESP-IDF and some quick links to related documents and application examples. + +.. only:: esp32 + + {IDF_TARGET_NAME} supports Dual-Mode Bluetooth 4.2 and is certified for Dual-Mode Bluetooth 4.2 and Bluetooth LE 5.0. + +.. only:: esp32c3 or esp32s3 + + {IDF_TARGET_NAME} supports Bluetooth 5.0 (LE) and is certified for Bluetooth LE 5.4. + +.. only:: esp32c2 or esp32c6 or esp32h2 + + {IDF_TARGET_NAME} supports Bluetooth 5.0 (LE) and is certified for Bluetooth LE 5.3. + +The Bluetooth LE stack in ESP-IDF is a layered architecture that enables Bluetooth functionality on {IDF_TARGET_NAME} chip series. The table below shows its architecture. + +.. only:: esp32 or esp32s3 or esp32c3 or esp32c6 + + .. figure:: ../../../_static/bluetooth-architecture.png + :align: center + :scale: 90% + :alt: {IDF_TARGET_NAME} Bluetooth LE Stack Architecture + + {IDF_TARGET_NAME} Bluetooth LE Stack Architecture + +.. only:: esp32c2 + + .. figure:: ../../../_static/bluetooth-architecture-no-ble-mesh.png + :align: center + :scale: 90% + :alt: {IDF_TARGET_NAME} Bluetooth LE Stack Architecture + + {IDF_TARGET_NAME} Bluetooth LE Stack Architecture + +.. only:: esp32h2 + + .. figure:: ../../../_static/bluetooth-architecture-no-blufi.png + :align: center + :scale: 90% + :alt: {IDF_TARGET_NAME} Bluetooth LE Stack Architecture + + {IDF_TARGET_NAME} Bluetooth LE Stack Architecture + +The table below shows whether the Bluetooth LE modules are supported in a specific chip series. + +.. list-table:: + :width: 100% + :widths: auto + :header-rows: 1 + + * - Chip Series + - Controller + - ESP-Bluedroid + - ESP-NimBLE + - ESP-BLE-MESH + - BluFi + * - ESP32 + - Y + - Y + - Y + - Y + - Y + * - ESP32-S2 + - \– + - \– + - \– + - \– + - \– + * - ESP32-S3 + - Y + - Y + - Y + - Y + - Y + * - ESP32-C2 + - Y + - Y + - Y + - \– + - Y + * - ESP32-C3 + - Y + - Y + - Y + - Y + - Y + * - ESP32-C6 + - Y + - Y + - Y + - Y + - Y + * - ESP32-H2 + - Y + - Y + - Y + - Y + - \– + +The following sections briefly describe each layer and provide quick links to the related documents and application examples. + + +ESP Bluetooth Controller +------------------------ + +At the bottom layer is ESP Bluetooth Controller, which encompasses various modules such as PHY, Baseband, Link Controller, Link Manager, Device Manager, and HCI. It handles hardware interface management and link management. It provides functions in the form of libraries and is accessible through APIs. This layer directly interacts with the hardware and low-level Bluetooth protocols. + +- :doc:`API reference <../../api-reference/bluetooth/controller_vhci>` +- :example:`Application examples ` + + +Hosts +----- + +There are two hosts, ESP-Bluedroid and ESP-NimBLE. The major difference between them is as follows: + +- Although both support Bluetooth LE, ESP-NimBLE requires less heap and flash size. + +.. only:: esp32 + + - ESP-Bluedroid supports both Classic Bluetooth and Bluetooth LE, while ESP-NimBLE only supports Bluetooth LE. + + +ESP-Bluedroid +^^^^^^^^^^^^^ + +ESP-Bluedroid is a modified version of the native Android Bluetooth stack, Bluedroid. It consists of two layers: the Bluetooth Upper Layer (BTU) and the Bluetooth Transport Controller layer (BTC). The BTU layer is responsible for processing bottom layer Bluetooth protocols such as L2CAP, GATT/ATT, SMP, GAP, and other profiles. The BTU layer provides an interface prefixed with "bta". The BTC layer is mainly responsible for providing a supported interface, prefixed with "esp", to the application layer, processing GATT-based profiles and handling miscellaneous tasks. All the APIs are located in the ESP_API layer. Developers should use the Bluetooth Low Energy APIs prefixed with "esp". + +.. only:: esp32 + + ESP-Bluedroid for {IDF_TARGET_NAME} supports Classic Bluetooth and Bluetooth LE. + +.. only:: not esp32 + + ESP-Bluedroid for {IDF_TARGET_NAME} supports Bluetooth LE only. Classic Bluetooth is not supported. + +- API references + + - :doc:`../../api-reference/bluetooth/bt_common` + - :doc:`Bluetooth LE <../../api-reference/bluetooth/bt_le>` + +.. only:: esp32 + + - :example:`Bluetooth LE 4.2 Application Examples ` + +.. only:: not esp32 + + - :example:`Bluetooth LE 4.2 Application Examples ` + - :example:`Bluetooth LE 5.0 Application Examples ` + +ESP-NimBLE +^^^^^^^^^^ + +ESP-NimBLE is a host stack built on top of the NimBLE host stack developed by Apache Mynewt. The NimBLE host stack is ported for {IDF_TARGET_NAME} chip series and FreeRTOS. The porting layer is kept clean by maintaining all the existing APIs of NimBLE along with a single ESP-NimBLE API for initialization, making it simpler for the application developers. + +ESP-NimBLE supports Bluetooth LE only. Classic Bluetooth is not supported. + +- `Apache Mynewt NimBLE User Guide `__ +- API references + + - `NimBLE API references `__ + - :doc:`ESP-NimBLE API references for initialization <../../api-reference/bluetooth/nimble/index>` + +- :example:`Application examples ` + + +Profiles +-------- + +Above the host stacks are the profile implementations by Espressif and some common profiles. Depending on your configuration, these profiles can run on ESP-Bluedroid or ESP-NimBLE. + + +.. only:: SOC_BLE_MESH_SUPPORTED + + ESP-BLE-MESH + ^^^^^^^^^^^^ + + Built on top of Zephyr Bluetooth Mesh stack, the ESP-BLE-MESH implementation supports device provisioning and node control. It also supports such node features as Proxy, Relay, Low power and Friend. + + - :doc:`ESP-BLE-MESH documentation <../esp-ble-mesh/ble-mesh-index>`: feature list, get started, architecture, description of application examples, frequently asked questions, etc. + - :example:`Application examples ` + + +.. only:: SOC_BLUFI_SUPPORTED + + BluFi + ^^^^^ + + The BluFi for {IDF_TARGET_NAME} is a Wi-Fi network configuration function via Bluetooth channel. It provides a secure protocol to pass Wi-Fi configuration and credentials to {IDF_TARGET_NAME}. Using this information, {IDF_TARGET_NAME} can then connect to an AP or establish a softAP. + + - :doc:`BluFi documentation ` + - :example:`Application examples ` + + +Applications +------------ + +At the uppermost layer are applications. You can build your own applications on top of the ESP-Bluedroid and ESP-NimBLE stacks, leveraging the provided APIs and profiles to create Bluetooth LE-enabled applications tailored to specific use cases. diff --git a/docs/en/api-guides/classic-bt/index.rst b/docs/en/api-guides/classic-bt/index.rst new file mode 100644 index 0000000000..e6e9141c70 --- /dev/null +++ b/docs/en/api-guides/classic-bt/index.rst @@ -0,0 +1,13 @@ +####################### +Bluetooth® Classic +####################### + +:link_to_translation:`zh_CN:[中文]` + +********* +Overview +********* +.. toctree:: + :maxdepth: 2 + + overview diff --git a/docs/en/api-guides/classic-bt/overview.rst b/docs/en/api-guides/classic-bt/overview.rst new file mode 100644 index 0000000000..4c28f800e8 --- /dev/null +++ b/docs/en/api-guides/classic-bt/overview.rst @@ -0,0 +1,80 @@ +Introduction +============= + +:link_to_translation:`zh_CN:[中文]` + +This document provides an architecture overview of the Bluetooth Classic stack in ESP-IDF and some quick links to related documents and application examples. + +.. only:: esp32 + + {IDF_TARGET_NAME} supports Dual-Mode Bluetooth 4.2. + +The Bluetooth Classic stack in ESP-IDF is a layered architecture that enables Bluetooth functionality on {IDF_TARGET_NAME} chip series. The table below shows its architecture. + +.. only:: esp32 + + .. figure:: ../../../_static/classic-bluetooth-architecture.png + :align: center + :scale: 90% + :alt: {IDF_TARGET_NAME} Bluetooth Classic Stack Architecture + + {IDF_TARGET_NAME} Bluetooth Classic Stack Architecture + +The table below shows whether the Bluetooth Classic Controller are supported in a specific chip series. + +.. list-table:: + :width: 100% + :widths: auto + :header-rows: 1 + + * - Chip Series + - Controller + * - ESP32 + - Y + * - ESP32-S2 + - \– + * - ESP32-S3 + - \– + * - ESP32-C2 + - \– + * - ESP32-C3 + - \- + * - ESP32-C6 + - \- + * - ESP32-H2 + - \- + +The following sections briefly describe each layer and provide quick links to the related documents and application examples. + + +ESP Bluetooth Controller +------------------------ + +At the bottom layer is ESP Bluetooth Controller, which encompasses various modules such as PHY, Baseband, Link Controller, Link Manager, Device Manager, and HCI. It handles hardware interface management and link management. It provides functions in the form of libraries and is accessible through APIs. This layer directly interacts with the hardware and low-level Bluetooth protocols. + +- :doc:`API reference <../../api-reference/bluetooth/controller_vhci>` +- :example:`Application examples ` + + +Hosts +----- + +There is one host, ESP-Bluedroid, supporting Classic Bluetooth in IDF. + + +ESP-Bluedroid +^^^^^^^^^^^^^ + +ESP-Bluedroid is a modified version of the native Android Bluetooth stack, Bluedroid. It consists of two layers: the Bluetooth Upper Layer (BTU) and the Bluetooth Transport Controller layer (BTC). The BTU layer is responsible for processing bottom layer Bluetooth protocols such as L2CAP and other profiles. The BTU layer provides an interface prefixed with "bta". The BTC layer is mainly responsible for providing a supported interface, prefixed with "esp", to the application layer and handling miscellaneous tasks. All the APIs are located in the ESP_API layer. Developers should use the Classic Bluetooth APIs prefixed with "esp". + +- API references + + - :doc:`../../api-reference/bluetooth/bt_common` + - :doc:`../../api-reference/bluetooth/classic_bt` +- :example:`Application examples ` + + +Applications +------------ + +At the uppermost layer are applications. You can build your own applications on top of the ESP-Bluedroid stacks, leveraging the provided APIs and profiles to create Bluetooth Classic applications tailored to specific use cases. diff --git a/docs/en/api-guides/esp-ble-mesh/ble-mesh-architecture.rst b/docs/en/api-guides/esp-ble-mesh/ble-mesh-architecture.rst index e66c5fb790..6fb4102b49 100644 --- a/docs/en/api-guides/esp-ble-mesh/ble-mesh-architecture.rst +++ b/docs/en/api-guides/esp-ble-mesh/ble-mesh-architecture.rst @@ -1,5 +1,5 @@ -ESP-BLE-MESH Architecture -========================= +Architecture +============= :link_to_translation:`zh_CN:[中文]` @@ -41,7 +41,7 @@ ESP-BLE-MESH architecture includes five key parts: - ``Features`` - - Include several ESP-BLE-MESH features, e.g. Low Power feature, Friend feature, Relay feature, etc. + - Include several ESP-BLE-MESH features, e.g., Low Power feature, Friend feature, Relay feature, etc. - ``Mesh Bearer Layer`` @@ -182,7 +182,7 @@ Functions of each layer are shown in Table 1.3: The ``Applications`` in the protocol stack architecture implement the corresponding functions by calling the API provided by the ESP-BLE-MESH protocol stack and processing the Event reported by the protocol stack. There are some common applications, such as gateway, lighting and etc. -Interaction between application layer（``Applications``）and ``API / Event`` +Interaction between application layer (``Applications``) and ``API/Event`` - Application layer calls API diff --git a/docs/en/api-guides/esp-ble-mesh/ble-mesh-faq.rst b/docs/en/api-guides/esp-ble-mesh/ble-mesh-faq.rst index d7f89e0c4f..4256297eda 100644 --- a/docs/en/api-guides/esp-ble-mesh/ble-mesh-faq.rst +++ b/docs/en/api-guides/esp-ble-mesh/ble-mesh-faq.rst @@ -1,5 +1,5 @@ -ESP-BLE-MESH FAQ -================ +FAQ +===== :link_to_translation:`zh_CN:[中文]` @@ -23,7 +23,7 @@ Users could refer to the sections for quick answer to their questions. This docu Generally, a Provisioner is used to provision unprovisioned devices and form a mesh network. And after provisioning, roles of the unprovisioned devices will be changed to those of a node. -1.1 What is the flow for an unprovisioned device to join ESP-BLE-MESH network? +1.1 What Is the Flow for an Unprovisioned Device to Join ESP-BLE-MESH Network? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ There are two phases for a device to join ESP-BLE-MESH network via a Provisioner, namely, provisioning and configuration. @@ -32,76 +32,76 @@ Generally, a Provisioner is used to provision unprovisioned devices and form a m - The phase of configuration is to add AppKeys to the node and bind AppKeys to corresponding models. And some items are optional during configuration, including adding subscription addresses to the node, set publication information, etc. By configuration, the node can actually transmit messages to a Provisioner and receive messages from it. -1.2 If a Provisioner wants to change states of a node, what requirements should be met for a Provisioner? +1.2 If a Provisioner Wants to Change States of a Node, What Requirements Should Be Met for a Provisioner? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - Client model that corresponds to server model of the node is required. - NetKey and AppKey used to encrypt messages shall be owned by both the node and the Provisioner. - The address owned by the node shall be known, which could be its unicast address or subscription address. -1.3 How can NetKey and AppKey be used? +1.3 How Can NetKey and AppKey Be Used? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - NetKey is used for encryption of messages in Network Layer. Nodes with the same NetKey are assumed to be in the same subnet while those with different NetKeys cannot communicate with each other. - AppKey is used for encryption of messages in Upper Transport Layer. If client model and server model are bound to different AppKeys, the communication cannot be achieved. -1.4 How to generate a NetKey or AppKey for Provisioner? Can we use a fixed NetKey or AppKey? +1.4 How to Generate a NetKey or AppKey for Provisioner? Can We Use a Fixed NetKey or AppKey? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - The API :cpp:func:`esp_ble_mesh_provisioner_add_local_net_key` can be used to add a NetKey with a fixed or random value. - The API :cpp:func:`esp_ble_mesh_provisioner_add_local_app_key` can be used to add an AppKey with a fixed or random value. -1.5 Is the unicast address of Provisioner fixed? +1.5 Is the Unicast Address of Provisioner Fixed? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - The value of :code:`prov_unicast_addr` in :cpp:type:`esp_ble_mesh_prov_t` is used to set the unicast address of Provisioner, it can be set only once during initialization and can't be changed afterwards. + The value of :code:`prov_unicast_addr` in :cpp:type:`esp_ble_mesh_prov_t` is used to set the unicast address of Provisioner, it can be set only once during initialization and cannot be changed afterwards. -1.6 Can the address of Provisioner serve as destination address of the node-reporting-status message？ +1.6 Can the Address of Provisioner Serve as Destination Address of the Node-reporting-status Message? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - The unicast address of Provisioner can be set only once during initialization and can't be changed afterwards. In theory, it can serve as the destination address of the node-reporting-status message, provided that the unicast address of the Provisioner is known by nodes. Nodes can know the unicast address of Provisioner during configuration since Provisioner sends messages to them with its unicast address used as the source address. + The unicast address of Provisioner can be set only once during initialization and cannot be changed afterwards. In theory, it can serve as the destination address of the node-reporting-status message, provided that the unicast address of the Provisioner is known by nodes. Nodes can know the unicast address of Provisioner during configuration since Provisioner sends messages to them with its unicast address used as the source address. Subscription address can also be used. Provisioner subscribes to a group address or virtual address, and nodes send messages to the subscription address. -1.7 Is the unicast address of the node that is firstly provisioned by Provisioner to ESP-BLE-MESH network fixed？ +1.7 Is the Unicast Address of the Node That Is Firstly Provisioned by ProvIsioner to ESP-BLE-MESH Network Fixed? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - The value of :code:`prov_start_address` in :cpp:type:`esp_ble_mesh_prov_t` is used to set the starting address when the Provisioner provisions unprovisioned devices, i.e. the unicast address of the node it firstly provisioned. It can be set only once during initialization and can't be changed afterwards. + The value of :code:`prov_start_address` in :cpp:type:`esp_ble_mesh_prov_t` is used to set the starting address when the Provisioner provisions unprovisioned devices, i.e., the unicast address of the node it firstly provisioned. It can be set only once during initialization and cannot be changed afterwards. -1.8 Is the unicast address of the node that mobile App firstly provisioned fixed? +1.8 Is the Unicast Address of the Node That Mobile App Firstly Provisioned Fixed? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The App will decide the unicast address, and currently most of them are fixed. -1.9 How to know which unprovisioned device is the Provisioner that is provisioning currently? +1.9 How to Know Which Unprovisioned Device Is the ProvIsioner That Is Provisioning Currently? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - The value of :code:`prov_attention` in :cpp:type:`esp_ble_mesh_prov_t` is used by Provisioner set to unprovisioned device during provisioning. It can be set only once during initialization and can't be changed afterwards. When the unprovisioned device is joining the mesh network, it can display in a specific way like flashing light to notify Provisioner that it is being provisioned. + The value of :code:`prov_attention` in :cpp:type:`esp_ble_mesh_prov_t` is used by Provisioner set to unprovisioned device during provisioning. It can be set only once during initialization and cannot be changed afterwards. When the unprovisioned device is joining the mesh network, it can display in a specific way like flashing light to notify Provisioner that it is being provisioned. -1.10 How many ways to authenticate the devices during provisioning? Which way was used in the :example:`provided examples `? +1.10 How Many Ways to Authenticate the Devices During Provisioning? Which Way Was Used in the :example:`provided examples `? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - There are four authentication methods, i.e. No OOB, Static OOB, Output OOB and Input OOB. In the provided examples, No OOB is used. + There are four authentication methods, i.e., No OOB, Static OOB, Output OOB and Input OOB. In the provided examples, No OOB is used. -1.11 What information can be carried by the advertising packets of the unprovisioned device before provisioning into the network? +1.11 What Information Can Be Carried by the Advertising Packets of the Unprovisioned Device Before Provisioning into the Network? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - Device UUID - OOB Info - URL Hash (optional) -1.12 Can such information be used for device identification? +1.12 Can Such Information Be Used for Device Identification? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ For example, each unprovisioned device contains a unique Device UUID, which can be used for device identification. -1.13 How is the unicast address assigned when the node provisioned by Provisioner contains multiple elements? +1.13 How Is the Unicast Address Assigned When the Node Provisioned by ProvIsioner Contains Multiple Elements? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - Provisioner will assign an unicast address for the primary element of the node, and unicast address of the remaining elements are incremented one by one. - - For example: If an unprovisioned device has three elements, i.e. the primary element, the second element and the third element. After provisioning, the primary element address of the node is 0x0002 while the second element address is 0x0003, and the third element address is 0x0004. + - For example: If an unprovisioned device has three elements, i.e., the primary element, the second element and the third element. After provisioning, the primary element address of the node is 0x0002 while the second element address is 0x0003, and the third element address is 0x0004. -1.14 How can Provisioner get and parse the :ref:`Composition Data ` of nodes through Configuration Client Model? +1.14 How Can Provisioner Get and Parse the :ref:`Composition Data ` of Nodes Through Configuration Client Model? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - Provisioner can get the Composition Data of nodes using the :ref:`Configuration Client Model ` API :cpp:func:`esp_ble_mesh_config_client_set_state` with :code:`comp_data_get` in the parameter :cpp:type:`esp_ble_mesh_cfg_client_get_state_t` set properly. @@ -204,7 +204,7 @@ Generally, a Provisioner is used to provision unprovisioned devices and form a m } } -1.15 How can Provisioner further configure nodes through obtained Composition Data? +1.15 How Can Provisioner Further Configure Nodes Through Obtained Composition Data? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Provisioner do the following configuration by calling the :ref:`Configuration Client Model ` API :cpp:func:`esp_ble_mesh_config_client_set_state`. @@ -213,7 +213,7 @@ Generally, a Provisioner is used to provision unprovisioned devices and form a m - Add subscription address to the models of nodes with :code:`model_sub_add` in the parameter :cpp:type:`esp_ble_mesh_cfg_client_set_state_t` set properly. - Set publication information to the models of nodes with :code:`model_pub_set` in the parameter :cpp:type:`esp_ble_mesh_cfg_client_set_state_t` set properly. -1.16 Can nodes add corresponding configurations for themselves? +1.16 Can Nodes Add Corresponding Configurations for Themselves? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ This method can be used in special cases like testing period. @@ -271,7 +271,7 @@ Generally, a Provisioner is used to provision unprovisioned devices and form a m When the NVS storage of the node is enabled, group address added and AppKey bound by this method will not be saved in the NVS when the device is powered off currently. These configuration information can only be saved if they are configured by Configuration Client Model. -1.17 How does Provisioner control nodes by grouping? +1.17 How Does Provisioner Control Nodes by Grouping? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Generally there are two approaches to implement group control in ESP-BLE-MESH network, group address approach and virtual address approach. And supposing there are 10 devices, i.e., five devices with blue lights and five devices with red lights. @@ -280,12 +280,12 @@ Generally, a Provisioner is used to provision unprovisioned devices and form a m - Method 2: 5 blue lights can subscribe to a virtual address, 5 red lights subscribe to another one. By sending messages to different virtual addresses, Provisioner can realize group control. -1.18 How does Provisioner add nodes to multiple subnets? +1.18 How Does Provisioner Add Nodes to Multiple Subnets? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Provisioner can add multiple NetKeys to nodes during configuration, and nodes sharing the same NetKey belong to the same subnet. Provisioner can communicate with nodes on different subnets by using different NetKeys. -1.19 How does Provisioner know if a node in the mesh network is offline? +1.19 How Does ProvIsioner Know If a Node in the Mesh Network Is Offline? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Node offline is usually defined as: the condition that the node cannot be properly communicated with other nodes in the mesh network due to power failure or some other reasons. @@ -300,7 +300,7 @@ Generally, a Provisioner is used to provision unprovisioned devices and form a m The heartbeat message should be designed into a single package (less than 11 bytes), so the transmission and reception of it can be more efficient. -1.20 What operations should be performed when Provisioner removes nodes from the network? +1.20 What Operations Should Be Performed When Provisioner Removes Nodes from the Network? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Usually when Provisioner tries to remove node from the mesh network, the procedure includes three main steps: @@ -311,19 +311,19 @@ Generally, a Provisioner is used to provision unprovisioned devices and form a m - Lastly, the node performs node reset procedure, and switches itself to an unprovisioned device. -1.21 In the Key Refresh procedure, how does Provisioner update the Netkey owned by nodes? +1.21 In the Key Refresh Procedure, How Does Provisioner Update the Netkey Owned by Nodes? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - Provisioner updates the NetKey of nodes using the :ref:`Configuration Client Model ` API :cpp:func:`esp_ble_mesh_config_client_set_state` with :code:`net_key_update` in the parameter :cpp:type:`esp_ble_mesh_cfg_client_set_state_t` set properly. - Provisioner updates the AppKey of nodes using the :ref:`Configuration Client Model ` API :cpp:func:`esp_ble_mesh_config_client_set_state` with :code:`app_key_update` in the parameter :cpp:type:`esp_ble_mesh_cfg_client_set_state_t` set properly. -1.22 How does Provisioner manage nodes in the mesh network? +1.22 How Does Provisioner Manage Nodes in the Mesh Network? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ESP-BLE-MESH implements several functions related to basic node management in the example, such as :cpp:func:`esp_ble_mesh_store_node_info`. And ESP-BLE-MESH also provides the API :cpp:func:`esp_ble_mesh_provisioner_set_node_name` which can be used to set the node's local name and the API :cpp:func:`esp_ble_mesh_provisioner_get_node_name` which can be used to get the node's local name. -1.23 What does Provisioner need when trying to control the server model of nodes? +1.23 What Does Provisioner Need When Trying to Control the Server Model of Nodes? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Provisioner must include corresponding client model before controlling the server model of nodes. @@ -338,8 +338,8 @@ Generally, a Provisioner is used to provision unprovisioned devices and form a m - Provisioner bind AppKey to its own client model by calling the API :cpp:func:`esp_ble_mesh_provisioner_bind_app_key_to_local_model`. -1.24 How does Provisoner control the server model of nodes? -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +1.24 How Does Provisioner Control the Server Model of Nodes? +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ESP-BLE-MESH supports all SIG-defined client models. Provisioner can use these client models to control the server models of nodes. And the client models are divided into 6 categories with each category has the corresponding functions. @@ -378,7 +378,7 @@ Generally, a Provisioner is used to provision unprovisioned devices and form a m 2. Node Development ------------------- -2.1 What kind of models are included by nodes? +2.1 What Kind of Models Are Included by Nodes? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - In ESP-BLE-MESH, nodes are all composed of a series of models with each model implements some functions of the node. @@ -387,14 +387,14 @@ Generally, a Provisioner is used to provision unprovisioned devices and form a m - Model can also be divided into SIG model and vendor model. All behaviors of SIG models are officially defined while behaviors of vendor models are defined by users. -2.2 Is the format of messages corresponding to each model fixed? +2.2 Is the Format of Messages Corresponding to Each Model Fixed? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - Messages, which consist of opcode and payload, are divided by opcode. - The type and the format of the messages corresponding to models are both fixed, which means the messages transmitted between models are fixed. -2.3 Which functions can be used to send messages with the models of nodes? +2.3 Which Functions Can Be Used to Send Messages with the Models of Nodes? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - For client models, users can use the API :cpp:func:`esp_ble_mesh_client_model_send_msg` to send messages. @@ -403,40 +403,40 @@ Generally, a Provisioner is used to provision unprovisioned devices and form a m - For publication, users call the API :cpp:func:`esp_ble_mesh_model_publish` to publish messages. -2.4 How to achieve the transmission of messages without packet loss? +2.4 How to Achieve the Transmission of Messages Without Packet Loss? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - Acknowledegd message is needed if users want to transmit messages without packet loss. The default time to wait for corresponding response is set in :ref:`CONFIG_BLE_MESH_CLIENT_MSG_TIMEOUT`. If the sender waits for the response until the timer expires, the corresponding timeout event would be triggered. + Acknowledged message is needed if users want to transmit messages without packet loss. The default time to wait for corresponding response is set in :ref:`CONFIG_BLE_MESH_CLIENT_MSG_TIMEOUT`. If the sender waits for the response until the timer expires, the corresponding timeout event would be triggered. .. note:: Response timeout can be set in the API :cpp:func:`esp_ble_mesh_client_model_send_msg`. The default value (4 seconds) would be applied if the parameter :code:`msg_timeout` is set to **0**. -2.5 How to send unacknowledged messages? +2.5 How to Send Unacknowledged Messages? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ For client models, users can use the API :cpp:func:`esp_ble_mesh_client_model_send_msg` with the parameter :code:`need_rsp` set to :code:`false` to send unacknowledged messages. For server models, the messages sent by using the API :cpp:func:`esp_ble_mesh_server_model_send_msg` are always unacknowledged messages. -2.6 How to add subscription address to models? +2.6 How to Add Subscription Address to Models? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Subscription address can be added through Configuration Client Model. -2.7 What is the difference between messages sent and published by models? +2.7 What Is the Difference Between Messages Sent and Published by Models? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Messages sent by calling the API :cpp:func:`esp_ble_mesh_client_model_send_msg` or :cpp:func:`esp_ble_mesh_server_model_send_msg` will be sent in the duration determined by the Network Transmit state. Messages published by calling the API :cpp:func:`esp_ble_mesh_model_publish` will be published determined by the Model Publication state. And the publication of messages is generally periodic or with a fixed number of counts. The publication period and publication count are controlled by the Model Publication state, and can be configured through Configuration Client Model. -2.8 How many bytes can be carried when sending unsegmented messages? +2.8 How Many Bytes Can Be Carried When Sending Unsegmented Messages? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The total payload length (which can be set by users) of unsegmented message is 11 octets, so if the opcode of the message is 2 octets, then the message can carry 9-octets of valid information. For vendor messages, due to the 3-octets opcode, the remaining payload length is 8 octets. -2.9 When should the :ref:`Relay ` feature of nodes be enabled? +2.9 When Should the :ref:`Relay ` Feature of Nodes Be Enabled? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Users can enable the Relay feature of all nodes when nodes detected in the mesh network are sparse. @@ -445,17 +445,17 @@ Generally, a Provisioner is used to provision unprovisioned devices and form a m And users can enable the Relay feature by default if the mesh network size is unknown. -2.10 When should the :ref:`Proxy ` feature of node be enabled? +2.10 When Should the :ref:`Proxy ` Feature of Node Be Enabled? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ If the unprovisioned device is expected to be provisioned by a phone, then it should enable the Proxy feature since almost all the phones do not support sending ESP-BLE-MESH packets through advertising bearer currently. And after the unprovisioned device is provisioned successfully and becoming a Proxy node, it will communicate with the phone using GATT bearer and using advertising bearer to communicate with other nodes in the mesh network. -2.11 How to use the Proxy filter? +2.11 How to Use the Proxy Filter? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - The Proxy filter is used to reduce the number of Network PDUs exchanged between a Proxy Client (e.g. the phone) and a Proxy Server (e.g. the node). And with the Proxy filter, Proxy Client can explicitly request to receive only mesh messages with certain destination addresses from Proxy Server. + The Proxy filter is used to reduce the number of Network PDUs exchanged between a Proxy Client (e.g., the phone) and a Proxy Server (e.g., the node). And with the Proxy filter, Proxy Client can explicitly request to receive only mesh messages with certain destination addresses from Proxy Server. -2.12 When a message can be relayed by a Relay node? +2.12 When a Message Can Be Relayed by a Relay Node? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ If a message need to be relayed, the following conditions should be met. @@ -466,12 +466,12 @@ Generally, a Provisioner is used to provision unprovisioned devices and form a m - The value of TTL in the message is greater than 1. -2.13 If a message is segmented into several segments, should the other Relay nodes just relay when one of these segments is received or wait until the message is received completely? +2.13 If a Message Is Segmented into Several Segments, Should the Other Relay Nodes Just Relay When One of These Segments Is Received or Wait Until the Message Is Received Completely? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Relay nodes will forward segments when one of them are received rather than keeping waiting until all the segments are received. -2.14 What is the principle of reducing power consumption using :ref:`Low Power ` feature? +2.14 What Is the Principle of Reducing Power Consumption Using :ref:`Low Power ` Feature? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - When the radio is turned on for listening, the device is consuming energy. When low power feature of the node is enabled, it will turn off its radio in the most of the time. @@ -480,17 +480,17 @@ Generally, a Provisioner is used to provision unprovisioned devices and form a m - When there are some new messages for low power node, its friend node will store the messages for it. And low power node can poll friend nodes to see if there are new messages at a fixed interval. -2.15 How to continue the communication on the network after powering-down and powering-up again? +2.15 How to Continue the Communication on the Network After Powering-down and Powering-up Again? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Enable the configuration :code:`Store ESP-BLE-MESH Node configuration persistently` in `menuconfig`. -2.16 How to send out the self-test results of nodes? +2.16 How to Send out the Self-test Results of Nodes? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ It is recommended that nodes can publish its self-test results periodically through Health Server Model. -2.17 How to transmit information between nodes? +2.17 How to Transmit Information Between Nodes? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ One possible application scenario for transmitting information between nodes is that spray nodes would be triggered once smoke alarm detected high smoke concentration. There are two approaches in implementation. @@ -499,19 +499,19 @@ Generally, a Provisioner is used to provision unprovisioned devices and form a m - Approach 2 is that Provisioner can configure the unicast address of spray node to the smoke alarm. When high smoke concentration is detected, smoke alarm can use send messages to the spray node with the spray node's unicast address as the destination address. -2.18 Is gateway a must for nodes communication? +2.18 Is Gateway a Must for Nodes Communication? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - Situation 1: nodes only communicate within the mesh network. In this situation, no gateway is need. ESP-BLE-MESH network is a flooded network, messages in the network have no fixed paths, and nodes can communicate with each other freely. - Situation 2: if users want to control the nodes remotely, for example turn on some nodes before getting home, then a gateway is needed. -2.19 When will the IV Update procedure be performed? +2.19 When Will the IV Update Procedure Be Performed? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ IV Update procedure would be performed once sequence number of messages sent detected by the bottom layer of node reached a critical value. -2.20 How to perform IV Update procedure? +2.20 How to Perform IV Update Procedure? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Nodes can perform IV Update procedure with Secure Network Beacon. @@ -522,25 +522,25 @@ Generally, a Provisioner is used to provision unprovisioned devices and form a m 3. ESP-BLE-MESH and Wi-Fi Coexistence ------------------------------------- -3.1 Which modes does Wi-Fi support when it coexists with ESP-BLE-MESH? +3.1 Which Modes Does Wi-Fi Support When it Coexists with ESP-BLE-MESH? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Currently only Wi-Fi station mode supports the coexistence. -3.2 Why is the Wi-Fi throughput so low when Wi-Fi and ESP-BLE-MESH coexist? +3.2 Why Is the Wi-Fi Throughput So Low When Wi-Fi and ESP-BLE-MESH Coexist? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. only:: esp32 - The :doc:`ESP32-DevKitC <../../hw-reference/esp32/get-started-devkitc>` board without PSRAM can run properly but the throughput of it is low since it has no PSRAM. When Bluetooth and Wi-Fi coexist, the throughput of ESP32-DevKitC with PSRAM can be stabilized to more than 1Mbps. + The `ESP32-DevKitC `__ board without PSRAM can run properly but the throughput of it is low since it has no PSRAM. When Bluetooth and Wi-Fi coexist, the throughput of ESP32-DevKitC with PSRAM can be stabilized to more than 1 Mbps. Some configurations in menuconfig shall be enabled to support PSRAM. - - :code:`{IDF_TARGET_NAME}-specific --> Support for external,SPI-connected RAM --> Try to allocate memories of Wi-Fi and LWIP...` - - :code:`Bluetooth --> Bluedroid Enable --> BT/BLE will first malloc the memory from the PSRAM` - - :code:`Bluetooth --> Bluedroid Enable --> Use dynamic memory allocation in BT/BLE stack.` - - :code:`Bluetooth --> Bluetooth controller --> BLE full scan feature supported.` - - :code:`Wi-Fi --> Software controls Wi-Fi/Bluetooth coexistence --> Wi-Fi` + - ``{IDF_TARGET_NAME}-specific`` > ``Support for external,SPI-connected RAM`` > ``Try to allocate memories of Wi-Fi and LWIP...`` + - ``Bluetooth`` > ``Bluedroid Enable`` > ``BT/BLE will first malloc the memory from the PSRAM`` + - ``Bluetooth`` > ``Bluedroid Enable`` > ``Use dynamic memory allocation in BT/BLE stack`` + - ``Bluetooth`` > ``Bluetooth controller`` > ``BLE full scan feature supported`` + - ``Wi-Fi`` > ``Software controls Wi-Fi/Bluetooth coexistence`` > ``Wi-Fi`` .. _ble-mesh-faq-fast-provisioning: @@ -548,32 +548,32 @@ Generally, a Provisioner is used to provision unprovisioned devices and form a m 4. Fast Provisioning -------------------- -4.1 Why is fast provisioning needed? +4.1 Why Is Fast Provisioning Needed? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - Normally when they are several unprovisioned devices, users can provision them one by one. But when it comes to a large number of unprovisioned devices (e.g. 100), provisioning them one by one will take huge amount of time. With fast provisioning, users can provision 100 unprovisioned devices in about 50 seconds. + Normally when they are several unprovisioned devices, users can provision them one by one. But when it comes to a large number of unprovisioned devices (e.g., 100), provisioning them one by one will take huge amount of time. With fast provisioning, users can provision 100 unprovisioned devices in about 50 seconds. -4.2 Why EspBleMesh App would wait for a long time during fast provisioning? +4.2 Why EspBleMesh App Would Wait for a Long Time During Fast Provisioning? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ After the App provisioned one Proxy node, it will disconnect from the App during fast provisioning, and reconnect with the App when all the nodes are provisioned. -4.3 Why is the number of node addresses displayed in the App is more than that of existing node addresses? +4.3 Why Is the Number of Node Addresses Displayed in the App Is More than That of Existing Node Addresses? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Each time after a fast provisioning process, and before starting a new one, the node addresses in the App should be cleared, otherwise the number of the node address will be incorrect. -4.4 What is the usage of the **count** value which was input in EspBleMesh App? +4.4 What Is the Usage of the **count** Value Which Was Input in EspBleMesh App? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The **count** value is provided to the Proxy node which is provisioned by the App so as to determine when to start Proxy advertising in advance. -4.5 When will Configuration Client Model of the node running :example:`fast_prov_server ` example start to work? +4.5 When will Configuration Client Model of the node running :example:`fast_prov_server ` example start to work? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Configuration Client Model will start to work after the Temporary Provisioner functionality is enabled. -4.6 Will the Temporary Provisioner functionality be enabled all the time? +4.6 Will the Temporary Provisioner Functionality Be Enabled All the Time? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ After the nodes receive messages used to turn on/off lights, all the nodes will disable its Temporary Provisioner functionality and become nodes. @@ -586,37 +586,37 @@ Generally, a Provisioner is used to provision unprovisioned devices and form a m You can find meaning of errors or warnings when they appear at the bottom of ESP-BLE-MESH stack. -5.1 What is the meaning of warning :code:`ran out of retransmit attempts`? +5.1 What Is the Meaning of Warning ``ran out of retransmit attempts``? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - When the node transmits a segmented message, and due to some reasons, the receiver doesn't receive the complete message. Then the node will retransmit the message. When the retransmission count reaches the maximum number, which is 4 currently, then this warning will appear. + When the node transmits a segmented message, and due to some reasons, the receiver does not receive the complete message. Then the node will retransmit the message. When the retransmission count reaches the maximum number, which is 4 currently, then this warning will appear. -5.2 What is the meaning of warning :code:`Duplicate found in Network Message Cache`? +5.2 What Is the Meaning of Warning ``Duplicate found in Network Message Cache``? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ When the node receives a message, it will compare the message with the ones stored in the network cache. If the same has been found in the cache, which means it has been received before, then the message will be dropped. -5.3 What is the meaning of warning :code:`Incomplete timer expired`? +5.3 What Is the Meaning of Warning ``Incomplete timer expired``? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - When the node doesn't receive all the segments of a segmented message during a certain period (e.g. 10 seconds), then the Incomplete timer will expire and this warning will appear. + When the node does not receive all the segments of a segmented message during a certain period (e.g., 10 seconds), then the Incomplete timer will expire and this warning will appear. -5.4 What is the meaning of warning :code:`No matching TX context for ack`? +5.4 What Is the Meaning of Warning ``No matching TX context for ack``? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - When the node receives a segment ack and it doesn't find any self-send segmented message related with this ack, then this warning will appear. + When the node receives a segment ack and it does not find any self-send segmented message related with this ack, then this warning will appear. -5.5 What is the meaning of warning :code:`No free slots for new incoming segmented messages`? +5.5 What Is the Meaning of Warning ``No free slots for new incoming segmented messages``? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ When the node has no space for receiving new segmented message, this warning will appear. Users can make the space larger through the configuration :ref:`CONFIG_BLE_MESH_RX_SEG_MSG_COUNT`. -5.6 What is the meaning of error :code:`Model not bound to Appkey 0x0000`？ +5.6 What Is the Meaning of Error ``Model not bound to Appkey 0x0000``? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ When the node sends messages with a model and the model has not been bound to the AppKey with AppKey Index 0x000, then this error will appear. -5.7 What is the meaning of error :code:`Busy sending message to DST xxxx`? +5.7 What Is the Meaning of Error ``Busy sending message to DST xxxx``? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ This error means client model of the node has transmitted a message to the target node and now is waiting for a response, users can not send messages to the same node with the same unicast address. After the corresponding response is received or timer is expired, then another message can be sent. @@ -627,7 +627,7 @@ You can find meaning of errors or warnings when they appear at the bottom of ESP 6. Example Help --------------- -6.1 How are the ESP-BLE-MESH callback functions classified? +6.1 How Are the ESP-BLE-MESH Callback Functions Classified? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - The API :cpp:func:`esp_ble_mesh_register_prov_callback` is used to register callback function used to handle provisioning and networking related events. @@ -647,22 +647,22 @@ You can find meaning of errors or warnings when they appear at the bottom of ESP 7. Others --------- -7.1 How to print the message context? +7.1 How to Print the Message Context? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The examples use :cpp:func:`ESP_LOG_BUFFER_HEX` to print the message context while the ESP-BLE-MESH protocol stack uses :cpp:func:`bt_hex`. -7.2 Which API can be used to restart {IDF_TARGET_NAME}? +7.2 Which API Can Be Used to Restart {IDF_TARGET_NAME}? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The API :cpp:func:`esp_restart`. -7.3 How to monitor the remaining space of the stack of a task? +7.3 How to Monitor the Remaining Space of the Stack of a Task? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The API :cpp:func:`vTaskList` can be used to print the remaining space of the task stack periodically. -7.4 How to change the level of log without changing the menuconfig output level? +7.4 How to Change the Level of Log Without Changing the Menuconfig Output Level? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The API :cpp:func:`esp_log_level_set` can be used to change the log output level rather than using menuconfig to change it. diff --git a/docs/en/api-guides/esp-ble-mesh/ble-mesh-feature-list.rst b/docs/en/api-guides/esp-ble-mesh/ble-mesh-feature-list.rst index 017af20fa4..28739f7407 100644 --- a/docs/en/api-guides/esp-ble-mesh/ble-mesh-feature-list.rst +++ b/docs/en/api-guides/esp-ble-mesh/ble-mesh-feature-list.rst @@ -1,5 +1,7 @@ -ESP-BLE-MESH Feature List -========================= +Feature List +============= + +:link_to_translation:`zh_CN:[中文]` Supported Features ------------------ @@ -7,11 +9,7 @@ Supported Features Mesh Core """"""""" -* Provisioning: Node Role - * PB-ADV and PB-GATT - * OOB Authentication - -* Provisioning: Provisioner Role +* Provisioning: * PB-ADV and PB-GATT * OOB Authentication @@ -109,8 +107,8 @@ Mesh Models * Light LC Server * Light LC Setup Server -Mesh Applications -""""""""""""""""" +Mesh Examples +""""""""""""" * ESP-BLE-MESH Node * :example_file:`Tutorial ` @@ -130,18 +128,3 @@ Mesh Applications * `Demo Video `__ * ESP-BLE-MESH Console Commands * :example:`Example ` - - -Future Release Features ------------------------ - -Mesh Core -""""""""" - -* Provisioner NVS Storage - -Mesh Applications -""""""""""""""""" - -* Fast OTA -* Friendship diff --git a/docs/en/api-guides/esp-ble-mesh/ble-mesh-index.rst b/docs/en/api-guides/esp-ble-mesh/ble-mesh-index.rst index 58c66ccdeb..8ba88273ac 100644 --- a/docs/en/api-guides/esp-ble-mesh/ble-mesh-index.rst +++ b/docs/en/api-guides/esp-ble-mesh/ble-mesh-index.rst @@ -17,7 +17,7 @@ Please see the :doc:`ble-mesh-architecture` for information about the implementa ESP-BLE-MESH is implemented and certified based on the latest Mesh Profile v1.0.1, users can refer `here `_ for the certification details of ESP-BLE-MESH. .. only:: SOC_WIFI_MESH_SUPPORT - + .. note:: If you are looking for Wi-Fi based implementation of mesh for {IDF_TARGET_NAME}, please check another product by Espressif called ESP-WIFI-MESH. For more information and documentation see :doc:`ESP-WIFI-MESH <../../api-reference/network/esp-wifi-mesh>`. @@ -25,8 +25,8 @@ ESP-BLE-MESH is implemented and certified based on the latest Mesh Profile v1.0. .. _getting-started-with-ble-mesh: -Getting Started with ESP-BLE-MESH -================================= +Getting Started +================= This section is intended to help you get started with ESP-BLE-MESH for the hardware based on the {IDF_TARGET_NAME} chip by Espressif. @@ -107,7 +107,7 @@ The Scanner is App's functionality to search for unprovisioned devices in range. 4.2 Identify ^^^^^^^^^^^^ -Users can select any unprovisioned device, then the App will try to set up a connection with the selected device. After the BLE connection is established successfully (sometimes users need to try multiple times to get connected), and proper ESP-BLE-MESH GATT Service is discovered, users can see the **IDENTIFY** interface button on the screen. The IDENTIFY operation can be used to tell users which device is going to be provisioned. +Users can select any unprovisioned device, then the App will try to set up a connection with the selected device. After the Bluetooth LE connection is established successfully (sometimes users need to try multiple times to get connected), and proper ESP-BLE-MESH GATT Service is discovered, users can see the **IDENTIFY** interface button on the screen. The IDENTIFY operation can be used to tell users which device is going to be provisioned. .. note:: The IDENTIFY operation also needs some cooperation on the device side, then users can see which device is in the provisioning process. Currently when pressing the **IDENTIFY** interface button, no signs can been seen from the device except from the log on the serial monitor. @@ -210,8 +210,8 @@ The following screenshot shows different board with different color on. .. _esp-ble-mesh-examples: -ESP-BLE-MESH Examples -===================== +Examples +========= * :example_file:`ESP-BLE-MESH Node OnOff Server ` - shows the use of ESP-BLE-MESH as a node having a Configuration Server model and a Generic OnOff Server model. A ESP-BLE-MESH Provisioner can then provision the unprovisioned device and control a RGB LED representing on/off state, see :example:`example code `. @@ -228,15 +228,15 @@ ESP-BLE-MESH Examples .. _esp-ble-mesh-demo-videos: -ESP-BLE-MESH Demo Videos -======================== +Demo Videos +============ * `Espressif Fast Provisioning using ESP-BLE-MESH App `_ * `Espressif ESP-BLE-MESH and Wi-Fi Coexistence `_ -ESP-BLE-MESH FAQ -================ +FAQ +==== * :ref:`ble-mesh-faq-provisioner-development` * :ref:`ble-mesh-faq-node-development` diff --git a/docs/en/api-guides/esp-ble-mesh/ble-mesh-terminology.rst b/docs/en/api-guides/esp-ble-mesh/ble-mesh-terminology.rst index 263fabca78..675a195434 100644 --- a/docs/en/api-guides/esp-ble-mesh/ble-mesh-terminology.rst +++ b/docs/en/api-guides/esp-ble-mesh/ble-mesh-terminology.rst @@ -1,5 +1,5 @@ -ESP-BLE-MESH Terminology -======================== +Terminology +============ :link_to_translation:`zh_CN:[中文]` @@ -14,16 +14,16 @@ ESP-BLE-MESH Terminology - Detailed Explanation * - Unprovisioned Device - A device that is not a member of a mesh network is known as an unprovisioned device. - - Examples: lighting devices, temperature control devices, manufacturing equipments and electric doors, etc. + - Examples: lighting devices, temperature control devices, manufacturing equipment and electric doors, etc. * - Node - A node is a provisioned device. - - The role of unprovisioned device will change to node after being provisioned to ESP-BLE-MESH network. Nodes (such as lighting devices, temperature control devices, manufacturing equipments, and electric doors) are devices that can send, receive, or relay messages in ESP-BLE-MESH network, and they can optionally support one or more subnets. + - The role of unprovisioned device will change to node after being provisioned to ESP-BLE-MESH network. Nodes (such as lighting devices, temperature control devices, manufacturing equipment, and electric doors) are devices that can send, receive, or relay messages in ESP-BLE-MESH network, and they can optionally support one or more subnets. * - Relay Node - A node that supports the Relay feature and has the Relay feature enabled is known as a Relay node. - Relay nodes can receive and resend ESP-BLE-MESH messages, so the messages can be transferred further. Users can decide whether or not to enable forwarding function of nodes according to nodes' status. Messages can be relayed for multiple times, and each relay is considered as a "hop". Messages can hop up to 126 times, which is enough for message transmission in a wide area. * - Proxy Node - A node that supports the Proxy feature and has the Proxy feature enabled is known as a Proxy node. - - Proxy nodes receive messages from one bearer (it generally includes advertising bearer and GATT bearer) and resend it from another one. The purpose is to connect communication equipments that only support GATT bearer to ESP-BLE-MESH network. Generally, mobile apps need a Proxy node to access Mesh network. Without Proxy nodes, mobile apps cannot communicate with members in Mesh network. + - Proxy nodes receive messages from one bearer (it generally includes advertising bearer and GATT bearer) and resend it from another one. The purpose is to connect communication equipment that only support GATT bearer to ESP-BLE-MESH network. Generally, mobile apps need a Proxy node to access Mesh network. Without Proxy nodes, mobile apps cannot communicate with members in Mesh network. * - Friend Node - A node that supports the Friend feature, has the Friend feature enabled, and has a friendship with a node that supports the Low Power feature is known as a Friend node. - Friend node, like the backup of Low Power node (LPN), can store messages that are sent to Low Power node and security updates; the stored information will be transferred to Low Power node when Low Power node needs it. Low Power node must establish "friendship" with another node that supports the Friend Feature to reduce duty cycle of its receiver, thus power consumption of Low Power node can be reduced. Low Power node needs to find a Friend node to establish a friendship with it. The process involved is called "friendship establishment". Cooperation between Low Power node and Friend nodes enables Low Power node to schedule the use of the radio, thus Low Power node can receive messages at an appropriate or lower frequency without the need of keeping listening. Low Power node will poll Friend node to see if there is new message. @@ -150,7 +150,7 @@ ESP-BLE-MESH Terminology - Detailed Explanation * - Device Key (DevKey) - There is also a device key, which is a special application key that is unique to each node, is known only to the node and a Configuration Client, and is used to secure communications between the node and a Configuration Client. - - The device key enables you to provision the devices, configure the nodes. The device key is used to encrypt Configuration Messages, i.e. the message transferred between the Provisioner and the node when the device is configured. + - The device key enables you to provision the devices, configure the nodes. The device key is used to encrypt Configuration Messages, i.e., the message transferred between the Provisioner and the node when the device is configured. * - Application Key (AppKey) - Application keys are used to secure communications at the upper transport layer. - Application key is used for decryption of application data before delivering application data to application layer and encryption of them during the delivery of application layer. Some nodes in the network have a specific purpose and can restrict access to potentially sensitive data based on the needs of the application. With specific application keys, these nodes are associated with specific applications. Generally speaking, the fields using different application keys include security (access control of buildings, machine rooms and CEO offices), lighting (plant, exterior building and sidewalks) and HVAC systems. Application keys are bound to Network keys. This means application keys are only used in a context of a Network key they are bound to. An application key shall only be bound to a single Network key. @@ -168,10 +168,10 @@ ESP-BLE-MESH Terminology * - Term - Official Definition - Detailed Explanation - * - Reassembly / Segmentation + * - Reassembly/Segmentation - Segmentation and reassembly (SAR) is a method of communication network, which is divided into small units before transmitting packets and reassembled in a proper order at the communication receiving end. - The lower transport layer will automatically segment the message whose size is too big. The receiving end will return a response message, and the transmitting end will send the data packet again that the receiving end does not receive according to the response message. This is automatically completed by the lower transport layer. Unsegmented messages have at most 15 bytes, of which 4 bytes are transMIC, so the remaining is 11 bytes; in the case of segmentation, there are 12 valid bytes in the first several packets, and 8 in the last one. Special case: A shorter packet requires mandatory segmentation from lower transport layer, in which case the valid byte is 8 bytes. - * - Unacknowledged / Acknowledged + * - Unacknowledged/Acknowledged - There are two types of messages: Unacknowledged or Acknowledged - Based on the whether or not the receiving end needs to send the response message, the messages sent are divided into two kinds. The sending end should set the maximum number of retransmission. @@ -211,11 +211,8 @@ ESP-BLE-MESH Terminology * - Key Refresh procedure - This procedure is used when the security of one or more network keys and/or one or more of the application keys has been compromised or could be compromised. - Key Refresh Procedure is used to update network key and application key of ESP-BLE-MESH network. Key Refresh Procedure is used when the security of one or more network keys and/or one or more application keys is threatened or potentially threatened. Keys are usually updated after some nodes in the network are removed. - * - IV (Initialisation Vector) Update Procedure + * - IV (Initialization Vector) Update Procedure - A node can also use an IV Update procedure to signal to peer nodes that it is updating the IV Index. - The IV Update procedure is used to update the value of ESP-BLE-MESH network's IV Index. This value is related to the random number required for message encryption. To ensure that the value of the random number is not repeated, this value is periodically incremented. IV Index is a 32-bit value and a shared network resource. For example, all nodes in a mesh network share the same IV Index value. Starting from 0x00000000, the IV Index increments during the IV Update procedure and maintained by a specific process, ensuring the IV Index shared in the mesh network is the same. This can be done when the node believes that it has the risk of exhausting its sequence number, or when it determines that another node is nearly exhausting its sequence number. Note: The update time must not be less than 96 hours. It can be triggered when a secure network beacon is received, or when the node determines that its sequence number is greater than a certain value. For more terms, please see: `ESP-BLE-MESH Glossary of Terms `_. - - - diff --git a/docs/en/api-guides/index.rst b/docs/en/api-guides/index.rst index bc679d9eaf..f88d0c82bf 100644 --- a/docs/en/api-guides/index.rst +++ b/docs/en/api-guides/index.rst @@ -7,7 +7,9 @@ API Guides app_trace startup - :SOC_BLUFI_SUPPORTED: blufi + :SOC_BT_CLASSIC_SUPPORTED: classic-bt/index + :SOC_BLE_SUPPORTED: ble/index + :SOC_BLE_MESH_SUPPORTED: esp-ble-mesh/ble-mesh-index bootloader build-system :SOC_SUPPORT_COEXISTENCE: coexist @@ -16,7 +18,6 @@ API Guides :SOC_RTC_MEM_SUPPORTED: deep-sleep-stub :SOC_USB_OTG_SUPPORTED: dfu error-handling - :SOC_BLE_MESH_SUPPORTED: esp-ble-mesh/ble-mesh-index :SOC_WIFI_MESH_SUPPORT: esp-wifi-mesh :SOC_SPIRAM_SUPPORTED: external-ram fatal-errors diff --git a/docs/zh_CN/api-guides/ble/ble-feature-support-status.rst b/docs/zh_CN/api-guides/ble/ble-feature-support-status.rst new file mode 100644 index 0000000000..72e3544554 --- /dev/null +++ b/docs/zh_CN/api-guides/ble/ble-feature-support-status.rst @@ -0,0 +1,338 @@ +主要功能支持状态 +================ + +:link_to_translation:`en:[English]` + +本文档介绍了乐鑫低功耗蓝牙模块主要功能在 {IDF_TARGET_NAME} 上的支持状态。 + +|supported_def| **该功能已完成开发和内部测试。** [1]_ + +|experimental_def| **该功能已完成开发，正在进行内部测试。** +你可以探索这些功能以进行评估和反馈，但应注意可能出现的问题。 + +|developing_def| **该功能目前正在积极开发中， 预计在 YYYY/MM 月底之前支持。** +请关注此表以获得该功能的最新进展。 +如果确实有紧急的开发需求，请联系 `乐鑫客户支持团队 `__ 以了解是否可以进行功能试用。 + +|unsupported_def| **该功能在此芯片上不支持。** 如果你有相关需求，请优先选择其他支持该功能的乐鑫芯片系列。 +如果当前的乐鑫产品都不支持此功能，请联系 `乐鑫客户支持团队 `__ ，我们的研发团队会对你的需求进行内部可行性评估。 + +|NA_def| 具有此标签的功能可能为以下两种类型： + - **Host-only 功能**：该功能仅存在于 HCI 层之上，例如 GATT Caching。此类功能不需要蓝牙控制器的支持。 + - **Controller-only 功能**：该功能仅存在于 HCI 层之下，且无法通过主机API配置或启用，例如 Advertising Channel Index 。此类功能不需要蓝牙主机的支持。 + +.. list-table:: + :width: 100% + :widths: auto + :header-rows: 1 + + * - .. centered:: 核心协议 + - .. centered:: 主要功能 + - .. centered:: ESP 控制器 + - .. centered:: ESP-Bluedroid 主机 + - .. centered:: ESP-NimBLE 主机 + * - .. centered:: |4.2| + - LE Data Packet Length Extension + - |supported| + - |supported| + - |supported| + * - + - LE Secure Connections + - |supported| + - |supported| + - |supported| + * - + - Link Layer Privacy + - |supported| + - |supported| + - |supported| + * - + - Link Layer Extended Filter Policies + - |supported| + - |supported| + - |supported| + * - .. centered:: |5.0| + - 2 Msym/s PHY for LE + - .. only:: esp32 + + |unsupported| + .. only:: not esp32 + + |supported| + - .. only:: esp32 + + |unsupported| + .. only:: not esp32 + + |supported| + - .. only:: esp32 + + |unsupported| + .. only:: not esp32 + + |supported| + * - + - LE Long Range (Coded PHY S=2/S=8) + - .. only:: esp32 + + |unsupported| + .. only:: not esp32 + + |supported| + - .. only:: esp32 + + |unsupported| + .. only:: not esp32 + + |supported| + - .. only:: esp32 + + |unsupported| + .. only:: not esp32 + + |supported| + * - + - High Duty Cycle Non-Connectable Advertising + - .. only:: esp32 + + |unsupported| + .. only:: not esp32 + + |supported| + - .. only:: esp32 + + |unsupported| + .. only:: not esp32 + + |supported| + - .. only:: esp32 + + |unsupported| + .. only:: not esp32 + + |supported| + * - + - LE Advertising Extensions + - .. only:: esp32 + + |unsupported| + .. only:: not esp32 + + |supported| + - .. only:: esp32 + + |unsupported| + .. only:: not esp32 + + |supported| + - .. only:: esp32 + + |unsupported| + .. only:: not esp32 + + |supported| + * - + - LE Channel Selection Algorithm #2 + - .. only:: esp32 + + |unsupported| + .. only:: not esp32 + + |supported| + - .. only:: esp32 + + |unsupported| + .. only:: not esp32 + + |supported| + - .. only:: esp32 + + |unsupported| + .. only:: not esp32 + + |supported| + * - .. centered:: |5.1| + - Angle of Arrival (AoA)/Angle of Departure (AoD) + - |unsupported| + - |unsupported| + - |unsupported| + * - + - GATT Caching + - |NA| + - |experimental| + - |experimental| + * - + - Advertising Channel Index + - |unsupported| + - |NA| + - |NA| + * - + - Periodic Advertising Sync Transfer + - .. only:: esp32 or esp32c3 or esp32s3 + + |unsupported| + .. only:: esp32c6 or esp32h2 or esp32c2 or esp32c5 + + |experimental| + - .. only:: esp32 or esp32c3 or esp32s3 + + |unsupported| + .. only:: esp32c6 or esp32h2 or esp32c2 or esp32c5 + + |experimental| + - .. only:: esp32 or esp32c3 or esp32s3 + + |unsupported| + .. only:: esp32c6 or esp32h2 or esp32c2 or esp32c5 + + |experimental| + * - .. centered:: |5.2| + - LE Isochronous Channels (BIS/CIS) + - |unsupported| + - |unsupported| + - |unsupported| + * - + - Enhanced Attribute Protocol + - |NA| + - |unsupported| + - |developing202412| + * - + - LE Power Control + - .. only:: esp32 or esp32c2 + + |unsupported| + .. only:: esp32c6 or esp32h2 or esp32c3 or esp32s3 or esp32c5 + + |experimental| + - |unsupported| + - .. only:: esp32 or esp32c2 + + |unsupported| + .. only:: esp32c6 or esp32h2 or esp32c3 or esp32s3 or esp32c5 + + |developing202412| + * - .. centered:: |5.3| + - AdvDataInfo in Periodic Advertising + - .. only:: esp32 or esp32c3 or esp32s3 + + |unsupported| + .. only:: esp32c6 or esp32c2 or esp32h2 or esp32c5 + + |supported| + - .. only:: esp32 or esp32c3 or esp32s3 + + |unsupported| + .. only:: esp32c6 or esp32c2 or esp32h2 or esp32c5 + + |supported| + - .. only:: esp32 or esp32c3 or esp32s3 + + |unsupported| + .. only:: esp32c6 or esp32c2 or esp32h2 or esp32c5 + + |supported| + * - + - LE Enhanced Connection Update (Connection Subrating) + - .. only:: esp32 or esp32c6 or esp32c2 or esp32h2 or esp32c5 + + |unsupported| + .. only:: esp32c3 or esp32s3 + + |experimental| + - |unsupported| + - .. only:: esp32 or esp32c6 or esp32c2 or esp32h2 or esp32c5 + + |unsupported| + .. only:: esp32c3 or esp32s3 + + |experimental| + * - + - LE Channel Classification + - .. only:: esp32 or esp32c3 or esp32s3 or esp32c2 + + |unsupported| + .. only:: esp32c6 or esp32h2 or esp32c5 + + |experimental| + - .. only:: esp32 or esp32c3 or esp32s3 or esp32c2 + + |unsupported| + .. only:: esp32c6 or esp32h2 or esp32c5 + + |experimental| + - .. only:: esp32 or esp32c3 or esp32s3 or esp32c2 + + |unsupported| + .. only:: esp32c6 or esp32h2 or esp32c5 + + |experimental| + * - .. centered:: |5.4| + - Advertising Coding Selection + - .. only:: esp32 or esp32c6 or esp32c2 or esp32h2 or esp32c5 + + |unsupported| + .. only:: esp32c3 or esp32s3 + + |experimental| + - |unsupported| + - .. only:: esp32 or esp32c6 or esp32c2 or esp32h2 or esp32c5 + + |unsupported| + .. only:: esp32c3 or esp32s3 + + |experimental| + * - + - Encrypted Advertising Data + - |NA| + - |unsupported| + - |experimental| + * - + - LE GATT Security Levels Characteristic + - |NA| + - |unsupported| + - |developing202412| + * - + - Periodic Advertising with Responses + - |unsupported| + - |unsupported| + - |unsupported| + +.. [1] + 如果想了解支持功能的 Bluetooth SIG 认证状态， + 请查阅 `SIG 蓝牙产品数据库 `__ 。 + +对于大部分开发需要在控制器 (Controller) 完成的功能，其主机层 (Host) 的支持状态将会受限于控制器层的支持状态。 +如果你计划将乐鑫低功耗蓝牙控制器和主机跑在不同的乐鑫芯片上，则主机的功能将不再受限于这颗跑主机的芯片上的控制器的功能支持状态， +请参阅 :doc:`ESP 主机主要功能支持状态 ` 。 + +请注意，本文档不构成对客户的约束性承诺。 +以上所列出来的功能支持状态信息仅供参考，可能会在不通知的情况下发生更改。 +建议联系 `乐鑫客户支持团队 `__ 以获取最新信息，并确认功能是否适合你的特定需求。 + + +.. |supported| image:: ../../../_static/ble/feature_status/supported.svg + :class: align-center + :width: 65px +.. |developing202412| image:: ../../../_static/ble/feature_status/developing202412.svg + :class: align-center + :width: 120px +.. |unsupported| image:: ../../../_static/ble/feature_status/unsupported.svg + :class: align-center + :width: 75px +.. |experimental| image:: ../../../_static/ble/feature_status/experimental.svg + :class: align-center + :width: 75px +.. |NA| image:: ../../../_static/ble/feature_status/NA.svg + :class: align-center + :width: 25px +.. |supported_def| image:: ../../../_static/ble/feature_status/supported.svg +.. |developing_def| image:: ../../../_static/ble/feature_status/developingYYYYMM.svg +.. |unsupported_def| image:: ../../../_static/ble/feature_status/unsupported.svg +.. |experimental_def| image:: ../../../_static/ble/feature_status/experimental.svg +.. |NA_def| image:: ../../../_static/ble/feature_status/NA.svg +.. |4.2| replace:: `4.2 `__ +.. |5.0| replace:: `5.0 `__ +.. |5.1| replace:: `5.1 `__ +.. |5.2| replace:: `5.2 `__ +.. |5.3| replace:: `5.3 `__ +.. |5.4| replace:: `5.4 `__ diff --git a/docs/zh_CN/api-guides/blufi.rst b/docs/zh_CN/api-guides/ble/blufi.rst similarity index 85% rename from docs/zh_CN/api-guides/blufi.rst rename to docs/zh_CN/api-guides/ble/blufi.rst index e0374a5db8..33737b6298 100644 --- a/docs/zh_CN/api-guides/blufi.rst +++ b/docs/zh_CN/api-guides/ble/blufi.rst @@ -1,9 +1,10 @@ BluFi -^^^^^ +^^^^^^ + :link_to_translation:`en:[English]` 概览 ------ +-------- BluFi 是一项基于蓝牙通道的 Wi-Fi 网络配置功能，适用于 {IDF_TARGET_NAME}。它通过安全协议将 Wi-Fi 的 SSID、密码等配置信息传输到 {IDF_TARGET_NAME}。基于这些信息，{IDF_TARGET_NAME} 可进而连接到 AP 或建立 SoftAP。 @@ -12,19 +13,19 @@ BluFi 流程的关键部分包括数据的分片、加密以及校验和验证 用户可按需自定义用于对称加密、非对称加密以及校验的算法。此处，我们采用 DH 算法进行密钥协商，128-AES 算法用于数据加密，CRC16 算法用于校验和验证。 BluFi 流程 ----------- +----------- BluFi 配网流程包含配置 SoftAP 和配置 Station 两部分。 下面以配置 Station 为例，介绍了广播、连接、服务发现、协商共享密钥、传输数据、回传连接状态等关键步骤。 -1. {IDF_TARGET_NAME} 开启 GATT Server 模式，发送带有特定 *advertising data* 的广播。该广播不属于 BluFi Profile，您可以按需对其进行自定义。 +1. {IDF_TARGET_NAME} 开启 GATT Server 模式，发送带有特定 *advertising data* 的广播。该广播不属于 BluFi Profile，可以按需对其进行自定义。 2. 使用手机应用程序搜索到该广播后，手机将作为 GATT Client 连接 {IDF_TARGET_NAME}。该步骤对具体使用哪款手机应用程序并无特殊要求。 3. 成功建立 GATT 连接后，手机会向 {IDF_TARGET_NAME} 发送数据帧进行密钥协商（详见 :ref:`frame_formats` ）。 -4. {IDF_TARGET_NAME} 收到密钥协商的数据帧后，会按照您自定义的协商方法进行解析。 +4. {IDF_TARGET_NAME} 收到密钥协商的数据帧后，会按照自定义的协商方法进行解析。 5. 手机与 {IDF_TARGET_NAME} 进行密钥协商。协商过程可使用 DH/RSA/ECC 等加密算法。 @@ -45,7 +46,7 @@ BluFi 配网流程包含配置 SoftAP 和配置 Station 两部分。 2. 进行对称加密和解密时，加密和解密前后的数据长度必须一致。支持原地加密和解密。 BluFi 流程图 ---------------- +------------ .. seqdiag:: :caption: BluFi Flow Chart @@ -74,22 +75,22 @@ BluFi 流程图 .. _frame_formats: BluFi 中定义的帧格式 ----------------------------- +--------------------- 手机应用程序与 {IDF_TARGET_NAME} 之间的 BluFi 通信格式定义如下： 帧不分片格式： -.. list-table:: - :header-rows: 1 - :widths: 25 25 - +.. list-table:: + :header-rows: 1 + :widths: 25 25 + * - 字段 - 值（字节） * - 类型（最低有效位） - 1 * - 帧控制 - - 1 + - 1 * - 序列号 - 1 * - 数据长度 @@ -103,50 +104,50 @@ BluFi 中定义的帧格式 帧分片格式： -.. list-table:: - :header-rows: 1 - :widths: 25 25 - +.. list-table:: + :header-rows: 1 + :widths: 25 25 + * - 字段 - 值（字节） * - 类型（最低有效位） - - 1 + - 1 * - 帧控制（分片） - - 1 + - 1 * - 序列号 - - 1 + - 1 * - 数据长度 - - 1 + - 1 * - 数据 - * 内容总长度：2 - * 数据内容长度：${Data Length} - 2 + * 数据内容长度：${Data Length} - 2 * - 校验（最高有效位） - - 2 + - 2 通常情况下，控制帧不包含数据位，ACK 帧类型除外。 -ACK 帧格式（8 bit）： +ACK 帧格式 (8 bit)： + +.. list-table:: + :header-rows: 1 + :widths: 25 25 -.. list-table:: - :header-rows: 1 - :widths: 25 25 - * - 字段 - 值（字节） * - 类型 - ACK（最低有效位） - - 1 + - 1 * - 帧控制 - - 1 + - 1 * - 序列号 - - 1 + - 1 * - 数据长度 - - 1 + - 1 * - 数据 - - ACK 序列号: 2 + - ACK 序列号: 2 * - 校验（最高有效位） - - 2 + - 2 + - 1. 类型字段 **类型** 字段占 1 字节，分为 **类型** 和 **子类型** 两部分。其中，**类型** 占低 2 位，表明该帧为数据帧或是控制帧；**子类型** 占高 6 位，表示此数据帧或者控制帧的具体含义。 @@ -157,74 +158,74 @@ ACK 帧格式（8 bit）： 1.1 控制帧（二进制：0x0 b’00） -.. list-table:: - :header-rows: 1 - :widths: 5 15 20 30 - +.. list-table:: + :header-rows: 1 + :widths: 5 15 20 30 + * - 控制帧 - 含义 - 解释 - - 备注 + - 备注 * - 0x0 (b’000000) - ACK - ACK 帧的数据字段使用回复对象帧的序列值。 - 数据字段占用 1 字节，其序列值与回复对象帧的序列值相同。 - + * - 0x1 (b’000001) - 将 ESP 设备设置为安全模式。 - - 通知 ESP 设备发送数据时使用的安全模式，在数据发送过程中可多次重置。设置后，将影响后续使用的安全模式。 - + - 通知 ESP 设备发送数据时使用的安全模式，在数据发送过程中可多次重置。设置后，将影响后续使用的安全模式。 + 如果不设置，ESP 设备将默认发送不带校验和加密的控制帧和数据帧。从手机到 ESP 设备的数据传输是由这个控制帧控制的。 - 数据字段占一个字节。高 4 位用于控制帧的安全模式设置，低 4 位用于数据帧的安全模式设置。 * b’0000：无校验、无加密； * b’0001：有校验、无加密； - * b’0010：无校验、有加密； + * b’0010：无校验、有加密； * b’0011：有校验、有加密。 - + * - 0x2 (b’000010) - 设置 Wi-Fi 的 opmode。 - 该帧包含设置 ESP 设备 Wi-Fi 模式 (opmode) 的设置信息。 - - data[0] 用于设置 opmode，包括： + - data[0] 用于设置 opmode，包括： - * 0x00: NULL - * 0x01: STA - * 0x02: SoftAP - * 0x03: SoftAP & STA + * 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]，依次类推。 - + - + - data[0~5] 为 STA 设备的 MAC 地址。如有多个 STA 设备，则第二个使用 data[6-11]，依次类推。 + * - 0x7 (b’000111) - 获取版本信息。 - - - - + - + - * - 0x8 (b’001000) - 断开 BLE GATT 连接。 - - - - ESP 设备收到该指令后主动断开 BLE GATT 连接。 + - + - ESP 设备收到该指令后主动断开 BLE GATT 连接。 * - 0x9 (b’001001) - 获取 Wi-Fi 列表。 @@ -233,47 +234,47 @@ ACK 帧格式（8 bit）： -1.2 数据帧 (二进制：0x1 b’01) +1.2 数据帧（二进制：0x1 b’01） + +.. list-table:: + :header-rows: 1 + :widths: 5 15 20 30 -.. list-table:: - :header-rows: 1 - :widths: 5 15 20 30 - * - 数据帧 - 含义 - 解释 - - 备注 + - 备注 * - 0x0 (b’000000) - 发送协商数据。 - 协商数据会发送到应用层注册的回调函数中。 - - 数据的长度取决于数据长度字段。 + - 数据的长度取决于数据长度字段。 * - 0x1 (b’000001) - 发送 STA 模式的 BSSID。 - - 在 SSID 隐藏的情况下，发送 STA 设备要连接的 AP 的 BSSID。 + - 在 SSID 隐藏的情况下，发送 STA 设备要连接的 AP 的 BSSID。 - 请参考备注 1。 * - 0x2 (b’000010) - 发送 STA 模式的 SSID - - 发送 STA 设备要连接的 AP 的 SSID。 - - 请参考备注 1。 + - 发送 STA 设备要连接的 AP 的 SSID。 + - 请参考备注 1。 * - 0x3 (b’000011) - 发送 STA 模式的密码。 - - 发送 STA 设备要连接的 AP 的密码。 - - 请参考备注 1。 + - 发送 STA 设备要连接的 AP 的密码。 + - 请参考备注 1。 * - 0x4 (b’000100) - 发送 SoftAP 模式的 SSID。 - - - - 请参考备注 1。 + - + - 请参考备注 1。 * - 0x5 (b’000101) - 发送 SoftAPmode 模式的密码。 - - - - 请参考备注 1。 + - + - 请参考备注 1。 * - 0x6 (b’000110) - 设置 SoftAPmode 模式的最大连接数。 - - - - data[0] 为连接数的值，范围从 1 到 4。当传输方向是 ESP 设备到手机时，表示向手机端提供所需信息。 + - + - data[0] 为连接数的值，范围从 1 到 4。当传输方向是 ESP 设备到手机时，表示向手机端提供所需信息。 * - 0x7 (b’000111) - 设置 SoftAP 的认证模式。 - - + - - data[0] 包括： * 0x00: OPEN @@ -282,11 +283,11 @@ ACK 帧格式（8 bit）： * 0x03: WPA2_PSK * 0x04: WPA_WPA2_PSK - 若传输方向是从 ESP 设备到手机，则表示向手机端提供所需信息。 + 若传输方向是从 ESP 设备到手机，则表示向手机端提供所需信息。 * - 0x8 (b’001000) - 设置 SoftAP 模式的通道数量。 - - - - data[0] 代表支持的通道的数量，范围从 1 到 14。若传输方向是从 ESP 设备到手机，则表示向手机端提供所需信息。 + - + - data[0] 代表支持的通道的数量，范围从 1 到 14。若传输方向是从 ESP 设备到手机，则表示向手机端提供所需信息。 * - 0x9 (b’001001) - 用户名 - 在进行企业级加密时提供 GATT 客户端的用户名。 @@ -298,19 +299,19 @@ ACK 帧格式（8 bit）： * - 0xb (b’001011) - 客户端认证 - 在进行企业级加密时提供客户端认证。是否包含私钥，取决于认证的内容。 - - 请参考备注 2。 + - 请参考备注 2。 * - 0xc (b’001100) - 服务端认证 - 在进行企业级加密时提供服务端认证。是否包含私钥，取决于认证的内容。 - - 请参考备注 2。 + - 请参考备注 2。 * - 0xd (b’001101) - 客户端私钥 - 在进行企业级加密时提供客户端私钥。 - - 请参考备注 2。 + - 请参考备注 2。 * - 0xe (b’001110) - 服务端私钥 - 在进行企业级加密时提供服务端私钥。 - - 请参考备注 2。 + - 请参考备注 2。 * - 0xf (b’001111) - Wi-Fi 连接状态报告 - 通知手机 ESP 设备的 Wi-Fi 状态，包括 STA 状态和 SoftAP 状态。用于 STA 设备连接手机或 SoftAP。但是，当手机接收到 Wi-Fi 状态时，除了本帧之外，还可以回复其他帧。 @@ -325,12 +326,12 @@ ACK 帧格式（8 bit）： data[2]：SoftAP 的连接状态，即表示有多少 STA 设备已经连接。 - data[3]及后面的数据是按照 SSID/BSSID 格式提供的信息。 如果 Wi-Fi 处于正在连接状态，这里将会包含最大重连次数；如果 Wi-Fi 处于非连接状态，这里将会包含 Wi-Fi 断开连接原因和 RSSI 信息。 + data[3]及后面的数据是按照 SSID/BSSID 格式提供的信息。 如果 Wi-Fi 处于正在连接状态，这里将会包含最大重连次数；如果 Wi-Fi 处于非连接状态，这里将会包含 Wi-Fi 断开连接原因和 RSSI 信息。 * - 0x10 (b’010000) - 版本 - - + - - * data[0]= 主版本 - * data[1]= 子版本 + * data[1]= 子版本 * - 0x11 (b’010001) - Wi-Fi 热点列表 - 将 Wi-Fi 热点列表发送给 ESP 设备 @@ -346,53 +347,53 @@ ACK 帧格式（8 bit）： * 0x05: dh malloc error * 0x06: dh param error * 0x07: read param error - * 0x08: make public error + * 0x08: make public error * 0x09: data format error * 0x0a: calculate MD5 error * 0x0b: Wi-Fi scan error * - 0x13 (b’010011) - 自定义数据 - 用户发送或者接收自定义数据。 - - 数据较长时可分片发送。 + - 数据较长时可分片发送。 * - 0x14 (b’010100) - 设置最大 Wi-Fi 重连次数。 - - + - - data[0] 表示 Wi-Fi 最大重连次数。 * - 0x15 (b’010101) - 设置 Wi-Fi 连接失败原因。 - - + - - data[0] 表示 Wi-Fi 连接失败原因，它的类型应该和 `wifi_err_reason_t` 一致。 * - 0x16 (b’010110) - 设置 Wi-Fi 连接失败的 RSSI 。 - - + - - data[0] 表示在 Wi-Fi 连接失败时的 RSSI。 如果在连接结束时没有有意义的 RSSI ， 这个值应该为一个无意义值 `-128`。 .. note:: - 备注 1: 数据的长度取决于数据长度字段。若传输方向是从 ESP 设备到手机，则表示向手机端提供所需信息。 - - - 备注 2: 数据的长度取决于数据长度字段。如果数据长度不够，该帧可用分片。 + + - 备注 2: 数据的长度取决于数据长度字段。如果数据长度不够，该帧可用分片。 2. Frame Control 帧控制字段，占 1 字节，每个位表示不同含义。 -.. list-table:: - :header-rows: 1 - :widths: 10 35 +.. list-table:: + :header-rows: 1 + :widths: 10 35 * - 位 - - 含义 + - 含义 * - 0x01 - 表示帧是否加密。 * 1 表示加密。 * 0 表示未加密。 - 该帧的加密部分包括数据字段加密之前的完整明文数据（不包括校验部分）。控制帧暂不加密，故控制帧此位为 0。 + 该帧的加密部分包括数据字段加密之前的完整明文数据（不包括校验部分）。控制帧暂不加密，故控制帧此位为 0。 * - 0x02 - - 该数据字段表示帧尾是否包含校验位，如 SHA1、MD5、CRC 等。该数据字段包含序列、数据长度以及明文。控制帧和数据帧都可以选择包含或不包含校验位。 + - 该数据字段表示帧尾是否包含校验位，如 SHA1、MD5、CRC 等。该数据字段包含序列、数据长度以及明文。控制帧和数据帧都可以选择包含或不包含校验位。 * - 0x04 - 表示数据方向。 @@ -402,16 +403,16 @@ ACK 帧格式（8 bit）： - 表示是否要求对方回复 ACK。 * 0 表示不要求回复 ACK。 - * 1 表示要求回复 ACK。 + * 1 表示要求回复 ACK。 * - 0x10 - 表示是否有后续的数据分片。 * 0 表示此帧没有后续数据分片。 * 1 表示还有后续数据分片，用来传输较长的数据。 - - 对于分片帧，在数据字段的前两个字节中，会给定当前内容部分和随后内容部分的总长度（即最大支持 64 K 的数据内容）。 - * - 0x10~0x80 - - 保留 + + 对于分片帧，在数据字段的前两个字节中，会给定当前内容部分和随后内容部分的总长度（即最大支持 64 K 的数据内容）。 + * - 0x10~0x80 + - 保留 3. 序列控制 @@ -430,7 +431,7 @@ ACK 帧格式（8 bit）： 此字段占两个字节，用来校验序列、数据长度以及明文。 {IDF_TARGET_NAME} 端的安全实现 ----------------------------------- +----------------------------- 1. 数据安全 @@ -449,7 +450,7 @@ ACK 帧格式（8 bit）： 添加其到序列字段中，并且在数据校验过程中使用。 在 {IDF_TARGET_NAME} 端的代码中，你可以决定和开发如密钥协商等安全处理的流程。手机应用向 {IDF_TARGET_NAME} 发送协商数据，数据会传送给应用层处理。如果应用层不处理，可使用 BluFi 提供的 DH 加密算法来协商密钥。 - + 应用层需向 BluFi 注册以下几个与安全相关的函数： .. code-block:: c @@ -488,6 +489,6 @@ UUID BluFi Service UUID： 0xFFFF，16 bit -BluFi （手机 -> {IDF_TARGET_NAME}）特性：0xFF01，主要权限：可写 +BluFi（手机 > {IDF_TARGET_NAME}）特性：0xFF01，主要权限：可写 -BluFi （{IDF_TARGET_NAME} -> 手机）特性：0xFF02，主要权限：可读可通知 +BluFi（{IDF_TARGET_NAME} > 手机）特性：0xFF02，主要权限：可读可通知 diff --git a/docs/zh_CN/api-guides/ble/host-feature-support-status.rst b/docs/zh_CN/api-guides/ble/host-feature-support-status.rst new file mode 100644 index 0000000000..110fece669 --- /dev/null +++ b/docs/zh_CN/api-guides/ble/host-feature-support-status.rst @@ -0,0 +1,159 @@ +:orphan: + +ESP 主机主要功能支持状态 +======================== + +:link_to_translation:`en:[English]` + +本文档介绍了乐鑫低功耗蓝牙主机 ESP-Bluedroid 和 ESP-NimBLE 主要功能的支持状态。 +如果你计划将低功耗蓝牙控制器和主机跑在 {IDF_TARGET_NAME} 上，主机的功能支持可能会受限于控制器的功能支持状态， +请参阅 :doc:`{IDF_TARGET_NAME} 主要功能支持状态 ` 。 + +|supported_def| **该功能已完成开发和内部测试。** [1]_ + +|experimental_def| **该功能已完成开发，正在进行内部测试。** +你可以探索这些功能以进行评估和反馈，但应注意可能出现的问题。 + +|developing_def| **该功能目前正在积极开发中， 预计在 YYYY/MM 月底之前支持。** +请关注此表以获得该功能的最新进展。 +如果确实有紧急的开发需求，请联系 `乐鑫客户支持团队 `__ 以了解是否可以进行功能试用。 + +|unsupported_def| **该功能在该蓝牙主机上不支持。** 如果你有相关需求，请优先选择其他支持该功能的乐鑫蓝牙主机。 +如果当前的乐鑫产品都不支持此功能，请联系 `乐鑫客户支持团队 `__ ，我们的研发团队会对你的需求进行内部可行性评估。 + +|NA_def| 具有此标签的功能可能为以下类型： + - **Controller-only 功能**：该功能仅存在于 HCI 层之下，且无法通过主机API配置或启用，例如 Advertising Channel Index 。 + 此类功能不需要蓝牙主机的支持。 + +.. list-table:: + :width: 100% + :widths: auto + :header-rows: 1 + + * - .. centered:: 核心协议 + - .. centered:: 主要功能 + - .. centered:: ESP-Bluedroid 主机 + - .. centered:: ESP-NimBLE 主机 + * - .. centered:: |4.2| + - LE Data Packet Length Extension + - |supported| + - |supported| + * - + - LE Secure Connections + - |supported| + - |supported| + * - + - Link Layer Privacy + - |supported| + - |supported| + * - + - Link Layer Extended Filter Policies + - |supported| + - |supported| + * - .. centered:: |5.0| + - 2 Msym/s PHY for LE + - |supported| + - |supported| + * - + - LE Long Range (Coded PHY S=2/S=8) + - |supported| + - |supported| + * - + - High Duty Cycle Non-Connectable Advertising + - |supported| + - |supported| + * - + - LE Advertising Extensions + - |supported| + - |supported| + * - + - LE Channel Selection Algorithm #2 + - |supported| + - |supported| + * - .. centered:: |5.1| + - Angle of Arrival (AoA)/Angle of Departure (AoD) + - |unsupported| + - |developing202412| + * - + - GATT Caching + - |experimental| + - |experimental| + * - + - Advertising Channel Index + - |NA| + - |NA| + * - + - Periodic Advertising Sync Transfer + - |supported| + - |supported| + * - .. centered:: |5.2| + - LE Isochronous Channels (BIS/CIS) + - |unsupported| + - |developing202412| + * - + - Enhanced Attribute Protocol + - |unsupported| + - |developing202412| + * - + - LE Power Control + - |unsupported| + - |developing202412| + * - .. centered:: |5.3| + - AdvDataInfo in Periodic Advertising + - |supported| + - |supported| + * - + - LE Enhanced Connection Update (Connection Subrating) + - |unsupported| + - |supported| + * - + - LE Channel Classification + - |supported| + - |supported| + * - .. centered:: |5.4| + - Advertising Coding Selection + - |unsupported| + - |supported| + * - + - Encrypted Advertising Data + - |unsupported| + - |experimental| + * - + - LE GATT Security Levels Characteristic + - |unsupported| + - |developing202412| + * - + - Periodic Advertising with Responses + - |unsupported| + - |developing202412| + +.. [1] + 如果想了解支持功能的 Bluetooth SIG 认证状态， + 请查阅 `SIG 蓝牙产品数据库 `__ 。 + +请注意，本文档不构成对客户的约束性承诺。 +以上所列出来的功能支持状态信息仅供参考，可能会在不通知的情况下发生更改。 +建议联系 `乐鑫客户支持团队 `__ 以获取最新信息，并确认功能是否适合你的特定需求。 + + +.. |supported| image:: ../../../_static/ble/feature_status/supported.svg + :class: align-center +.. |developing202412| image:: ../../../_static/ble/feature_status/developing202412.svg + :class: align-center +.. |unsupported| image:: ../../../_static/ble/feature_status/unsupported.svg + :class: align-center +.. |experimental| image:: ../../../_static/ble/feature_status/experimental.svg + :class: align-center +.. |NA| image:: ../../../_static/ble/feature_status/NA.svg + :class: align-center +.. |supported_def| image:: ../../../_static/ble/feature_status/supported.svg +.. |developing_def| image:: ../../../_static/ble/feature_status/developingYYYYMM.svg +.. |unsupported_def| image:: ../../../_static/ble/feature_status/unsupported.svg +.. |experimental_def| image:: ../../../_static/ble/feature_status/experimental.svg +.. |NA_def| image:: ../../../_static/ble/feature_status/NA.svg +.. |4.2| replace:: `4.2 `__ +.. |5.0| replace:: `5.0 `__ +.. |5.1| replace:: `5.1 `__ +.. |5.2| replace:: `5.2 `__ +.. |5.3| replace:: `5.3 `__ +.. |5.4| replace:: `5.4 `__ diff --git a/docs/zh_CN/api-guides/ble/index.rst b/docs/zh_CN/api-guides/ble/index.rst new file mode 100644 index 0000000000..f3c9def151 --- /dev/null +++ b/docs/zh_CN/api-guides/ble/index.rst @@ -0,0 +1,24 @@ +################ +低功耗蓝牙® +################ + +:link_to_translation:`en:[English]` + +***** +概览 +***** +.. toctree:: + :maxdepth: 1 + + overview + ble-feature-support-status + +********** +蓝牙规范 +********** + +.. toctree:: + :maxdepth: 2 + + :SOC_BLE_MESH_SUPPORTED: ../esp-ble-mesh/ble-mesh-index + :SOC_BLUFI_SUPPORTED: blufi diff --git a/docs/zh_CN/api-guides/ble/overview.rst b/docs/zh_CN/api-guides/ble/overview.rst new file mode 100644 index 0000000000..62dbc36db0 --- /dev/null +++ b/docs/zh_CN/api-guides/ble/overview.rst @@ -0,0 +1,203 @@ +介绍 +======= + +:link_to_translation:`en:[English]` + +此文档概述了 ESP-IDF 中低功耗蓝牙协议栈的架构，并提供了一些相关文档和应用示例的快速链接。 + +.. only:: esp32 + + {IDF_TARGET_NAME} 支持双模蓝牙 4.2，并且已经获得双模蓝牙 4.2 认证和蓝牙 LE 5.0 认证 + +.. only:: esp32c3 or esp32s3 + + {IDF_TARGET_NAME} 支持蓝牙 5.0 (LE)，并且已经获得蓝牙 LE 5.4 认证。 + +.. only:: esp32c2 or esp32c6 or esp32h2 + + {IDF_TARGET_NAME} 支持蓝牙 5.0 (LE)，并且已经获得蓝牙 LE 5.3 认证。 + +ESP-IDF 中的低功耗蓝牙协议栈是一个分层架构，可在 {IDF_TARGET_NAME} 系列芯片上实现低功耗蓝牙功能，详见下。 + +.. only:: esp32 or esp32s3 or esp32c3 or esp32c6 + + .. figure:: ../../../_static/bluetooth-architecture.png + :align: center + :scale: 90% + :alt: {IDF_TARGET_NAME} 蓝牙协议栈架构 + + {IDF_TARGET_NAME} 蓝牙协议栈架构 + +.. only:: esp32c2 + + .. figure:: ../../../_static/bluetooth-architecture-no-ble-mesh.png + :align: center + :scale: 90% + :alt: {IDF_TARGET_NAME} 蓝牙协议栈架构 + + {IDF_TARGET_NAME} 蓝牙协议栈架构 + +.. only:: esp32h2 + + .. figure:: ../../../_static/bluetooth-architecture-no-blufi.png + :align: center + :scale: 90% + :alt: {IDF_TARGET_NAME} 蓝牙协议栈架构 + + {IDF_TARGET_NAME} 蓝牙协议栈架构 + +参考下表可知特定芯片是否支持低功耗蓝牙模块。 + +.. list-table:: + :width: 100% + :widths: auto + :header-rows: 1 + + * - 芯片系列 + - 控制器 + - ESP-Bluedroid + - ESP-NimBLE + - ESP-BLE-MESH + - BluFi + * - ESP32 + - Y + - Y + - Y + - Y + - Y + * - ESP32-S2 + - \– + - \– + - \– + - \– + - \– + * - ESP32-S3 + - Y + - Y + - Y + - Y + - Y + * - ESP32-C2 + - Y + - Y + - Y + - \– + - Y + * - ESP32-C3 + - Y + - Y + - Y + - Y + - Y + * - ESP32-C6 + - Y + - Y + - Y + - Y + - Y + * - ESP32-H2 + - Y + - Y + - Y + - Y + - \– + +以下各节简要介绍了每个层，并提供了相关文档和应用示例的快速链接。 + + +ESP 蓝牙控制器 +-------------- + +底层为 ESP 蓝牙控制器，包含 PHY、基带、链路控制器、链路管理器、设备管理器和 HCI 等各种模块。该层管理硬件接口和链路，以库的形式提供功能，并通过 API 访问，且直接与硬件和低级别蓝牙协议交互。 + +- :doc:`API 参考 <../../api-reference/bluetooth/controller_vhci>` +- :example:`应用示例 ` + + +ESP 蓝牙主机 +------------- + +有 ESP-Bluedroid 和 ESP-NimBLE 两个主机，其主要区别如下： + +- 虽然两者都支持低功耗蓝牙，但 ESP-NimBLE 需要的堆和 flash 空间更少。 + +.. only:: esp32 + + - ESP-Bluedroid 支持经典蓝牙和低功耗蓝牙，而 ESP-NimBLE 仅支持低功耗蓝牙。 + + +ESP-Bluedroid +^^^^^^^^^^^^^ + +ESP-Bluedroid 是原生 Android 蓝牙协议栈 Bluedroid 的修改版，由两层组成：蓝牙上层 (BTU) 和蓝牙传输控制器层 (BTC)。BTU 层负责处理 L2CAP、GATT/ATT、SMP、GAP 等底层蓝牙协议以及其他配置文件，提供以 "bta" 为前缀的接口。BTC 层主要负责向应用层提供以 "esp" 为前缀的支持接口，并处理基于 GATT 的配置文件以及其他任务。所有的 API 都位于 ESP_API 层，开发者应使用以 "esp" 为前缀的低功耗蓝牙 API。 + +.. only:: esp32 + + {IDF_TARGET_NAME} 的 ESP-Bluedroid 支持经典蓝牙和低功耗蓝牙。 + +.. only:: not esp32 + + {IDF_TARGET_NAME} 的 ESP-Bluedroid 仅支持低功耗蓝牙，不支持经典蓝牙。 + +- API 参考 + + - :doc:`../../api-reference/bluetooth/bt_common` + - :doc:`低功耗蓝牙 <../../api-reference/bluetooth/bt_le>` + +.. only:: esp32 + + - :example:`低功耗蓝牙 4.2 应用程序示例 ` + +.. only:: not esp32 + + - :example:`低功耗蓝牙 4.2 应用程序示例 ` + - :example:`低功耗蓝牙 5.0 应用程序示例 ` + +ESP-NimBLE +^^^^^^^^^^ + +ESP-NimBLE 是建立在 Apache Mynewt 开发的 NimBLE 主机协议栈之上的主机协议栈，已经为 {IDF_TARGET_NAME} 系列芯片和 FreeRTOS 进行了移植。通过维持现有 NimBLE API，并添加一个单独的 ESP-NimBLE API 进行初始化，使端口层保持简洁，也便于开发者操作。 + +ESP-NimBLE 仅支持低功耗蓝牙，不支持经典蓝牙。 + +- `Apache Mynewt NimBLE 用户指南 `__ +- API 参考 + + - `NimBLE API 参考 `__ + - :doc:`ESP-NimBLE 初始化 API 参考 initialization <../../api-reference/bluetooth/nimble/index>` + +- :example:`应用程序示例 ` + + +蓝牙规范 +-------- + +主机协议层之上是 Espressif 的蓝牙规范和一些常见的蓝牙规范。根据具体配置，这些规范可以在 ESP-Bluedroid 或 ESP-NimBLE 上运行。 + + +.. only:: SOC_BLE_MESH_SUPPORTED + + ESP-BLE-MESH + ^^^^^^^^^^^^ + + ESP-BLE-MESH 基于 Zephyr 蓝牙 Mesh 协议栈，其实现支持设备配网和节点控制，还支持代理、中继、低功耗和朋友等节点功能。 + + - :doc:`ESP-BLE-MESH 文档 <../esp-ble-mesh/ble-mesh-index>`：功能列表、快速入门、架构、应用示例描述、常见问题等。 + - :example:`应用示例 ` + + +.. only:: SOC_BLUFI_SUPPORTED + + BluFi + ^^^^^ + + {IDF_TARGET_NAME} 的 BluFi 是通过蓝牙信道进行的 Wi-Fi 网络配置功能。BluFi 提供了将 Wi-Fi 配置和凭据传递给 {IDF_TARGET_NAME} 的安全协议，从而使 {IDF_TARGET_NAME} 连接到 AP 或搭建软 AP。 + + - :doc:`BluFi 文档 ` + - :example:`应用示例 ` + + +应用 +---- + +最上层是应用层。利用上述 API 和蓝牙规范，可以在 ESP-Bluedroid 和 ESP-NimBLE 协议栈之上创建特定用例的低功耗蓝牙应用程序。 diff --git a/docs/zh_CN/api-guides/classic-bt/index.rst b/docs/zh_CN/api-guides/classic-bt/index.rst new file mode 100644 index 0000000000..57aba1ca5d --- /dev/null +++ b/docs/zh_CN/api-guides/classic-bt/index.rst @@ -0,0 +1,13 @@ +########### +经典蓝牙® +########### + +:link_to_translation:`en:[English]` + +***** +概览 +***** +.. toctree:: + :maxdepth: 2 + + overview diff --git a/docs/zh_CN/api-guides/classic-bt/overview.rst b/docs/zh_CN/api-guides/classic-bt/overview.rst new file mode 100644 index 0000000000..53a1e3eac3 --- /dev/null +++ b/docs/zh_CN/api-guides/classic-bt/overview.rst @@ -0,0 +1,80 @@ +介绍 +======= + +:link_to_translation:`en:[English]` + +此文档概述了 ESP-IDF 中经典蓝牙协议栈的架构，并提供了一些相关文档和应用示例的快速链接。 + +.. only:: esp32 + + {IDF_TARGET_NAME} 支持双模蓝牙 4.2，并且已经获得双模蓝牙 4.2 认证。 + +ESP-IDF 中的经典蓝牙协议栈是一个分层架构，可在 {IDF_TARGET_NAME} 系列芯片上实现经典蓝牙功能，详见下。 + +.. only:: esp32 + + .. figure:: ../../../_static/classic-bluetooth-architecture.png + :align: center + :scale: 90% + :alt: {IDF_TARGET_NAME} 经典蓝牙协议栈架构 + + {IDF_TARGET_NAME} 经典蓝牙协议栈架构 + +参考下表可知特定芯片是否支持经典蓝牙控制器。 + +.. list-table:: + :width: 100% + :widths: auto + :header-rows: 1 + + * - 芯片系列 + - 控制器 + * - ESP32 + - Y + * - ESP32-S2 + - \– + * - ESP32-S3 + - \– + * - ESP32-C2 + - \- + * - ESP32-C3 + - \- + * - ESP32-C6 + - \- + * - ESP32-H2 + - \- + +以下各节简要介绍了每个层，并提供了相关文档和应用示例的快速链接。 + + +ESP 蓝牙控制器 +-------------- + +底层为 ESP 蓝牙控制器，包含 PHY、基带、链路控制器、链路管理器、设备管理器和 HCI 等各种模块。该层管理硬件接口和链路，以库的形式提供功能，并通过 API 访问，且直接与硬件和低级别蓝牙协议交互。 + +- :doc:`API 参考 <../../api-reference/bluetooth/controller_vhci>` +- :example:`应用示例 ` + + +ESP 蓝牙主机 +------------- + +IDF 中的ESP-Bluedroid 主机支持经典蓝牙。 + + +ESP-Bluedroid +^^^^^^^^^^^^^ + +ESP-Bluedroid 是原生 Android 蓝牙协议栈 Bluedroid 的修改版，由两层组成：蓝牙上层 (BTU) 和蓝牙传输控制器层 (BTC)。BTU 层负责处理 L2CAP 等底层蓝牙协议以及其他配置文件，提供以 "bta" 为前缀的接口。BTC 层主要负责向应用层提供以 "esp" 为前缀的支持接口，并处理其他任务。所有的 API 都位于 ESP_API 层，开发者应使用以 "esp" 为前缀的经典蓝牙 API。 + +- API 参考 + + - :doc:`../../api-reference/bluetooth/bt_common` + - :doc:`经典蓝牙 <../../api-reference/bluetooth/classic_bt>` +- :example:`应用程序示例 ` + + +应用 +---- + +最上层是应用层。利用上述 API 和蓝牙规范，可以在 ESP-Bluedroid 协议栈之上创建特定用例的经典蓝牙应用程序。 diff --git a/docs/zh_CN/api-guides/esp-ble-mesh/ble-mesh-architecture.rst b/docs/zh_CN/api-guides/esp-ble-mesh/ble-mesh-architecture.rst index 69d5fd3dd2..18d6290a10 100644 --- a/docs/zh_CN/api-guides/esp-ble-mesh/ble-mesh-architecture.rst +++ b/docs/zh_CN/api-guides/esp-ble-mesh/ble-mesh-architecture.rst @@ -1,5 +1,5 @@ -ESP-BLE-MESH 架构 -================= +架构 +==== :link_to_translation:`en:[English]` @@ -20,7 +20,7 @@ ESP-BLE-MESH 架构 1. ESP-BLE-MESH 架构概览 ------------------------ -目前，ESP-BLE-MESH 已经实现了 Mesh Profile 的大多数功能及 Mesh Model 规范中定义的所有 Client Model。未支持的功能/模型尚在开发中，会尽快提供。 ESP-BLE-MESH 已通过 Bluetooth SIG 蓝牙技术联盟的 `认证 `__。 +目前，ESP-BLE-MESH 已经实现了 Mesh Profile 的大多数功能及 Mesh Model 规范中定义的所有 Client Model。未支持的功能/模型尚在开发中，会尽快提供。ESP-BLE-MESH 已通过 Bluetooth SIG 蓝牙技术联盟的 `认证 `__。 .. figure:: ../../../_static/esp-ble-mesh-architecture.png :align: center @@ -91,7 +91,7 @@ ESP-BLE-MESH 架构主要由以下 5 大部分组成： 协议栈架构中的 ``Mesh Provisioning`` 实现了如下功能： - 对未配网设备的配网。 -- Mesh 网络资源的分配 (单播地址、网络索引和网络秘钥)。 +- Mesh 网络资源的分配（单播地址、网络索引和网络秘钥）。 - 配网期间对 4 种验证方法的支持。 - 更多功能，请参见 :doc:`ble-mesh-feature-list`。 @@ -204,7 +204,7 @@ ESP-BLE-MESH 架构主要由以下 5 大部分组成： ``API /事件`` 与 ESP-BLE-MESH 协议栈的交互 -- 用户使用的 API 主要调用``Mesh Networking``、``Mesh Provisioning`` 和 ``Mesh Models`` 提供的函数。 +- 用户使用的 API 主要调用 ``Mesh Networking``、 ``Mesh Provisioning`` 和 ``Mesh Models`` 提供的函数。 - ``API /事件`` 和协议栈的交互不会跨越协议栈的层级进行操作。比如 API 不会调用 ``Network Layer`` 相关的函数。 diff --git a/docs/zh_CN/api-guides/esp-ble-mesh/ble-mesh-faq.rst b/docs/zh_CN/api-guides/esp-ble-mesh/ble-mesh-faq.rst index 2ffe7b9179..6dfb42e10b 100644 --- a/docs/zh_CN/api-guides/esp-ble-mesh/ble-mesh-faq.rst +++ b/docs/zh_CN/api-guides/esp-ble-mesh/ble-mesh-faq.rst @@ -1,5 +1,5 @@ -ESP-BLE-MESH 常见问题手册 -========================= +常见问题手册 +============= :link_to_translation:`en:[English]` @@ -88,7 +88,7 @@ ESP-BLE-MESH 常见问题手册 - Device UUID - OOB Info - - URL Hash (可选的) + - URL Hash（可选的） 1.12 这些信息可以用于设备识别吗？ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -338,7 +338,7 @@ ESP-BLE-MESH 常见问题手册 - Provisioner 调用 API :cpp:func:`esp_ble_mesh_provisioner_bind_app_key_to_local_model` 以绑定应用密钥至自己的客户端模型。 -1.24 Provisoner 如何控制节点的服务器模型？ +1.24 Provisioner 如何控制节点的服务器模型？ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ESP-BLE-MESH 支持所有 SIG 定义的客户端模型。Provisioner 可以使用这些客户端模型控制节点的服务器模型。客户端模型分为 6 类，每类有相应的功能。 @@ -385,7 +385,7 @@ ESP-BLE-MESH 常见问题手册 - 模型分为两种，客户端模型和服务器模型。客户端模型可以获取并设置服务器模型的状态。 - - 模型也可以分为 SIG 模型和自定义模型。 SIG 模型的所有行为都由官方定义，而自定义模型的行为均由用户定义。 + - 模型也可以分为 SIG 模型和自定义模型。SIG 模型的所有行为都由官方定义，而自定义模型的行为均由用户定义。 2.2 每个模型对应的消息格式是不是固定的？ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -532,15 +532,15 @@ ESP-BLE-MESH 常见问题手册 .. only:: esp32 - 未搭载 PSRAM 的 :doc:`ESP32-DevKitC <../../hw-reference/esp32/get-started-devkitc>` 开发板，Wi-Fi 和 ESP-BLE-MESH 共存可以正常运行，但是吞吐率较低。当 Wi-Fi 和 ESP-BLE-MESH 共存时，搭载 PSRAM 的 ESP32-DevKitC 速率可以稳定在 1 Mbps 以上。 + 未搭载 PSRAM 的 `ESP32-DevKitC `__ 开发板，Wi-Fi 和 ESP-BLE-MESH 共存可以正常运行，但是吞吐率较低。当 Wi-Fi 和 ESP-BLE-MESH 共存时，搭载 PSRAM 的 ESP32-DevKitC 速率可以稳定在 1 Mbps 以上。 应使能 menuconfig 中的一些配置来支持 PSRAM。 - - :code:`{IDF_TARGET_NAME}-specific --> Support for external,SPI-connected RAM --> Try to allocate memories of Wi-Fi and LWIP...` - - :code:`Bluetooth --> Bluedriod Enable --> BT/BLE will first malloc the memory from the PSRAM` - - :code:`Bluetooth --> Bluedriod Enable --> Use dynamic memory allocation in BT/BLE stack.` - - :code:`Bluetooth --> Blutooth controller --> BLE full scan feature supported.` - - :code:`Wi-Fi --> Software controls Wi-Fi/Bluetooth coexistence --> Wi-Fi` + - ``{IDF_TARGET_NAME}-specific`` > ``Support for external,SPI-connected RAM`` > ``Try to allocate memories of Wi-Fi and LWIP...`` + - ``Bluetooth`` > ``Bluedroid Enable`` > ``BT/BLE will first malloc the memory from the PSRAM`` + - ``Bluetooth`` > ``Bluedroid Enable`` > ``Use dynamic memory allocation in BT/BLE stack`` + - ``Bluetooth`` > ``Bluetooth controller`` > ``BLE full scan feature supported`` + - ``Wi-Fi`` > ``Software controls Wi-Fi/Bluetooth coexistence`` > ``Wi-Fi`` .. _ble-mesh-faq-fast-provisioning: @@ -563,12 +563,12 @@ ESP-BLE-MESH 常见问题手册 每完成一次快速配网后、开始新一次快速配网前，APP 会存有上次配网的数据，因此 APP 中显示的节点地址的数量比现有的节点地址更多。 -4.4 在 EspBleMesh App 中输入的 ** count ** 值有什么用途？ +4.4 在 EspBleMesh App 中输入的 **count** 值有什么用途？ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 此 **count** 值提供给 App 配置的代理节点，以决定何时提前开始 Proxy 广播信息。 -4.5 运行以下示例 :example:`fast_prov_server ` 的节点的 Configuration Client Model 何时开始工作？ +4.5 运行以下示例 :example:`fast_prov_server ` 的节点的 Configuration Client Model 何时开始工作？ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 使能了 Temporary Provisioner 功能后，Configuration Client Model 会开始工作。 @@ -584,39 +584,39 @@ ESP-BLE-MESH 常见问题手册 5. Log 帮助 ----------- -当 ESP-BLE-MESH 协议栈底层出现错误或者警告时，您可以在这儿找到这些错误和警告的含义。 +当 ESP-BLE-MESH 协议栈底层出现错误或者警告时，可以在这儿找到这些错误和警告的含义。 -5.1 :code:`ran out of retransmit attempts` 代表什么？ +5.1 ``ran out of retransmit attempts`` 代表什么？ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 节点发送分段消息时，由于某些原因，接收端未收到完整的消息。节点会重传消息。当重传次数达到最大重传数时，会出现该警告，当前最大重传数为 4。 -5.2 :code:`Duplicate found in Network Message Cache` 代表什么？ +5.2 ``Duplicate found in Network Message Cache`` 代表什么？ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 当节点收到一条消息时，它会把该消息与网络缓存中存储的消息进行比较。如果在缓存中找到相同的消息，这意味着之前已接受过该消息，则该消息会被丢弃。 -5.3 :code:`Incomplete timer expired` 代表什么？ +5.3 ``Incomplete timer expired`` 代表什么？ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 当节点在一定时间段（比如 10 秒）内未收到分段消息的所有段时，则 Incomplete 计时器到时，并且出现该警告。 -5.4 :code:`No matching TX context for ack` 代表什么？ +5.4 ``No matching TX context for ack`` 代表什么？ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 当节点收到一个分段 ack 且不能找到任何自己发送的与该 ack 相关的消息时，会出现该警告。 -5.5 :code:`No free slots for new incoming segmented messages` 代表什么？ +5.5 ``No free slots for new incoming segmented messages`` 代表什么？ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 当节点没有空间来接收新的分段消息时，会出现该警告。用户可以通过配置 :ref:`CONFIG_BLE_MESH_RX_SEG_MSG_COUNT` 扩大空间。 -5.6 :code:`Model not bound to AppKey 0x0000` 代表什么？ +5.6 ``Model not bound to AppKey 0x0000`` 代表什么？ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 当节点发送带有模型的消息且该模型尚未绑定到索引为 0x000 的应用密钥时，会出现该报错。 -5.7 :code:`Busy sending message to DST xxxx` 代表什么？ +5.7 ``Busy sending message to DST xxxx`` 代表什么？ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 该错误表示节点的客户端模型已将消息发送给目标节点，并且正在等待响应，用户无法将消息发送到单播地址相同的同一节点。接收到相应的响应或计时器到时后，可以发送另一条消息。 diff --git a/docs/zh_CN/api-guides/esp-ble-mesh/ble-mesh-feature-list.rst b/docs/zh_CN/api-guides/esp-ble-mesh/ble-mesh-feature-list.rst index e208eeddd8..366ae11a45 100644 --- a/docs/zh_CN/api-guides/esp-ble-mesh/ble-mesh-feature-list.rst +++ b/docs/zh_CN/api-guides/esp-ble-mesh/ble-mesh-feature-list.rst @@ -1 +1,130 @@ -.. include:: ../../../en/api-guides/esp-ble-mesh/ble-mesh-feature-list.rst \ No newline at end of file +功能列表 +======== + +:link_to_translation:`en:[English]` + +支持的功能 +---------- + +Mesh 核心 +""""""""" + +* 入网： + * PB-ADV，PB-GATT + * OOB 验证 + +* 网络 + * 中继 + * 分包和重组 + * 密钥更新程序 + * IV 更新程序 + * 朋友节点 + * 低功耗节点 + * 代理服务器 + * 代理客户端 + +* 多个客户端模型同时运行 + * 支持多个客户端模型同时向不同节点发送数据包 + * 客户端模型与服务器模型之间无阻塞 + +* NVS 存储 + * 存储 ESP-BLE-MESH 节点的入网和配置信息 + +Mesh 模型 +""""""""" + +* 基础模型 + * 配置服务器模型 + * 配置客户端模型 + * 健康服务器模型 + * 健康客户端模型 + +* 通用客户端模型 + * 通用开关客户端 + * 通用电平客户端 + * 通用默认过渡时间客户端 + * 通用电源开关客户端 + * 通用功率电平客户端 + * 通用电池客户端 + * 通用位置客户端 + * 通用属性客户端 + +* 传感器客户端模型 + * 传感器客户端 + +* 时间与场景客户端模型 + * 时间客户端 + * 场景客户端 + * 调度器客户端 + +* 照明客户端模型 + * 灯光亮度客户端 + * 灯光 CTL 客户端 + * 灯光 HSL 客户端 + * 灯光 xyL 客户端 + * 灯光 LC 客户端 + +* 通用服务器模型 + * 通用开关服务器 + * 通用电平服务器 + * 通用默认过渡时间服务器 + * 通用电源开关服务器 + * 通用电源开关设置服务器 + * 通用功率电平服务器 + * 通用功率电平设置服务器 + * 通用电池服务器 + * 通用位置服务器 + * 通用位置设置服务器 + * 通用用户属性服务器 + * 通用管理员属性服务器 + * 通用制造商属性服务器 + * 通用客户端属性服务器 + +* 传感器服务器模型 + * 传感器服务器 + * 传感器设置服务器 + +* 时间和场景服务器模型 + * 时间服务器 + * 时间设置服务器 + * 场景服务器 + * 场景设置服务器 + * 调度器服务器 + * 调度器设置服务器 + +* 照明服务器模型 + * 灯光亮度服务器 + * 灯光亮度设置服务器 + * 灯光 CTL 服务器 + * 灯光 CTL 温度服务器 + * 灯光 CTL 设置服务器 + * 灯光 HSL 服务器 + * 灯光 HSL 色调服务器 + * 灯光 HSL 饱和度服务器 + * 灯光 HSL 设置服务器 + * 灯光 xyL 服务器 + * 灯光 xyL 设置服务器 + * 灯光 LC 服务器 + * 灯光 LC 设置服务器 + +Mesh 示例 +""""""""""" + +* ESP-BLE-MESH 节点 + * :example_file:`教程 ` + * :example_file:`教程 ` + * :example:`示例 ` +* ESP-BLE-MESH 供应者 + * :example_file:`教程 ` + * :example:`示例 ` +* ESP-BLE-MESH 快速入网 + * :example_file:`客户端模型快速入网教程 ` + * :example_file:`服务器模型快速入网教程 ` + * :example:`示例 ` + * `演示视频 `__ +* ESP-BLE-MESH 及 Wi-Fi 共存 + * :example_file:`教程 ` + * :example:`示例 ` + * `演示视频 `__ +* ESP-BLE-MESH 命令行 + * :example:`Example ` diff --git a/docs/zh_CN/api-guides/esp-ble-mesh/ble-mesh-index.rst b/docs/zh_CN/api-guides/esp-ble-mesh/ble-mesh-index.rst index 82b33ba351..e462985d90 100644 --- a/docs/zh_CN/api-guides/esp-ble-mesh/ble-mesh-index.rst +++ b/docs/zh_CN/api-guides/esp-ble-mesh/ble-mesh-index.rst @@ -20,19 +20,19 @@ ESP-BLE-MESH 的实现和认证基于最新的 `Mesh Profile v1.0.1 `。 + 如果你在寻找 ESP32 基于 Wi-Fi 的 mesh 方案，请查阅乐鑫的另一款产品 ESP-WIFI-MESH。更多相关信息及文档，请参见 :doc:`ESP-WIFI-MESH <../../api-reference/network/esp-wifi-mesh>`。 .. _getting-started-with-ble-mesh: -ESP-BLE-MESH 快速入门 -===================== +快速入门 +======== -该章节旨在帮助您基于乐鑫的 ESP32 开发板搭建 ESP-BLE-MESH 网络。 +该章节旨在帮助你基于乐鑫的 ESP32 开发板搭建 ESP-BLE-MESH 网络。 我们将会展示如何搭建并运行一个包含 3 个节点的小型 ESP-BLE-MESH 网络，其中包含设备配网、节点配置，以及向特定节点上的 Generic OnOff Server Model 发送开关灯命令。 -如果您是第一次接触 ESP-IDF，请参见 esp-idf :doc:`../../get-started/index` 来设置开发环境，编译、烧写和运行示例应用程序。 +如果你是第一次接触 ESP-IDF，请参见 esp-idf :doc:`../../get-started/index` 来设置开发环境，编译、烧写和运行示例应用程序。 硬件及软件准备 @@ -56,7 +56,7 @@ ESP-BLE-MESH 快速入门 安装 ---- -以下详细步骤可指导您完成安装过程。 +以下详细步骤可指导你完成安装过程。 .. _get-started-ble-mesh-check-hardware: @@ -64,11 +64,11 @@ ESP-BLE-MESH 快速入门 步骤 1. 检查硬件 """"""""""""""""" -`ESP32-DevKitC`_ 和 `ESP-WROVER-KIT`_ 开发板均支持 ESP-BLE-MESH。您可以通过 menuconfig: :code:`idf.py menuconfig` > ``Example Configuration`` > ``Board selection for ESP-BLE-MESH`` 选择特定的开发板。 +`ESP32-DevKitC`_ 和 `ESP-WROVER-KIT`_ 开发板均支持 ESP-BLE-MESH。你可以通过 menuconfig: :code:`idf.py menuconfig` > ``Example Configuration`` > ``Board selection for ESP-BLE-MESH`` 选择特定的开发板。 .. note:: - 如果您打算使用 `ESP32-DevKitC`_ 开发板，请将 RGB 灯焊接至 GPIO 管脚 25、26 和 27。 + 如果你打算使用 `ESP32-DevKitC`_ 开发板，请将 RGB 灯焊接至 GPIO 管脚 25、26 和 27。 步骤 2. 配置软件 @@ -210,8 +210,8 @@ Step 5. 运行网络 .. _esp-ble-mesh-examples: -ESP-BLE-MESH 示例 -=================== +示例 +===== * :example_file:`ESP-BLE-MESH 节点 ` - 展示了将 ESP-BLE-MESH 作为拥有 Configuration Server model 和 Generic OnOff Server model 的节点设备的用法。然后，ESP-BLE-MESH Provisioner 可以配网设备，控制表示开/关状态的 RGB 灯，示例请见 :example:`example code `。 @@ -228,15 +228,15 @@ ESP-BLE-MESH 示例 .. _esp-ble-mesh-demo-videos: -ESP-BLE-MESH 演示视频 -====================== +演示视频 +======== * `Espressif Fast Provisioning using ESP-BLE-MESH App `_ * `Espressif ESP-BLE-MESH and Wi-Fi Coexistence `_ -ESP-BLE-MESH 常见问题手册 -========================= +常见问题手册 +============= * :ref:`ble-mesh-faq-provisioner-development` * :ref:`ble-mesh-faq-node-development` diff --git a/docs/zh_CN/api-guides/esp-ble-mesh/ble-mesh-terminology.rst b/docs/zh_CN/api-guides/esp-ble-mesh/ble-mesh-terminology.rst index ce89b36dc0..7c8281a765 100644 --- a/docs/zh_CN/api-guides/esp-ble-mesh/ble-mesh-terminology.rst +++ b/docs/zh_CN/api-guides/esp-ble-mesh/ble-mesh-terminology.rst @@ -1,10 +1,10 @@ -ESP-BLE-MESH Terminology -======================== - -.. _ble-mesh-terminology-role: +常见术语 +======== :link_to_translation:`en:[English]` +.. _ble-mesh-terminology-role: + .. list-table:: 表 1 ESP-BLE-MESH 术语 - 身份 :widths: 10 40 60 :header-rows: 1 @@ -216,6 +216,3 @@ ESP-BLE-MESH Terminology 官方定义摘自 `ESP-BLE-MESH Glossary of Terms `_. 查看更多术语，也请参照上述网址。 - - - diff --git a/docs/zh_CN/api-guides/index.rst b/docs/zh_CN/api-guides/index.rst index 1032811507..4f1e5554ed 100644 --- a/docs/zh_CN/api-guides/index.rst +++ b/docs/zh_CN/api-guides/index.rst @@ -7,7 +7,9 @@ API 指南 app_trace startup - :SOC_BLUFI_SUPPORTED: blufi + :SOC_BT_CLASSIC_SUPPORTED: classic-bt/index + :SOC_BLE_SUPPORTED: ble/index + :SOC_BLE_MESH_SUPPORTED: esp-ble-mesh/ble-mesh-index bootloader build-system :SOC_SUPPORT_COEXISTENCE: coexist @@ -16,7 +18,6 @@ API 指南 :SOC_RTC_MEM_SUPPORTED: deep-sleep-stub :SOC_USB_OTG_SUPPORTED: dfu error-handling - :SOC_BLE_MESH_SUPPORTED: esp-ble-mesh/ble-mesh-index :SOC_WIFI_MESH_SUPPORT: esp-wifi-mesh :SOC_SPIRAM_SUPPORTED: external-ram fatal-errors