add some code

managed_components/espressif__button/include/button_adc.h

@@ -0,0 +1,57 @@
+/* SPDX-FileCopyrightText: 2022-2025 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#pragma once
+
+#include "driver/gpio.h"
+#include "esp_adc/adc_oneshot.h"
+#include "button_types.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @brief adc button configuration
+ *
+ */
+typedef struct {
+    adc_oneshot_unit_handle_t *adc_handle;           /**< handle of adc unit, if NULL will create new one internal, else will use the handle */
+    adc_unit_t unit_id;                              /**< ADC unit */
+    uint8_t adc_channel;                             /**< Channel of ADC */
+    uint8_t button_index;                            /**< button index on the channel */
+    uint16_t min;                                    /**< min voltage in mv corresponding to the button */
+    uint16_t max;                                    /**< max voltage in mv corresponding to the button */
+} button_adc_config_t;
+
+/**
+ * @brief Create a new ADC button device
+ *
+ * This function initializes and configures a new ADC button device using the given configuration parameters.
+ * It manages the ADC unit, channels, and button-specific parameters, and ensures proper resource allocation
+ * for the ADC button object.
+ *
+ * @param[in] button_config Configuration for the button device, including callbacks and debounce parameters.
+ * @param[in] adc_config Configuration for the ADC channel and button, including the ADC unit, channel,
+ *                        button index, and voltage range (min and max).
+ * @param[out] ret_button Handle to the newly created button device.
+ *
+ * @return
+ *     - ESP_OK: Successfully created the ADC button device.
+ *     - ESP_ERR_INVALID_ARG: Invalid argument provided.
+ *     - ESP_ERR_NO_MEM: Memory allocation failed.
+ *     - ESP_ERR_INVALID_STATE: The requested button index or channel is already in use, or no channels are available.
+ *     - ESP_FAIL: Failed to initialize or configure the ADC or button device.
+ *
+ * @note
+ * - If the ADC unit is not already configured, it will be initialized with the provided or default settings.
+ * - If the ADC channel is not initialized, it will be configured for the specified unit and calibrated.
+ * - This function ensures that ADC resources are reused whenever possible to optimize resource allocation.
+ */
+esp_err_t iot_button_new_adc_device(const button_config_t *button_config, const button_adc_config_t *adc_config, button_handle_t *ret_button);
+
+#ifdef __cplusplus
+}
+#endif

managed_components/espressif__button/include/button_gpio.h

@@ -0,0 +1,53 @@
+/* SPDX-FileCopyrightText: 2022-2025 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#pragma once
+
+#include "esp_err.h"
+#include "button_types.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @brief gpio button configuration
+ *
+ */
+typedef struct {
+    int32_t gpio_num;              /**< num of gpio */
+    uint8_t active_level;          /**< gpio level when press down */
+    bool enable_power_save;        /**< enable power save mode */
+    bool disable_pull;             /**< disable internal pull up or down */
+} button_gpio_config_t;
+
+/**
+ * @brief Create a new GPIO button device
+ *
+ * This function initializes and configures a GPIO-based button device using the given configuration parameters.
+ * It sets up the GPIO pin, configures its input mode, and optionally enables power-saving features or wake-up functionality.
+ *
+ * @param[in] button_config Configuration for the button device, including callbacks and debounce parameters.
+ * @param[in] gpio_cfg Configuration for the GPIO, including the pin number, active level, and power-save options.
+ * @param[out] ret_button Handle to the newly created GPIO button device.
+ *
+ * @return
+ *     - ESP_OK: Successfully created the GPIO button device.
+ *     - ESP_ERR_INVALID_ARG: Invalid argument provided, such as an invalid GPIO number.
+ *     - ESP_ERR_NO_MEM: Memory allocation failed.
+ *     - ESP_ERR_INVALID_STATE: Failed to configure GPIO wake-up or interrupt settings.
+ *     - ESP_FAIL: General failure, such as unsupported wake-up configuration on the target.
+ *
+ * @note
+ * - If power-saving is enabled, the GPIO will be configured as a wake-up source for light sleep.
+ * - Pull-up or pull-down resistors are configured based on the `active_level` and the `disable_pull` flag.
+ * - This function checks for the validity of the GPIO as a wake-up source when power-saving is enabled.
+ * - If power-saving is not supported by the hardware or configuration, the function will return an error.
+ */
+esp_err_t iot_button_new_gpio_device(const button_config_t *button_config, const button_gpio_config_t *gpio_config, button_handle_t *ret_button);
+
+#ifdef __cplusplus
+}
+#endif

