diff --git a/components/esp_hw_support/include/esp_sleep.h b/components/esp_hw_support/include/esp_sleep.h index bb5db22e7d..29c2af96d8 100644 --- a/components/esp_hw_support/include/esp_sleep.h +++ b/components/esp_hw_support/include/esp_sleep.h @@ -267,6 +267,59 @@ esp_err_t esp_sleep_enable_ext0_wakeup(gpio_num_t gpio_num, int level); * the pins during sleep. HOLD feature will be acted on the pin internally * before the system entering sleep, and this can further reduce power consumption. * + * @note Call this func will reset the previous ext1 configuration. + * + * @note This function will be deprecated in release/v6.0. Please switch to use `esp_sleep_enable_ext1_wakeup_io` and `esp_sleep_disable_ext1_wakeup_io` + * + * @param io_mask Bit mask of GPIO numbers which will cause wakeup. Only GPIOs + * which have RTC functionality can be used in this bit map. + * For different SoCs, the related GPIOs are: + * - ESP32: 0, 2, 4, 12-15, 25-27, 32-39 + * - ESP32-S2: 0-21 + * - ESP32-S3: 0-21 + * - ESP32-C6: 0-7 + * - ESP32-H2: 7-14 + * @param level_mode Select logic function used to determine wakeup condition: + * When target chip is ESP32: + * - ESP_EXT1_WAKEUP_ALL_LOW: wake up when all selected GPIOs are low + * - ESP_EXT1_WAKEUP_ANY_HIGH: wake up when any of the selected GPIOs is high + * When target chip is ESP32-S2, ESP32-S3, ESP32-C6 or ESP32-H2: + * - ESP_EXT1_WAKEUP_ANY_LOW: wake up when any of the selected GPIOs is low + * - ESP_EXT1_WAKEUP_ANY_HIGH: wake up when any of the selected GPIOs is high + * @return + * - ESP_OK on success + * - ESP_ERR_INVALID_ARG if io_mask is zero,, + * or mode is invalid + */ +esp_err_t esp_sleep_enable_ext1_wakeup(uint64_t io_mask, esp_sleep_ext1_wakeup_mode_t level_mode); + +/** + * @brief Enable ext1 wakeup pins with IO masks. + * + * This will append selected IOs to the wakeup IOs, it will not reset previously enabled IOs. + * To reset specific previously enabled IOs, call esp_sleep_disable_ext1_wakeup_io with the io_mask. + * To reset all the enabled IOs, call esp_sleep_disable_ext1_wakeup_io(0). + * + * This function uses external wakeup feature of RTC controller. + * It will work even if RTC peripherals are shut down during sleep. + * + * This feature can monitor any number of pins which are in RTC IOs. + * Once selected pins go into the state given by level_mode argument, + * the chip will be woken up. + * + * @note This function does not modify pin configuration. The pins are + * configured in esp_deep_sleep_start/esp_light_sleep_start, + * immediately before entering sleep mode. + * + * @note Internal pullups and pulldowns don't work when RTC peripherals are + * shut down. In this case, external resistors need to be added. + * Alternatively, RTC peripherals (and pullups/pulldowns) may be + * kept enabled using esp_sleep_pd_config function. If we turn off the + * ``RTC_PERIPH`` domain or certain chips lack the ``RTC_PERIPH`` domain, + * we will use the HOLD feature to maintain the pull-up and pull-down on + * the pins during sleep. HOLD feature will be acted on the pin internally + * before the system entering sleep, and this can further reduce power consumption. + * * @param io_mask Bit mask of GPIO numbers which will cause wakeup. Only GPIOs * which have RTC functionality can be used in this bit map. * For different SoCs, the related GPIOs are: @@ -286,8 +339,28 @@ esp_err_t esp_sleep_enable_ext0_wakeup(gpio_num_t gpio_num, int level); * - ESP_OK on success * - ESP_ERR_INVALID_ARG if any of the selected GPIOs is not an RTC GPIO, * or mode is invalid + * - ESP_ERR_NOT_ALLOWED when wakeup level will become different between + * ext1 IOs if !SOC_PM_SUPPORT_EXT1_WAKEUP_MODE_PER_PIN */ -esp_err_t esp_sleep_enable_ext1_wakeup(uint64_t io_mask, esp_sleep_ext1_wakeup_mode_t level_mode); +esp_err_t esp_sleep_enable_ext1_wakeup_io(uint64_t io_mask, esp_sleep_ext1_wakeup_mode_t level_mode); + +/** + * @brief Disable ext1 wakeup pins with IO masks. This will remove selected IOs from the wakeup IOs. + * @param io_mask Bit mask of GPIO numbers which will cause wakeup. Only GPIOs + * which have RTC functionality can be used in this bit map. + * If value is zero, this func will remove all previous ext1 configuration. + * For different SoCs, the related GPIOs are: + * - ESP32: 0, 2, 4, 12-15, 25-27, 32-39 + * - ESP32-S2: 0-21 + * - ESP32-S3: 0-21 + * - ESP32-C6: 0-7 + * - ESP32-H2: 7-14 + * + * @return + * - ESP_OK on success + * - ESP_ERR_INVALID_ARG if any of the selected GPIOs is not an RTC GPIO. + */ +esp_err_t esp_sleep_disable_ext1_wakeup_io(uint64_t io_mask); #if SOC_PM_SUPPORT_EXT1_WAKEUP_MODE_PER_PIN /** @@ -327,7 +400,9 @@ esp_err_t esp_sleep_enable_ext1_wakeup(uint64_t io_mask, esp_sleep_ext1_wakeup_m * - ESP_ERR_INVALID_ARG if any of the selected GPIOs is not an RTC GPIO, * or mode is invalid */ -esp_err_t esp_sleep_enable_ext1_wakeup_with_level_mask(uint64_t io_mask, uint64_t level_mask); +esp_err_t esp_sleep_enable_ext1_wakeup_with_level_mask(uint64_t io_mask, uint64_t level_mask) +__attribute__((deprecated("please use 'esp_sleep_enable_ext1_wakeup_io' and 'esp_sleep_disable_ext1_wakeup_io' instead"))); + #endif // SOC_PM_SUPPORT_EXT1_WAKEUP_MODE_PER_PIN #endif // SOC_PM_SUPPORT_EXT1_WAKEUP diff --git a/components/esp_hw_support/sleep_modes.c b/components/esp_hw_support/sleep_modes.c index 4d03e5eecb..cefe36448c 100644 --- a/components/esp_hw_support/sleep_modes.c +++ b/components/esp_hw_support/sleep_modes.c @@ -634,11 +634,13 @@ static esp_err_t IRAM_ATTR esp_sleep_start(uint32_t pd_flags, esp_sleep_mode_t m if (s_config.wakeup_triggers & RTC_EXT0_TRIG_EN) { ext0_wakeup_prepare(); } + // for !(s_config.wakeup_triggers & RTC_EXT0_TRIG_EN), ext0 wakeup will be turned off in hardware in the real call to sleep #endif #if SOC_PM_SUPPORT_EXT1_WAKEUP if (s_config.wakeup_triggers & RTC_EXT1_TRIG_EN) { ext1_wakeup_prepare(); } + // for !(s_config.wakeup_triggers & RTC_EXT1_TRIG_EN), ext1 wakeup will be turned off in hardware in the real call to sleep #endif #if SOC_GPIO_SUPPORT_DEEPSLEEP_WAKEUP @@ -1471,12 +1473,25 @@ static void ext0_wakeup_prepare(void) rtcio_hal_function_select(rtc_gpio_num, RTCIO_LL_FUNC_RTC); rtcio_hal_input_enable(rtc_gpio_num); } + #endif // SOC_PM_SUPPORT_EXT0_WAKEUP #if SOC_PM_SUPPORT_EXT1_WAKEUP esp_err_t esp_sleep_enable_ext1_wakeup(uint64_t io_mask, esp_sleep_ext1_wakeup_mode_t level_mode) { - if (level_mode > ESP_EXT1_WAKEUP_ANY_HIGH) { + if (io_mask == 0 && level_mode > ESP_EXT1_WAKEUP_ANY_HIGH) { + return ESP_ERR_INVALID_ARG; + } + // Reset all EXT1 configs + esp_sleep_disable_ext1_wakeup_io(0); + + return esp_sleep_enable_ext1_wakeup_io(io_mask, level_mode); +} + + +esp_err_t esp_sleep_enable_ext1_wakeup_io(uint64_t io_mask, esp_sleep_ext1_wakeup_mode_t level_mode) +{ + if (io_mask == 0 && level_mode > ESP_EXT1_WAKEUP_ANY_HIGH) { return ESP_ERR_INVALID_ARG; } // Translate bit map of GPIO numbers into the bit map of RTC IO numbers @@ -1491,16 +1506,61 @@ esp_err_t esp_sleep_enable_ext1_wakeup(uint64_t io_mask, esp_sleep_ext1_wakeup_m } rtc_gpio_mask |= BIT(rtc_io_number_get(gpio)); } - s_config.ext1_rtc_gpio_mask = rtc_gpio_mask; + +#if !SOC_PM_SUPPORT_EXT1_WAKEUP_MODE_PER_PIN + uint32_t ext1_rtc_gpio_mask = 0; + uint32_t ext1_trigger_mode = 0; + + ext1_rtc_gpio_mask = s_config.ext1_rtc_gpio_mask | rtc_gpio_mask; if (level_mode) { - s_config.ext1_trigger_mode = rtc_gpio_mask; + ext1_trigger_mode = s_config.ext1_trigger_mode | rtc_gpio_mask; } else { - s_config.ext1_trigger_mode = 0; + ext1_trigger_mode = s_config.ext1_trigger_mode & (~rtc_gpio_mask); + } + if (((ext1_rtc_gpio_mask & ext1_trigger_mode) != ext1_rtc_gpio_mask) && + ((ext1_rtc_gpio_mask & ext1_trigger_mode) != 0)) { + return ESP_ERR_NOT_ALLOWED; + } +#endif + + s_config.ext1_rtc_gpio_mask |= rtc_gpio_mask; + if (level_mode) { + s_config.ext1_trigger_mode |= rtc_gpio_mask; + } else { + s_config.ext1_trigger_mode &= (~rtc_gpio_mask); } s_config.wakeup_triggers |= RTC_EXT1_TRIG_EN; return ESP_OK; } +esp_err_t esp_sleep_disable_ext1_wakeup_io(uint64_t io_mask) +{ + if (io_mask == 0) { + s_config.ext1_rtc_gpio_mask = 0; + s_config.ext1_trigger_mode = 0; + } else { + // Translate bit map of GPIO numbers into the bit map of RTC IO numbers + uint32_t rtc_gpio_mask = 0; + for (int gpio = 0; io_mask; ++gpio, io_mask >>= 1) { + if ((io_mask & 1) == 0) { + continue; + } + if (!esp_sleep_is_valid_wakeup_gpio(gpio)) { + ESP_LOGE(TAG, "Not an RTC IO Considering io_mask: GPIO%d", gpio); + return ESP_ERR_INVALID_ARG; + } + rtc_gpio_mask |= BIT(rtc_io_number_get(gpio)); + } + s_config.ext1_rtc_gpio_mask &= (~rtc_gpio_mask); + s_config.ext1_trigger_mode &= (~rtc_gpio_mask); + } + + if (s_config.ext1_rtc_gpio_mask == 0) { + s_config.wakeup_triggers &= (~RTC_EXT1_TRIG_EN); + } + return ESP_OK; +} + #if SOC_PM_SUPPORT_EXT1_WAKEUP_MODE_PER_PIN esp_err_t esp_sleep_enable_ext1_wakeup_with_level_mask(uint64_t io_mask, uint64_t level_mask) { diff --git a/components/esp_pm/include/esp_pm.h b/components/esp_pm/include/esp_pm.h index b7f7d045fd..cb6919084b 100644 --- a/components/esp_pm/include/esp_pm.h +++ b/components/esp_pm/include/esp_pm.h @@ -55,6 +55,7 @@ typedef enum { * Argument is unused and should be set to 0. */ ESP_PM_NO_LIGHT_SLEEP, + ESP_PM_LOCK_MAX, } esp_pm_lock_type_t; /** @@ -100,10 +101,13 @@ typedef struct esp_pm_lock* esp_pm_lock_handle_t; * @param[out] out_handle handle returned from this function. Use this handle when calling * esp_pm_lock_delete, esp_pm_lock_acquire, esp_pm_lock_release. * Must not be NULL. + * + * @note If the lock_type argument is not valid, it will cause an abort. + * * @return * - ESP_OK on success * - ESP_ERR_NO_MEM if the lock structure can not be allocated - * - ESP_ERR_INVALID_ARG if out_handle is NULL or type argument is not valid + * - ESP_ERR_INVALID_ARG if out_handle is NULL * - ESP_ERR_NOT_SUPPORTED if CONFIG_PM_ENABLE is not enabled in sdkconfig */ esp_err_t esp_pm_lock_create(esp_pm_lock_type_t lock_type, int arg, diff --git a/components/esp_pm/test_apps/esp_pm/main/test_pm.c b/components/esp_pm/test_apps/esp_pm/main/test_pm.c index 5245c7527a..14c1d5c2cb 100644 --- a/components/esp_pm/test_apps/esp_pm/main/test_pm.c +++ b/components/esp_pm/test_apps/esp_pm/main/test_pm.c @@ -182,7 +182,7 @@ TEST_CASE("Can wake up from automatic light sleep by GPIO", "[pm][ignore]") rtc_gpio_set_level(ext1_wakeup_gpio, 0); /* Enable wakeup */ - TEST_ESP_OK(esp_sleep_enable_ext1_wakeup(1ULL << ext1_wakeup_gpio, ESP_EXT1_WAKEUP_ANY_HIGH)); + TEST_ESP_OK(esp_sleep_enable_ext1_wakeup_io(1ULL << ext1_wakeup_gpio, ESP_EXT1_WAKEUP_ANY_HIGH)); /* To simplify test environment, we'll use a ULP program to set GPIO high */ ulp_insn_t ulp_code[] = { diff --git a/components/esp_system/test_apps/esp_system_unity_tests/main/test_sleep.c b/components/esp_system/test_apps/esp_system_unity_tests/main/test_sleep.c index 22ec2f21af..d830f3f27c 100644 --- a/components/esp_system/test_apps/esp_system_unity_tests/main/test_sleep.c +++ b/components/esp_system/test_apps/esp_system_unity_tests/main/test_sleep.c @@ -416,7 +416,7 @@ TEST_CASE("wake up using ext1 when RTC_PERIPH is off (13 high)", "[deepsleep][ig { // This test needs external pulldown ESP_ERROR_CHECK(rtc_gpio_init(GPIO_NUM_13)); - ESP_ERROR_CHECK(esp_sleep_enable_ext1_wakeup(BIT(GPIO_NUM_13), ESP_EXT1_WAKEUP_ANY_HIGH)); + ESP_ERROR_CHECK(esp_sleep_enable_ext1_wakeup_io(BIT(GPIO_NUM_13), ESP_EXT1_WAKEUP_ANY_HIGH)); esp_deep_sleep_start(); } @@ -425,9 +425,9 @@ TEST_CASE("wake up using ext1 when RTC_PERIPH is off (13 low)", "[deepsleep][ign // This test needs external pullup ESP_ERROR_CHECK(rtc_gpio_init(GPIO_NUM_13)); #if CONFIG_IDF_TARGET_ESP32 - ESP_ERROR_CHECK(esp_sleep_enable_ext1_wakeup(BIT(GPIO_NUM_13), ESP_EXT1_WAKEUP_ALL_LOW)); + ESP_ERROR_CHECK(esp_sleep_enable_ext1_wakeup_io(BIT(GPIO_NUM_13), ESP_EXT1_WAKEUP_ALL_LOW)); #else - ESP_ERROR_CHECK(esp_sleep_enable_ext1_wakeup(BIT(GPIO_NUM_13), ESP_EXT1_WAKEUP_ANY_LOW)); + ESP_ERROR_CHECK(esp_sleep_enable_ext1_wakeup_io(BIT(GPIO_NUM_13), ESP_EXT1_WAKEUP_ANY_LOW)); #endif esp_deep_sleep_start(); } @@ -438,7 +438,7 @@ TEST_CASE("wake up using ext1 when RTC_PERIPH is on (13 high)", "[deepsleep][ign ESP_ERROR_CHECK(gpio_pullup_dis(GPIO_NUM_13)); ESP_ERROR_CHECK(gpio_pulldown_en(GPIO_NUM_13)); ESP_ERROR_CHECK(esp_sleep_pd_config(ESP_PD_DOMAIN_RTC_PERIPH, ESP_PD_OPTION_ON)); - ESP_ERROR_CHECK(esp_sleep_enable_ext1_wakeup(BIT(GPIO_NUM_13), ESP_EXT1_WAKEUP_ANY_HIGH)); + ESP_ERROR_CHECK(esp_sleep_enable_ext1_wakeup_io(BIT(GPIO_NUM_13), ESP_EXT1_WAKEUP_ANY_HIGH)); esp_deep_sleep_start(); } @@ -449,9 +449,9 @@ TEST_CASE("wake up using ext1 when RTC_PERIPH is on (13 low)", "[deepsleep][igno ESP_ERROR_CHECK(gpio_pulldown_dis(GPIO_NUM_13)); ESP_ERROR_CHECK(esp_sleep_pd_config(ESP_PD_DOMAIN_RTC_PERIPH, ESP_PD_OPTION_ON)); #if CONFIG_IDF_TARGET_ESP32 - ESP_ERROR_CHECK(esp_sleep_enable_ext1_wakeup(BIT(GPIO_NUM_13), ESP_EXT1_WAKEUP_ALL_LOW)); + ESP_ERROR_CHECK(esp_sleep_enable_ext1_wakeup_io(BIT(GPIO_NUM_13), ESP_EXT1_WAKEUP_ALL_LOW)); #else - ESP_ERROR_CHECK(esp_sleep_enable_ext1_wakeup(BIT(GPIO_NUM_13), ESP_EXT1_WAKEUP_ANY_LOW)); + ESP_ERROR_CHECK(esp_sleep_enable_ext1_wakeup_io(BIT(GPIO_NUM_13), ESP_EXT1_WAKEUP_ANY_LOW)); #endif esp_deep_sleep_start(); } diff --git a/components/hal/esp32/include/hal/rtc_io_ll.h b/components/hal/esp32/include/hal/rtc_io_ll.h index d92ab124fd..d10deaa96b 100644 --- a/components/hal/esp32/include/hal/rtc_io_ll.h +++ b/components/hal/esp32/include/hal/rtc_io_ll.h @@ -360,7 +360,7 @@ static inline void rtcio_ll_disable_sleep_setting(int rtcio_num) } /** - * Set specific logic level on an RTC IO pin as a wakeup trigger. + * Set specific logic level on an RTC IO pin as a ext0 wakeup trigger. * * @param rtcio_num The index of rtcio. 0 ~ MAX(rtcio). * @param level Logic level (0) diff --git a/components/hal/esp32c6/include/hal/lp_aon_ll.h b/components/hal/esp32c6/include/hal/lp_aon_ll.h index ef77b7561d..93dc73a9f7 100644 --- a/components/hal/esp32c6/include/hal/lp_aon_ll.h +++ b/components/hal/esp32c6/include/hal/lp_aon_ll.h @@ -47,21 +47,14 @@ static inline void lp_aon_ll_ext1_clear_wakeup_status(void) */ static inline void lp_aon_ll_ext1_set_wakeup_pins(uint32_t io_mask, uint32_t level_mask) { - uint32_t wakeup_sel_mask = HAL_FORCE_READ_U32_REG_FIELD(LP_AON.ext_wakeup_cntl, ext_wakeup_sel); - wakeup_sel_mask |= io_mask; - HAL_FORCE_MODIFY_U32_REG_FIELD(LP_AON.ext_wakeup_cntl, ext_wakeup_sel, wakeup_sel_mask); - - uint32_t wakeup_level_mask = HAL_FORCE_READ_U32_REG_FIELD(LP_AON.ext_wakeup_cntl, ext_wakeup_lv); - wakeup_level_mask |= io_mask & level_mask; - wakeup_level_mask &= ~(io_mask & ~level_mask); - - HAL_FORCE_MODIFY_U32_REG_FIELD(LP_AON.ext_wakeup_cntl, ext_wakeup_lv, wakeup_level_mask); + HAL_FORCE_MODIFY_U32_REG_FIELD(LP_AON.ext_wakeup_cntl, ext_wakeup_sel, io_mask); + HAL_FORCE_MODIFY_U32_REG_FIELD(LP_AON.ext_wakeup_cntl, ext_wakeup_lv, level_mask); } /** * @brief Clear all ext1 wakup-source setting */ -static inline void lp_aon_ll_ext1_clear_wakeup_pins(void) +static inline void lp_aon_ll_ext1_clear_wakeup_pins(void) { HAL_FORCE_MODIFY_U32_REG_FIELD(LP_AON.ext_wakeup_cntl, ext_wakeup_sel, 0); } diff --git a/components/hal/esp32h2/include/hal/lp_aon_ll.h b/components/hal/esp32h2/include/hal/lp_aon_ll.h index 38492a1728..53e1f1fa5d 100644 --- a/components/hal/esp32h2/include/hal/lp_aon_ll.h +++ b/components/hal/esp32h2/include/hal/lp_aon_ll.h @@ -47,21 +47,14 @@ static inline void lp_aon_ll_ext1_clear_wakeup_status(void) */ static inline void lp_aon_ll_ext1_set_wakeup_pins(uint32_t io_mask, uint32_t level_mask) { - uint32_t wakeup_sel_mask = HAL_FORCE_READ_U32_REG_FIELD(LP_AON.ext_wakeup_cntl, ext_wakeup_sel); - wakeup_sel_mask |= io_mask; - HAL_FORCE_MODIFY_U32_REG_FIELD(LP_AON.ext_wakeup_cntl, ext_wakeup_sel, wakeup_sel_mask); - - uint32_t wakeup_level_mask = HAL_FORCE_READ_U32_REG_FIELD(LP_AON.ext_wakeup_cntl, ext_wakeup_lv); - wakeup_level_mask |= io_mask & level_mask; - wakeup_level_mask &= ~(io_mask & ~level_mask); - - HAL_FORCE_MODIFY_U32_REG_FIELD(LP_AON.ext_wakeup_cntl, ext_wakeup_lv, wakeup_level_mask); + HAL_FORCE_MODIFY_U32_REG_FIELD(LP_AON.ext_wakeup_cntl, ext_wakeup_sel, io_mask); + HAL_FORCE_MODIFY_U32_REG_FIELD(LP_AON.ext_wakeup_cntl, ext_wakeup_lv, level_mask); } /** * @brief Clear all ext1 wakup-source setting */ -static inline void lp_aon_ll_ext1_clear_wakeup_pins(void) +static inline void lp_aon_ll_ext1_clear_wakeup_pins(void) { HAL_FORCE_MODIFY_U32_REG_FIELD(LP_AON.ext_wakeup_cntl, ext_wakeup_sel, 0); } diff --git a/components/hal/include/hal/rtc_io_hal.h b/components/hal/include/hal/rtc_io_hal.h index 2e6d50ca81..67b2201bca 100644 --- a/components/hal/include/hal/rtc_io_hal.h +++ b/components/hal/include/hal/rtc_io_hal.h @@ -259,7 +259,7 @@ void rtcio_hal_set_direction_in_sleep(int rtcio_num, rtc_gpio_mode_t mode); #define rtcio_hal_wakeup_disable(rtcio_num) rtcio_ll_wakeup_disable(rtcio_num) /** - * Set specific logic level on an RTC IO pin as a wakeup trigger. + * Set specific logic level on an RTC IO pin as a ext0 wakeup trigger. * * @param rtcio_num The index of rtcio. 0 ~ SOC_RTCIO_PIN_COUNT. * @param level Logic level (0) diff --git a/docs/en/api-reference/system/sleep_modes.rst b/docs/en/api-reference/system/sleep_modes.rst index 9ec9ebc836..0f36b12e1d 100644 --- a/docs/en/api-reference/system/sleep_modes.rst +++ b/docs/en/api-reference/system/sleep_modes.rst @@ -220,7 +220,7 @@ RTC peripherals or RTC memories do not need to be powered on during sleep in thi External Wakeup (``ext1``) ^^^^^^^^^^^^^^^^^^^^^^^^^^ - The RTC controller contains the logic to trigger wakeup using multiple RTC GPIOs. One of the following two logic functions can be used to trigger general ext1 wakeup: + The RTC controller contains the logic to trigger wakeup using multiple RTC GPIOs. One of the following two logic functions can be used to trigger ext1 wakeup: .. only:: esp32 @@ -248,11 +248,13 @@ RTC peripherals or RTC memories do not need to be powered on during sleep in thi gpio_pullup_dis(gpio_num); gpio_pulldown_en(gpio_num); - :cpp:func:`esp_sleep_enable_ext1_wakeup` function can be used to enable this wakeup source for general ext1 wakeup. + :cpp:func:`esp_sleep_enable_ext1_wakeup_io` function can be used to append ext1 wakeup IO and set corresponding wakeup level. + + :cpp:func:`esp_sleep_disable_ext1_wakeup_io` function can be used to remove ext1 wakeup IO. .. only:: SOC_PM_SUPPORT_EXT1_WAKEUP_MODE_PER_PIN - Besides the above mentioned general ext1 wakeup, the RTC controller also contains a more powerful logic to trigger wakeup using multiple RTC GPIOs with a customized RTC IO wakeup level bitmap. This can be configured with :cpp:func`esp_sleep_enable_ext1_wakeup_with_level_mask`. + The RTC controller also supports triggering wakeup, allowing configurable IO to use different wakeup levels simultaneously. This can be configured with :cpp:func`esp_sleep_enable_ext1_wakeup_io`. .. warning:: diff --git a/docs/en/migration-guides/release-5.x/5.3/index.rst b/docs/en/migration-guides/release-5.x/5.3/index.rst index caccc54187..b4717423b3 100644 --- a/docs/en/migration-guides/release-5.x/5.3/index.rst +++ b/docs/en/migration-guides/release-5.x/5.3/index.rst @@ -7,3 +7,4 @@ Migration from 5.2 to 5.3 :maxdepth: 1 peripherals + system diff --git a/docs/en/migration-guides/release-5.x/5.3/system.rst b/docs/en/migration-guides/release-5.x/5.3/system.rst new file mode 100644 index 0000000000..32c4f08b69 --- /dev/null +++ b/docs/en/migration-guides/release-5.x/5.3/system.rst @@ -0,0 +1,9 @@ +System +====== + +:link_to_translation:`zh_CN:[中文]` + +Power Management +----------------------- + +* ``esp_sleep_enable_ext1_wakeup_with_level_mask`` is deprecated, use ``esp_sleep_enable_ext1_wakeup_io`` and ``esp_sleep_disable_ext1_wakeup_io`` instead. diff --git a/docs/zh_CN/api-reference/system/sleep_modes.rst b/docs/zh_CN/api-reference/system/sleep_modes.rst index 6cef60238e..c322424e77 100644 --- a/docs/zh_CN/api-reference/system/sleep_modes.rst +++ b/docs/zh_CN/api-reference/system/sleep_modes.rst @@ -220,7 +220,7 @@ RTC 控制器中内嵌定时器，可用于在预定义的时间到达后唤醒 外部唤醒 (``ext1``) ^^^^^^^^^^^^^^^^^^^^^^ - RTC 控制器中包含使用多个 RTC GPIO 触发唤醒的逻辑。从以下两个逻辑函数中任选其一，均可触发普通 ext1 唤醒： + RTC 控制器中包含使用多个 RTC GPIO 触发唤醒的逻辑。从以下两个逻辑函数中任选其一，均可触发 ext1 唤醒： .. only:: esp32 @@ -248,11 +248,13 @@ RTC 控制器中内嵌定时器，可用于在预定义的时间到达后唤醒 gpio_pullup_dis(gpio_num); gpio_pulldown_en(gpio_num); - 可调用 :cpp:func:`esp_sleep_enable_ext1_wakeup` 函数来启用普通 ext1 唤醒。 + 可调用 :cpp:func:`esp_sleep_enable_ext1_wakeup_io` 函数可用于增加 ext1 唤醒 IO 并设置相应的唤醒电平。 + + 可调用 :cpp:func:`esp_sleep_disable_ext1_wakeup_io` 函数可用于移除 ext1 唤醒 IO。 .. only:: SOC_PM_SUPPORT_EXT1_WAKEUP_MODE_PER_PIN - 除了上述提到的普通 ext1 唤醒之外，当前的 RTC 控制器也包含更强大的逻辑，可以使用多个 RTC GPIO 并根据自定义的 RTC IO 唤醒电平位图来唤醒。这可以通过:cpp:func:`esp_sleep_enable_ext1_wakeup_with_level_mask` 函数来进行配置。 + 当前的 RTC 控制器也包含更强大的逻辑，允许配置的 IO 同时使用不同的唤醒电平。这可以通过:cpp:func:`esp_sleep_enable_ext1_wakeup_io` 函数来进行配置。 .. warning:: diff --git a/docs/zh_CN/migration-guides/release-5.x/5.3/index.rst b/docs/zh_CN/migration-guides/release-5.x/5.3/index.rst index 25aeb7dff3..40d26176f4 100644 --- a/docs/zh_CN/migration-guides/release-5.x/5.3/index.rst +++ b/docs/zh_CN/migration-guides/release-5.x/5.3/index.rst @@ -7,3 +7,4 @@ :maxdepth: 1 peripherals + system diff --git a/docs/zh_CN/migration-guides/release-5.x/5.3/system.rst b/docs/zh_CN/migration-guides/release-5.x/5.3/system.rst new file mode 100644 index 0000000000..d984c08a77 --- /dev/null +++ b/docs/zh_CN/migration-guides/release-5.x/5.3/system.rst @@ -0,0 +1 @@ +.. include:: ../../../../en/migration-guides/release-5.x/5.3/system.rst \ No newline at end of file diff --git a/examples/bluetooth/nimble/throughput_app/blecent_throughput/components/cmd_system/cmd_system.c b/examples/bluetooth/nimble/throughput_app/blecent_throughput/components/cmd_system/cmd_system.c index 060cd61c31..59fe12c6e8 100644 --- a/examples/bluetooth/nimble/throughput_app/blecent_throughput/components/cmd_system/cmd_system.c +++ b/examples/bluetooth/nimble/throughput_app/blecent_throughput/components/cmd_system/cmd_system.c @@ -217,7 +217,7 @@ static int deep_sleep(int argc, char **argv) io_num, level ? "HIGH" : "LOW"); #if SOC_PM_SUPPORT_EXT1_WAKEUP - ESP_ERROR_CHECK( esp_sleep_enable_ext1_wakeup(1ULL << io_num, level) ); + ESP_ERROR_CHECK( esp_sleep_enable_ext1_wakeup_io(1ULL << io_num, level) ); #endif } diff --git a/examples/openthread/ot_sleepy_device/deep_sleep/main/esp_ot_sleepy_device.c b/examples/openthread/ot_sleepy_device/deep_sleep/main/esp_ot_sleepy_device.c index 4c2e592485..64659f6db9 100644 --- a/examples/openthread/ot_sleepy_device/deep_sleep/main/esp_ot_sleepy_device.c +++ b/examples/openthread/ot_sleepy_device/deep_sleep/main/esp_ot_sleepy_device.c @@ -150,8 +150,8 @@ static void ot_deep_sleep_init(void) const uint64_t gpio_wakeup_pin_mask = 1ULL << gpio_wakeup_pin; // The configuration mode depends on your hardware design. // Since the BOOT button is connected to a pull-up resistor, the wake-up mode is configured as LOW. - const uint64_t ext_wakeup_mode = 0 << gpio_wakeup_pin; - ESP_ERROR_CHECK(esp_sleep_enable_ext1_wakeup_with_level_mask(gpio_wakeup_pin_mask, ext_wakeup_mode)); + const uint64_t ext_wakeup_mode = 0; + ESP_ERROR_CHECK(esp_sleep_enable_ext1_wakeup_io(gpio_wakeup_pin_mask, ext_wakeup_mode)); // Also these two GPIO configurations are also depended on the hardware design. // The BOOT button is connected to the pull-up resistor, so enable the pull-up mode and disable the pull-down mode. diff --git a/examples/system/console/advanced/components/cmd_system/cmd_system_sleep.c b/examples/system/console/advanced/components/cmd_system/cmd_system_sleep.c index e656e5207e..0dd3ef9a18 100644 --- a/examples/system/console/advanced/components/cmd_system/cmd_system_sleep.c +++ b/examples/system/console/advanced/components/cmd_system/cmd_system_sleep.c @@ -82,7 +82,7 @@ static int deep_sleep(int argc, char **argv) ESP_LOGI(TAG, "Enabling wakeup on GPIO%d, wakeup on %s level", io_num, level ? "HIGH" : "LOW"); - ESP_ERROR_CHECK( esp_sleep_enable_ext1_wakeup(1ULL << io_num, level) ); + ESP_ERROR_CHECK( esp_sleep_enable_ext1_wakeup_io(1ULL << io_num, level) ); ESP_LOGE(TAG, "GPIO wakeup from deep sleep currently unsupported on ESP32-C3"); } #endif // SOC_PM_SUPPORT_EXT1_WAKEUP diff --git a/examples/system/deep_sleep/main/ext_wakeup.c b/examples/system/deep_sleep/main/ext_wakeup.c index de329b6973..35dcaf4b94 100644 --- a/examples/system/deep_sleep/main/ext_wakeup.c +++ b/examples/system/deep_sleep/main/ext_wakeup.c @@ -40,12 +40,10 @@ void example_deep_sleep_register_ext1_wakeup(void) printf("Enabling EXT1 wakeup on pins GPIO%d, GPIO%d\n", ext_wakeup_pin_1, ext_wakeup_pin_2); #if SOC_PM_SUPPORT_EXT1_WAKEUP_MODE_PER_PIN - const uint64_t ext_wakeup_mode = CONFIG_EXAMPLE_EXT1_WAKEUP_MODE_PIN_1 << ext_wakeup_pin_1 | \ - CONFIG_EXAMPLE_EXT1_WAKEUP_MODE_PIN_2 << ext_wakeup_pin_2; - ESP_ERROR_CHECK(esp_sleep_enable_ext1_wakeup_with_level_mask(ext_wakeup_pin_1_mask | ext_wakeup_pin_2_mask, ext_wakeup_mode)); + ESP_ERROR_CHECK(esp_sleep_enable_ext1_wakeup_io(ext_wakeup_pin_1_mask, CONFIG_EXAMPLE_EXT1_WAKEUP_MODE_PIN_1)); + ESP_ERROR_CHECK(esp_sleep_enable_ext1_wakeup_io(ext_wakeup_pin_2_mask, CONFIG_EXAMPLE_EXT1_WAKEUP_MODE_PIN_2)); #else - const esp_sleep_ext1_wakeup_mode_t ext_wakeup_mode = CONFIG_EXAMPLE_EXT1_WAKEUP_MODE; - ESP_ERROR_CHECK(esp_sleep_enable_ext1_wakeup(ext_wakeup_pin_1_mask | ext_wakeup_pin_2_mask, ext_wakeup_mode)); + ESP_ERROR_CHECK(esp_sleep_enable_ext1_wakeup_io(ext_wakeup_pin_1_mask | ext_wakeup_pin_2_mask, CONFIG_EXAMPLE_EXT1_WAKEUP_MODE)); #endif /* If there are no external pull-up/downs, tie wakeup pins to inactive level with internal pull-up/downs via RTC IO