Merge branch 'feat/button_add_button_end_event' into 'master'

feat(button): support enter power save manually

See merge request ae_group/esp-iot-solution!1056

Author: lijunru-hub

components/button/CHANGELOG.md

@@ -1,5 +1,12 @@
 # ChangeLog
 
+## v3.3.0 - 2024-8-7
+
+### Enhancements:
+
+* Add Callback **button_power_save_cb_t** to support enter power save manually.
+* Increase the maximum polling interval supported by the button from 20ms to 50ms.
+
 ## v3.2.3 - 2024-7-2
 
 * Fixed the issue where the GPIO button in low-power mode continuously woke up the CPU after being pressed, causing abnormal power consumption.

components/button/Kconfig

@@ -2,7 +2,7 @@ menu "IoT Button"
 
     config BUTTON_PERIOD_TIME_MS
         int "BUTTON PERIOD TIME (MS)"
-        range 2 20
+        range 2 50
         default 5
         help
             "Button scan interval"

components/button/idf_component.yml

@@ -1,4 +1,4 @@
-version: "3.2.3"
+version: "3.3.0"
 description: GPIO and ADC button driver
 url: https://github.com/espressif/esp-iot-solution/tree/master/components/button
 repository: https://github.com/espressif/esp-iot-solution.git

components/button/include/iot_button.h

@@ -18,6 +18,20 @@ extern "C" {
 #endif
 
 typedef void (* button_cb_t)(void *button_handle, void *usr_data);
+
+#if CONFIG_GPIO_BUTTON_SUPPORT_POWER_SAVE
+typedef void (* button_power_save_cb_t)(void *usr_data);
+
+/**
+ * @brief Structs to store power save callback info
+ *
+ */
+typedef struct {
+    button_power_save_cb_t enter_power_save_cb;
+    void *usr_data;
+} button_power_save_config_t;
+#endif
+
 typedef void *button_handle_t;
 
 /**
@@ -301,6 +315,21 @@ esp_err_t iot_button_resume(void);
  */
 esp_err_t iot_button_stop(void);
 
+#if CONFIG_GPIO_BUTTON_SUPPORT_POWER_SAVE
+/**
+ * @brief Register a callback function for power saving.
+ *        The config->enter_power_save_cb function will be called when all keys stop working.
+ *
+ * @param config Button power save config
+ * @return
+ *     - ESP_OK                  on success
+ *     - ESP_ERR_INVALID_STATE   No button registered
+ *     - ESP_ERR_INVALID_ARG     Arguments is invalid
+ *     - ESP_ERR_NO_MEM          Not enough memory
+ */
+esp_err_t iot_button_register_power_save_cb(const button_power_save_config_t *config);
+#endif
+
 #ifdef __cplusplus
 }
 #endif

components/button/iot_button.c

@@ -70,6 +70,9 @@ typedef struct Button {
 static button_dev_t *g_head_handle = NULL;
 static esp_timer_handle_t g_button_timer_handle = NULL;
 static bool g_is_timer_running = false;
+#if CONFIG_GPIO_BUTTON_SUPPORT_POWER_SAVE
+static button_power_save_config_t power_save_usr_cfg = {0};
+#endif
 
 #define TICKS_INTERVAL    CONFIG_BUTTON_PERIOD_TIME_MS
 #define DEBOUNCE_TICKS    CONFIG_BUTTON_DEBOUNCE_TICKS //MAX 8
@@ -318,6 +321,10 @@ static void button_cb(void *args)
                 button_gpio_enable_gpio_wakeup((uint32_t)(target->hardware_data), target->active_level, true);
             }
         }
+        /*!< Notify the user that the Button has entered power save mode by calling this callback function. */
+        if (power_save_usr_cfg.enter_power_save_cb) {
+            power_save_usr_cfg.enter_power_save_cb(power_save_usr_cfg.usr_data);
+        }
     }
 #endif
 }
@@ -764,3 +771,15 @@ esp_err_t iot_button_stop(void)
     g_is_timer_running = false;
     return ESP_OK;
 }
