MyCountingButton.h, a comprehensive guide¶
1. What does the library offer?¶
Couting of clicks on the RISING/FALLING/CHANGING edges
Couting on hardware interruption enabled pins (expl: for encodes), or any “normal” pin
Triggering of a custom callback function when a set value is reached
Set the counting direction (++/--), and set a custom value to count from
All happening in a non-blocking manner.
2. How to use?¶
There’s a number of options availabe when it comes to creating a counting button. The subject that we’ll discuss in the next section.
2.1. Instanciation of a counting button¶
The instanciation is simple, MyCountingButton my_counting_btn
and now you have a counting button, but that’s not enough to start using the methods, since this objects requires beginning, and here is where the options arise:
Interruption based counting:
If you’re new to interruptions, you can visit this link and discover them in details: https://create.arduino.cc/projecthub/rafitc/interrupts-basics-f475d5
This counting method could be used for
encoders
, since usually, that’s where such detection speed (the one offered by using an interruption) would be required.we can begin the interruption based counting through the call of one of these:
void beginCountingInterrupter(uint8_t irq_pin, void (*_ISR_callback)(void));
void beginCountingInterrupter(uint8_t irq_pin, void (*_ISR_callback)(void), uint8_t dir_);
void beginCountingInterrupter(uint8_t irq_pin, void (*_ISR_callback)(void), uint8_t dir_, uint8_t trigger_on);
Where each non-provided option falls to the default ones, the default direction is
ASCENDING (++)
, and default trigger_on isFALLING
.A call to this begin function would look like this:
my_counting_btn.beginCountingInterrupter(ISR_BTN_PIN, GET_ISR(isr_btn, countingInterruption));
Normal events counting:
We can begin the noraml counting button through the call of one of these:
void begin(uint8_t pin);
void begin(uint8_t pin, uint8_t off_state);
void begin(uint8_t pin, uint8_t off_state, uint8_t dir);
void begin(uint8_t pin, uint8_t off_state, uint8_t dir, uint8_t debounce_t);
Defaults:
off_state:
NORMAL_UP
dir:
ASCENDING
debounce_t:
5 [milliseconds]
A call to this begin function would look like this:
my_counting_btn.begin(BTN_PIN, NORMAL_UP, ASCENDING, 25);
2.2. Available methods¶
2.2.1. Settings¶
We have a number of settings possible that we can perform on our counting button.
Configure a custom function to be called whenever a certain count is reached:
void setupTriggerOnCount(long count, void (*callback)(void));
Example:
#define BUTTON_PIN 5 void callback(){ Serial.println("10 clicks!"); my_counting_btn.resetCount(); } void setup(){ Serial.begin(9600); my_counting_btn.begin(BUTTON_PIN, NORMAL_UP, ASCENDING, 25); my_counting_btn.setupTriggerOnCount(10, callback); }
- And we can change the value to be triggered at dynamically through the call to:
void setTriggerCount(long count);
- Configure whether to count UP or DOWN:
void setDirection(int8_t direction);
- Reset the count to 0:
void resetCount();
- Sets the current value of the count(passed in value):
void setCount(long count);
- Configures on which edge the conting happens
profile = {ON_RISING, ON_FALLING, ON_CHANGE}
: void setCountingProfile(uint8_t profile);
- Configures on which edge the conting happens
2.2.2. Functionalities¶
Returns the current count value:
long getCount();
Keep the listening for the counting events happening:
void loopCounter();
. In fact, this function must be called in theloop()
of your Arduino sketch in order to not miss any pressing events.
2.3. Notes¶
A button could only be began as one of the two options, either interruption based, or normal, not both (it just won’t work).
The interruption based counting buttons must be wired on hardware-interrupt enabled pins, otherwise it won’t work.
In case you choose to do a NORMAL_DOWN button, make sure to externally pull down the push-button, otherwise, an internal pull-up resistor is used by default to the NORMAL_UP mode.