Merge branch 'backport/openthread_related_feature_v52_20241125' into 'release/v5.2'

Backport openthread related features to 5.2

See merge request espressif/esp-idf!35173

docs/en/api-guides/openthread.rst

@@ -102,6 +102,22 @@ The following steps are required to deinitialize the OpenThread stack:
 - Call :cpp:func:`esp_netif_destroy` and :cpp:func:`esp_openthread_netif_glue_deinit` to deinitialize the OpenThread network interface if you have created one.
 - Call :cpp:func:`esp_openthread_deinit` to deinitialize the OpenThread stack.
 
+
+OpenThread Macro Definitions
+----------------------------
+
+In the OpenThread protocol stack, defining macros to enable features and configure parameters is a common practice. Users can define macro values to enable or disable specific features and adjust parameters. ESP provides the following methods for defining OpenThread macros:
+
+- Using configuration menu (``menuconfig``): Some macros are mapped to Kconfig files and can be configured through ``idf.py menuconfig → Component config → OpenThread``. This allows enabling or disabling features and setting related parameters.
+- Using user-defined header files: Users can create a custom header file and enable it via ``idf.py menuconfig → Component config → OpenThread → Thread Extended Features → Use a header file defined by customer``. The priority of the custom header file is second only to the ``menuconfig``.
+- Using ``openthread-core-esp32x-xxx-config.h`` for configuration: Some macros have default values set in the OpenThread private header files. These cannot currently be modified through the ``menuconfig``, but can be modified via user-defined header files.
+- Using OpenThread stack default configurations: Other macros are assigned default values when defined in the OpenThread stack.
+
+.. note::
+
+    The priority of the above configuration methods, from highest to lowest, is as follows:
+    Configuration Menu → User-defined Header File → openthread-core-esp32x-xxx-config.h → OpenThread Stack Default Configuration
+
 The OpenThread Border Router
 ----------------------------
 

docs/en/api-reference/network/esp_openthread.rst

@@ -18,6 +18,12 @@ The :example:`openthread` directory of ESP-IDF examples contains the following a
 - The Thread Radio Co-Processor :example:`openthread/ot_rcp`
 
 
+- :example:`openthread/ot_trel` demonstrates Thread Radio Encapsulation Link (TREL) function. This requires a board equipped with a Wi-Fi module.
+
+- :example:`openthread/ot_sleepy_device/deep_sleep` demonstrates Thread Deep-sleep function.
+
+- :example:`openthread/ot_sleepy_device/light_sleep` demonstrates Thread Light-sleep function.
+
 API Reference
 -------------
 

docs/zh_CN/api-guides/openthread.rst

@@ -102,6 +102,21 @@ OpenThread API 非线程安全。当从其他任务中调用 OpenThread API 时
 - 如果创建了 OpenThread 网络接口，请调用 :cpp:func:`esp_netif_destroy` 和 :cpp:func:`esp_openthread_netif_glue_deinit` 卸载 OpenThread 协议栈。
 - 调用 :cpp:func:`esp_openthread_deinit` 卸载 OpenThread 协议栈。
 
+
+OpenThread 宏定义
+-----------------
+
+在 OpenThread 协议栈中，定义宏来进行功能启用以及参数配置是常见行为。在实际使用中，用户可以通过定义宏的值来启用/禁用相关功能和修改参数。乐鑫提供以下方式来进行 OpenThread 宏定义：
+
+- 使用配置菜单配置 (``menuconfig``)：部分宏已经映射到 Kconfig 文件，可通过 ``idf.py menuconfig → Component config → OpenThread`` 启用/关闭相应功能，并配置相关参数。
+- 使用用户自定义头文件配置：用户可编写头文件，并启用 ``idf.py menuconfig → Component config → OpenThread → Thread Extensioned Features → Use a header file defined by customer`` 来应用自定义头文件。自定义头文件的优先级将仅次于配置菜单。
+- 使用 ``openthread-core-esp32x-xxx-config.h`` 的配置：部分宏在 OpenThread private 头文件中已经设置默认值，暂不支持通过 menuconfig 修改，但可以通过用户自定义头文件修改。
+- 使用 OpenThread 协议栈默认配置：对于其他宏，OpenThread 协议栈在定义时已设置默认值。
+
+.. 注意::
+
+    以上四种配置方式，优先级由高到低为：配置菜单 → 用户自定义头文件 → openthread-core-esp32x-xxx-config.h → OpenThread 协议栈默认配置
+
 OpenThread 边界路由器
 ---------------------
 

docs/zh_CN/api-reference/network/esp_openthread.rst

@@ -18,6 +18,12 @@ ESP-IDF 示例目录 :example:`openthread` 包含以下应用程序：
 - Thread 无线电协处理器 (Thread Radio Co-Processor)：:example:`openthread/ot_rcp`
 
 
+- :example:`openthread/ot_trel` 演示了 Thread Radio Encapsulation Link (TREL) 功能。该示例需要在配备 Wi-Fi 模块的开发板上运行。
+
+- :example:`openthread/ot_sleepy_device/deep_sleep` 演示了 Thread 深度睡眠功能。
+
+- :example:`openthread/ot_sleepy_device/light_sleep` 演示了 Thread 浅睡眠功能。
+
 API参考
 -------------