Button

[中文]

The button component supports GPIO and ADC mode, and it allows the creation of two different kinds of the button at the same time. The following figure shows the hardware design of the button:

• GPIO button: The advantage of the GPIO button is that each button occupies an independent IO and therefore does not affect each other, and has high stability however when the number of buttons increases, it may take too many IO resources.

• ADC button: The advantage of using the ADC button is that one ADC channel can share multiple buttons and occupy fewer IO resources. The disadvantages include that you cannot press multiple buttons at the same time, and instability increases due to increase in the closing resistance of the button due to oxidation and other factors.

Note

• The GPIO button needs to pay attention to the problem of pull-up and pull-down resistor inside the chip, which will be enabled by default. But there is no such resistor inside the IO that only supports input, external connection requires.

• The voltage of the ADC button should not exceed the ADC range.

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
BUTTON_PRESS_END	Indicate that the button has completed its current detection.

Each button supports call-back and pooling mode.

• Call-back: Each event of a button can register a call-back function for it, and the call-back function will be called when an event is generated. This method has high efficiency and real-time performance, and no events will be lost.

• Polling: Periodically call iot_button_get_event() in the program to query the current event of the button. This method is easy to use and is suitable for occasions with simple tasks. Not all key press events are captured in time, leading to a risk of missing events.

Note

you can also combine the above two methods.

Attention

No blocking operations such as TaskDelay are allowed in the call-back function

Configuration

• BUTTON_PERIOD_TIME_MS : scan cycle

• BUTTON_DEBOUNCE_TICKS : debounce time

• BUTTON_SHORT_PRESS_TIME_MS : short press down effective time

• BUTTON_LONG_PRESS_TIME_MS : long press down effective time

• ADC_BUTTON_MAX_CHANNEL : maximum number of channel for ADC

• ADC_BUTTON_MAX_BUTTON_PER_CHANNEL : maximum number of ADC buttons per channel

• ADC_BUTTON_SAMPLE_TIMES: The number of samples per ADC scan.

• BUTTON_LONG_PRESS_HOLD_SERIAL_TIME_MS: The interval time for triggering the callback during a long press.

Demonstration

Create a button

// create gpio button
button_config_t gpio_btn_cfg = {
    .type = BUTTON_TYPE_GPIO,
    .long_press_time = CONFIG_BUTTON_LONG_PRESS_TIME_MS,
    .short_press_time = CONFIG_BUTTON_SHORT_PRESS_TIME_MS,
    .gpio_button_config = {
        .gpio_num = 0,
        .active_level = 0,
    },
};
button_handle_t gpio_btn = iot_button_create(&gpio_btn_cfg);
if(NULL == gpio_btn) {
    ESP_LOGE(TAG, "Button create failed");
}

// create adc button
button_config_t adc_btn_cfg = {
    .type = BUTTON_TYPE_ADC,
    .long_press_time = CONFIG_BUTTON_LONG_PRESS_TIME_MS,
    .short_press_time = CONFIG_BUTTON_SHORT_PRESS_TIME_MS,
    .adc_button_config = {
        .adc_channel = 0,
        .button_index = 0,
        .min = 100,
        .max = 400,
    },
};
button_handle_t adc_btn = iot_button_create(&adc_btn_cfg);
if(NULL == adc_btn) {
    ESP_LOGE(TAG, "Button create failed");
}

// create matrix keypad button
button_config_t matrix_button_cfg = {
    .type = BUTTON_TYPE_MATRIX,
    .long_press_time = CONFIG_BUTTON_LONG_PRESS_TIME_MS,
    .short_press_time = CONFIG_BUTTON_SHORT_PRESS_TIME_MS,
    .matrix_button_config = {
        .row_gpio_num = 0,
        .col_gpio_num = 1,
    }
};
button_handle_t matrix_button = iot_button_create(&matrix_button_cfg);
if(NULL == matrix_button) {
    ESP_LOGE(TAG, "Button create failed");
}

Note

When the IDF version is greater than or equal to release/5.0, the ADC button uses ADC1. If ADC1 is used elsewhere in the project, please provide the adc_handle and adc_channel to configure the ADC button.

Register callback function

The Button component supports registering callback functions for multiple events, with each event capable of having its own callback function. When an event occurs, the callback function will be invoked.

In this context:

• The BUTTON_LONG_PRESS_START and BUTTON_LONG_PRESS_UP enumerations support setting specific long press times.

• The BUTTON_MULTIPLE_CLICK enumeration supports setting the number of consecutive button presses.

