An easy to use but comprehensive Arduino Event Library for both physical and logical Buttons, Encoders, Encoder Buttons, Analog Inputs, Joysticks and Switches. Tested on Arduino, ESP and Teensy.
Although this library is primarily for physical inputs, all it really cares about is the pin(s). So if you have a digital input, use an EventSwitch or EventButton and for an analog input, use an EventAnalog. The EventEncoder could be connected to any encoder but I have not (yet) attached it to a motor...
The EventButton and EventSwitch classes use Thomas Fredericks' Bounce2 library and Paul Stoffregen's Encoder library is the default for EventEncoder and EventButtonEncoder classes, so many, many thanks to them for releasing their code.
Please see Encoder Adapter Notes on using encoder libraries and additional notes on using PJRC's Encoder library with InputEvents.
Also a huge thanks to @kfoltman for genty guiding me towards 'better' solutions to issues I was having and the 'interesting' approaches I was trying.
I am standing on the shoulders of giants.
Not heard of the term 'event' programming? Here's a quick primer: Event Programming 101. It is by far the easiest way to get your project working with external controls.
Feedback and bug reports are welcome or chat on Discord if you have any questions.
If you're in a hurry, please see the full Doxygen generated API documentation.
Install the InputEvents and Encoder libraries via the Arduino IDE Libary Manager. Bounce2 and EncoderAdapter should automatically install, but if they don't, install them too.
Add the following to your platformio.ini file:
lib_deps =
thomasfredericks/Bounce2@^2.72
paulstoffregen/Encoder@^1.4.4
stutchbury/InputEvents@^1.3.0
Bounce2 and EncoderAdapter should automatically install as a dependencies of InputEvents.
Paul Stoffregen's Encoder library is the default for EventEncoder and EventEncoderButton but is not a hard dependency so will need to be installed separately.
#include <EventButton.h>
// Create a button
EventButton myButton(<YOUR_BUTTON_PIN>);
// Create a callback function
void onButtonCallback(InputEventType et, EventButton& eb) {
Serial.println("A button event was fired!");
}
void setup() {
myButton.begin();
// Link the button's callback to function defined above
myButton.setCallback(onButtonCallback);
}
void loop() {
// Call the button's update() method
myButton.update();
}That's it! A function and four lines of code and you have a button connected and ready to process events.
There is one class for each type of physical input. All classes have some common methods for handling enable/disable and idle timeout (detailed below).
An overview of the events each input type fires is in the InputEventType section below with details provided in each the documentation page for each input type.
The EventButton class is used with monentary switches or inputs, usually refered to as 'buttons'.
The EventEncoder class is used for plain encoders such as an MPG or motor encoder. If you use this with an encoder button, no button events will be fired!
The EventAnalog class is generally used for potentiometers but anything that normally connects to an analog pin will suffice. The analog input value is redefined as a limited number of increments or 'slices' so events are fired at specified thresholds rather than 1024 times over the range of the input.
The EventSwitch class is for plain on/off switches or inputs.
The EventEncoderButton class contains an EventEncoder and an EventButton. Certain button events are changed if the encoder is turned while pressed. See InputEventType section below for an overview.
The EventJoystick class contains two EventAnalog(s), enabling very easy use of joysticks with 'interesting' resistance values across their range. The joystick will automatically adjust the extent of the analog range, adjusting slices accordingly. Both X and Y axis can be accessed and configured directly if required.
The InputEventType is an enum class using a uint8_t to identify the type of event. Some are common to all input, others are specific to a type of input:
-
Common to all Event Input classes
ENABLED- fired when the input is enabled.DISABLED- fired when the input is disabled.IDLE- fired after no other event (exceptENABLED&DISABLED) has been fired for a specified time. Each input can define its own idle timeout, default is 10 seconds.
-
EventButton,EventEncoderButtonandEventTouchScreen(experimental) classesPRESSED- fired after a button is pressedRELEASED- fired after a button is released but if anEventEncoderButtonis pressed and turned, this is translated to aCHANGED_RELEASEDevent.CLICKED- fired afterRELEASEDif notLONG_CLICKEDand button is pressed and released once.DOUBLE_CLICKED- fired afterRELEASEDif notLONG_CLICKEDand button is pressed and released twice.MULTI_CLICKED- fired afterRELEASEDif notLONG_CLICKEDand button is pressed and released more than twice (no limit!). The method clickCount() returns the number of clicks.LONG_CLICKED- fired after a long press.LONG_PRESS- fired during a long press (hence change of tense). Will repeat by default but this can be turned off. Note: If anEventEncoderButtonis turned while pressed orEventTouchScreenis dragged,RELEASED,CLICKED,LONG_CLICKEDandLONG_PRESSare not fired.
-
EventEncoderandEventAnalogclassesCHANGEDfired if an encoder or analog is moved.
-
EventEncoderButtonclassCHANGED_PRESSED- fired when the encoder is turned while pressed.CHANGED_RELEASED- fired when button is released after turning while pressed.
-
EventJoystickclassCHANGED_X- fired when the X axis of a joystick is moved.CHANGED_Y- fired when the Y axis of a joystick is moved.
-
EventSwitchclassON- fired when the switch is turned on.OFF- fired when the switch is turned on.
-
EventTouchScreenclass (currently a separate experimental library)DRAGGED- fired while touched and dragging.DRAGGED_RELEASED- fired after drag is released (ie not touched).
Please see documentation pages for more detailed information or chat on Discord if you have any questions.