From f0fd8fb0d081c224c4b9c38723e06bbf218f5f5e Mon Sep 17 00:00:00 2001 From: Chen Jichang Date: Tue, 21 Jul 2026 11:26:38 +0800 Subject: [PATCH] docs(pcnt): add gpio pull mode migration guide Closes https://github.com/espressif/esp-idf/issues/18862 --- docs/en/api-reference/peripherals/pcnt.rst | 10 +++++++--- .../migration-guides/release-6.x/6.0/peripherals.rst | 5 +++++ docs/zh_CN/api-reference/peripherals/pcnt.rst | 10 +++++++--- .../migration-guides/release-6.x/6.0/peripherals.rst | 5 +++++ examples/peripherals/pcnt/rotary_encoder/README.md | 7 +++++-- .../pcnt/rotary_encoder/main/Kconfig.projbuild | 8 ++++++++ .../rotary_encoder/main/rotary_encoder_example_main.c | 8 +++++++- 7 files changed, 44 insertions(+), 9 deletions(-) diff --git a/docs/en/api-reference/peripherals/pcnt.rst b/docs/en/api-reference/peripherals/pcnt.rst index 4f438422b63..32a794fac21 100644 --- a/docs/en/api-reference/peripherals/pcnt.rst +++ b/docs/en/api-reference/peripherals/pcnt.rst @@ -110,7 +110,7 @@ If a previously created PCNT channel is no longer needed, it is recommended to r .. note:: - In PCNT, the GPIOs involved can be reconfigured for pull-up or pull-down after initializing PCNT using functions such as :cpp:func:`gpio_pullup_en` and :cpp:func:`gpio_pullup_dis`. + The PCNT driver does not configure internal pull-up or pull-down resistors for the edge or level signal GPIOs. If your signal source needs a defined idle level, configure the GPIO pull mode explicitly with functions such as :cpp:func:`gpio_set_pull_mode`, :cpp:func:`gpio_pullup_en`, and :cpp:func:`gpio_pullup_dis`. .. _pcnt-setup-channel-actions: @@ -256,8 +256,12 @@ This function should be called when the unit is in the init state. Otherwise, it The PCNT unit can receive a clear signal from the GPIO. The parameters that can be configured for the clear signal are listed in :cpp:type:`pcnt_clear_signal_config_t`: - - :cpp:member:`pcnt_clear_signal_config_t::clear_signal_gpio_num` specify the GPIO numbers used by **clear** signal. The default active level is high, and the input mode is pull-down enabled. - - :cpp:member:`pcnt_clear_signal_config_t::flags::invert_clear_signal` is used to decide whether to invert the input signal before it going into PCNT hardware. The invert is done by GPIO matrix instead of PCNT hardware. The input mode is pull-up enabled when the input signal is inverted. + - :cpp:member:`pcnt_clear_signal_config_t::clear_signal_gpio_num` specifies the GPIO number used by the **clear** signal. The default active level is high. + - :cpp:member:`pcnt_clear_signal_config_t::flags::invert_clear_signal` is used to decide whether to invert the input signal before it goes into PCNT hardware. The inversion is done by the GPIO matrix instead of PCNT hardware. + + .. note:: + + The PCNT driver does not configure internal pull-up or pull-down resistors for the clear signal GPIO. If the clear signal requires a defined idle level, configure the GPIO pull mode explicitly with GPIO APIs. This signal acts in the same way as calling :cpp:func:`pcnt_unit_clear_count`, but is not subject to software latency, and is suitable for use in situations with low latency requirements. Also please note, the flip frequency of this signal can not be too high. diff --git a/docs/en/migration-guides/release-6.x/6.0/peripherals.rst b/docs/en/migration-guides/release-6.x/6.0/peripherals.rst index 2447bc97b72..b6abfca8a01 100644 --- a/docs/en/migration-guides/release-6.x/6.0/peripherals.rst +++ b/docs/en/migration-guides/release-6.x/6.0/peripherals.rst @@ -261,6 +261,11 @@ The legacy timer group driver ``driver/timer.h`` is deprecated since version 5.0 The legacy PCNT driver ``driver/pcnt.h`` is deprecated since version 5.0 (see :ref:`deprecate_pcnt_legacy_driver`). Starting from version 6.0, the legacy driver is completely removed. The new driver is placed in the :component:`esp_driver_pcnt`, and the header file path is ``driver/pulse_cnt.h``. + PCNT GPIO Pull-up/Pull-down Configuration + ----------------------------------------- + + The new PCNT driver no longer enables or disables internal pull-up/pull-down resistors on the GPIOs used for edge, level, or clear signals. If the input signal requires a defined idle level, configure the GPIO pull mode explicitly by calling the corresponding GPIO APIs. + .. only:: SOC_RMT_SUPPORTED Legacy RMT Driver is Removed diff --git a/docs/zh_CN/api-reference/peripherals/pcnt.rst b/docs/zh_CN/api-reference/peripherals/pcnt.rst index 983c5f8a414..bdbf2882fa5 100644 --- a/docs/zh_CN/api-reference/peripherals/pcnt.rst +++ b/docs/zh_CN/api-reference/peripherals/pcnt.rst @@ -110,7 +110,7 @@ PCNT 单元和通道分别用 :cpp:type:`pcnt_unit_handle_t` 与 :cpp:type:`pcnt .. note:: - PCNT 中涉及到的 GPIO 都可以在初始化完 PCNT 后, 通过 :cpp:func:`gpio_pullup_en` 和 :cpp:func:`gpio_pullup_dis` 等函数，重新进行上下拉等配置。 + PCNT 驱动不会为边沿信号或电平信号对应的 GPIO 配置内部上拉或下拉电阻。如果信号源需要确定的空闲电平，请使用 :cpp:func:`gpio_set_pull_mode`、:cpp:func:`gpio_pullup_en` 和 :cpp:func:`gpio_pullup_dis` 等函数显式配置 GPIO 上下拉模式。 .. _pcnt-setup-channel-actions: @@ -256,8 +256,12 @@ PCNT 单元的滤波器可滤除信号中的短时毛刺，:cpp:type:`pcnt_glitc PCNT 单元的可以接收来自 GPIO 的清零信号，:cpp:type:`pcnt_clear_signal_config_t` 中列出了清零信号的配置参数： - - :cpp:member:`pcnt_clear_signal_config_t::clear_signal_gpio_num` 用于指定 **清零** 信号对应的 GPIO 编号。默认有效电平为高，使能下拉输入。 - - :cpp:member:`pcnt_clear_signal_config_t::flags::invert_clear_signal` 用于确定信号在输入 PCNT 之前是否需要被翻转，信号翻转由 GPIO 矩阵 (不是 PCNT 单元) 执行。驱动会使能上拉输入，以确保信号在未连接时保持高电平。 + - :cpp:member:`pcnt_clear_signal_config_t::clear_signal_gpio_num` 用于指定 **清零** 信号对应的 GPIO 编号。默认有效电平为高。 + - :cpp:member:`pcnt_clear_signal_config_t::flags::invert_clear_signal` 用于确定信号在输入 PCNT 之前是否需要被翻转，信号翻转由 GPIO 矩阵（不是 PCNT 单元）执行。 + + .. note:: + + PCNT 驱动不会为清零信号对应的 GPIO 配置内部上拉或下拉电阻。如果清零信号需要确定的空闲电平，请使用 GPIO API 显式配置 GPIO 上下拉模式。 该输入信号的作用与调用 :cpp:func:`pcnt_unit_clear_count` 函数相同，但它不受软件延迟的限制，更适用于需要低延迟的场合。请注意，该信号的翻转频率不能太高。 diff --git a/docs/zh_CN/migration-guides/release-6.x/6.0/peripherals.rst b/docs/zh_CN/migration-guides/release-6.x/6.0/peripherals.rst index b2f30cc72a8..3552b3ac498 100644 --- a/docs/zh_CN/migration-guides/release-6.x/6.0/peripherals.rst +++ b/docs/zh_CN/migration-guides/release-6.x/6.0/peripherals.rst @@ -261,6 +261,11 @@ UART 旧版的 PCNT 驱动 ``driver/pcnt.h`` 在 5.0 的版本中就已经被弃用 （参考 :ref:`deprecate_pcnt_legacy_driver`）。从 6.0 版本开始，旧版驱动被完全移除。新驱动位于 :component:`esp_driver_pcnt` 组件中，头文件引用路径为 ``driver/pulse_cnt.h``。 + PCNT GPIO 上下拉配置 + ---------------------- + + 新版 PCNT 驱动不再对边沿信号、电平信号或清零信号所使用的 GPIO 自动使能或关闭内部上拉/下拉电阻。如果输入信号需要确定的空闲电平，请调用相应的 GPIO API 显式配置 GPIO 的上下拉模式。 + .. only:: SOC_RMT_SUPPORTED 旧版 RMT 驱动被移除 diff --git a/examples/peripherals/pcnt/rotary_encoder/README.md b/examples/peripherals/pcnt/rotary_encoder/README.md index 937274712d2..e86bf097404 100644 --- a/examples/peripherals/pcnt/rotary_encoder/README.md +++ b/examples/peripherals/pcnt/rotary_encoder/README.md @@ -33,25 +33,28 @@ B +-----+ +-----+ +-----+ * An ESP development board * EC11 rotary encoder (or other encoders which can produce quadrature waveforms) +* Pull-up resistors for the A and B signal lines. It is recommended to provide external pull-up resistors on the PCB. Connection : ```text +--------+ +---------------------------------+ | | | | - | A +--------------+ GPIO_A (internal pull up) | + | A +--------------+ GPIO_A (external pull up) | | | | | +-------+ | | | | | | GND +--------------+ GND | +-------+ | | | | | | | - | B +--------------+ GPIO_B (internal pull up) | + | B +--------------+ GPIO_B (external pull up) | | | | | +--------+ +---------------------------------+ ``` The GPIO used by the example can be changed according to your board by `EXAMPLE_EC11_GPIO_A` and `EXAMPLE_EC11_GPIO_B` in [source file](main/rotary_encoder_example_main.c). +The PCNT driver does not configure internal pull-up or pull-down resistors for the input GPIOs. If your board does not have external pull-up resistors for the EC11 A/B signal lines, enable `EXAMPLE_ENABLE_INTERNAL_PULL_UPS` from `menuconfig`, or call GPIO APIs such as `gpio_pullup_en()` or `gpio_set_pull_mode()` in your application. + ### Build and Flash By configuring one of the EC11 GPIO (e.g. `EXAMPLE_EC11_GPIO_A`) as a wake up source, you can make the rotary encoder wake the system from light sleep. This example can illustrate this feature if you enable the `EXAMPLE_WAKE_UP_LIGHT_SLEEP` from the menuconfig. diff --git a/examples/peripherals/pcnt/rotary_encoder/main/Kconfig.projbuild b/examples/peripherals/pcnt/rotary_encoder/main/Kconfig.projbuild index c7e6cd1f348..eb8d221c047 100644 --- a/examples/peripherals/pcnt/rotary_encoder/main/Kconfig.projbuild +++ b/examples/peripherals/pcnt/rotary_encoder/main/Kconfig.projbuild @@ -1,4 +1,12 @@ menu "Example Configuration" + config EXAMPLE_ENABLE_INTERNAL_PULL_UPS + bool "Enable internal pull-up resistors" + default "n" + help + Enable the internal pull-up resistors for the EC11 A/B signal GPIOs. + It is recommended to provide external pull-up resistors on the PCB. + Enable this option only when external pull-up resistors are not available. + config EXAMPLE_WAKE_UP_LIGHT_SLEEP bool "Configure the EC11 to wake up light sleep" default "n" diff --git a/examples/peripherals/pcnt/rotary_encoder/main/rotary_encoder_example_main.c b/examples/peripherals/pcnt/rotary_encoder/main/rotary_encoder_example_main.c index eea9e965a59..8a1cba2e117 100644 --- a/examples/peripherals/pcnt/rotary_encoder/main/rotary_encoder_example_main.c +++ b/examples/peripherals/pcnt/rotary_encoder/main/rotary_encoder_example_main.c @@ -1,5 +1,5 @@ /* - * SPDX-FileCopyrightText: 2010-2022 Espressif Systems (Shanghai) CO LTD + * SPDX-FileCopyrightText: 2010-2026 Espressif Systems (Shanghai) CO LTD * * SPDX-License-Identifier: CC0-1.0 */ @@ -46,6 +46,12 @@ void app_main(void) }; ESP_ERROR_CHECK(pcnt_unit_set_glitch_filter(pcnt_unit, &filter_config)); +#if CONFIG_EXAMPLE_ENABLE_INTERNAL_PULL_UPS + ESP_LOGI(TAG, "enable internal pull-up resistors"); + ESP_ERROR_CHECK(gpio_pullup_en(EXAMPLE_EC11_GPIO_A)); + ESP_ERROR_CHECK(gpio_pullup_en(EXAMPLE_EC11_GPIO_B)); +#endif + ESP_LOGI(TAG, "install pcnt channels"); pcnt_chan_config_t chan_a_config = { .edge_gpio_num = EXAMPLE_EC11_GPIO_A,