diff --git a/docs/doxygen/Doxyfile_common b/docs/doxygen/Doxyfile_common index a04b7ee12f..3a4f3b4a70 100644 --- a/docs/doxygen/Doxyfile_common +++ b/docs/doxygen/Doxyfile_common @@ -154,7 +154,9 @@ INPUT = \ $(IDF_PATH)/components/nvs_flash/include/nvs.h \ $(IDF_PATH)/components/nvs_flash/include/nvs_flash.h \ $(IDF_PATH)/components/openthread/include/esp_openthread.h \ + $(IDF_PATH)/components/openthread/include/esp_openthread_border_router.h \ $(IDF_PATH)/components/openthread/include/esp_openthread_lock.h \ + $(IDF_PATH)/components/openthread/include/esp_openthread_netif_glue.h \ $(IDF_PATH)/components/openthread/include/esp_openthread_types.h \ $(IDF_PATH)/components/openthread/include/openthread-core-esp32x-config.h \ $(IDF_PATH)/components/vfs/include/esp_vfs.h \ diff --git a/docs/en/api-guides/index.rst b/docs/en/api-guides/index.rst index b2b750bfbb..0df4d7d040 100644 --- a/docs/en/api-guides/index.rst +++ b/docs/en/api-guides/index.rst @@ -28,6 +28,7 @@ API Guides Linker Script Generation Memory Types lwIP TCP/IP Stack + OpenThread Partition Tables Performance RF Calibration diff --git a/docs/en/api-guides/openthread.rst b/docs/en/api-guides/openthread.rst new file mode 100644 index 0000000000..4b0d5b354c --- /dev/null +++ b/docs/en/api-guides/openthread.rst @@ -0,0 +1,108 @@ +OpenThread +========== + +`OpenThread `_ is a IP stack running on the 802.15.4 MAC layer which features mesh network and low power consumption. + +Mode of the OpenThread stack +---------------------------- + +OpenThread can run under the following modes on Espressif chips: + +Standalone node ++++++++++++++++ + +The full OpenThread stack and the application layer runs on the same chip. This mode is available on chips with 15.4 radio such as ESP32-H2. + +Radio Co-Processor (RCP) +++++++++++++++++++++++++ + +The chip will be connected to another host running the OpenThread IP stack. It will send and received 15.4 packets on behalf of the host. This mode is available on chips with 15.4 radio such as ESP32-H2. The underlying transport between the chip and the host can be SPI or UART. For sake of latency, we recommend to use SPI as the underlying transport. + +OpenThread host ++++++++++++++++ + +For chips without 15.4 radio, it can be connected to an RCP and run OpenThread under host mode. This mode enables OpenThread on Wi-Fi chips such as ESP32, ESP32-S2, ESP32-S3 and ESP32-C3. The following diagram shows how devices work under different modes: + +.. blockdiag:: + :caption: OpenThread device modes + :align: center + + blockdiag openthread-device-modes { + + # global attributes + node_height = 90; + node_width = 220; + span_width = 100 + default_shape = roundedbox; + default_group_color = none; + + # node labels + HOST_NODE [label="OpenThread \nhost\n(ESP32)", fontsize=14]; + RCP [label="Radio \nCo-Processor\n(ESP32-H2)", fontsize=14]; + STANDALONE [label="Standalone \nnode\n (ESP32-H2)", fontsize=14]; + + # node connections + labels + RCP -> STANDALONE [label="15.4 radio", dir=both, style=dashed]; + + # arrange nodes vertically + group { + orientation = portrait; + HOST_NODE -> RCP [label="SPI", dir=both]; + } + } + + +How To Write an OpenThread Application +-------------------------------------- + +The OpenThread :example:`openthread/ot_cli` example will be a good place to start at. It demonstrates basic OpenThread initialization and simple socket-based server and client. + +Before OpenThread initialization +++++++++++++++++++++++++++++++++ + +- s1.1 The main task calls :cpp:func:`esp_vfs_eventfd_register` to initialize the eventfd virtual filesystem. The eventfd file system is used for task notification in the OpenThread driver. + +- s1.2 The main task calls :cpp:func:`nvs_flash_init` to initialize the NVS where the Thread network data is stored. + +- s1.3 **Optional**, The main task calls :cpp:func:`esp_netif_init` only when it wants to create the network interface for Thread. + +- s1.4: The main task calls :cpp:func:`esp_event_loop_create` to create the system Event task and initialize an application event's callback function. + +OpenThread stack initialization ++++++++++++++++++++++++++++++++ +- s2.1: Call :cpp:func:`esp_openthread_init` to initialize the OpenThread stack. + +OpenThread network interface initialization ++++++++++++++++++++++++++++++++++++++++++++ +The whole stage is **optional** and only required if the application wants to create the network interface for Thread. +- s3.1: Call :cpp:func:`esp_netif_new` with `ESP_NETIF_DEFAULT_OPENTHREAD` to create the interface. +- s3.2: Call :cpp:func:`esp_openthread_netif_glue_init` to create the OpenThread interface handlers. +- s3.3: Call :cpp:func:`esp_netif_attach` to attach the handlers to the interface. + +The OpenThread main loop +++++++++++++++++++++++++ + +- s4.3: Call :cpp:func:`esp_openthread_launch_mainloop` to launch the OpenThread main loop. Note that this is a busy loop and will not return until the OpenThread stack is terminated. + +Calling OpenThread APIs +++++++++++++++++++++++++ + +The OpenThread APIs are not thread-safe. When calling OpenThread APIs from other tasks, make sure to hold the lock with :cpp:func:`esp_openthread_lock_acquire` and release the lock with :cpp:func:`esp_openthread_lock_release` afterwards. + +Deinitialization +++++++++++++++++ + +The following steps are required to deintialize the OpenThread stack: +- Call :cpp:func:`esp_netif_destroy` and :cpp:func:`esp_openthread_netif_glue_deinit` to deintialize the OpenThread network interface if you have created one. +- Call :cpp:func:`esp_openthread_deinit` to deintialize the OpenThread stack. + +The OpenThread border router +---------------------------- + +The OpenThread border router connects the Thread network with other IP networks. It will provide IPv6 connectivity, service registration and commission functionality. +To launch an OpenThread border router on a ESP chip, you need to connect an RCP to a Wi-Fi capable chip such as ESP32. +Call :cpp:func:`esp_openthread_border_router_init` during the initialization will launch all the border routing functionalities. + +You may refer to the :example:`openthread/ot_br` example and the README for further border router details. + + diff --git a/docs/en/api-reference/index.rst b/docs/en/api-reference/index.rst index 0709667b7d..21189adb58 100644 --- a/docs/en/api-reference/index.rst +++ b/docs/en/api-reference/index.rst @@ -14,4 +14,4 @@ API Reference Storage System Configuration Options - Error Codes Reference \ No newline at end of file + Error Codes Reference diff --git a/docs/en/api-reference/network/esp_openthread.rst b/docs/en/api-reference/network/esp_openthread.rst new file mode 100644 index 0000000000..8771b8b5dc --- /dev/null +++ b/docs/en/api-reference/network/esp_openthread.rst @@ -0,0 +1,32 @@ +Thread +========== + +Introduction +------------ + +`Thread `_ is a IP-based mesh networking protocol. It's based on the 802.15.4 physical and MAC layer. + +Application Examples +-------------------- + +The :example:`openthread` directory of ESP-IDF examples contains the following applications: + +- The OpenThread interactive shell :example:`openthread/ot_cli`. +- The Thread border router :example:`openthread/ot_cli`. + + +API Reference +------------- + +For manipulating the Thread network, the OpenThread api shall be used. +The OpenThread api docs can be found at the `OpenThread official website `_. + +ESP-IDF provides extra apis for launching and managing the OpenThread stack, binding to network interfaces and border routing features. + +.. include-build-file:: inc/esp_openthread.inc +.. include-build-file:: inc/esp_openthread_types.inc +.. include-build-file:: inc/esp_openthread_lock.inc +.. include-build-file:: inc/esp_openthread_netif_glue.inc +.. include-build-file:: inc/esp_openthread_border_router.inc + + diff --git a/docs/en/api-reference/network/index.rst b/docs/en/api-reference/network/index.rst index f4a0977a7a..e93245226f 100644 --- a/docs/en/api-reference/network/index.rst +++ b/docs/en/api-reference/network/index.rst @@ -29,6 +29,16 @@ Ethernet Code examples for the Ethernet API are provided in the :example:`ethernet` directory of ESP-IDF examples. +Thread +========== + +.. toctree:: + :maxdepth: 1 + + Thread + +Thread is an IPv6-based mesh networking technology for IoT. +Code examples for the Thread API are provided in the :example:`openthread` directory of ESP-IDF examples. IP Network Layer ================ diff --git a/docs/zh_CN/api-guides/index.rst b/docs/zh_CN/api-guides/index.rst index 842f38da88..c8fcde9649 100644 --- a/docs/zh_CN/api-guides/index.rst +++ b/docs/zh_CN/api-guides/index.rst @@ -27,6 +27,7 @@ API 指南 JTAG 调试 链接脚本生成机制 lwIP TCP/IP 协议栈 + OpenThread Memory Types 分区表 Performance diff --git a/docs/zh_CN/api-guides/openthread.rst b/docs/zh_CN/api-guides/openthread.rst new file mode 100644 index 0000000000..4d1abad6ce --- /dev/null +++ b/docs/zh_CN/api-guides/openthread.rst @@ -0,0 +1 @@ +.. include:: ../../en/api-guides/openthread.rst diff --git a/docs/zh_CN/api-reference/network/esp_openthread.rst b/docs/zh_CN/api-reference/network/esp_openthread.rst new file mode 100644 index 0000000000..299652af27 --- /dev/null +++ b/docs/zh_CN/api-reference/network/esp_openthread.rst @@ -0,0 +1 @@ +.. include:: ../../../en/api-reference/network/esp_openthread.rst diff --git a/docs/zh_CN/api-reference/network/index.rst b/docs/zh_CN/api-reference/network/index.rst index 4964066e52..2d79310c81 100644 --- a/docs/zh_CN/api-reference/network/index.rst +++ b/docs/zh_CN/api-reference/network/index.rst @@ -29,6 +29,16 @@ ESP-WIFI-MESH 的示例代码存放在 ESP-IDF 示例项目的 :example:`mesh` 本部分的以太网 API 示例代码存放在 ESP-IDF 示例项目的 :example:`ethernet` 目录下。 +Thread +======== + +.. toctree:: + :maxdepth: 1 + + Thread + +本部分的Thread API 示例代码存放在 ESP-IDF 示例项目的 :example:`openthread` 目录下。 + IP 网络层协议 ================ diff --git a/examples/openthread/ot_br/README.md b/examples/openthread/ot_br/README.md index 2bc7a64d4e..18b37c37cb 100644 --- a/examples/openthread/ot_br/README.md +++ b/examples/openthread/ot_br/README.md @@ -1,4 +1,4 @@ -# OpenThread command line example +# OpenThread Border Router example ## Overview