vortigont / ESPAsyncButton

Event-based asynchronous button library for ESP32 family chips. It generate events for various button press patterns, like short/long press, clicks, autorepeat, multiple clicks

ESPAsyncButton

EXAMPLES | CHANGELOG | |

Event-based asynchronous button library for the ESP32 Arduino/IDF

This project has started as a fork of rwmingis/InterruptButton - a really nice lib for ESP32 interrupt based buttons. But then I reworked it down to scratch to implement a set of classes for versatile button management for ESP32 family chips. It uses event-driven approach to register, transfer an handle button events. Utilizing RTOS features and HW timers event handling is fully asynchronous and decoupled from gpio ISRs. It allows to build flexible event-drivent derivatives for asynchronous, thread-aware projects.

Features:

• GPIO-based momentary buttons with/without debouncing
• Interrupts + HW timers are used to register button press/release and generate events
• gpio's ISRs and event processing are decoupled from each other, i.e. it is possible to handle multiple gpios from a single callback-handler
• this library does NOT have any Arduino loop() hooks for polling or updating button states, calculating timers, etc...
• this library does NOT call any user callback code in ISRs, event processing are handled in separate RTOS thread depending on Policy
• button event propagation and handling via ESP Event loop
• selectable button behavior
  • defaults are generating press/release events
  • longPress, longRelease events on button hold
  • AutoRepeat events with counter while button is kept on hold
  • Click, MultiClick events for any number of consecutive short clicks counting
• policy-based class templates to easy integrate user-defined event handler policies
• an easy-to-use all-in-one Async Event Button class with callbacks
• Pseudo Rotary encoder - a counting encoder made of two push-buttons, a handy object to work with scrolling menus, controls, etc...
  • auto-repeat on press and hold
  • variable steps count per press
  • initial conditions, min/max constrains
  • counter rollover on min/max boundaries
  • multiplicative steps on button multiclicks

Operation states

Depending on enabled event types button generates events when switching between logical states. Following diagrams could help to understand it better.

Short/Long press events

By default only two events are enabled for GeneralButton object:

• ESPButton::event_t::press - generated each time button was pressed
• ESPButton::event_t::release - generated each time button was released

If LongPress/LongRelease events were enabled, then each time button is pressed a timer is started with timeout TimeOuts::longPress ms. If this timer expires before button is released, then an event ESPButton::event_t::longPress is generated. Then, if longPress was triggered, on button release ESPButton::event_t::longRelease event will be generated instead of ESPButton::event_t::release.

Timeline events diagram:

Autorepeat event

Autorepeat event generation might be enabled to generate events periodically while button is kept in pressed state. I.e. to repeat some action like if the button was continously pressed and released multiple times. This could be used for scrolling, step-by-step increments, etc...

Timeline events diagram:

Click/MultiClick events

Click/Multiclick events are enabled disabled independently. ESPButton::event_t::click is just a short press/release and it is generated on button 'release'. MulttiClicks could be enabled if you need to differentiate events like 2 or more consecutive key press/release counts. Once single click is complete, button waits for TimeOuts::multiClick ms, if no more consecutive clicks where performed then multiclick event is generated with additional counter value. Any number of consecutive clicks could be executed.

Note

Long button press does not generate ESPButton::event_t::click event.

Timeline events diagram:

Thanks

Thanks to R. Mingis for his original lib and inspiration for this project.