managed_components/espressif__button/include/button_matrix.h

@@ -0,0 +1,70 @@
+/*
+ * SPDX-FileCopyrightText: 2023-2025 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+#pragma once
+
+#include "esp_err.h"
+#include "button_types.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @brief Button matrix key configuration.
+ *        Just need to configure the GPIO associated with this GPIO in the matrix keyboard.
+ *
+ *        Matrix Keyboard Layout (3x3):
+ *        ----------------------------------------
+ *        |  Button 1  |  Button 2  |  Button 3  |
+ *        |  (R1-C1)   |  (R1-C2)   |  (R1-C3)   |
+ *        |--------------------------------------|
+ *        |  Button 4  |  Button 5  |  Button 6  |
+ *        |  (R2-C1)   |  (R2-C2)   |  (R2-C3)   |
+ *        |--------------------------------------|
+ *        |  Button 7  |  Button 8  |  Button 9  |
+ *        |  (R3-C1)   |  (R3-C2)   |  (R3-C3)   |
+ *        ----------------------------------------
+ *
+ *        - Button matrix key is driven using row scanning.
+ *        - Buttons within the same column cannot be detected simultaneously,
+ *          but buttons within the same row can be detected without conflicts.
+ */
+typedef struct {
+    int32_t *row_gpios;        /**< GPIO number list for the row */
+    int32_t *col_gpios;        /**< GPIO number list for the column */
+    uint32_t row_gpio_num;     /**< Number of GPIOs associated with the row */
+    uint32_t col_gpio_num;     /**< Number of GPIOs associated with the column */
+} button_matrix_config_t;
+
+/**
+ * @brief Create a new button matrix device
+ *
+ * This function initializes and configures a button matrix device using the specified row and column GPIOs.
+ * Each button in the matrix is represented as an independent button object, and its handle is returned in the `ret_button` array.
+ *
+ * @param[in] button_config Configuration for the button device, including callbacks and debounce parameters.
+ * @param[in] matrix_config Configuration for the matrix, including row and column GPIOs and their counts.
+ * @param[out] ret_button Array of handles for the buttons in the matrix.
+ * @param[inout] size Pointer to the total number of buttons in the matrix. Must match the product of row and column GPIO counts.
+ *                    On success, this value is updated to reflect the size of the button matrix.
+ *
+ * @return
+ *     - ESP_OK: Successfully created the button matrix device.
+ *     - ESP_ERR_INVALID_ARG: Invalid argument provided, such as null pointers or mismatched matrix dimensions.
+ *     - ESP_ERR_NO_MEM: Memory allocation failed.
+ *     - ESP_FAIL: General failure, such as button creation failure for one or more buttons.
+ *
+ * @note
+ * - Each row GPIO is configured as an output, while each column GPIO is configured as an input.
+ * - The total number of buttons in the matrix must equal the product of the row and column GPIO counts.
+ * - The `ret_button` array must be large enough to store handles for all buttons in the matrix.
+ * - If any button creation fails, the function will free all allocated resources and return an error.
+ */
+esp_err_t iot_button_new_matrix_device(const button_config_t *button_config, const button_matrix_config_t *matrix_config, button_handle_t *ret_button, size_t *size);
+
+#ifdef __cplusplus
+}
+#endif

managed_components/espressif__button/include/button_types.h

@@ -0,0 +1,57 @@
+/*
+ * SPDX-FileCopyrightText: 2024-2025 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+#pragma once
+
+#include <stdint.h>
+#include "esp_err.h"
+#include "button_interface.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+enum {
+    BUTTON_INACTIVE = 0,
+    BUTTON_ACTIVE,
+};
+
+typedef struct button_dev_t *button_handle_t;
+
+/**
+ * @brief Button configuration
+ *
+ */
+typedef struct {
+    uint16_t long_press_time;                         /**< Trigger time(ms) for long press, if 0 default to BUTTON_LONG_PRESS_TIME_MS */
+    uint16_t short_press_time;                        /**< Trigger time(ms) for short press, if 0 default to BUTTON_SHORT_PRESS_TIME_MS */
+} button_config_t;
+
+/**
+ * @brief Create a new IoT button instance
+ *
+ * This function initializes a new button instance with the specified configuration
+ * and driver. It also sets up internal resources such as the button timer if not
+ * already initialized.
+ *
+ * @param[in] config        Pointer to the button configuration structure
+ * @param[in] driver        Pointer to the button driver structure
+ * @param[out] ret_button   Pointer to where the handle of the created button will be stored
+ *
+ * @return
+ *      - ESP_OK: Successfully created the button
+ *      - ESP_ERR_INVALID_ARG: Invalid arguments passed to the function
+ *      - ESP_ERR_NO_MEM: Memory allocation failed
+ *
+ * @note
+ * - The first call to this function logs the IoT Button version.
+ * - The function initializes a global button timer if it is not already running.
+ * - Timer is started only if the driver does not enable power-saving mode.
+ */
+esp_err_t iot_button_create(const button_config_t *config, const button_driver_t *driver, button_handle_t *ret_button);
+
+#ifdef __cplusplus
+}
+#endif

