feat(example): support esp32p4 VBAT under volt wakeup in deepsleep example

examples/lowpower/.build-test-rules.yml

@@ -0,0 +1,9 @@
+# Documentation: .gitlab/ci/README.md#manifest-file-to-control-the-buildtest-apps
+
+examples/lowpower/vbat:
+  enable:
+    - if: SOC_VBAT_SUPPORTED == 1
+  disable_test:
+    - if: IDF_TARGET in ["esp32h2"]
+      temporary: true
+      reason: not supported yet

examples/lowpower/README.md

@@ -0,0 +1,8 @@
+| Supported Targets | ESP32 | ESP32-C2 | ESP32-C3 | ESP32-C5 | ESP32-C6 | ESP32-C61 | ESP32-H2 | ESP32-P4 | ESP32-S2 | ESP32-S3 |
+| ----------------- | ----- | -------- | -------- | -------- | -------- | --------- | -------- | -------- | -------- | -------- |
+
+# System Examples
+
+Configuration and management of ESP chips lowpower related features.
+
+See the [README.md](../README.md) file in the upper level [examples](../) directory for more information about examples.

examples/lowpower/vbat/CMakeLists.txt

@@ -0,0 +1,8 @@
+# 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)
+# "Trim" the build. Include the minimal set of components, main, and anything it depends on.
+idf_build_set_property(MINIMAL_BUILD ON)
+project(vbat)

examples/lowpower/vbat/README.md

@@ -0,0 +1,100 @@
+| Supported Targets | ESP32-H2 | ESP32-P4 |
+| ----------------- | -------- | -------- |
+
+# VBAT Example
+
+(See the README.md file in the upper level 'examples' directory for more information about examples.)
+
+When the application is idle and the chip enters deepsleep, you may want to turn off the main power to save power (because the main power usually also drives other power-consuming devices on the board), but you also want the ESP chip to maintain the RTC timing and wake-up functions. Or you want to enter deepsleep mode that only maintains RTC timing but with another power supply when the main power is about to undervoltage. In these cases, you can use this feature, which allows the chip to switch to backup battery power when entering deepsleep.
+
+This example demonstrates the ESP backup battery power supply solution, which has the following features:
+
+    - Supports using backup power (VBAT) during deepsleep, and RTC Timer can keep timing after the main power is lost.
+    - Supports automatic power switching by PMU during sleep/wake-up, automatically switches to backup power supply when entering sleep mode and switches to main power supply when waking up.
+    - Support battery voltage detection, wake up the chip and switch to the main power supply when undervoltage occurs.
+    - Support battery charging, automatically stop charging when threshold voltage is reached, and charging current can be configured.
+    - Supports selection of chip status when charging the battery, options include keep active, entering lightsleep or entering deepsleep.
+
+## How to use example
+
+### Hardware Required
+
+This example should be run on a development board with a backup battery. Currently the following development boards are supported:
+    - [ESP32-P4-Function-EV-Board Rev](https://docs.espressif.com/projects/esp-dev-kits/en/latest/esp32p4/esp32-p4-function-ev-board/index.html#esp32-p4-function-ev-board)
+
+```
+                    0(%1)NC   ┌──────────┐
+       BAT ─────^^^^─────┐    │          │
+                         │    │          │  
+                         │    │ ESP32-P4 │  
+                         │    │          │  
+   ESP_3V3 ─────^^^^─────┴────┤VBAT      │
+                    0(%1)     └──────────┘
+```
+
+By default, the ESP_VBAT power supply on this development board is shorted to ESP_3V3 through a 0 Ω resistor.
+
+**You need to re-solder the resistor 0 Ω on ESP_3V3 to the empty pad on BAT. (You can find the resistor position on the schematic doc of the development board). Then connect `RTC_Battery +` to the positive terminal of the battery and `RTC_Battery -` to the negative terminal of the battery.**
+
+### Configure the project
+
+```
+idf.py menuconfig
+```
+
+- If you are using a non-rechargeable battery, VBAT brownout wakeup can be enabled via `Component config → Hardware Settings → Power Supplier → RTC Backup Battery`.
+- If you are using a rechargeable battery, the automatic wake-up charging feature can be enabled via `Component config → Hardware Settings → Power Supplier → RTC Backup Battery -> The battery for RTC battery is a rechargeable battery`.
+- The charging current limiting resistor can be configured via `Component config → Hardware Settings → Power Supplier → RTC Backup Battery -> vbat charger circuit resistor value (ohms)`.
+- The chip state while waiting for battery charging the battery can be selected by `Example Configuration → Configure the chip state while waiting for battery charging`.
+- The period to check whether the battery has been charged done can be selected by `Battery charging done check period (in seconds)`.
+
+### Build and Flash
+
+Build the project and flash it to the board, then run monitor tool to view serial output:
+
+```
+idf.py -p PORT flash monitor
+```
+
+(Replace PORT with the name of the serial port to use.)
+
+(To exit the serial monitor, type ``Ctrl-]``.)
+
+See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects.
+
+## Example Output
+
+On initial startup, this example will detect that this is the first boot and output the following log:
+
+```
+...
+I (271) main_task: Started on CPU0
+I (281) main_task: Calling app_main()
+Not a deep sleep reset
+Current RTC Time: 110106 (us)
+Entering deep sleep
+```
+
+Then the chip will then enter deep sleep, and switch to VBAT power supply.
+
+If non-rechargeable battery is used, nothing will happens when VBAT is undervoltage by default, but if `CONFIG_ESP_VBAT_WAKEUP_CHIP_ON_VBAT_BROWNOUT` is enabled, when the battery voltage drops to the configured brownout threshold `ESP_VBAT_BROWNOUT_DET_LVL_SEL`, the chip will wake up and go to sleep again, but will not switch to VBAT power during deepsleep. 
+
+```
+W VBAT: RTC battery voltage low, please change battery...
+Battery is low, VBAT power will not be used during deep sleep!
+Current RTC Time: 18493666 (us)
+Entering deep sleep
+```
+
+If rechargeable battery is used, when the battery voltage drops to the configured charging threshold (`CONFIG_ESP_VBAT_DET_LVL_LOW_SEL`), the chip will wake up and start charge the battery, when the battery voltage rises to the configured stop charging threshold (`CONFIG_ESP_VBAT_DET_LVL_HIGH_SEL`), the chip will stop charging the battery and re-enter deepsleep, and so on. The following log will be output:
+
+```
+...
+W VBAT: RTC battery voltage low, start charging...
+Wake up from Low power VBAT 
+Battery is low, waiting for charging to complete before going to sleep!
+W VBAT: RTC battery voltage reaches high limit , stop charging...
+Current RTC Time: 20753113 (us)
+Entering deep sleep
+...
+```

