Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/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
https://github.com/vortigont/espasyncbutton
arduino asynchronous button event-driven
Last synced: 9 days ago
JSON representation
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
- Host: GitHub
- URL: https://github.com/vortigont/espasyncbutton
- Owner: vortigont
- License: lgpl-2.1
- Created: 2022-01-31T18:55:48.000Z (almost 3 years ago)
- Default Branch: main
- Last Pushed: 2024-08-16T07:35:19.000Z (3 months ago)
- Last Synced: 2024-10-11T13:36:19.981Z (25 days ago)
- Topics: arduino, asynchronous, button, event-driven
- Language: C++
- Homepage:
- Size: 2.33 MB
- Stars: 7
- Watchers: 4
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# ESPAsyncButton
__[EXAMPLES](/examples/) | [CHANGELOG](CHANGELOG.md) |__ [](https://github.com/vortigont/ESPAsyncButton/actions/workflows/pio_build.yml) | [](https://registry.platformio.org/libraries/vortigont/ESPAsyncButton)
Event-based asynchronous button library for the ESP32 Arduino/IDF
This project has started as a fork of [rwmingis/InterruptButton](https://github.com/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](https://docs.espressif.com/projects/esp-idf/en/stable/esp32/api-reference/system/esp_event.html)
* 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](/examples/00_AsyncEventButton) class with callbacks
* [Pseudo Rotary encoder](/examples/03_PseudoEncoder) - 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](https://github.com/rwmingis) for his original [lib](https://github.com/rwmingis/InterruptButton) and inspiration for this project.