managed_components/espressif__button/include/iot_button.h

@@ -0,0 +1,265 @@
+/* SPDX-FileCopyrightText: 2022-2024 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#pragma once
+
+#include "sdkconfig.h"
+#include "esp_err.h"
+#include "button_types.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+typedef void (* button_cb_t)(void *button_handle, void *usr_data);
+
+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;  /**< Callback function when entering power save mode */
+    void *usr_data;                              /**< User data for the callback */
+} button_power_save_config_t;
+
+/**
+ * @brief Button events
+ *
+ */
+typedef enum {
+    BUTTON_PRESS_DOWN = 0,
+    BUTTON_PRESS_UP,
+    BUTTON_PRESS_REPEAT,
+    BUTTON_PRESS_REPEAT_DONE,
+    BUTTON_SINGLE_CLICK,
+    BUTTON_DOUBLE_CLICK,
+    BUTTON_MULTIPLE_CLICK,
+    BUTTON_LONG_PRESS_START,
+    BUTTON_LONG_PRESS_HOLD,
+    BUTTON_LONG_PRESS_UP,
+    BUTTON_PRESS_END,
+    BUTTON_EVENT_MAX,
+    BUTTON_NONE_PRESS,
+} button_event_t;
+
+/**
+ * @brief Button events arg
+ *
+ */
+typedef union {
+    /**
+     * @brief Long press time event data
+     *
+     */
+    struct long_press_t {
+        uint16_t press_time;    /**< press time(ms) for the corresponding callback to trigger */
+    } long_press;               /**< long press struct, for event BUTTON_LONG_PRESS_START and BUTTON_LONG_PRESS_UP */
+
+    /**
+     * @brief Multiple clicks event data
+     *
+     */
+    struct multiple_clicks_t {
+        uint16_t clicks;        /**< number of clicks, to trigger the callback */
+    } multiple_clicks;          /**< multiple clicks struct, for event BUTTON_MULTIPLE_CLICK */
+} button_event_args_t;
+
+/**
+ * @brief Button parameter
+ *
+ */
+typedef enum {
+    BUTTON_LONG_PRESS_TIME_MS = 0,
+    BUTTON_SHORT_PRESS_TIME_MS,
+    BUTTON_PARAM_MAX,
+} button_param_t;
+
+/**
+ * @brief Delete a button
+ *
+ * @param btn_handle A button handle to delete
+ *
+ * @return
+ *      - ESP_OK  Success
+ *      - ESP_FAIL Failure
+ */
+esp_err_t iot_button_delete(button_handle_t btn_handle);
+
+/**
+ * @brief Register the button event callback function.
+ *
+ * @param btn_handle A button handle to register
+ * @param event Button event
+ * @param event_args Button event arguments
+ * @param cb Callback function.
+ * @param usr_data user data
+ *
+ * @return
+ *      - ESP_OK on success
+ *      - ESP_ERR_INVALID_ARG   Arguments is invalid.
+ *      - ESP_ERR_INVALID_STATE The Callback is already registered. No free Space for another Callback.
+ *      - ESP_ERR_NO_MEM        No more memory allocation for the event
+ */
+esp_err_t iot_button_register_cb(button_handle_t btn_handle, button_event_t event, button_event_args_t *event_args, button_cb_t cb, void *usr_data);
+
+/**
+ * @brief Unregister all the callbacks associated with the event.
+ *
+ * @param btn_handle A button handle to unregister
+ * @param event Button event
+ * @param event_args Used for unregistering a specific callback.
+ *
+ * @return
+ *      - ESP_OK on success
+ *      - ESP_ERR_INVALID_ARG   Arguments is invalid.
+ *      - ESP_ERR_INVALID_STATE No callbacks registered for the event
+ */
+esp_err_t iot_button_unregister_cb(button_handle_t btn_handle, button_event_t event, button_event_args_t *event_args);
+
+/**
+ * @brief counts total callbacks registered
+ *
+ * @param btn_handle A button handle to the button
+ *
+ * @return
+ *      - 0 if no callbacks registered, or 1 .. (BUTTON_EVENT_MAX-1) for the number of Registered Buttons.
+ *      - ESP_ERR_INVALID_ARG if btn_handle is invalid
+ */
+size_t iot_button_count_cb(button_handle_t btn_handle);
+
+/**
+ * @brief how many callbacks are registered for the event
+ *
+ * @param btn_handle A button handle to the button
+ *
+ * @param event Button event
+ *
+ * @return
+ *      - 0 if no callbacks registered, or 1 .. (BUTTON_EVENT_MAX-1) for the number of Registered Buttons.
+ *      - ESP_ERR_INVALID_ARG if btn_handle is invalid
+ */
+size_t iot_button_count_event_cb(button_handle_t btn_handle, button_event_t event);
+
+/**
+ * @brief Get button event
+ *
+ * @param btn_handle Button handle
+ *
+ * @return Current button event. See button_event_t
+ */
+button_event_t iot_button_get_event(button_handle_t btn_handle);
+
+/**
+ * @brief Get the string representation of a button event.
+ *
+ * This function returns the corresponding string for a given button event.
+ * If the event value is outside the valid range, the function returns error string "event value is invalid".
+ *
+ * @param[in] event The button event to be converted to a string.
+ *
+ * @return
+ *      - Pointer to the event string if the event is valid.
+ *      - "invalid event" if the event value is invalid.
+ */
+const char *iot_button_get_event_str(button_event_t event);
+
+/**
+ * @brief Log the current button event as a string.
+ *
+ * This function prints the string representation of the current event associated with the button.
+ *
+ * @param[in] btn_handle Handle to the button object.
+ *
+ * @return
+ *      - ESP_OK: Successfully logged the event string.
+ *      - ESP_FAIL: Invalid button handle.
+ */
+esp_err_t iot_button_print_event(button_handle_t btn_handle);
+
+/**
+ * @brief Get button repeat times
+ *
+ * @param btn_handle Button handle
+ *
+ * @return button pressed times. For example, double-click return 2, triple-click return 3, etc.
+ */
+uint8_t iot_button_get_repeat(button_handle_t btn_handle);
+
+/**
+ * @brief Get button ticks time
+ *
+ * @param btn_handle Button handle
+ *
+ * @return Actual time from press down to up (ms).
+ */
+uint32_t iot_button_get_ticks_time(button_handle_t btn_handle);
+
+/**
+ * @brief Get button long press hold count
+ *
+ * @param btn_handle Button handle
+ *
+ * @return Count of trigger cb(BUTTON_LONG_PRESS_HOLD)
+ */
+uint16_t iot_button_get_long_press_hold_cnt(button_handle_t btn_handle);
+
+/**
+ * @brief Dynamically change the parameters of the iot button
+ *
+ * @param btn_handle Button handle
+ * @param param Button parameter
+ * @param value new value
+ * @return
+ *      - ESP_OK on success
+ *      - ESP_ERR_INVALID_ARG   Arguments is invalid.
+ */
+esp_err_t iot_button_set_param(button_handle_t btn_handle, button_param_t param, void *value);
+
+/**
+ * @brief Get button key level
+ *
+ * @param btn_handle Button handle
+ * @return
+ *      - 1 if key is pressed
+ *      - 0 if key is released or invalid button handle
+ */
+uint8_t iot_button_get_key_level(button_handle_t btn_handle);
+
+/**
+ * @brief resume button timer, if button timer is stopped. Make sure iot_button_create() is called before calling this API.
+ *
+ * @return
+ *     - ESP_OK on success
+ *     - ESP_ERR_INVALID_STATE   timer state is invalid.
+ */
+esp_err_t iot_button_resume(void);
+
+/**
+ * @brief stop button timer, if button timer is running. Make sure iot_button_create() is called before calling this API.
+ *
+ * @return
+ *     - ESP_OK on success
+ *     - ESP_ERR_INVALID_STATE   timer state is invalid
+ */
+esp_err_t iot_button_stop(void);
+
+/**
+ * @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);
+
+#ifdef __cplusplus
+}
+#endif