examples/lowpower/vbat/main/CMakeLists.txt

@@ -0,0 +1,6 @@
+set(srcs "vbat_example_main.c")
+set(includes ".")
+
+idf_component_register(SRCS ${srcs}
+                        PRIV_REQUIRES esp_pm
+                        INCLUDE_DIRS ${includes})

examples/lowpower/vbat/main/Kconfig.projbuild

@@ -0,0 +1,26 @@
+menu "Example Configuration"
+    choice EXAMPLE_STATE_WHILE_WAITING_BATTERY_CHARGE_DONE
+        bool "Configure the chip state while waiting for battery charging"
+        default EXAMPLE_WAITING_BATTERY_CHARGING_IN_ACTIVE
+        depends on ESP_VBAT_USE_RECHARGEABLE_BATTERY
+        help
+            Select chip state when waiting battery charging done
+
+        config EXAMPLE_WAITING_BATTERY_CHARGING_IN_ACTIVE
+            bool "Waiting for battery charging in active state"
+        config EXAMPLE_WAITING_BATTERY_CHARGING_IN_LIGHT_SLEEP
+            bool "Waiting for battery charging in light sleep state"
+            select PM_ENABLE
+            select FREERTOS_USE_TICKLESS_IDLE
+        config EXAMPLE_WAITING_BATTERY_CHARGING_IN_DEEP_SLEEP
+            bool "Waiting for battery charging in deep sleep state"
+    endchoice
+
+    config EXAMPLE_VBAT_CHARGING_DONE_CHECK_PERIOD
+        int "Battery charging done check period (in seconds)"
+        default 60
+        depends on ESP_VBAT_USE_RECHARGEABLE_BATTERY
+        help
+            Period in seconds to check whether the battery has been charged done
+
+endmenu

examples/lowpower/vbat/main/vbat_example_main.c