+
+#if CONFIG_GPIO_BUTTON_SUPPORT_POWER_SAVE
+esp_err_t iot_button_register_power_save_cb(const button_power_save_config_t *config)
+{
+    BTN_CHECK(g_head_handle, "No button registered", ESP_ERR_INVALID_STATE);
+    BTN_CHECK(config->enter_power_save_cb, "Enter power save callback is invalid", ESP_ERR_INVALID_ARG);
+
+    power_save_usr_cfg.enter_power_save_cb = config->enter_power_save_cb;
+    power_save_usr_cfg.usr_data = config->usr_data;
+    return ESP_OK;
+}
+#endif

docs/en/input_device/button.rst

@@ -21,35 +21,34 @@ Button event
 
 Triggering conditions for each button event are enlisted in the table below:
 
-
-+--------------------------+-----------------------------------+
-|          Event           |         Trigger Condition         |
-+==========================+===================================+
-| BUTTON_PRESS_DOWN        | Pressed                           |
-+--------------------------+-----------------------------------+
-| BUTTON_PRESS_UP          | Released                          |
-+--------------------------+-----------------------------------+
-| BUTTON_PRESS_REPEAT      | Pressed and released >= 2 times   |
-+--------------------------+-----------------------------------+
-| BUTTON_PRESS_REPEAT_DONE | Repeated press completed          |
-+--------------------------+-----------------------------------+
-| BUTTON_SINGLE_CLICK      | Pressed and released once         |
-+--------------------------+-----------------------------------+
-| BUTTON_DOUBLE_CLICK      | Pressed and released twice        |
-+--------------------------+-----------------------------------+
-| BUTTON_MULTIPLE_CLICK    | Pressed and released N times      |
-|                          | specified, triggers when achieved |
-+--------------------------+-----------------------------------+
-| BUTTON_LONG_PRESS_START  | Instant when held for a threshold |
-|                          | duration of time                  |
-+--------------------------+-----------------------------------+
-| BUTTON_LONG_PRESS_HOLD   | Triggered continuously during     |
-|                          | long press                        |
-+--------------------------+-----------------------------------+
-| BUTTON_LONG_PRESS_UP     | Released after a long press       |
-+--------------------------+-----------------------------------+
-| BUTTON_PRESS_REPEAT_DONE | Repeated press and release ended  |
-+--------------------------+-----------------------------------+
++--------------------------+--------------------------------------+
+|          Event           |          Trigger Condition           |
++==========================+======================================+
+| BUTTON_PRESS_DOWN        | Pressed                              |
++--------------------------+--------------------------------------+
+| BUTTON_PRESS_UP          | Released                             |
++--------------------------+--------------------------------------+
+| BUTTON_PRESS_REPEAT      | Pressed and released >= 2 times      |
++--------------------------+--------------------------------------+
+| BUTTON_PRESS_REPEAT_DONE | Repeated press completed             |
++--------------------------+--------------------------------------+
+| BUTTON_SINGLE_CLICK      | Pressed and released once            |
++--------------------------+--------------------------------------+
+| BUTTON_DOUBLE_CLICK      | Pressed and released twice           |
++--------------------------+--------------------------------------+
+| BUTTON_MULTIPLE_CLICK    | Pressed and released N times         |
+|                          | specified, triggers when achieved    |
++--------------------------+--------------------------------------+
+| BUTTON_LONG_PRESS_START  | Instant when held for a threshold    |
+|                          | duration of time                     |
++--------------------------+--------------------------------------+
+| BUTTON_LONG_PRESS_HOLD   | Triggered continuously during        |
+|                          | long press                           |
++--------------------------+--------------------------------------+
+| BUTTON_LONG_PRESS_UP     | Released after a long press          |
++--------------------------+--------------------------------------+
+| BUTTON_PRESS_REPEAT_DONE | Repeated press and release ended     |
++--------------------------+--------------------------------------+
 
 Each button supports **call-back** and **pooling** mode.
 
@@ -277,6 +276,25 @@ As shown, low-power mode results in more power savings.
     };
     button_handle_t btn = iot_button_create(&btn_cfg);
 