• Here’s a simple example:

  static void button_single_click_cb(void *arg,void *usr_data)
  {
      ESP_LOGI(TAG, "BUTTON_SINGLE_CLICK");
  }
  
  iot_button_register_cb(gpio_btn, BUTTON_SINGLE_CLICK, NULL, button_single_click_cb,NULL);
  

• And here’s an example involving multiple callback functions:

  static void button_long_press_1_cb(void *arg,void *usr_data)
  {
      ESP_LOGI(TAG, "BUTTON_LONG_PRESS_START_1");
  }
  
  static void button_long_press_2_cb(void *arg,void *usr_data)
  {
      ESP_LOGI(TAG, "BUTTON_LONG_PRESS_START_2");
  }
  
  button_event_args_t args = {
      .long_press.press_time = 2000,
  };
  
  iot_button_register_cb(gpio_btn, BUTTON_LONG_PRESS_START, &args, button_auto_check_cb_1, NULL);
  
  args.long_press.press_time = 5000;
  iot_button_register_cb(gpio_btn, BUTTON_LONG_PRESS_START, &args, button_long_press_2_cb, NULL);
  

Dynamically Modifying Default Button Values

iot_button_set_param(btn, BUTTON_LONG_PRESS_TIME_MS, 5000);

Find an event

button_event_t event;
event = iot_button_get_event(button_handle);

Low power

In light_sleep mode, the esp_timer triggers periodically, resulting in sustained high overall CPU power consumption. To address this issue, the button component offers a low-power mode.

Configuration Required:

• Ensure all created buttons type are GPIO type and have enable_power_save activated. The presence of other buttons may render the low-power mode ineffective.

Note

This feature ensures that the Button component only wakes up the CPU when in use, but does not guarantee the CPU will always enter low-power mode.

Power Consumption Comparison:

• Without enabling low-power mode, pressing the button once:

  

• With low-power mode enabled, pressing the button once:

  

Because GPIO wakes up the CPU, supporting only level triggering, the CPU is awakened only when the button is at its operating level. Therefore, in low-power mode, the average current during a single press is higher than when low-power mode is not enabled, depending on the duration of the button press. However, over larger operational periods, it saves more power than when low-power mode is not enabled.

• Without enabling low-power mode, pressing the button three times within 4 seconds:

  

• With low-power mode enabled, pressing the button three times within 4 seconds:

  

As shown, low-power mode results in more power savings.

button_config_t btn_cfg = {0};
button_gpio_config_t gpio_cfg = {
    .gpio_num = button_num,
    .active_level = BUTTON_ACTIVE_LEVEL,
    .enable_power_save = true,
};

button_handle_t btn;
iot_button_new_gpio_device(&btn_cfg, &gpio_cfg, &btn);

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.

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);

How to Use Buttons Normally After Enabling the CONFIG_PM_POWER_DOWN_PERIPHERAL_IN_LIGHT_SLEEP Option?

• When this macro is enabled, the GPIO module will be powered down. To use the button functionality, you must use RTC/LP GPIO and change the wake-up source to EXT 1.

GPIO Type	CONFIG_PM_POWER_DOWN_PERIPHERAL_IN_LIGHT_SLEEP Enabled?	Wake-Up Source
Digital Pin	N	GPIO Level Trigger
Digital Pin	Y	None
RTC/LP Pin	N	GPIO Level Trigger / EXT 1
RTC/LP Pin	Y	EXT 1

Note

The LP GPIOs of ESP32-C5 and ESP32-C6 support both GPIO level wake-up and EXT 1 wake-up, and you also need to enable gpio_hold_en.

Stop and resume

The component supports being turned on and off at any given moment.

// stop button
iot_button_stop();
// resume button
iot_button_resume();

API Reference

Header File

• components/button/include/iot_button.h

Functions

esp_err_t iot_button_delete(button_handle_t btn_handle)

Delete a button.

Parameters

btn_handle – A button handle to delete

Returns

• ESP_OK Success

• ESP_FAIL Failure

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)

Register the button event callback function.

Parameters

• btn_handle – A button handle to register

• event – Button event

• event_args – Button event arguments

• cb – Callback function.

• usr_data – user data

Returns

• 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_unregister_cb(button_handle_t btn_handle, button_event_t event, button_event_args_t *event_args)

Unregister all the callbacks associated with the event.

Parameters

• btn_handle – A button handle to unregister

• event – Button event

• event_args – Used for unregistering a specific callback.

Returns

• ESP_OK on success

• ESP_ERR_INVALID_ARG Arguments is invalid.

• ESP_ERR_INVALID_STATE No callbacks registered for the event

size_t iot_button_count_cb(button_handle_t btn_handle)

counts total callbacks registered

Parameters

btn_handle – A button handle to the button

Returns

• 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)

how many callbacks are registered for the event

Parameters

