From 9b3e40c9d1e1dd30102edf0e655a4b9d7efe8211 Mon Sep 17 00:00:00 2001 From: Lou Tianhao Date: Thu, 13 Jul 2023 14:06:10 +0800 Subject: [PATCH 1/4] feat(pm/deepsleep): Support EXT1_WAKEUP_MODE_PER_PIN --- components/esp_hw_support/include/esp_sleep.h | 74 ++++++++++++++----- components/esp_hw_support/sleep_modes.c | 47 ++++++++++-- .../hal/esp32/include/hal/rtc_cntl_ll.h | 18 +++-- .../hal/esp32c6/include/hal/lp_aon_hal.h | 12 +-- .../hal/esp32c6/include/hal/lp_aon_ll.h | 20 ++--- .../hal/esp32h2/include/hal/lp_aon_hal.h | 12 +-- .../hal/esp32h2/include/hal/lp_aon_ll.h | 20 ++--- .../hal/esp32s2/include/hal/rtc_cntl_ll.h | 18 +++-- .../hal/esp32s3/include/hal/rtc_cntl_ll.h | 18 +++-- components/hal/include/hal/rtc_hal.h | 12 +-- .../esp32c6/include/soc/Kconfig.soc_caps.in | 4 + components/soc/esp32c6/include/soc/soc_caps.h | 1 + .../esp32h2/include/soc/Kconfig.soc_caps.in | 4 + components/soc/esp32h2/include/soc/soc_caps.h | 1 + .../system/deep_sleep/main/Kconfig.projbuild | 34 +++++++++ examples/system/deep_sleep/main/ext_wakeup.c | 51 +++++++++++-- 16 files changed, 263 insertions(+), 83 deletions(-) diff --git a/components/esp_hw_support/include/esp_sleep.h b/components/esp_hw_support/include/esp_sleep.h index 169a3b2fbf..1adfe8b458 100644 --- a/components/esp_hw_support/include/esp_sleep.h +++ b/components/esp_hw_support/include/esp_sleep.h @@ -251,7 +251,7 @@ esp_err_t esp_sleep_enable_ext0_wakeup(gpio_num_t gpio_num, int level); * 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 any of the selected pins goes into the state given by mode argument, + * 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 @@ -267,28 +267,68 @@ 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. * - * @param 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 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 + * @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 any of the selected GPIOs is not an RTC GPIO, * or mode is invalid */ -esp_err_t esp_sleep_enable_ext1_wakeup(uint64_t mask, esp_sleep_ext1_wakeup_mode_t mode); +esp_err_t esp_sleep_enable_ext1_wakeup(uint64_t io_mask, esp_sleep_ext1_wakeup_mode_t level_mode); +#if SOC_PM_SUPPORT_EXT1_WAKEUP_MODE_PER_PIN +/** + * @brief Enable wakeup using multiple pins, allows different trigger mode per pin + * + * 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: + * - ESP32-C6: 0-7. + * - ESP32-H2: 7-14. + * @param level_mask Select logic function used to determine wakeup condition per pin. + * Each bit of the level_mask corresponds to the respective GPIO. Each bit's corresponding + * position is set to 0, the wakeup level will be low, on the contrary, + * each bit's corresponding position is set to 1, the wakeup level will be high. + * @return + * - 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_t esp_sleep_enable_ext1_wakeup_with_level_mask(uint64_t io_mask, uint64_t level_mask); +#endif // SOC_PM_SUPPORT_EXT1_WAKEUP_MODE_PER_PIN #endif // SOC_PM_SUPPORT_EXT1_WAKEUP #if SOC_GPIO_SUPPORT_DEEPSLEEP_WAKEUP diff --git a/components/esp_hw_support/sleep_modes.c b/components/esp_hw_support/sleep_modes.c index f6121e12fc..cbcba00cdf 100644 --- a/components/esp_hw_support/sleep_modes.c +++ b/components/esp_hw_support/sleep_modes.c @@ -193,8 +193,8 @@ typedef struct { uint64_t sleep_duration; uint32_t wakeup_triggers : 15; #if SOC_PM_SUPPORT_EXT1_WAKEUP - uint32_t ext1_trigger_mode : 1; - uint32_t ext1_rtc_gpio_mask : 22; // 22 is the maximum RTCIO number in all chips + uint32_t ext1_trigger_mode : 22; // 22 is the maximum RTCIO number in all chips + uint32_t ext1_rtc_gpio_mask : 22; #endif #if SOC_PM_SUPPORT_EXT0_WAKEUP uint32_t ext0_trigger_level : 1; @@ -1369,15 +1369,15 @@ static void ext0_wakeup_prepare(void) #endif // SOC_PM_SUPPORT_EXT0_WAKEUP #if SOC_PM_SUPPORT_EXT1_WAKEUP -esp_err_t esp_sleep_enable_ext1_wakeup(uint64_t mask, esp_sleep_ext1_wakeup_mode_t mode) +esp_err_t esp_sleep_enable_ext1_wakeup(uint64_t io_mask, esp_sleep_ext1_wakeup_mode_t level_mode) { - if (mode > ESP_EXT1_WAKEUP_ANY_HIGH) { + if (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 uint32_t rtc_gpio_mask = 0; - for (int gpio = 0; mask; ++gpio, mask >>= 1) { - if ((mask & 1) == 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)) { @@ -1387,11 +1387,44 @@ esp_err_t esp_sleep_enable_ext1_wakeup(uint64_t mask, esp_sleep_ext1_wakeup_mode rtc_gpio_mask |= BIT(rtc_io_number_get(gpio)); } s_config.ext1_rtc_gpio_mask = rtc_gpio_mask; - s_config.ext1_trigger_mode = mode; + if (level_mode) { + s_config.ext1_trigger_mode = io_mask; + } else { + s_config.ext1_trigger_mode = 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) +{ + if ((level_mask & io_mask) != level_mask) { + return ESP_ERR_INVALID_ARG; + } + // Translate bit map of GPIO numbers into the bit map of RTC IO numbers + // Translate bit map of GPIO wakeup mode into the bit map of RTC IO wakeup mode + uint32_t rtc_gpio_mask = 0, rtc_gpio_wakeup_mode_mask = 0; + for (int gpio = 0; io_mask; ++gpio, io_mask >>= 1, level_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)); + if ((level_mask & 1) == 1) { + rtc_gpio_wakeup_mode_mask |= BIT(rtc_io_number_get(gpio)); + } + } + s_config.ext1_rtc_gpio_mask = rtc_gpio_mask; + s_config.ext1_trigger_mode = rtc_gpio_wakeup_mode_mask; + s_config.wakeup_triggers |= RTC_EXT1_TRIG_EN; + return ESP_OK; +} +#endif + static void ext1_wakeup_prepare(void) { // Configure all RTC IOs selected as ext1 wakeup inputs diff --git a/components/hal/esp32/include/hal/rtc_cntl_ll.h b/components/hal/esp32/include/hal/rtc_cntl_ll.h index 7e87d1d2ab..3c495752d3 100644 --- a/components/hal/esp32/include/hal/rtc_cntl_ll.h +++ b/components/hal/esp32/include/hal/rtc_cntl_ll.h @@ -1,5 +1,5 @@ /* - * SPDX-FileCopyrightText: 2020-2022 Espressif Systems (Shanghai) CO LTD + * SPDX-FileCopyrightText: 2020-2023 Espressif Systems (Shanghai) CO LTD * * SPDX-License-Identifier: Apache-2.0 */ @@ -11,6 +11,7 @@ #include "esp_attr.h" #include "clk_tree_ll.h" #include "esp_rom_sys.h" +#include "hal/assert.h" #ifdef __cplusplus extern "C" { @@ -32,11 +33,18 @@ FORCE_INLINE_ATTR uint32_t rtc_cntl_ll_ext1_get_wakeup_status(void) return REG_GET_FIELD(RTC_CNTL_EXT_WAKEUP1_STATUS_REG, RTC_CNTL_EXT_WAKEUP1_STATUS); } -FORCE_INLINE_ATTR void rtc_cntl_ll_ext1_set_wakeup_pins(uint32_t mask, int mode) +FORCE_INLINE_ATTR void rtc_cntl_ll_ext1_set_wakeup_pins(uint32_t io_mask, uint32_t mode_mask) { - REG_SET_FIELD(RTC_CNTL_EXT_WAKEUP1_REG, RTC_CNTL_EXT_WAKEUP1_SEL, mask); - SET_PERI_REG_BITS(RTC_CNTL_EXT_WAKEUP_CONF_REG, 0x1, - mode, RTC_CNTL_EXT_WAKEUP1_LV_S); + // The target only supports a unified trigger mode among all EXT1 wakeup IOs + HAL_ASSERT((io_mask & mode_mask) == io_mask || (io_mask & mode_mask) == 0); + REG_SET_FIELD(RTC_CNTL_EXT_WAKEUP1_REG, RTC_CNTL_EXT_WAKEUP1_SEL, io_mask); + if ((io_mask & mode_mask) == io_mask) { + SET_PERI_REG_BITS(RTC_CNTL_EXT_WAKEUP_CONF_REG, 0x1, + 1, RTC_CNTL_EXT_WAKEUP1_LV_S); + } else { + SET_PERI_REG_BITS(RTC_CNTL_EXT_WAKEUP_CONF_REG, 0x1, + 0, RTC_CNTL_EXT_WAKEUP1_LV_S); + } } FORCE_INLINE_ATTR void rtc_cntl_ll_ext1_clear_wakeup_pins(void) diff --git a/components/hal/esp32c6/include/hal/lp_aon_hal.h b/components/hal/esp32c6/include/hal/lp_aon_hal.h index f3cd9e6b85..c38f6da831 100644 --- a/components/hal/esp32c6/include/hal/lp_aon_hal.h +++ b/components/hal/esp32c6/include/hal/lp_aon_hal.h @@ -8,10 +8,10 @@ #include "hal/lp_aon_ll.h" -#define rtc_hal_ext1_get_wakeup_status() lp_aon_ll_ext1_get_wakeup_status() -#define rtc_hal_ext1_clear_wakeup_status() lp_aon_ll_ext1_clear_wakeup_status() -#define rtc_hal_ext1_set_wakeup_pins(mask, mode) lp_aon_ll_ext1_set_wakeup_pins(mask, mode) -#define rtc_hal_ext1_clear_wakeup_pins() lp_aon_ll_ext1_clear_wakeup_pins() -#define rtc_hal_ext1_get_wakeup_pins() lp_aon_ll_ext1_get_wakeup_pins() +#define rtc_hal_ext1_get_wakeup_status() lp_aon_ll_ext1_get_wakeup_status() +#define rtc_hal_ext1_clear_wakeup_status() lp_aon_ll_ext1_clear_wakeup_status() +#define rtc_hal_ext1_set_wakeup_pins(io_mask, mode_mask) lp_aon_ll_ext1_set_wakeup_pins(io_mask, mode_mask) +#define rtc_hal_ext1_clear_wakeup_pins() lp_aon_ll_ext1_clear_wakeup_pins() +#define rtc_hal_ext1_get_wakeup_pins() lp_aon_ll_ext1_get_wakeup_pins() -#define lp_aon_hal_inform_wakeup_type(dslp) lp_aon_ll_inform_wakeup_type(dslp) +#define lp_aon_hal_inform_wakeup_type(dslp) lp_aon_ll_inform_wakeup_type(dslp) diff --git a/components/hal/esp32c6/include/hal/lp_aon_ll.h b/components/hal/esp32c6/include/hal/lp_aon_ll.h index 22ae12dbf6..ef77b7561d 100644 --- a/components/hal/esp32c6/include/hal/lp_aon_ll.h +++ b/components/hal/esp32c6/include/hal/lp_aon_ll.h @@ -39,22 +39,22 @@ static inline void lp_aon_ll_ext1_clear_wakeup_status(void) /** * @brief Set the wake-up LP_IO of the ext1 wake-up source - * @param mask wakeup LP_IO bitmap, bit 0~7 corresponds to LP_IO 0~7 - * @param mode 0: Wake the chip when any of the selected GPIOs go low - * 1: Wake the chip when any of the selected GPIOs go high + * @param io_mask wakeup LP_IO bitmap, bit 0~7 corresponds to LP_IO 0~7 + * @param level_mask LP_IO wakeup level bitmap, bit 0~7 corresponds to LP_IO 0~7 wakeup level + * each bit's corresponding position is set to 0, the wakeup level will be low + * on the contrary, each bit's corresponding position is set to 1, the wakeup + * level will be high */ -static inline void lp_aon_ll_ext1_set_wakeup_pins(uint32_t mask, int mode) +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 |= mask; + 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); - if (mode) { - wakeup_level_mask |= mask; - } else { - wakeup_level_mask &= ~mask; - } + 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); } diff --git a/components/hal/esp32h2/include/hal/lp_aon_hal.h b/components/hal/esp32h2/include/hal/lp_aon_hal.h index f3cd9e6b85..c38f6da831 100644 --- a/components/hal/esp32h2/include/hal/lp_aon_hal.h +++ b/components/hal/esp32h2/include/hal/lp_aon_hal.h @@ -8,10 +8,10 @@ #include "hal/lp_aon_ll.h" -#define rtc_hal_ext1_get_wakeup_status() lp_aon_ll_ext1_get_wakeup_status() -#define rtc_hal_ext1_clear_wakeup_status() lp_aon_ll_ext1_clear_wakeup_status() -#define rtc_hal_ext1_set_wakeup_pins(mask, mode) lp_aon_ll_ext1_set_wakeup_pins(mask, mode) -#define rtc_hal_ext1_clear_wakeup_pins() lp_aon_ll_ext1_clear_wakeup_pins() -#define rtc_hal_ext1_get_wakeup_pins() lp_aon_ll_ext1_get_wakeup_pins() +#define rtc_hal_ext1_get_wakeup_status() lp_aon_ll_ext1_get_wakeup_status() +#define rtc_hal_ext1_clear_wakeup_status() lp_aon_ll_ext1_clear_wakeup_status() +#define rtc_hal_ext1_set_wakeup_pins(io_mask, mode_mask) lp_aon_ll_ext1_set_wakeup_pins(io_mask, mode_mask) +#define rtc_hal_ext1_clear_wakeup_pins() lp_aon_ll_ext1_clear_wakeup_pins() +#define rtc_hal_ext1_get_wakeup_pins() lp_aon_ll_ext1_get_wakeup_pins() -#define lp_aon_hal_inform_wakeup_type(dslp) lp_aon_ll_inform_wakeup_type(dslp) +#define lp_aon_hal_inform_wakeup_type(dslp) lp_aon_ll_inform_wakeup_type(dslp) diff --git a/components/hal/esp32h2/include/hal/lp_aon_ll.h b/components/hal/esp32h2/include/hal/lp_aon_ll.h index f556def282..38492a1728 100644 --- a/components/hal/esp32h2/include/hal/lp_aon_ll.h +++ b/components/hal/esp32h2/include/hal/lp_aon_ll.h @@ -39,22 +39,22 @@ static inline void lp_aon_ll_ext1_clear_wakeup_status(void) /** * @brief Set the wake-up LP_IO of the ext1 wake-up source - * @param mask wakeup LP_IO bitmap, bit 0~7 corresponds to LP_IO 0~7 - * @param mode 0: Wake the chip when any of the selected GPIOs go low - * 1: Wake the chip when any of the selected GPIOs go high + * @param io_mask wakeup LP_IO bitmap, bit 0~7 corresponds to LP_IO 0~7 + * @param level_mask LP_IO wakeup level bitmap, bit 0~7 corresponds to LP_IO 0~7 wakeup level + * each bit's corresponding position is set to 0, the wakeup level will be low + * on the contrary, each bit's corresponding position is set to 1, the wakeup + * level will be high */ -static inline void lp_aon_ll_ext1_set_wakeup_pins(uint32_t mask, int mode) +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 |= mask; + 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); - if (mode) { - wakeup_level_mask |= mask; - } else { - wakeup_level_mask &= ~mask; - } + 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); } diff --git a/components/hal/esp32s2/include/hal/rtc_cntl_ll.h b/components/hal/esp32s2/include/hal/rtc_cntl_ll.h index 0ccdedc879..754e9bcf11 100644 --- a/components/hal/esp32s2/include/hal/rtc_cntl_ll.h +++ b/components/hal/esp32s2/include/hal/rtc_cntl_ll.h @@ -1,5 +1,5 @@ /* - * SPDX-FileCopyrightText: 2020-2022 Espressif Systems (Shanghai) CO LTD + * SPDX-FileCopyrightText: 2020-2023 Espressif Systems (Shanghai) CO LTD * * SPDX-License-Identifier: Apache-2.0 */ @@ -10,6 +10,7 @@ #include "soc/rtc.h" #include "soc/rtc_cntl_reg.h" #include "esp_attr.h" +#include "hal/assert.h" #ifdef __cplusplus extern "C" { @@ -34,11 +35,18 @@ FORCE_INLINE_ATTR uint32_t rtc_cntl_ll_ext1_get_wakeup_status(void) return REG_GET_FIELD(RTC_CNTL_EXT_WAKEUP1_STATUS_REG, RTC_CNTL_EXT_WAKEUP1_STATUS); } -FORCE_INLINE_ATTR void rtc_cntl_ll_ext1_set_wakeup_pins(uint32_t mask, int mode) +FORCE_INLINE_ATTR void rtc_cntl_ll_ext1_set_wakeup_pins(uint32_t io_mask, uint32_t mode_mask) { - REG_SET_FIELD(RTC_CNTL_EXT_WAKEUP1_REG, RTC_CNTL_EXT_WAKEUP1_SEL, mask); - SET_PERI_REG_BITS(RTC_CNTL_EXT_WAKEUP_CONF_REG, 0x1, - mode, RTC_CNTL_EXT_WAKEUP1_LV_S); + // The target only supports a unified trigger mode among all EXT1 wakeup IOs + HAL_ASSERT((io_mask & mode_mask) == io_mask || (io_mask & mode_mask) == 0); + REG_SET_FIELD(RTC_CNTL_EXT_WAKEUP1_REG, RTC_CNTL_EXT_WAKEUP1_SEL, io_mask); + if ((io_mask & mode_mask) == io_mask) { + SET_PERI_REG_BITS(RTC_CNTL_EXT_WAKEUP_CONF_REG, 0x1, + 1, RTC_CNTL_EXT_WAKEUP1_LV_S); + } else { + SET_PERI_REG_BITS(RTC_CNTL_EXT_WAKEUP_CONF_REG, 0x1, + 0, RTC_CNTL_EXT_WAKEUP1_LV_S); + } } FORCE_INLINE_ATTR void rtc_cntl_ll_ext1_clear_wakeup_pins(void) diff --git a/components/hal/esp32s3/include/hal/rtc_cntl_ll.h b/components/hal/esp32s3/include/hal/rtc_cntl_ll.h index 464aa99cd6..34d4cb8e34 100644 --- a/components/hal/esp32s3/include/hal/rtc_cntl_ll.h +++ b/components/hal/esp32s3/include/hal/rtc_cntl_ll.h @@ -1,5 +1,5 @@ /* - * SPDX-FileCopyrightText: 2020-2022 Espressif Systems (Shanghai) CO LTD + * SPDX-FileCopyrightText: 2020-2023 Espressif Systems (Shanghai) CO LTD * * SPDX-License-Identifier: Apache-2.0 */ @@ -11,6 +11,7 @@ #include "soc/rtc_cntl_reg.h" #include "soc/apb_ctrl_reg.h" #include "esp_attr.h" +#include "hal/assert.h" #ifdef __cplusplus extern "C" { @@ -38,11 +39,18 @@ FORCE_INLINE_ATTR uint32_t rtc_cntl_ll_ext1_get_wakeup_status(void) return REG_GET_FIELD(RTC_CNTL_EXT_WAKEUP1_STATUS_REG, RTC_CNTL_EXT_WAKEUP1_STATUS); } -FORCE_INLINE_ATTR void rtc_cntl_ll_ext1_set_wakeup_pins(uint32_t mask, int mode) +FORCE_INLINE_ATTR void rtc_cntl_ll_ext1_set_wakeup_pins(uint32_t io_mask, uint32_t mode_mask) { - REG_SET_FIELD(RTC_CNTL_EXT_WAKEUP1_REG, RTC_CNTL_EXT_WAKEUP1_SEL, mask); - SET_PERI_REG_BITS(RTC_CNTL_EXT_WAKEUP_CONF_REG, 0x1, - mode, RTC_CNTL_EXT_WAKEUP1_LV_S); + // The target only supports a unified trigger mode among all EXT1 wakeup IOs + HAL_ASSERT((io_mask & mode_mask) == io_mask || (io_mask & mode_mask) == 0); + REG_SET_FIELD(RTC_CNTL_EXT_WAKEUP1_REG, RTC_CNTL_EXT_WAKEUP1_SEL, io_mask); + if ((io_mask & mode_mask) == io_mask) { + SET_PERI_REG_BITS(RTC_CNTL_EXT_WAKEUP_CONF_REG, 0x1, + 1, RTC_CNTL_EXT_WAKEUP1_LV_S); + } else { + SET_PERI_REG_BITS(RTC_CNTL_EXT_WAKEUP_CONF_REG, 0x1, + 0, RTC_CNTL_EXT_WAKEUP1_LV_S); + } } FORCE_INLINE_ATTR void rtc_cntl_ll_ext1_clear_wakeup_pins(void) diff --git a/components/hal/include/hal/rtc_hal.h b/components/hal/include/hal/rtc_hal.h index 6848d559d8..c889a2ad07 100644 --- a/components/hal/include/hal/rtc_hal.h +++ b/components/hal/include/hal/rtc_hal.h @@ -1,5 +1,5 @@ /* - * SPDX-FileCopyrightText: 2020-2022 Espressif Systems (Shanghai) CO LTD + * SPDX-FileCopyrightText: 2020-2023 Espressif Systems (Shanghai) CO LTD * * SPDX-License-Identifier: Apache-2.0 */ @@ -41,15 +41,15 @@ typedef struct rtc_cntl_sleep_retent { #if SOC_PM_SUPPORT_EXT1_WAKEUP -#define rtc_hal_ext1_get_wakeup_status() rtc_cntl_ll_ext1_get_wakeup_status() +#define rtc_hal_ext1_get_wakeup_status() rtc_cntl_ll_ext1_get_wakeup_status() -#define rtc_hal_ext1_clear_wakeup_status() rtc_cntl_ll_ext1_clear_wakeup_status() +#define rtc_hal_ext1_clear_wakeup_status() rtc_cntl_ll_ext1_clear_wakeup_status() -#define rtc_hal_ext1_set_wakeup_pins(mask, mode) rtc_cntl_ll_ext1_set_wakeup_pins(mask, mode) +#define rtc_hal_ext1_set_wakeup_pins(io_mask, mode_mask) rtc_cntl_ll_ext1_set_wakeup_pins(io_mask, mode_mask) -#define rtc_hal_ext1_clear_wakeup_pins() rtc_cntl_ll_ext1_clear_wakeup_pins() +#define rtc_hal_ext1_clear_wakeup_pins() rtc_cntl_ll_ext1_clear_wakeup_pins() -#define rtc_hal_ext1_get_wakeup_pins() rtc_cntl_ll_ext1_get_wakeup_pins() +#define rtc_hal_ext1_get_wakeup_pins() rtc_cntl_ll_ext1_get_wakeup_pins() #endif // SOC_PM_SUPPORT_EXT1_WAKEUP diff --git a/components/soc/esp32c6/include/soc/Kconfig.soc_caps.in b/components/soc/esp32c6/include/soc/Kconfig.soc_caps.in index 3bd19bcd5a..5ca2b6fb28 100644 --- a/components/soc/esp32c6/include/soc/Kconfig.soc_caps.in +++ b/components/soc/esp32c6/include/soc/Kconfig.soc_caps.in @@ -1123,6 +1123,10 @@ config SOC_PM_SUPPORT_EXT1_WAKEUP bool default y +config SOC_PM_SUPPORT_EXT1_WAKEUP_MODE_PER_PIN + bool + default y + config SOC_PM_SUPPORT_CPU_PD bool default y diff --git a/components/soc/esp32c6/include/soc/soc_caps.h b/components/soc/esp32c6/include/soc/soc_caps.h index 5081a69a4c..0c317d21f7 100644 --- a/components/soc/esp32c6/include/soc/soc_caps.h +++ b/components/soc/esp32c6/include/soc/soc_caps.h @@ -472,6 +472,7 @@ #define SOC_PM_SUPPORT_BEACON_WAKEUP (1) #define SOC_PM_SUPPORT_BT_WAKEUP (1) #define SOC_PM_SUPPORT_EXT1_WAKEUP (1) +#define SOC_PM_SUPPORT_EXT1_WAKEUP_MODE_PER_PIN (1) /*! Date: Tue, 5 Sep 2023 12:03:01 +0800 Subject: [PATCH 2/4] docs(pm): add ext1 wakeup per pin description --- docs/en/api-reference/system/sleep_modes.rst | 10 +++++++--- docs/zh_CN/api-reference/system/sleep_modes.rst | 12 ++++++++---- 2 files changed, 15 insertions(+), 7 deletions(-) diff --git a/docs/en/api-reference/system/sleep_modes.rst b/docs/en/api-reference/system/sleep_modes.rst index 5a5320c70b..6249822a52 100644 --- a/docs/en/api-reference/system/sleep_modes.rst +++ b/docs/en/api-reference/system/sleep_modes.rst @@ -95,7 +95,7 @@ RTC peripherals or RTC memories don't need to be powered on during sleep in this 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 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 general ext1 wakeup: .. only:: esp32 @@ -123,13 +123,17 @@ RTC peripherals or RTC memories don't need to be powered on during sleep in this 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. + + .. 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`. + .. warning:: - To use the EXT1 wakeup, the IO pad(s) are configured as RTC IO. Therefore, before using these pads as digital GPIOs, users need to reconfigure them by calling the :cpp:func:`rtc_gpio_deinit` function. - If the RTC peripherals are configured to be powered down (which is by default), the wakeup IOs will be set to the holding state before entering sleep. Therefore, after the chip wakes up from Light-sleep, please call `rtc_gpio_hold_dis` to disable the hold function to perform any pin re-configuration. For Deep-sleep wakeup, this is already being handled at the application startup stage. - :cpp:func:`esp_sleep_enable_ext1_wakeup` function can be used to enable this wakeup source. - .. only:: SOC_ULP_SUPPORTED ULP Coprocessor Wakeup diff --git a/docs/zh_CN/api-reference/system/sleep_modes.rst b/docs/zh_CN/api-reference/system/sleep_modes.rst index 3465bccf0f..49aafaffb8 100644 --- a/docs/zh_CN/api-reference/system/sleep_modes.rst +++ b/docs/zh_CN/api-reference/system/sleep_modes.rst @@ -92,10 +92,10 @@ RTC 控制器中内嵌定时器，可用于在预定义的时间到达后唤醒 .. only:: SOC_PM_SUPPORT_EXT1_WAKEUP - 外部唤醒 (ext1) + 外部唤醒 (``ext1``) ^^^^^^^^^^^^^^^^^^^^^^ - RTC 控制器中包含使用多个 RTC GPIO 触发唤醒的逻辑。您可以从以下两个逻辑函数中选择其一，用于触发唤醒： + RTC 控制器中包含使用多个 RTC GPIO 触发唤醒的逻辑。从以下两个逻辑函数中任选其一，均可触发普通 ext1 唤醒： .. only:: esp32 @@ -123,13 +123,17 @@ RTC 控制器中内嵌定时器，可用于在预定义的时间到达后唤醒 gpio_pullup_dis(gpio_num); gpio_pulldown_en(gpio_num); + 可调用 :cpp:func:`esp_sleep_enable_ext1_wakeup` 函数来启用普通 ext1 唤醒。 + + .. 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` 函数来进行配置。 + .. warning:: - 使用 EXT1 唤醒源时，用于唤醒的 IO pad 将被配置为 RTC IO。因此，在将该 pad 用作数字 GPIO 之前，请调用 :cpp:func:`rtc_gpio_deinit` 函数对其进行重新配置。 - RTC 外设在默认情况下配置为断电，此时，唤醒 IO 在进入睡眠状态前将被设置为保持状态。因此，从 Light-sleep 状态唤醒芯片后，请调用 `rtc_gpio_hold_dis` 来禁用保持功能，以便对管脚进行重新配置。对于 Deep-sleep 唤醒，此问题已经在应用启动阶段解决。 - 可调用 :cpp:func:`esp_sleep_enable_ext1_wakeup` 函数来启用此唤醒源。 - .. only:: SOC_ULP_SUPPORTED ULP 协处理器唤醒 From a1ceb251a0f2087f5d61e2f2ec667308abc7bb40 Mon Sep 17 00:00:00 2001 From: zwx Date: Mon, 16 Oct 2023 17:35:52 +0800 Subject: [PATCH 3/4] feat(openthread): add config for radio statistic feature --- components/openthread/Kconfig | 8 ++++++++ .../openthread-core-esp32x-ftd-config.h | 11 +++++++++++ .../openthread-core-esp32x-mtd-config.h | 11 +++++++++++ 3 files changed, 30 insertions(+) diff --git a/components/openthread/Kconfig b/components/openthread/Kconfig index 3f0300f07c..d18ec6b892 100644 --- a/components/openthread/Kconfig +++ b/components/openthread/Kconfig @@ -353,4 +353,12 @@ menu "OpenThread" Select this option to enable time synchronization feature, the devices in the same Thread network could sync to the same network time. + config OPENTHREAD_RADIO_STATS_ENABLE + bool "Enable Radio Statistics feature" + depends on OPENTHREAD_FTD || OPENTHREAD_MTD + default n + help + Select this option to enable the radio statistics feature, you can use radio command to print some radio + Statistics informations. + endmenu diff --git a/components/openthread/private_include/openthread-core-esp32x-ftd-config.h b/components/openthread/private_include/openthread-core-esp32x-ftd-config.h index 0da476f5e1..b27bc53963 100644 --- a/components/openthread/private_include/openthread-core-esp32x-ftd-config.h +++ b/components/openthread/private_include/openthread-core-esp32x-ftd-config.h @@ -579,4 +579,15 @@ #define OPENTHREAD_CONFIG_TIME_SYNC_ENABLE 1 #endif +/** + * @def OPENTHREAD_CONFIG_RADIO_STATS_ENABLE + * + * Set to 1 to enable support for Radio Statistics. Note that this option only works for OPENTHREAD_FTD and + * OPENTHREAD_MTD. + * + */ +#if CONFIG_OPENTHREAD_RADIO_STATS_ENABLE +#define OPENTHREAD_CONFIG_RADIO_STATS_ENABLE 1 +#endif + #define OPENTHREAD_FTD 1 diff --git a/components/openthread/private_include/openthread-core-esp32x-mtd-config.h b/components/openthread/private_include/openthread-core-esp32x-mtd-config.h index e5980244b7..f706d364e2 100644 --- a/components/openthread/private_include/openthread-core-esp32x-mtd-config.h +++ b/components/openthread/private_include/openthread-core-esp32x-mtd-config.h @@ -263,4 +263,15 @@ #define OPENTHREAD_CONFIG_TIME_SYNC_ENABLE 1 #endif +/** + * @def OPENTHREAD_CONFIG_RADIO_STATS_ENABLE + * + * Set to 1 to enable support for Radio Statistics. Note that this option only works for OPENTHREAD_FTD and + * OPENTHREAD_MTD. + * + */ +#if CONFIG_OPENTHREAD_RADIO_STATS_ENABLE +#define OPENTHREAD_CONFIG_RADIO_STATS_ENABLE 1 +#endif + #define OPENTHREAD_MTD 1 From 9f8655cdefc60702c6960cd51263de2736a53d66 Mon Sep 17 00:00:00 2001 From: zwx Date: Mon, 23 Oct 2023 17:27:16 +0800 Subject: [PATCH 4/4] feat(openthread): Add deep sleep support for SED --- .../{ => deep_sleep}/CMakeLists.txt | 0 .../ot_sleepy_device/deep_sleep/README.md | 64 +++++ .../image/H2-deep-sleep-power-consumption.png | Bin 0 -> 92589 bytes .../{ => deep_sleep}/main/CMakeLists.txt | 0 .../deep_sleep/main/esp_ot_sleepy_device.c | 220 ++++++++++++++++++ .../main/esp_ot_sleepy_device_config.h | 53 +++++ .../{ => deep_sleep}/partitions.csv | 0 .../deep_sleep/sdkconfig.defaults | 54 +++++ .../light_sleep/CMakeLists.txt | 6 + .../{ => light_sleep}/README.md | 4 +- .../light_sleep/main/CMakeLists.txt | 2 + .../main/esp_ot_sleepy_device.c | 0 .../main/esp_ot_sleepy_device_config.h | 0 .../light_sleep/partitions.csv | 5 + .../light_sleep/sdkconfig.ci.sleepy_c6 | 6 + .../light_sleep/sdkconfig.ci.sleepy_h2 | 6 + .../{ => light_sleep}/sdkconfig.defaults | 0 17 files changed, 418 insertions(+), 2 deletions(-) rename examples/openthread/ot_sleepy_device/{ => deep_sleep}/CMakeLists.txt (100%) create mode 100644 examples/openthread/ot_sleepy_device/deep_sleep/README.md create mode 100644 examples/openthread/ot_sleepy_device/deep_sleep/image/H2-deep-sleep-power-consumption.png rename examples/openthread/ot_sleepy_device/{ => deep_sleep}/main/CMakeLists.txt (100%) create mode 100644 examples/openthread/ot_sleepy_device/deep_sleep/main/esp_ot_sleepy_device.c create mode 100644 examples/openthread/ot_sleepy_device/deep_sleep/main/esp_ot_sleepy_device_config.h rename examples/openthread/ot_sleepy_device/{ => deep_sleep}/partitions.csv (100%) create mode 100644 examples/openthread/ot_sleepy_device/deep_sleep/sdkconfig.defaults create mode 100644 examples/openthread/ot_sleepy_device/light_sleep/CMakeLists.txt rename examples/openthread/ot_sleepy_device/{ => light_sleep}/README.md (89%) create mode 100644 examples/openthread/ot_sleepy_device/light_sleep/main/CMakeLists.txt rename examples/openthread/ot_sleepy_device/{ => light_sleep}/main/esp_ot_sleepy_device.c (100%) rename examples/openthread/ot_sleepy_device/{ => light_sleep}/main/esp_ot_sleepy_device_config.h (100%) create mode 100644 examples/openthread/ot_sleepy_device/light_sleep/partitions.csv create mode 100644 examples/openthread/ot_sleepy_device/light_sleep/sdkconfig.ci.sleepy_c6 create mode 100644 examples/openthread/ot_sleepy_device/light_sleep/sdkconfig.ci.sleepy_h2 rename examples/openthread/ot_sleepy_device/{ => light_sleep}/sdkconfig.defaults (100%) diff --git a/examples/openthread/ot_sleepy_device/CMakeLists.txt b/examples/openthread/ot_sleepy_device/deep_sleep/CMakeLists.txt similarity index 100% rename from examples/openthread/ot_sleepy_device/CMakeLists.txt rename to examples/openthread/ot_sleepy_device/deep_sleep/CMakeLists.txt diff --git a/examples/openthread/ot_sleepy_device/deep_sleep/README.md b/examples/openthread/ot_sleepy_device/deep_sleep/README.md new file mode 100644 index 0000000000..5ee3f7d9b2 --- /dev/null +++ b/examples/openthread/ot_sleepy_device/deep_sleep/README.md @@ -0,0 +1,64 @@ +| Supported Targets | ESP32-H2 | +| ----------------- | -------- | + +# OpenThread Sleepy Device Example + +The example demonstrates the Thread Sleepy End Device (SED), the device will enter [Deep Sleep mode](https://docs.espressif.com/projects/esp-idf/en/latest/esp32c6/api-reference/system/sleep_modes.html#sleep-modes) during idle state. + +This example is designed to address a specific deep sleep application scenario. First, it connects to the Thread network, and after 5 seconds when the state changes to CHILD, it enters deep sleep mode. There are two ways to wake up in this example: one is by using a 20-second periodic RTC timer, and the other is through GPIO input. Deep sleep is part of the upper-layer logic, and it's the user's responsibility to manage it in their own applications. If you need more wake-up methods, you can refer to the [Exapmle deep sleep](../../../system/deep_sleep/). Additionally, Espressif provides a stub for handling wake-ups, which allows for a quick check, and the user can decide whether to wake up or continue deep sleep in this stub, as explained in the [Example deep sleep stub](../../../system/deep_sleep_wake_stub). + +Note: Implementing a standard Thread Sleepy Device is recommended using the [Light Sleep example](../light_sleep). Deep sleep triggers a reboot, and the device needs to undergo a re-attach process to rejoin the network. This means additional packet interactions are necessary after each wake-up from deep sleep. It can be advantageous in reducing power consumption, especially when the device remains in a sleep state for extended periods, such as more than 30 minutes. +## How to use example + +### Hardware Required + +* Prepare two 802.15.4 SoC development boards, one for an OpenThread Leader and the other one for an OpenThread Sleepy End Device (SED). +* Connect the board using a USB cable for power supply and programming. + +## Configure the Openthread Dataset + +* Run [ot_cli](../../ot_cli/) on another 802.15.4 SoC device to create openthread dataset configuration and start an openthread network as the Leader. +* Configure the Openthread dataset using `idf.py menuconfig` in `Component config ---> Openthread ---> Thread Operation Dataset`, ensuring that the openthread sleepy device's dataset matches the dataset of the Leader device. + +### Build and Flash + +Build the project and flash it to the board. Use the following command: `idf.py -p erase-flash flash monitor`. + +### Example Output + +As the example runs, you will see the log output indicating the initialization and operation of OpenThread, including the device joining the OpenThread network as a Sleepy End Device (SED). + +``` +I(281) OPENTHREAD:[I] Settings------: Read NetworkInfo {rloc:0x4001, extaddr:623954c9725869e6, role:child, mode:0x04, version:4, keyseq:0x0, ... +I(291) OPENTHREAD:[I] Settings------: ... pid:0x3b33d767, mlecntr:0x3ba17, maccntr:0x3baa8, mliid:868f19ce8c3f6207} +I(301) OPENTHREAD:[I] Settings------: Read ParentInfo {extaddr:3afe8db4802dc1aa, version:4} +I (311) ot_esp_power_save: Wake up from timer. Time spent in deep sleep and boot: 20321ms +I (331) ot_esp_power_save: Enabling timer wakeup, 20s +I (331) OPENTHREAD: OpenThread attached to netif +I(341) OPENTHREAD:[N] Mle-----------: Role disabled -> detached +I (291) main_task: Returned from app_main() +I (371) OT_STATE: netif up +I(511) OPENTHREAD:[N] Mle-----------: Role detached -> child +I (531) ot_esp_power_save: Start one-shot timer for 5s to enter the deep sleep +I (5531) ot_esp_power_save: Enter deep sleep +``` + +When the device enter deep sleep, GPIO9 also can wake up the device, you can push down the BOOT button then you can see the device wakes up: + +``` +I(281) OPENTHREAD:[I] Settings------: Read NetworkInfo {rloc:0x4001, extaddr:623954c9725869e6, role:child, mode:0x04, version:4, keyseq:0x0, ... +I(291) OPENTHREAD:[I] Settings------: ... pid:0x3b33d767, mlecntr:0x3d576, maccntr:0x3d609, mliid:868f19ce8c3f6207} +I(301) OPENTHREAD:[I] Settings------: Read ParentInfo {extaddr:3afe8db4802dc1aa, version:4} +I (321) ot_esp_power_save: Wake up from GPIO. Time spent in deep sleep and boot: 8470ms +I (331) ot_esp_power_save: Enabling timer wakeup, 20s +I (331) OPENTHREAD: OpenThread attached to netif +I(341) OPENTHREAD:[N] Mle-----------: Role disabled -> detached +I (291) main_task: Returned from app_main() +I (371) OT_STATE: netif up +I(511) OPENTHREAD:[N] Mle-----------: Role detached -> child +I (531) ot_esp_power_save: Start one-shot timer for 5s to enter the deep sleep +I (5531) ot_esp_power_save: Enter deep sleep +``` + +During the deep sleep, a typical power consumption is shown below: +![H2-deep-sleep-power-consumption](image/H2-deep-sleep-power-consumption.png) \ No newline at end of file diff --git a/examples/openthread/ot_sleepy_device/deep_sleep/image/H2-deep-sleep-power-consumption.png b/examples/openthread/ot_sleepy_device/deep_sleep/image/H2-deep-sleep-power-consumption.png new file mode 100644 index 0000000000000000000000000000000000000000..26df54501537fff4471feb405301f85736cd3e43 GIT binary patch literal 92589 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 K=#*&LhW!^r$4-*~ literal 0 HcmV?d00001 diff --git a/examples/openthread/ot_sleepy_device/main/CMakeLists.txt b/examples/openthread/ot_sleepy_device/deep_sleep/main/CMakeLists.txt similarity index 100% rename from examples/openthread/ot_sleepy_device/main/CMakeLists.txt rename to examples/openthread/ot_sleepy_device/deep_sleep/main/CMakeLists.txt 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 new file mode 100644 index 0000000000..4c2e592485 --- /dev/null +++ b/examples/openthread/ot_sleepy_device/deep_sleep/main/esp_ot_sleepy_device.c @@ -0,0 +1,220 @@ +/* + * SPDX-FileCopyrightText: 2023 Espressif Systems (Shanghai) CO LTD + * + * SPDX-License-Identifier: CC0-1.0 + * + * OpenThread Command Line Example + * + * This example code is in the Public Domain (or CC0 licensed, at your option.) + * + * Unless required by applicable law or agreed to in writing, this + * software is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR + * CONDITIONS OF ANY KIND, either express or implied. +*/ + +#include +#include +#include +#include +#include "esp_err.h" +#include "esp_event.h" +#include "esp_log.h" +#include "esp_sleep.h" +#include "esp_timer.h" +#include "esp_openthread.h" +#include "esp_openthread_netif_glue.h" +#include "esp_ot_sleepy_device_config.h" +#include "esp_vfs_eventfd.h" +#include "nvs_flash.h" +#include "driver/rtc_io.h" +#include "driver/uart.h" +#include "openthread/logging.h" +#include "openthread/thread.h" + +#if !SOC_IEEE802154_SUPPORTED +#error "Openthread sleepy device is only supported for the SoCs which have IEEE 802.15.4 module" +#endif + +#define TAG "ot_esp_power_save" + +static RTC_DATA_ATTR struct timeval s_sleep_enter_time; +static esp_timer_handle_t s_oneshot_timer; + +static void create_config_network(otInstance *instance) +{ + otLinkModeConfig linkMode = { 0 }; + + linkMode.mRxOnWhenIdle = false; + linkMode.mDeviceType = false; + linkMode.mNetworkData = false; + + if (otLinkSetPollPeriod(instance, CONFIG_OPENTHREAD_NETWORK_POLLPERIOD_TIME) != OT_ERROR_NONE) { + ESP_LOGE(TAG, "Failed to set OpenThread pollperiod."); + abort(); + } + + if (otThreadSetLinkMode(instance, linkMode) != OT_ERROR_NONE) { + ESP_LOGE(TAG, "Failed to set OpenThread linkmode."); + abort(); + } + ESP_ERROR_CHECK(esp_openthread_auto_start(NULL)); +} + +static esp_netif_t *init_openthread_netif(const esp_openthread_platform_config_t *config) +{ + esp_netif_config_t cfg = ESP_NETIF_DEFAULT_OPENTHREAD(); + esp_netif_t *netif = esp_netif_new(&cfg); + assert(netif != NULL); + ESP_ERROR_CHECK(esp_netif_attach(netif, esp_openthread_netif_glue_init(config))); + + return netif; +} + +static void ot_state_change_callback(otChangedFlags changed_flags, void* ctx) +{ + OT_UNUSED_VARIABLE(ctx); + static otDeviceRole s_previous_role = OT_DEVICE_ROLE_DISABLED; + otInstance* instance = esp_openthread_get_instance(); + if (!instance) { + return; + } + otDeviceRole role = otThreadGetDeviceRole(instance); + if (role == OT_DEVICE_ROLE_CHILD && s_previous_role != OT_DEVICE_ROLE_CHILD) { + // Start the one-shot timer + const int before_deep_sleep_time_sec = 5; + ESP_LOGI(TAG, "Start one-shot timer for %ds to enter the deep sleep", before_deep_sleep_time_sec); + ESP_ERROR_CHECK(esp_timer_start_once(s_oneshot_timer, before_deep_sleep_time_sec * 1000000)); + } + s_previous_role = role; +} + +static void s_oneshot_timer_callback(void* arg) +{ + // Enter deep sleep + ESP_LOGI(TAG, "Enter deep sleep"); + gettimeofday(&s_sleep_enter_time, NULL); + esp_deep_sleep_start(); +} + +static void ot_deep_sleep_init(void) +{ + // Within this function, we print the reason for the wake-up and configure the method of waking up from deep sleep. + // This example provides support for two wake-up sources from deep sleep: RTC timer and GPIO. + + // The one-shot timer will start when the device transitions to the CHILD state for the first time. + // After a 5-second delay, the device will enter deep sleep. + + const esp_timer_create_args_t s_oneshot_timer_args = { + .callback = &s_oneshot_timer_callback, + .name = "one-shot" + }; + + ESP_ERROR_CHECK(esp_timer_create(&s_oneshot_timer_args, &s_oneshot_timer)); + + // Print the wake-up reason: + struct timeval now; + gettimeofday(&now, NULL); + int sleep_time_ms = (now.tv_sec - s_sleep_enter_time.tv_sec) * 1000 + (now.tv_usec - s_sleep_enter_time.tv_usec) / 1000; + esp_sleep_wakeup_cause_t wake_up_cause = esp_sleep_get_wakeup_cause(); + switch (wake_up_cause) { + case ESP_SLEEP_WAKEUP_TIMER: { + ESP_LOGI(TAG, "Wake up from timer. Time spent in deep sleep and boot: %dms", sleep_time_ms); + break; + } + case ESP_SLEEP_WAKEUP_EXT1: { + ESP_LOGI(TAG, "Wake up from GPIO. Time spent in deep sleep and boot: %dms", sleep_time_ms); + break; + } + case ESP_SLEEP_WAKEUP_UNDEFINED: + default: + ESP_LOGI(TAG, "Not a deep sleep reset"); + break; + } + + // Set the methods of how to wake up: + // 1. RTC timer waking-up + const int wakeup_time_sec = 20; + ESP_LOGI(TAG, "Enabling timer wakeup, %ds\n", wakeup_time_sec); + ESP_ERROR_CHECK(esp_sleep_enable_timer_wakeup(wakeup_time_sec * 1000000)); + + // 2. GPIO waking-up +#if CONFIG_IDF_TARGET_ESP32C6 + // For ESP32C6 boards, RTCIO only supports GPIO0~GPIO7 + // GPIO7 pull down to wake up + const int gpio_wakeup_pin = 7; +#elif CONFIG_IDF_TARGET_ESP32H2 + // You can wake up by pulling down GPIO9. On ESP32H2 development boards, the BOOT button is connected to GPIO9. + // You can use the BOOT button to wake up the boards directly. + const int gpio_wakeup_pin = 9; +#endif + 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)); + + // 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. + + // Notice: if these GPIO configurations do not match the hardware design, the deep sleep module will enable the GPIO hold + // feature to hold the GPIO voltage when enter the sleep, which will ensure the board be waked up by GPIO. But it will cause + // 3~4 times power consumption increasing during sleep. + ESP_ERROR_CHECK(gpio_pullup_en(gpio_wakeup_pin)); + ESP_ERROR_CHECK(gpio_pulldown_dis(gpio_wakeup_pin)); +} + + +static void ot_task_worker(void *aContext) +{ + esp_openthread_platform_config_t config = { + .radio_config = ESP_OPENTHREAD_DEFAULT_RADIO_CONFIG(), + .host_config = ESP_OPENTHREAD_DEFAULT_HOST_CONFIG(), + .port_config = ESP_OPENTHREAD_DEFAULT_PORT_CONFIG(), + }; + + // Initialize the OpenThread stack + ESP_ERROR_CHECK(esp_openthread_init(&config)); + + ot_deep_sleep_init(); + +#if CONFIG_OPENTHREAD_LOG_LEVEL_DYNAMIC + // The OpenThread log level directly matches ESP log level + (void)otLoggingSetLevel(CONFIG_LOG_DEFAULT_LEVEL); +#endif + esp_netif_t *openthread_netif; + // Initialize the esp_netif bindings + openthread_netif = init_openthread_netif(&config); + esp_netif_set_default_netif(openthread_netif); + otSetStateChangedCallback(esp_openthread_get_instance(), ot_state_change_callback, NULL); + + create_config_network(esp_openthread_get_instance()); + + // Run the main loop + esp_openthread_launch_mainloop(); + + // Clean up + esp_netif_destroy(openthread_netif); + esp_openthread_netif_glue_deinit(); + + esp_vfs_eventfd_unregister(); + vTaskDelete(NULL); +} + + +void app_main(void) +{ + // Used eventfds: + // * netif + // * ot task queue + // * radio driver + esp_vfs_eventfd_config_t eventfd_config = { + .max_fds = 3, + }; + + ESP_ERROR_CHECK(nvs_flash_init()); + ESP_ERROR_CHECK(esp_event_loop_create_default()); + ESP_ERROR_CHECK(esp_netif_init()); + ESP_ERROR_CHECK(esp_vfs_eventfd_register(&eventfd_config)); + + xTaskCreate(ot_task_worker, "ot_power_save_main", 4096, NULL, 5, NULL); +} diff --git a/examples/openthread/ot_sleepy_device/deep_sleep/main/esp_ot_sleepy_device_config.h b/examples/openthread/ot_sleepy_device/deep_sleep/main/esp_ot_sleepy_device_config.h new file mode 100644 index 0000000000..145bb245cc --- /dev/null +++ b/examples/openthread/ot_sleepy_device/deep_sleep/main/esp_ot_sleepy_device_config.h @@ -0,0 +1,53 @@ +/* + * SPDX-FileCopyrightText: 2023 Espressif Systems (Shanghai) CO LTD + * + * SPDX-License-Identifier: CC0-1.0 + * + * OpenThread Command Line Example + * + * This example code is in the Public Domain (or CC0 licensed, at your option.) + * + * Unless required by applicable law or agreed to in writing, this + * software is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR + * CONDITIONS OF ANY KIND, either express or implied. + */ + +#pragma once + +#include "esp_openthread_types.h" + +# define CONFIG_OPENTHREAD_NETWORK_POLLPERIOD_TIME 30000 + +#if SOC_IEEE802154_SUPPORTED +#define ESP_OPENTHREAD_DEFAULT_RADIO_CONFIG() \ + { \ + .radio_mode = RADIO_MODE_NATIVE, \ + } +#endif + +#define ESP_OPENTHREAD_DEFAULT_HOST_CONFIG() \ + { \ + .host_connection_mode = HOST_CONNECTION_MODE_CLI_UART, \ + .host_uart_config = { \ + .port = 0, \ + .uart_config = \ + { \ + .baud_rate = 115200, \ + .data_bits = UART_DATA_8_BITS, \ + .parity = UART_PARITY_DISABLE, \ + .stop_bits = UART_STOP_BITS_1, \ + .flow_ctrl = UART_HW_FLOWCTRL_DISABLE, \ + .rx_flow_ctrl_thresh = 0, \ + .source_clk = UART_SCLK_DEFAULT, \ + }, \ + .rx_pin = UART_PIN_NO_CHANGE, \ + .tx_pin = UART_PIN_NO_CHANGE, \ + }, \ + } + +#define ESP_OPENTHREAD_DEFAULT_PORT_CONFIG() \ + { \ + .storage_partition_name = "nvs", \ + .netif_queue_size = 10, \ + .task_queue_size = 10, \ + } diff --git a/examples/openthread/ot_sleepy_device/partitions.csv b/examples/openthread/ot_sleepy_device/deep_sleep/partitions.csv similarity index 100% rename from examples/openthread/ot_sleepy_device/partitions.csv rename to examples/openthread/ot_sleepy_device/deep_sleep/partitions.csv diff --git a/examples/openthread/ot_sleepy_device/deep_sleep/sdkconfig.defaults b/examples/openthread/ot_sleepy_device/deep_sleep/sdkconfig.defaults new file mode 100644 index 0000000000..00774aa81d --- /dev/null +++ b/examples/openthread/ot_sleepy_device/deep_sleep/sdkconfig.defaults @@ -0,0 +1,54 @@ +# +# Partition Table +# +CONFIG_PARTITION_TABLE_CUSTOM=y +CONFIG_PARTITION_TABLE_CUSTOM_FILENAME="partitions.csv" +CONFIG_PARTITION_TABLE_FILENAME="partitions.csv" +# end of Partition Table + +# +# mbedTLS +# +# TODO: Re-enable HW acceleration when HW AES support pm_lock (IDF-7704) +CONFIG_MBEDTLS_HARDWARE_AES=n +CONFIG_MBEDTLS_HARDWARE_MPI=n +CONFIG_MBEDTLS_HARDWARE_SHA=n +CONFIG_MBEDTLS_CMAC_C=y +CONFIG_MBEDTLS_SSL_PROTO_DTLS=y +CONFIG_MBEDTLS_KEY_EXCHANGE_ECJPAKE=y +CONFIG_MBEDTLS_ECJPAKE_C=y +# end of mbedTLS + +# +# OpenThread +# +CONFIG_OPENTHREAD_ENABLED=y +CONFIG_OPENTHREAD_BORDER_ROUTER=n +CONFIG_OPENTHREAD_DNS64_CLIENT=y +# end of OpenThread + +# +# lwIP +# +CONFIG_LWIP_TCPIP_TASK_STACK_SIZE=4096 +CONFIG_LWIP_IPV6_NUM_ADDRESSES=8 +CONFIG_LWIP_IPV4=n +CONFIG_LWIP_ND6=n +# end of lwIP + +# +# IEEE 802.15.4 +# +CONFIG_IEEE802154_ENABLED=y +# end of IEEE 802.15.4 + +# +# deep sleep +# +CONFIG_ESP_DEFAULT_CPU_FREQ_MHZ_80=y +CONFIG_ESP_DEFAULT_CPU_FREQ_MHZ=80 +CONFIG_ULP_COPROC_ENABLED=y +CONFIG_ULP_COPROC_RESERVE_MEM=512 +CONFIG_NEWLIB_TIME_SYSCALL_USE_RTC_HRT=y +CONFIG_RTC_CLK_SRC_INT_RC=y +CONFIG_BOOTLOADER_SKIP_VALIDATE_IN_DEEP_SLEEP=y diff --git a/examples/openthread/ot_sleepy_device/light_sleep/CMakeLists.txt b/examples/openthread/ot_sleepy_device/light_sleep/CMakeLists.txt new file mode 100644 index 0000000000..876f5798c5 --- /dev/null +++ b/examples/openthread/ot_sleepy_device/light_sleep/CMakeLists.txt @@ -0,0 +1,6 @@ +# The following lines of boilerplate have to be in your project's CMakeLists +# in this exact order for cmake to work correctly +cmake_minimum_required(VERSION 3.16) + +include($ENV{IDF_PATH}/tools/cmake/project.cmake) +project(ot_sleepy_device) diff --git a/examples/openthread/ot_sleepy_device/README.md b/examples/openthread/ot_sleepy_device/light_sleep/README.md similarity index 89% rename from examples/openthread/ot_sleepy_device/README.md rename to examples/openthread/ot_sleepy_device/light_sleep/README.md index 5c832db28d..ebcf8eae27 100644 --- a/examples/openthread/ot_sleepy_device/README.md +++ b/examples/openthread/ot_sleepy_device/light_sleep/README.md @@ -3,7 +3,7 @@ # OpenThread Sleepy Device Example -The example demonstrates the Thread Sleepy End Device (SED), the device will enter [Light Sleep mode](https://docs.espressif.com/projects/esp-idf/en/latest/esp32c6/api-reference/system/sleep_modes.html#sleep-modes) during idle state. +The example demonstrates the Thread Sleepy End Device (SED), the device will enter [Light Sleep mode](https://docs.espressif.com/projects/esp-idf/en/latest/esp32h2/api-reference/system/sleep_modes.html#sleep-modes) during idle state. ## How to use example ### Hardware Required @@ -14,7 +14,7 @@ The example demonstrates the Thread Sleepy End Device (SED), the device will ent ## Configure the Openthread Dataset -* Run [ot_cli](../ot_cli/) on another 802.15.4 SoC device to create openthread dataset configuration and start an openthread network as the leader. +* Run [ot_cli](../../ot_cli/) on another 802.15.4 SoC device to create openthread dataset configuration and start an openthread network as the leader. * Configure the Openthread dataset using `idf.py menuconfig` in `Component config ---> Openthread ---> Thread Operation Dataset`, ensuring that the openthread sleepy device's dataset matches the dataset of the leader. ### Build and Flash diff --git a/examples/openthread/ot_sleepy_device/light_sleep/main/CMakeLists.txt b/examples/openthread/ot_sleepy_device/light_sleep/main/CMakeLists.txt new file mode 100644 index 0000000000..a7cde9d16a --- /dev/null +++ b/examples/openthread/ot_sleepy_device/light_sleep/main/CMakeLists.txt @@ -0,0 +1,2 @@ +idf_component_register(SRCS "esp_ot_sleepy_device.c" + INCLUDE_DIRS ".") diff --git a/examples/openthread/ot_sleepy_device/main/esp_ot_sleepy_device.c b/examples/openthread/ot_sleepy_device/light_sleep/main/esp_ot_sleepy_device.c similarity index 100% rename from examples/openthread/ot_sleepy_device/main/esp_ot_sleepy_device.c rename to examples/openthread/ot_sleepy_device/light_sleep/main/esp_ot_sleepy_device.c diff --git a/examples/openthread/ot_sleepy_device/main/esp_ot_sleepy_device_config.h b/examples/openthread/ot_sleepy_device/light_sleep/main/esp_ot_sleepy_device_config.h similarity index 100% rename from examples/openthread/ot_sleepy_device/main/esp_ot_sleepy_device_config.h rename to examples/openthread/ot_sleepy_device/light_sleep/main/esp_ot_sleepy_device_config.h diff --git a/examples/openthread/ot_sleepy_device/light_sleep/partitions.csv b/examples/openthread/ot_sleepy_device/light_sleep/partitions.csv new file mode 100644 index 0000000000..6c0e048dba --- /dev/null +++ b/examples/openthread/ot_sleepy_device/light_sleep/partitions.csv @@ -0,0 +1,5 @@ +# Name, Type, SubType, Offset, Size, Flags +# Note: if you have increased the bootloader size, make sure to update the offsets to avoid overlap +nvs, data, nvs, 0x9000, 0x6000, +phy_init, data, phy, 0xf000, 0x1000, +factory, app, factory, 0x10000, 0x120000, diff --git a/examples/openthread/ot_sleepy_device/light_sleep/sdkconfig.ci.sleepy_c6 b/examples/openthread/ot_sleepy_device/light_sleep/sdkconfig.ci.sleepy_c6 new file mode 100644 index 0000000000..80eea90801 --- /dev/null +++ b/examples/openthread/ot_sleepy_device/light_sleep/sdkconfig.ci.sleepy_c6 @@ -0,0 +1,6 @@ +CONFIG_IDF_TARGET="esp32c6" +CONFIG_IDF_TARGET_ESP32C6=y +CONFIG_OPENTHREAD_NETWORK_CHANNEL=12 +CONFIG_OPENTHREAD_NETWORK_MASTERKEY="aabbccddeeff00112233445566778899" +CONFIG_ESP_SLEEP_DEBUG=y +CONFIG_LOG_DEFAULT_LEVEL_DEBUG=y diff --git a/examples/openthread/ot_sleepy_device/light_sleep/sdkconfig.ci.sleepy_h2 b/examples/openthread/ot_sleepy_device/light_sleep/sdkconfig.ci.sleepy_h2 new file mode 100644 index 0000000000..4afe327821 --- /dev/null +++ b/examples/openthread/ot_sleepy_device/light_sleep/sdkconfig.ci.sleepy_h2 @@ -0,0 +1,6 @@ +CONFIG_IDF_TARGET="esp32h2" +CONFIG_IDF_TARGET_ESP32H2=y +CONFIG_OPENTHREAD_NETWORK_CHANNEL=12 +CONFIG_OPENTHREAD_NETWORK_MASTERKEY="aabbccddeeff00112233445566778899" +CONFIG_ESP_SLEEP_DEBUG=y +CONFIG_LOG_MAXIMUM_LEVEL_DEBUG=y diff --git a/examples/openthread/ot_sleepy_device/sdkconfig.defaults b/examples/openthread/ot_sleepy_device/light_sleep/sdkconfig.defaults similarity index 100% rename from examples/openthread/ot_sleepy_device/sdkconfig.defaults rename to examples/openthread/ot_sleepy_device/light_sleep/sdkconfig.defaults