generic_button

An ESP-IDF component for Physical Computing

Purpose

Generic Button functionality for ESP32 systems.

How it is done

For every button you want to use, you have to

create an instance of class GenericButton

For every button event you want to detect, you have to

prepare a callback function to handle the event
register the event and the callback function for the button

When one of the registered events occurs, the corresponding callback function is triggered.

Where to find it

generic_button is published on the ESP Registry at https://components.espressif.com/components/elrebo-de/generic_button.

The source code can be found at https://github.com/elrebo-de/generic_button.

How to use it

As an ESP-IDF component generic_button must be included into idf_component.yml as a dependency. As usual this can be done by executing this command:

idf.py add-dependency "elrebo-de/generic_button^1.1.0"

Now you can include generic_button.hpp and use the GenericButton class in your program.

There are two constructors available for the class, depending on the button type:

Button type GPIO

There are two parameters in the constructor of class GenericButton for GPIO buttons:

tag – the tag used for logging from this instance of GenericButton class
btn_gpio_cfg – the structure defining the configuration of the GPIO button

The structure btn_gpio_cfg is of type button_gpio_config_t and defines these items:

button_gpio_config_t btn_gpio_cfg = {
    .gpio_num = 9,
    .active_level = 0,
    .enable_power_save = false,
    .disable_pull = false,
};

Here the onBoard button of a ESP32-C6-DevKitM-1 V1.0 board is defined:

button_gpio_config_t btn_gpio_cfg = {
        .gpio_num = 9,
        .active_level = 0,
        .enable_power_save = false,
        .disable_pull = false,
    };
    GenericButton onBoardButton(
	   std::string("onBoardButton"),
	   btn_gpio_cfg
	);

Button type ADC

There are two parameters in the constructor of class GenericButton for ADC buttons:

tag – the tag used for logging from this instance of GenericButton class
btn_adc_cfg – the structure defining the configuration of the ADC button

The structure btn_adc_cfg is of type button_adc_config_t and defines these items:

    // adcButton0
    button_adc_config_t btn_adc_cfg_0 = {
        /**< handle of adc unit, 
           if NULL will create new one internal, 
           else will use the handle */
        .adc_handle = adc_handle,  

        /**< ADC unit */         
        .unit_id = ADC_UNIT_1,               

        /**< Channel of ADC */
        .adc_channel = ADC1_GPIO0_CHANNEL,  

        /**< button index on the channel */ 
        .button_index = 0, 

        /**< min voltage in mv corresponding to the button */                  
        .min = 0,   

        /**< max voltage in mv corresponding to the button */                         
        .max = 154,                          
    };

Here the second button_index in a resistor ladder of six buttons is defined:

    // adcButton1
    button_adc_config_t btn_adc_cfg_1 = {
        .adc_handle = adc_handle,
        .unit_id = ADC_UNIT_1, 
        .adc_channel = ADC1_GPIO0_CHANNEL,
        .button_index = 1,
        .min = 155,
        .max = 477,
    };
    GenericButton onBoardButton(
	   std::string("adcButton1"),
	   btn_adc_cfg_1
	);

Event Callback Functions

For every event you want to detect, you have to define a callback function. This function is called, when the event occurs.

Here is an example for the BUTTON_SINGLE_CLICK event:

// Callback function for BUTTON_SINGLE_CLICK event from onBoardButton
extern "C" void callback_onBoardButton_BUTTON_SINGLE_CLICK(void *arg, void *data)
{
    ESP_LOGI("onBoardButton Callback", "for Event BUTTON_SINGLE_CLICK called!");

    iot_button_print_event((button_handle_t)arg);

    // ToDo: add code here to execute in case of a single click
}

Register Callback Function for Event

To register this callback function with your button you have to call RegisterCallbackForEventwith your GenericButton instance (here onBoardButton):

onBoardButton.RegisterCallbackForEvent(BUTTON_SINGLE_CLICK, callback_onBoardButton_BUTTON_SINGLE_CLICK);

For ADC buttons you can hand in the button configuration with parameter data:

adcButton1.RegisterCallbackForEvent(BUTTON_SINGLE_CLICK, callback_onBoardButton_BUTTON_SINGLE_CLICK, (void *)&btn_adc_cfg_1);

Now you are able to identify in the callback function which ADC button has triggered the event.

Please have a look at the two examples onBoardButton and adcButtons.

elrebo