mirror of
https://github.com/espressif/esp-idf.git
synced 2026-10-02 11:10:54 +03:00
feat(doc): add uart wakeup migration guides
This commit is contained in:
hebinglin
BOT
@@ -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)
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
|
||||
@@ -23,3 +23,4 @@ ESP-IDF 6.x Migration Guide
|
||||
:maxdepth: 1
|
||||
|
||||
release-6.x/6.0/index
|
||||
release-6.x/6.1/index
|
||||
|
||||
@@ -0,0 +1,9 @@
|
||||
Migration from 6.0 to 6.1
|
||||
--------------------------
|
||||
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
peripherals
|
||||
@@ -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) <uart_wakeup_light_sleep>` section.
|
||||
@@ -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 模式）
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
|
||||
@@ -23,3 +23,4 @@
|
||||
:maxdepth: 1
|
||||
|
||||
release-6.x/6.0/index
|
||||
release-6.x/6.1/index
|
||||
|
||||
@@ -0,0 +1,9 @@
|
||||
从 6.0 迁移到 6.1
|
||||
------------------
|
||||
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
peripherals
|
||||
@@ -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 模式） <uart_wakeup_light_sleep>` 部分。
|
||||
Reference in New Issue
Block a user