-
Notifications
You must be signed in to change notification settings - Fork 40
TM16xxButtons class reference
A complete example can be found here:
The TM16xxButtons class supports the key-scanning features found in many TM16xx chips. The implementation is similar to the OneButton library by Matthias Hertel. It extends the getButtons() function of the base class and provides these features:
- setting callback functions
- multi-state keys: Press, LongPress, Click, Doubleclick
- tracking button state of combined key presses
These are some TM16xx chips that support key-scanning:
| chip | buttons |
|---|---|
| TM1628 | 10 x 2 multi |
| TM1630 | 7 x 1 multi |
| TM1637 | 8 x 2 single |
| TM1638 | 8 x 3 multi |
| TM1650 | 7 x 4 single |
| TM1668 | 10 x 2 multi |
A full overview of all the TM16xx chips and their support for key scanning can be found here.
Using a pointer to a TM16xx object, the TM16xxButtons object can be created.
-
TM16xx *pTM16xx- pointer to a chip specific TM16xx object -
byte nMaxButtons- number of slots to reserve for storing button events. Normally not specified.
After creating the TM16xxButtons object, it gives access to additional functions to process buttons being pressed.
Example:
#include <TM1638.h>
#include <TM16xxButtons.h>
TM1638 module(8, 9, 7); // DIO=8, CLK=9, STB=7
TM16xxButtons buttons(&module); // specify TM16xx module object
void fnClick(byte nButton)
{ // Handle the click event by printing the number of the button that was clicked.
// byte nButton is the button-number (first button is number 0)
Serial.print(F("Button "));
Serial.print(nButton);
Serial.println(F(" click."));
}
void setup()
{
buttons.attachClick(fnClick); // attach a handling function to the click event
// do your other things
}
void loop()
{
buttons.tick(); // check for button events
// do your other things
}Notes:
- The value TM16XX_BUTTONS_MAXBUTTONSLOTS is used to reserve memory for storing button state information. It determines how many buttons can be tracked simultaneously. It is defined as 2 for small processors and 4 for larger processors.
- To use dynamic memory allocation TM16XX_OPT_BUTTONS_MALLOC can be set to 1 in TM16xxButtons.h.
Set the number of milliseconds after which a single click is assumed.
-
int ticks- the number of milliseconds. Default value is 500 ms.
Set the number of milliseconds after which a long press is assumed.
-
int ticks- the number of milliseconds. Default value is 1000 ms.
Attach a single event handling callback function that will be called when a button event (such as a button press) occurred.
Note: To use this way of handling events TM16XX_OPT_BUTTONS_EVENT needs to be set to 1 in TM16xxButtons.h.
By default the library uses calling separate callback functions (see here).
Callback function definition:
void fnCallback(byte btEvent, byte nButton)
-
byte btEvent- the number of the the event that occurred. See list below. -
byte nButton- the number of the button for which the event occurred. First button has number 0.
When used the following events can occur:
-
TM16XX_BUTTONS_EVENT_RELEASE- button is released -
TM16XX_BUTTONS_EVENT_CLICK- button is clicked -
TM16XX_BUTTONS_EVENT_DOUBLECLICK- button is double-clicked -
TM16XX_BUTTONS_EVENT_LONGPRESSSTART- button is long pressed -
TM16XX_BUTTONS_EVENT_LONGPRESSSTOP- long pressed button is released -
TM16XX_BUTTONS_EVENT_LONGPRESSBUSY- button is still long pressed
Attach a function that will be called when a specific button event occurred.
Callback function definition:
void fnCallback(byte nButton)
-
byte nButton- the number of the button for which the event occurred. First button has number 0.
Example callback function:
void fnClick(byte nButton)
{ // Handle the click event
Serial.print(F("Button "));
Serial.print(nButton);
Serial.println(F(" click."));
}
Usually the callback function is registered in the setup() function using its attach method:
void setup()
{
buttons.attachClick(fnClick); // attach a handling function to the click event
// do your other things
}
Check input of the configured pin and then advance the finite state machine (FSM).
Updates the state of each button and calls callback functions as needed.
The return value is a 32-bit value, containing the pressed state of each button. It is the value that was returned by getButtons().
Note: to properly handle buttons in a timely fashion, the loop() needs to be as tight as possible. Preferably it should not contain calls to the delay() function. Instead of using delay() to time things, it is better to use millis() to track how much time has passed and act accordingly.
Simulate button event. Advance the finite state machine (FSM) using the given level.
-
byte nButton- the number of the button simulate. -
bool level- the new level (true means pressed, false means released).
This function is not used for normal button event processing, but it can be called to simulate button presses based on other input, such as the changing values of a motion detector or another sensor. Using this function no digital input pin is checked because the current level is given by the parameter.
Get the current pressed state for a specific button.
-
byte nButton- the number of the button to check.
Returns false when not pressed or true when still pressed.
Get the current long pressed state for a specific button.
-
byte nButton- the number of the button to check.
Returns false when not pressed or true when still pressed.
Get the time a specific button is currently being pressed.
-
byte nButton- the number of the button to check.
Returns 0 when not pressed or the time in milliseconds when still pressed.
Reset the state of all buttons to their initial value.