diff --git a/docs/conf_common.py b/docs/conf_common.py index b8f7249a53..abfd1b9e61 100644 --- a/docs/conf_common.py +++ b/docs/conf_common.py @@ -34,11 +34,11 @@ BLE_DOCS = ['api-reference/bluetooth/bt_le.rst', 'migration-guides/release-5.x/5.0/bluetooth-low-energy.rst'] -BLE_MESH_DOCS = ['api-guides/ble/esp-ble-mesh/ble-mesh-index.rst', - 'api-guides/ble/esp-ble-mesh/ble-mesh-feature-list.rst', - 'api-guides/ble/esp-ble-mesh/ble-mesh-terminology.rst', - 'api-guides/ble/esp-ble-mesh/ble-mesh-architecture.rst', - 'api-guides/ble/esp-ble-mesh/ble-mesh-faq.rst', +BLE_MESH_DOCS = ['api-guides/esp-ble-mesh/ble-mesh-index.rst', + 'api-guides/esp-ble-mesh/ble-mesh-feature-list.rst', + 'api-guides/esp-ble-mesh/ble-mesh-terminology.rst', + 'api-guides/esp-ble-mesh/ble-mesh-architecture.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', diff --git a/docs/en/api-guides/ble/index.rst b/docs/en/api-guides/ble/index.rst index f39237ac3d..85f20303cd 100644 --- a/docs/en/api-guides/ble/index.rst +++ b/docs/en/api-guides/ble/index.rst @@ -21,7 +21,7 @@ Profile ESP-BLE-MESH ^^^^^^^^^^^^^ - - See the :ref:`ESP-BLE-MESH ` section. + - See the :doc:`ESP-BLE-MESH documentation <../esp-ble-mesh/ble-mesh-index>`. .. only:: SOC_BLUFI_SUPPORTED @@ -32,17 +32,3 @@ Profile :maxdepth: 1 blufi - - -.. only:: SOC_BLE_MESH_SUPPORTED - - .. _mesh: - - ************* - ESP-BLE-MESH - ************* - - .. toctree:: - :maxdepth: 2 - - esp-ble-mesh/ble-mesh-index diff --git a/docs/en/api-guides/ble/overview.rst b/docs/en/api-guides/ble/overview.rst index 94572fdb41..37e04f5f4b 100644 --- a/docs/en/api-guides/ble/overview.rst +++ b/docs/en/api-guides/ble/overview.rst @@ -175,7 +175,7 @@ Above the host stacks are the profile implementations by Espressif and some comm 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 `: feature list, get started, architecture, description of application examples, frequently asked questions, etc. + - :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 ` diff --git a/docs/en/api-guides/ble/esp-ble-mesh/ble-mesh-architecture.rst b/docs/en/api-guides/esp-ble-mesh/ble-mesh-architecture.rst similarity index 99% rename from docs/en/api-guides/ble/esp-ble-mesh/ble-mesh-architecture.rst rename to docs/en/api-guides/esp-ble-mesh/ble-mesh-architecture.rst index 7d196c604a..64f1e09636 100644 --- a/docs/en/api-guides/ble/esp-ble-mesh/ble-mesh-architecture.rst +++ b/docs/en/api-guides/esp-ble-mesh/ble-mesh-architecture.rst @@ -22,7 +22,7 @@ This document introduces ESP-BLE-MESH architecture overview, ESP-BLE-MESH archit Currently ESP-BLE-MESH has implemented most functions of Mesh Profile and all the Client Models defined in Mesh Model specification. Those missing functions/models are under development and will be provided soon. ESP-BLE-MESH architecture has been granted the official Bluetooth `certification `__. -.. figure:: ../../../../_static/esp-ble-mesh-architecture.png +.. figure:: ../../../_static/esp-ble-mesh-architecture.png :align: center Figure 1.1 ESP-BLE-MESH Architecture Diagram @@ -217,7 +217,7 @@ The design and implementation of ESP-BLE-MESH architecture is based on layers an - **Module-based Approach**: Every file implements an independent function that can be called by other programs. -.. figure:: ../../../../_static/esp-ble-mesh-interface.png +.. figure:: ../../../_static/esp-ble-mesh-interface.png :align: center Figure 2.1 ESP-BLE-MESH Architecture Implementation Diagram diff --git a/docs/en/api-guides/ble/esp-ble-mesh/ble-mesh-faq.rst b/docs/en/api-guides/esp-ble-mesh/ble-mesh-faq.rst similarity index 100% rename from docs/en/api-guides/ble/esp-ble-mesh/ble-mesh-faq.rst rename to docs/en/api-guides/esp-ble-mesh/ble-mesh-faq.rst diff --git a/docs/en/api-guides/ble/esp-ble-mesh/ble-mesh-feature-list.rst b/docs/en/api-guides/esp-ble-mesh/ble-mesh-feature-list.rst similarity index 100% rename from docs/en/api-guides/ble/esp-ble-mesh/ble-mesh-feature-list.rst rename to docs/en/api-guides/esp-ble-mesh/ble-mesh-feature-list.rst diff --git a/docs/en/api-guides/ble/esp-ble-mesh/ble-mesh-index.rst b/docs/en/api-guides/esp-ble-mesh/ble-mesh-index.rst similarity index 94% rename from docs/en/api-guides/ble/esp-ble-mesh/ble-mesh-index.rst rename to docs/en/api-guides/esp-ble-mesh/ble-mesh-index.rst index 591e00d1b0..7144342bcc 100644 --- a/docs/en/api-guides/ble/esp-ble-mesh/ble-mesh-index.rst +++ b/docs/en/api-guides/esp-ble-mesh/ble-mesh-index.rst @@ -1,5 +1,6 @@ -Introduction -============== +************ +ESP-BLE-MESH +************ :link_to_translation:`zh_CN:[中文]` @@ -11,7 +12,7 @@ Bluetooth mesh is not a wireless communications technology, but a networking tec 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. -Please see the :doc:`ble-mesh-architecture` for information about the implementation of ESP-BLE-MESH architecture and :doc:`ESP-BLE-MESH API Reference <../../../api-reference/bluetooth/esp-ble-mesh>` for information about respective API. +Please see the :doc:`ble-mesh-architecture` for information about the implementation of ESP-BLE-MESH architecture and :doc:`ESP-BLE-MESH API Reference <../../api-reference/bluetooth/esp-ble-mesh>` for information about respective API. 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. @@ -19,19 +20,19 @@ ESP-BLE-MESH is implemented and certified based on the latest Mesh Profile v1.0. .. 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>`. + 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>`. .. _getting-started-with-ble-mesh: -Getting Started +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. We are going to demonstrate process of setting and operation of a small ESP-BLE-MESH network of three nodes. This process will cover device provisioning and node configuration, and then sending on/off commands to Generic OnOff Server Models on specific nodes. -If you are new to ESP-IDF, please first set up development environment, compile , flash and run example application following top level ESP-IDF :doc:`../../../get-started/index` documentation. +If you are new to ESP-IDF, please first set up development environment, compile , flash and run example application following top level ESP-IDF :doc:`../../get-started/index` documentation. What You Need @@ -82,7 +83,7 @@ After the :example:`bluetooth/esp_ble_mesh/onoff_models/onoff_server` example is Once boards are powered on, the RGB LED on each board should turn **GREEN**. -.. figure:: ../../../../_static/ble-mesh-device-power-on.png +.. figure:: ../../../_static/ble-mesh-device-power-on.png :align: center ESP-BLE-MESH Devices Power On @@ -97,7 +98,7 @@ In this section, we will use the **nRF Mesh Android** App to demonstrate how to The Scanner is App's functionality to search for unprovisioned devices in range. Open the App, press **Scanner** at the bottom and the search will start. After a short while we should see three unprovisioned devices displayed. -.. figure:: ../../../../_static/ble-mesh-scanner.png +.. figure:: ../../../_static/ble-mesh-scanner.png :align: center :height: 370 @@ -113,7 +114,7 @@ Users can select any unprovisioned device, then the App will try to set up a con After the **IDENTIFY** interface button is pressed, users can see the **PROVISION** interface button. -.. figure:: ../../../../_static/ble-mesh-identify-provision.png +.. figure:: ../../../_static/ble-mesh-identify-provision.png :align: center :height: 370 @@ -131,7 +132,7 @@ Then, the App will try to provision the unprovisioned device. When the device is When all the procedures are finished, the node is configured properly. And after pressing **OK**, users can see that unicast address is assigned, and Composition Data of the node is decoded successfully. -.. figure:: ../../../../_static/ble-mesh-config-complete.png +.. figure:: ../../../_static/ble-mesh-config-complete.png :align: center :height: 370 @@ -139,7 +140,7 @@ When all the procedures are finished, the node is configured properly. And after Sometimes in procedure 2, the App may fail to reconnect with the node. In this case, after pressing **OK**, users can see that only unicast address of the node has been assigned, but no Composition Data has been got. Then users need to press **CONNECT** on the top right, and the previously provisioned node will be displayed on the screen, and users need to choose it and try to connect with the node. -.. figure:: ../../../../_static/ble-mesh-initial-config-fail.png +.. figure:: ../../../_static/ble-mesh-initial-config-fail.png :align: center :height: 370 @@ -147,7 +148,7 @@ Sometimes in procedure 2, the App may fail to reconnect with the node. In this c After connecting successfully, the App will show the interface buttons which can be used to get Composition Data and add AppKey. -.. figure:: ../../../../_static/ble-mesh-reconnect-initial-config.png +.. figure:: ../../../_static/ble-mesh-reconnect-initial-config.png :align: center :height: 370 @@ -160,7 +161,7 @@ Here an example of three devices listed. * The left picture shows that the third device is provisioned successfully, but the App failed to connect with it. When it tries to reconnect with the third node, three nodes are displayed on the App. * The right picture shows that after connecting with any node successfully, the App displays the information of the three nodes. Users can see that the App has got the Composition Data of the first and the second nodes, but for the third one, only the unicast address has been assigned to it while the Composition Data is unknown. -.. figure:: ../../../../_static/ble-mesh-reconnect-three.png +.. figure:: ../../../_static/ble-mesh-reconnect-three.png :align: center :height: 370 @@ -173,7 +174,7 @@ When provisioning and initial configuration are finished, users can start to con Example below shows how to bind AppKey with Generic OnOff Server Model within the Primary Element. -.. figure:: ../../../../_static/ble-mesh-model-bind-appkey.png +.. figure:: ../../../_static/ble-mesh-model-bind-appkey.png :align: center :height: 370 @@ -190,7 +191,7 @@ After all the Generic OnOff Server Models within the three elements are bound wi In the :example:`bluetooth/esp_ble_mesh/onoff_models/onoff_server` example, the first Generic OnOff Server Model is used to control the **RED** color, the second one is used to control the **GREEN** color and the third one is used to control the **BLUE** color. -.. figure:: ../../../../_static/ble-mesh-generic-onoff.png +.. figure:: ../../../_static/ble-mesh-generic-onoff.png :align: center :height: 370 @@ -198,7 +199,7 @@ In the :example:`bluetooth/esp_ble_mesh/onoff_models/onoff_server` example, the The following screenshot shows different board with different color on. -.. figure:: ../../../../_static/ble-mesh-three-nodes-on.png +.. figure:: ../../../_static/ble-mesh-three-nodes-on.png :align: center Three ESP-BLE-MESH Nodes On diff --git a/docs/en/api-guides/ble/esp-ble-mesh/ble-mesh-terminology.rst b/docs/en/api-guides/esp-ble-mesh/ble-mesh-terminology.rst similarity index 100% rename from docs/en/api-guides/ble/esp-ble-mesh/ble-mesh-terminology.rst rename to docs/en/api-guides/esp-ble-mesh/ble-mesh-terminology.rst diff --git a/docs/en/api-guides/index.rst b/docs/en/api-guides/index.rst index 011537284c..4e7e40aa8c 100644 --- a/docs/en/api-guides/index.rst +++ b/docs/en/api-guides/index.rst @@ -8,6 +8,7 @@ API Guides app_trace startup :SOC_BLE_SUPPORTED: ble/index + :SOC_BLE_MESH_SUPPORTED: esp-ble-mesh/ble-mesh-index bootloader build-system :SOC_SUPPORT_COEXISTENCE: coexist diff --git a/docs/en/api-reference/bluetooth/esp-ble-mesh.rst b/docs/en/api-reference/bluetooth/esp-ble-mesh.rst index 138c4d88fa..bf03a8fe79 100644 --- a/docs/en/api-reference/bluetooth/esp-ble-mesh.rst +++ b/docs/en/api-reference/bluetooth/esp-ble-mesh.rst @@ -11,7 +11,7 @@ For an ESP32 to join and work on a ESP-BLE-MESH network, it must be provisioned Apart from ESP-BLE-MESH nodes, inside ESP-BLE-MESH network, there is also ESP32 that works as ESP-BLE-MESH provisioner, which could provision unprovisioned devices into ESP-BLE-MESH nodes and configure the nodes with various features. -For information how to start using ESP32 and ESP-BLE-MESH, please see the Section :ref:`getting-started-with-ble-mesh`. If you are interested in information on ESP-BLE-MESH architecture, including some details of software implementation, please see Section :doc:`../../api-guides/ble/esp-ble-mesh/ble-mesh-architecture`. +For information how to start using ESP32 and ESP-BLE-MESH, please see the Section :ref:`getting-started-with-ble-mesh`. If you are interested in information on ESP-BLE-MESH architecture, including some details of software implementation, please see Section :doc:`../../api-guides/esp-ble-mesh/ble-mesh-architecture`. Application Examples and Demos diff --git a/docs/zh_CN/api-guides/blufi.rst b/docs/zh_CN/api-guides/ble/blufi.rst similarity index 100% rename from docs/zh_CN/api-guides/blufi.rst rename to docs/zh_CN/api-guides/ble/blufi.rst diff --git a/docs/zh_CN/api-guides/ble/index.rst b/docs/zh_CN/api-guides/ble/index.rst index 0d581546b1..08301dac17 100644 --- a/docs/zh_CN/api-guides/ble/index.rst +++ b/docs/zh_CN/api-guides/ble/index.rst @@ -1,10 +1,34 @@ -蓝牙® -========= -:link_to_translation:`en:[English]` +################ +低功耗蓝牙® +################ -概述 --------- +:link_to_translation:`zh_CN:[中文]` + +***** +概览 +***** .. toctree:: :maxdepth: 1 overview + +********** +蓝牙规范 +********** + +.. only:: SOC_BLE_MESH_SUPPORTED + + ESP-BLE-MESH + ^^^^^^^^^^^^^ + + - See the :doc:`ESP-BLE-MESH documentation <../esp-ble-mesh/ble-mesh-index>`. + +.. only:: SOC_BLUFI_SUPPORTED + + BluFi + ^^^^^ + + .. toctree:: + :maxdepth: 1 + + blufi diff --git a/docs/zh_CN/api-guides/ble/overview.rst b/docs/zh_CN/api-guides/ble/overview.rst index a2d7a980b8..aacc40b68a 100644 --- a/docs/zh_CN/api-guides/ble/overview.rst +++ b/docs/zh_CN/api-guides/ble/overview.rst @@ -186,7 +186,7 @@ ESP-NimBLE 仅支持低功耗蓝牙，不支持经典蓝牙。 {IDF_TARGET_NAME} 的 BluFi 是通过蓝牙信道进行的 Wi-Fi 网络配置功能。BluFi 提供了将 Wi-Fi 配置和凭据传递给 {IDF_TARGET_NAME} 的安全协议，从而使 {IDF_TARGET_NAME} 连接到 AP 或搭建软 AP。 - - :doc:`BluFi 文档 <../blufi>` + - :doc:`BluFi 文档 ` - :example:`应用示例 ` diff --git a/docs/zh_CN/api-guides/index.rst b/docs/zh_CN/api-guides/index.rst index 953a4f42ff..3f49d592b6 100644 --- a/docs/zh_CN/api-guides/index.rst +++ b/docs/zh_CN/api-guides/index.rst @@ -7,8 +7,8 @@ API 指南 app_trace startup - :SOC_BLUFI_SUPPORTED: blufi :SOC_BLE_SUPPORTED: ble/index + :SOC_BLE_MESH_SUPPORTED: esp-ble-mesh/ble-mesh-index bootloader build-system :SOC_SUPPORT_COEXISTENCE: coexist @@ -20,7 +20,6 @@ API 指南 :SOC_RTC_MEM_SUPPORTED: deep-sleep-stub :SOC_USB_OTG_SUPPORTED and not esp32p4: 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