+When to Enter Light Sleep
+
+- Using Auto Light Sleep: The device will enter Light Sleep automatically after the button closes the esp_timer.
+
+- User-Controlled Light Sleep: The device can enter Light Sleep when ``enter_power_save_cb`` is called.
+
+.. code:: c
+
+    void btn_enter_power_save(void *usr_data)
+    {
+        ESP_LOGI(TAG, "Can enter power save now");
+    }
+
+    button_power_save_config_t config = {
+        .enter_power_save_cb = btn_enter_power_save,
+    };
+
+    iot_button_register_power_save_cb(&config);
+
 Stop and resume
 ^^^^^^^^^^^^^^^^^
 

docs/zh_CN/input_device/button.rst

@@ -277,6 +277,25 @@ Button 组件支持为多个事件注册回调函数，每个事件都可以注
     };
     button_handle_t btn = iot_button_create(&btn_cfg);
 
+什么时候进入 Light Sleep
+
+- 使用 Auto Light Sleep: 会在 button 自动关闭 esp_timer 后进入 Light Sleep
+
+- 用户控制 Light Sleep: 需要在 ``enter_power_save_cb`` 回调到来时进入 Light Sleep
+
+.. code:: c
+
+    void btn_enter_power_save(void *usr_data)
+    {
+        ESP_LOGI(TAG, "Can enter power save now");
+    }
+
+    button_power_save_config_t config = {
+        .enter_power_save_cb = btn_enter_power_save,
+    };
+
+    iot_button_register_power_save_cb(&config);
+
 开启和关闭
 ^^^^^^^^^^^^^
 

examples/get-started/button_power_save/main/Kconfig.projbuild

@@ -1,5 +1,18 @@
 menu "Example Configuration"
 
+    choice ENTER_LIGHT_SLEEP_MODE
+        prompt "Enter light sleep mode"
+        default ENTER_LIGHT_SLEEP_AUTO
+        depends on PM_ENABLE
+        help
+            Enable light sleep mode to save power.
+
+        config ENTER_LIGHT_SLEEP_AUTO
+            bool "Auto enter Light Sleep"
+        config ENTER_LIGHT_SLEEP_MODE_MANUALLY
+            bool "Manually enter Light Sleep"
+    endchoice
+
     choice EXAMPLE_MAX_CPU_FREQ
         prompt "Maximum CPU frequency"
         default EXAMPLE_MAX_CPU_FREQ_80 if !IDF_TARGET_ESP32H2

examples/get-started/button_power_save/main/main.c

@@ -47,6 +47,14 @@ static void button_event_cb(void *arg, void *data)
     }
 }
 
+#if CONFIG_ENTER_LIGHT_SLEEP_MODE_MANUALLY
+void button_enter_power_save(void *usr_data)
+{
+    ESP_LOGI(TAG, "Can enter power save now");
+    esp_light_sleep_start();
+}
+#endif
+
 void button_init(uint32_t button_num)
 {
     button_config_t btn_cfg = {
@@ -70,6 +78,15 @@ void button_init(uint32_t button_num)
     err |= iot_button_register_cb(btn, BUTTON_LONG_PRESS_START, button_event_cb, (void *)BUTTON_LONG_PRESS_START);
     err |= iot_button_register_cb(btn, BUTTON_LONG_PRESS_HOLD, button_event_cb, (void *)BUTTON_LONG_PRESS_HOLD);
     err |= iot_button_register_cb(btn, BUTTON_LONG_PRESS_UP, button_event_cb, (void *)BUTTON_LONG_PRESS_UP);
+
+#if CONFIG_ENTER_LIGHT_SLEEP_MODE_MANUALLY
+    /*!< For enter Power Save */
+    button_power_save_config_t config = {
+        .enter_power_save_cb = button_enter_power_save,
+    };
+    err |= iot_button_register_power_save_cb(&config);
+#endif
+
     ESP_ERROR_CHECK(err);
 }
 
@@ -111,6 +128,10 @@ void power_save_init(void)
 
 void app_main(void)
 {
-    power_save_init();
     button_init(BOOT_BUTTON_NUM);
+#if CONFIG_ENTER_LIGHT_SLEEP_AUTO
+    power_save_init();
+#else
+    esp_light_sleep_start();
+#endif
 }

examples/get-started/button_power_save/sdkconfig.ci.ls_manually

@@ -0,0 +1 @@
+CONFIG_ENTER_LIGHT_SLEEP_MODE_MANUALLY=y\