@@ -0,0 +1,77 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Unlicense OR CC0-1.0
+ */
+
+#include <stdio.h>
+#include <time.h>
+#include "sdkconfig.h"
+#include "soc/soc_caps.h"
+#include "esp_vbat.h"
+#include "esp_pm.h"
+#include "esp_rtc_time.h"
+#include "esp_sleep.h"
+
+void app_main(void)
+{
+#if CONFIG_EXAMPLE_WAITING_BATTERY_CHARGING_IN_LIGHT_SLEEP
+    esp_pm_config_t pm_config = {
+        .max_freq_mhz = CONFIG_ESP_DEFAULT_CPU_FREQ_MHZ,
+        .min_freq_mhz = CONFIG_XTAL_FREQ,
+        .light_sleep_enable = true
+    };
+    ESP_ERROR_CHECK(esp_pm_configure(&pm_config));
+#endif
+
+    if (esp_sleep_get_wakeup_cause() == ESP_SLEEP_WAKEUP_VBAT_UNDER_VOLT) {
+#if CONFIG_ESP_VBAT_USE_RECHARGEABLE_BATTERY
+        printf("Wake up from VBAT low power\n");
+#else
+        printf("Wake up from VBAT brownout\n");
+#endif
+    } else if (esp_sleep_get_wakeup_cause() == ESP_SLEEP_WAKEUP_TIMER) {
+        printf("Wake up from Timer\n");
+    } else {
+        printf("Not a deep sleep reset\n");
+    }
+
+    esp_err_t sleep_result;
+    do {
+#if CONFIG_ESP_VBAT_USE_RECHARGEABLE_BATTERY
+        if (esp_vbat_get_battery_state() == ESP_VBAT_STATE_CHARGING) {
+#if CONFIG_EXAMPLE_WAITING_BATTERY_CHARGING_IN_DEEP_SLEEP
+            printf("Battery is charging, wake up the chip every %d seconds to check whether the battery is charged done !\n", CONFIG_EXAMPLE_VBAT_CHARGING_DONE_CHECK_PERIOD);
+            esp_sleep_enable_timer_wakeup(CONFIG_EXAMPLE_VBAT_CHARGING_DONE_CHECK_PERIOD * 1000 * 1000);
+#else
+            printf("Battery is low, waiting for charging to complete before going to deep sleep!\n");
+            do {
+                // Task will enter block state in `esp_vbat_wait_battery_charge_done`, staying in active state or
+                // entering lightsleep is determined by esp_pm configuration.
+                if (esp_vbat_wait_battery_charge_done(CONFIG_EXAMPLE_VBAT_CHARGING_DONE_CHECK_PERIOD * 1000 / portTICK_PERIOD_MS) == ESP_OK) {
+                    printf("Battery charging done!\n");
+                    break;
+                }
+            } while (1);
+#endif
+        }
+#else
+        if (esp_vbat_get_battery_state() == ESP_VBAT_STATE_LOWBATTERY) {
+            printf("Battery is low, VBAT power will not be used during deep sleep!\n");
+        }
+#endif
+
+#if CONFIG_EXAMPLE_WAITING_BATTERY_CHARGING_IN_LIGHT_SLEEP
+        // Disable auto-lightsleep configured timer wakeup source here.
+        pm_config.light_sleep_enable = false;
+        ESP_ERROR_CHECK(esp_pm_configure(&pm_config));
+#endif
+
+        // enter deep sleep
+        printf("Current RTC Time: %lld (us)\n", esp_rtc_get_time_us());
+        printf("Entering deep sleep\n");
+        sleep_result = esp_deep_sleep_try_to_start();
+        vTaskDelay(1000 / portTICK_PERIOD_MS);
+        printf("Failed to enter deepsleep, please check wakeup source setting and state!\n");
+    } while (sleep_result != ESP_OK);
+}

examples/lowpower/vbat/sdkconfig.ci.nonrechargeable_batteray

@@ -0,0 +1,2 @@
+CONFIG_ESP_VBAT_USE_RECHARGEABLE_BATTERY=n
+CONFIG_ESP_VBAT_WAKEUP_CHIP_ON_VBAT_BROWNOUT=y

examples/lowpower/vbat/sdkconfig.ci.rechargeable_batteray

@@ -0,0 +1 @@
+CONFIG_ESP_VBAT_USE_RECHARGEABLE_BATTERY=y

examples/lowpower/vbat/sdkconfig.defaults

@@ -0,0 +1,2 @@
+# Generic config
+CONFIG_ESP_VBAT_INIT_AUTO=y