From 01fa2032a67deddeeb1fad319ed30d5e35924823 Mon Sep 17 00:00:00 2001 From: hebinglin Date: Mon, 2 Mar 2026 16:17:07 +0800 Subject: [PATCH] feat(doc): add uart wakeup migration guides --- docs/en/api-reference/system/sleep_modes.rst | 2 + docs/en/migration-guides/index.rst | 1 + .../release-6.x/6.1/index.rst | 9 +++ .../release-6.x/6.1/peripherals.rst | 76 +++++++++++++++++++ .../api-reference/system/sleep_modes.rst | 2 + docs/zh_CN/migration-guides/index.rst | 1 + .../release-6.x/6.1/index.rst | 9 +++ .../release-6.x/6.1/peripherals.rst | 76 +++++++++++++++++++ 8 files changed, 176 insertions(+) create mode 100644 docs/en/migration-guides/release-6.x/6.1/index.rst create mode 100644 docs/en/migration-guides/release-6.x/6.1/peripherals.rst create mode 100644 docs/zh_CN/migration-guides/release-6.x/6.1/index.rst create mode 100644 docs/zh_CN/migration-guides/release-6.x/6.1/peripherals.rst diff --git a/docs/en/api-reference/system/sleep_modes.rst b/docs/en/api-reference/system/sleep_modes.rst index 46479685a75..0e5682892fb 100644 --- a/docs/en/api-reference/system/sleep_modes.rst +++ b/docs/en/api-reference/system/sleep_modes.rst @@ -367,6 +367,8 @@ RTC peripherals or RTC memories do not need to be powered on during sleep in thi Any IO can be used as the external input to wake up the chip from Light-sleep. Each pin can be individually configured to trigger wakeup on high or low level using the :cpp:func:`gpio_wakeup_enable` function. Then the :cpp:func:`esp_sleep_enable_gpio_wakeup` function should be called to enable this wakeup source. +.. _uart_wakeup_light_sleep: + UART Wakeup (Light-sleep Only) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/en/migration-guides/index.rst b/docs/en/migration-guides/index.rst index 4089158940c..25b6666115e 100644 --- a/docs/en/migration-guides/index.rst +++ b/docs/en/migration-guides/index.rst @@ -23,3 +23,4 @@ ESP-IDF 6.x Migration Guide :maxdepth: 1 release-6.x/6.0/index + release-6.x/6.1/index diff --git a/docs/en/migration-guides/release-6.x/6.1/index.rst b/docs/en/migration-guides/release-6.x/6.1/index.rst new file mode 100644 index 00000000000..91afce2f489 --- /dev/null +++ b/docs/en/migration-guides/release-6.x/6.1/index.rst @@ -0,0 +1,9 @@ +Migration from 6.0 to 6.1 +-------------------------- + +:link_to_translation:`zh_CN:[中文]` + +.. toctree:: + :maxdepth: 1 + + peripherals diff --git a/docs/en/migration-guides/release-6.x/6.1/peripherals.rst b/docs/en/migration-guides/release-6.x/6.1/peripherals.rst new file mode 100644 index 00000000000..0cfbe45f793 --- /dev/null +++ b/docs/en/migration-guides/release-6.x/6.1/peripherals.rst @@ -0,0 +1,76 @@ +Peripherals +=============== + +:link_to_translation:`zh_CN:[中文]` + +UART +----- + +UART Wakeup API Update +~~~~~~~~~~~~~~~~~~~~~~~~ + +In ESP-IDF v6.1, the legacy UART wakeup APIs :cpp:func:`uart_set_wakeup_threshold` and :cpp:func:`uart_get_wakeup_threshold` have been marked as deprecated and will be removed in future versions. These APIs only support the RXD edge threshold wakeup mode (Mode 0). + +The new unified API :cpp:func:`uart_wakeup_setup` provides a more flexible configuration approach and supports multiple wakeup modes: + +- **Mode 0 (UART_WK_MODE_ACTIVE_THRESH)** - Active edge threshold wakeup (corresponds to the legacy API functionality) +- **Mode 1 (UART_WK_MODE_FIFO_THRESH)** - RX FIFO threshold wakeup +- **Mode 2 (UART_WK_MODE_START_BIT)** - Start bit detection wakeup +- **Mode 3 (UART_WK_MODE_CHAR_SEQ)** - Character sequence detection wakeup + +**Migration Example:** + +Old code: + +.. code-block:: c + + // Set wakeup threshold + ESP_ERROR_CHECK(uart_set_wakeup_threshold(UART_NUM_0, 3)); + ESP_ERROR_CHECK(esp_sleep_enable_uart_wakeup(UART_NUM_0)); + + // Get wakeup threshold + int threshold; + ESP_ERROR_CHECK(uart_get_wakeup_threshold(UART_NUM_0, &threshold)); + +New code: + +.. code-block:: c + + #include "driver/uart_wakeup.h" + + // Configure active edge threshold wakeup mode (corresponds to legacy API functionality) + uart_wakeup_cfg_t wakeup_cfg = { + .wakeup_mode = UART_WK_MODE_ACTIVE_THRESH, + .rx_edge_threshold = 3, // Corresponds to the wakeup_threshold parameter of the legacy API + }; + ESP_ERROR_CHECK(uart_wakeup_setup(UART_NUM_0, &wakeup_cfg)); + ESP_ERROR_CHECK(esp_sleep_enable_uart_wakeup(UART_NUM_0)); + + // Note: The new API does not have a direct corresponding get function + // If you need to get the current configuration, you should save the configuration value yourself + +Major Changes +^^^^^^^^^^^^^^^^^^^ + +1. **API Replacement**: + - :cpp:func:`uart_set_wakeup_threshold` → :cpp:func:`uart_wakeup_setup` + - :cpp:func:`uart_get_wakeup_threshold` → Removed + +2. **Configuration Method**: + - Legacy API uses a simple integer parameter + - New API uses :cpp:type:`uart_wakeup_cfg_t` structure, supporting multiple wakeup modes + +3. **Header File**: + - New API requires including the ``driver/uart_wakeup.h`` header file + +4. **Feature Extension**: + - New API supports multiple wakeup modes, which can be selected based on chip capabilities + - The availability of different wakeup modes depends on the chip's SOC capabilities (determined by ``SOC_UART_WAKEUP_SUPPORT_XXX_MODE`` macros) + +Notes +^^^^^^^^^^ + +- Legacy API only supports Mode 0 (active edge threshold wakeup). When migrating, simply set ``wakeup_mode = UART_WK_MODE_ACTIVE_THRESH`` +- The ``rx_edge_threshold`` parameter of the new API has the same meaning as the ``wakeup_threshold`` parameter of the legacy API +- If you need to get the current wakeup configuration at runtime, it is recommended to save the configuration value when calling :cpp:func:`uart_wakeup_setup` +- Different chips may support different wakeup modes. Please refer to the :ref:`UART Wakeup (Light-sleep Only) ` section. diff --git a/docs/zh_CN/api-reference/system/sleep_modes.rst b/docs/zh_CN/api-reference/system/sleep_modes.rst index 149e3afd231..da93e2f2f2c 100644 --- a/docs/zh_CN/api-reference/system/sleep_modes.rst +++ b/docs/zh_CN/api-reference/system/sleep_modes.rst @@ -367,6 +367,8 @@ RTC 控制器中内嵌定时器，可用于在预定义的时间到达后唤醒 任何一个 IO 都可以用作外部输入管脚，将芯片从 Light-sleep 状态唤醒。调用 :cpp:func:`gpio_wakeup_enable` 函数可以将任意管脚单独配置为在高电平或低电平触发唤醒。此后，应调用 :cpp:func:`esp_sleep_enable_gpio_wakeup` 函数来启用此唤醒源。 +.. _uart_wakeup_light_sleep: + UART 唤醒（仅适用于 Light-sleep 模式） ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/zh_CN/migration-guides/index.rst b/docs/zh_CN/migration-guides/index.rst index 21890dec0b2..f8447add4b3 100644 --- a/docs/zh_CN/migration-guides/index.rst +++ b/docs/zh_CN/migration-guides/index.rst @@ -23,3 +23,4 @@ :maxdepth: 1 release-6.x/6.0/index + release-6.x/6.1/index diff --git a/docs/zh_CN/migration-guides/release-6.x/6.1/index.rst b/docs/zh_CN/migration-guides/release-6.x/6.1/index.rst new file mode 100644 index 00000000000..be3eb5b2994 --- /dev/null +++ b/docs/zh_CN/migration-guides/release-6.x/6.1/index.rst @@ -0,0 +1,9 @@ +从 6.0 迁移到 6.1 +------------------ + +:link_to_translation:`en:[English]` + +.. toctree:: + :maxdepth: 1 + + peripherals diff --git a/docs/zh_CN/migration-guides/release-6.x/6.1/peripherals.rst b/docs/zh_CN/migration-guides/release-6.x/6.1/peripherals.rst new file mode 100644 index 00000000000..0a718edac2d --- /dev/null +++ b/docs/zh_CN/migration-guides/release-6.x/6.1/peripherals.rst @@ -0,0 +1,76 @@ +外设驱动 +========= + +:link_to_translation:`en:[English]` + +UART +------ + +UART 唤醒 API 更新 +~~~~~~~~~~~~~~~~~~~~~ + +在 ESP-IDF v6.1 中，旧的 UART 唤醒 API :cpp:func:`uart_set_wakeup_threshold` 和 :cpp:func:`uart_get_wakeup_threshold` 已被标记为废弃，并将在未来版本中移除。这些 API 仅支持基于 RXD 边沿阈值的唤醒模式（Mode 0）。 + +新的统一 API :cpp:func:`uart_wakeup_setup` 提供了更灵活的配置方式，支持多种唤醒模式： + +- **Mode 0 (UART_WK_MODE_ACTIVE_THRESH)** - 边沿阈值唤醒（对应旧 API 的功能） +- **Mode 1 (UART_WK_MODE_FIFO_THRESH)** - RX FIFO 阈值唤醒 +- **Mode 2 (UART_WK_MODE_START_BIT)** - 起始位检测唤醒 +- **Mode 3 (UART_WK_MODE_CHAR_SEQ)** - 字符序列检测唤醒 + +**迁移示例：** + +旧代码： + +.. code-block:: c + + // 设置唤醒阈值 + ESP_ERROR_CHECK(uart_set_wakeup_threshold(UART_NUM_0, 3)); + ESP_ERROR_CHECK(esp_sleep_enable_uart_wakeup(UART_NUM_0)); + + // 获取唤醒阈值 + int threshold; + ESP_ERROR_CHECK(uart_get_wakeup_threshold(UART_NUM_0, &threshold)); + +新代码： + +.. code-block:: c + + #include "driver/uart_wakeup.h" + + // 配置边沿阈值唤醒模式（对应旧 API 的功能） + uart_wakeup_cfg_t wakeup_cfg = { + .wakeup_mode = UART_WK_MODE_ACTIVE_THRESH, + .rx_edge_threshold = 3, // 对应旧 API 的 wakeup_threshold 参数 + }; + ESP_ERROR_CHECK(uart_wakeup_setup(UART_NUM_0, &wakeup_cfg)); + ESP_ERROR_CHECK(esp_sleep_enable_uart_wakeup(UART_NUM_0)); + + // 注意：新 API 没有直接对应的获取函数 + // 如果需要获取当前配置，需要自行保存配置值 + +主要变化 +^^^^^^^^^^^ + +1. **API 替换**： + - :cpp:func:`uart_set_wakeup_threshold` → :cpp:func:`uart_wakeup_setup` + - :cpp:func:`uart_get_wakeup_threshold` → 已移除 + +2. **配置方式**： + - 旧 API 使用简单的整数参数 + - 新 API 使用 :cpp:type:`uart_wakeup_cfg_t` 结构体，支持多种唤醒模式 + +3. **头文件**： + - 新 API 需要包含 ``driver/uart_wakeup.h`` 头文件 + +4. **功能扩展**： + - 新 API 支持多种唤醒模式，可根据芯片能力选择使用 + - 不同唤醒模式的可用性取决于芯片的 SOC 能力（通过 ``SOC_UART_WAKEUP_SUPPORT_XXX_MODE`` 宏判断） + +注意事项 +^^^^^^^^^^^ + +- 旧 API 仅支持 Mode 0（边沿阈值唤醒），迁移时只需设置 ``wakeup_mode = UART_WK_MODE_ACTIVE_THRESH`` +- 新 API 的 ``rx_edge_threshold`` 参数与旧 API 的 ``wakeup_threshold`` 参数含义相同 +- 如果需要在运行时获取当前唤醒配置，建议在调用 :cpp:func:`uart_wakeup_setup` 时保存配置值 +- 不同芯片支持的唤醒模式可能不同，请参考 :ref:`UART 唤醒（仅适用于 Light-sleep 模式） ` 部分。