• btn_handle – A button handle to the button

• event – Button event

Returns

• 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

button_event_t iot_button_get_event(button_handle_t btn_handle)

Get button event.

Parameters

btn_handle – Button handle

Returns

Current button event. See button_event_t

const char *iot_button_get_event_str(button_event_t event)

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”.

Parameters

event – [in] The button event to be converted to a string.

Returns

• Pointer to the event string if the event is valid.

• ”invalid event” if the event value is invalid.

esp_err_t iot_button_print_event(button_handle_t btn_handle)

Log the current button event as a string.

This function prints the string representation of the current event associated with the button.

Parameters

btn_handle – [in] Handle to the button object.

Returns

• ESP_OK: Successfully logged the event string.

• ESP_FAIL: Invalid button handle.

uint8_t iot_button_get_repeat(button_handle_t btn_handle)

Get button repeat times.

Parameters

btn_handle – Button handle

Returns

button pressed times. For example, double-click return 2, triple-click return 3, etc.

uint32_t iot_button_get_ticks_time(button_handle_t btn_handle)

Get button ticks time.

Parameters

btn_handle – Button handle

Returns

Actual time from press down to up (ms).

uint16_t iot_button_get_long_press_hold_cnt(button_handle_t btn_handle)

Get button long press hold count.

Parameters

btn_handle – Button handle

Returns

Count of trigger cb(BUTTON_LONG_PRESS_HOLD)

esp_err_t iot_button_set_param(button_handle_t btn_handle, button_param_t param, void *value)

Dynamically change the parameters of the iot button.

Parameters

• btn_handle – Button handle

• param – Button parameter

• value – new value

Returns

• ESP_OK on success

• ESP_ERR_INVALID_ARG Arguments is invalid.

uint8_t iot_button_get_key_level(button_handle_t btn_handle)

Get button key level.

Parameters

btn_handle – Button handle

Returns

• 1 if key is pressed

• 0 if key is released or invalid button handle

esp_err_t iot_button_resume(void)

resume button timer, if button timer is stopped. Make sure iot_button_create() is called before calling this API.

Returns

• ESP_OK on success

• ESP_ERR_INVALID_STATE timer state is invalid.

esp_err_t iot_button_stop(void)

stop button timer, if button timer is running. Make sure iot_button_create() is called before calling this API.

Returns

• ESP_OK on success

• ESP_ERR_INVALID_STATE timer state is invalid

esp_err_t iot_button_register_power_save_cb(const button_power_save_config_t *config)

Register a callback function for power saving. The config->enter_power_save_cb function will be called when all keys stop working.

Parameters

config – Button power save config

Returns

• 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

Unions

union button_event_args_t

#include <iot_button.h>

Button events arg.

Public Members

struct button_event_args_t::long_press_t long_press

long press struct, for event BUTTON_LONG_PRESS_START and BUTTON_LONG_PRESS_UP

struct button_event_args_t::multiple_clicks_t multiple_clicks

multiple clicks struct, for event BUTTON_MULTIPLE_CLICK

struct long_press_t

#include <iot_button.h>

Long press time event data.

Public Members

uint16_t press_time

press time(ms) for the corresponding callback to trigger

struct multiple_clicks_t

#include <iot_button.h>

Multiple clicks event data.

Public Members

uint16_t clicks

number of clicks, to trigger the callback

Structures

struct button_power_save_config_t

Structs to store power save callback info.

Public Members

button_power_save_cb_t enter_power_save_cb

Callback function when entering power save mode

void *usr_data

User data for the callback

Type Definitions

typedef void (*button_cb_t)(void *button_handle, void *usr_data)

typedef void (*button_power_save_cb_t)(void *usr_data)

Enumerations

enum button_event_t

Button events.

Values:

enumerator BUTTON_PRESS_DOWN

enumerator BUTTON_PRESS_UP

enumerator BUTTON_PRESS_REPEAT

enumerator BUTTON_PRESS_REPEAT_DONE

enumerator BUTTON_SINGLE_CLICK

enumerator BUTTON_DOUBLE_CLICK

enumerator BUTTON_MULTIPLE_CLICK

enumerator BUTTON_LONG_PRESS_START

enumerator BUTTON_LONG_PRESS_HOLD

enumerator BUTTON_LONG_PRESS_UP

enumerator BUTTON_PRESS_END

enumerator BUTTON_EVENT_MAX

enumerator BUTTON_NONE_PRESS

enum button_param_t

Button parameter.

Values:

enumerator BUTTON_LONG_PRESS_TIME_MS

enumerator BUTTON_SHORT_PRESS_TIME_MS

enumerator BUTTON_PARAM_MAX

Provide feedback about this document