User manual
LwBTN is simple button manager library, with great focus on embedded systems. Motivation behind start of development was linked to several on-going projects including some input reading (button handling), each of them demanding little differences in process.
LwBTN is therefore relatively simple and lightweight, yet it can provide pretty comprehensive processing of your application buttons.
How it works
User must define buttons array and pass it to the library. Next to that, 2 more functions are required:
Function to read the architecture button state
Function to receive various button events
User shall later periodically call processing function with current system time as simple parameter and get ready to receive various events.
A simple example for win32 is below:
1#include "lwbtn/lwbtn.h"
2#include "windows.h"
3#include <stdio.h>
4#include <stdlib.h>
5
6static LARGE_INTEGER freq, sys_start_time;
7static uint32_t get_tick(void);
8
9/* User defined settings */
10const int keys[] = {'0', '1', '2', '3', '4', '5', '6', '7', '8', '9'};
11uint32_t last_time_keys[sizeof(keys) / sizeof(keys[0])] = {0};
12
13/* List of buttons to process with assigned custom arguments for callback functions */
14static lwbtn_btn_t btns[] = {
15 {.arg = (void*)&keys[0]}, {.arg = (void*)&keys[1]}, {.arg = (void*)&keys[2]}, {.arg = (void*)&keys[3]},
16 {.arg = (void*)&keys[4]}, {.arg = (void*)&keys[5]}, {.arg = (void*)&keys[6]}, {.arg = (void*)&keys[7]},
17 {.arg = (void*)&keys[8]}, {.arg = (void*)&keys[9]},
18};
19
20/**
21 * \brief Get input state callback
22 * \param lw: LwBTN instance
23 * \param btn: Button instance
24 * \return `1` if button active, `0` otherwise
25 */
26uint8_t
27prv_btn_get_state(struct lwbtn* lw, struct lwbtn_btn* btn) {
28 (void)lw;
29
30 /*
31 * Function will return negative number if button is pressed,
32 * or zero if button is releases
33 */
34 return GetAsyncKeyState(*(int*)btn->arg) < 0;
35}
36
37/**
38 * \brief Button event
39 *
40 * \param lw: LwBTN instance
41 * \param btn: Button instance
42 * \param evt: Button event
43 */
44void
45prv_btn_event(struct lwbtn* lw, struct lwbtn_btn* btn, lwbtn_evt_t evt) {
46 const char* s;
47 uint32_t color, keepalive_cnt = 0;
48 HANDLE hConsole = GetStdHandle(STD_OUTPUT_HANDLE);
49 uint32_t* diff_time_ptr = &last_time_keys[(*(int*)btn->arg) - '0'];
50 uint32_t diff_time = get_tick() - *diff_time_ptr;
51
52 /* This is for purpose of test and timing validation */
53 if (diff_time > 2000) {
54 diff_time = 0;
55 }
56 *diff_time_ptr = get_tick(); /* Set current date as last one */
57
58 /* Get event string */
59 if (0) {
60#if LWBTN_CFG_USE_KEEPALIVE
61 } else if (evt == LWBTN_EVT_KEEPALIVE) {
62 s = "KEEPALIVE";
63 color = FOREGROUND_RED;
64#endif /* LWBTN_CFG_USE_KEEPALIVE */
65 } else if (evt == LWBTN_EVT_ONPRESS) {
66 s = " ONPRESS";
67 color = FOREGROUND_GREEN;
68 } else if (evt == LWBTN_EVT_ONRELEASE) {
69 s = "ONRELEASE";
70 color = FOREGROUND_BLUE;
71 } else if (evt == LWBTN_EVT_ONCLICK) {
72 s = " ONCLICK";
73 color = FOREGROUND_RED | FOREGROUND_GREEN;
74 } else {
75 s = " UNKNOWN";
76 color = FOREGROUND_RED | FOREGROUND_GREEN | FOREGROUND_BLUE;
77 }
78#if LWBTN_CFG_USE_KEEPALIVE
79 keepalive_cnt = btn->keepalive.cnt;
80#endif
81 SetConsoleTextAttribute(hConsole, color);
82 printf("[%7u][%6u] CH: %c, evt: %s, keep-alive cnt: %3u, click cnt: %3u\r\n", (unsigned)get_tick(),
83 (unsigned)diff_time, *(int*)btn->arg, s, (unsigned)keepalive_cnt, (unsigned)btn->click.cnt);
84 SetConsoleTextAttribute(hConsole, FOREGROUND_RED | FOREGROUND_GREEN | FOREGROUND_BLUE);
85 (void)lw;
86}
87
88/**
89 * \brief Example function
90 */
91int
92example_win32(void) {
93 uint32_t time_last;
94 printf("Application running\r\n");
95 QueryPerformanceFrequency(&freq);
96 QueryPerformanceCounter(&sys_start_time);
97
98 /* Define buttons */
99 lwbtn_init_ex(NULL, btns, sizeof(btns) / sizeof(btns[0]), prv_btn_get_state, prv_btn_event);
100
101 time_last = get_tick();
102 while (1) {
103 /* Process forever */
104 lwbtn_process_ex(NULL, get_tick());
105
106 /* Manually read button state */
107#if LWBTN_CFG_GET_STATE_MODE == LWBTN_GET_STATE_MODE_MANUAL
108 for (size_t i = 0; i < sizeof(btns) / sizeof(btns[0]); ++i) {
109 lwbtn_set_btn_state(&btns[i], prv_btn_get_state(NULL, &btns[i]));
110 }
111#endif /* LWBTN_CFG_GET_STATE_MODE == LWBTN_GET_STATE_MODE_MANUAL */
112
113 /* Check if specific button is active and do some action */
114 if (lwbtn_is_btn_active(&btns[0])) {
115 if ((get_tick() - time_last) > 200) {
116 time_last = get_tick();
117 printf("Button is active\r\n");
118 }
119 }
120
121 /* Artificial sleep to offload win process */
122 Sleep(5);
123 }
124 return 0;
125}
126
127/**
128 * \brief Get current tick in ms from start of program
129 * \return uint32_t: Tick in ms
130 */
131static uint32_t
132get_tick(void) {
133 LONGLONG ret;
134 LARGE_INTEGER now;
135
136 QueryPerformanceFrequency(&freq);
137 QueryPerformanceCounter(&now);
138 ret = now.QuadPart - sys_start_time.QuadPart;
139 return (uint32_t)((ret * 1000) / freq.QuadPart);
140}
Input events
During button (or input if you will) lifetime, application can expect some of these events (but not limited to):
LWBTN_EVT_ONPRESSevent is sent to application whenever input goes from inactive to active state and minimum debounce time passes byLWBTN_EVT_ONRELEASEevent is sent to application whenever input sent onpress event prior to that and when input goes from active to inactive stateLWBTN_EVT_KEEPALIVEevent is periodically sent between onpress and onrelease eventsLWBTN_EVT_ONCLICKevent is sent after onrelease and only if active button state was within allowed window for valid click event.
On-Press event
Onpress event is the first in a row when input is detected active.
With nature of embedded systems and various buttons connected to devices, it is necessary to filter out potential noise to ignore unintential multiple presses.
This is done by checking line to be at stable level for at least some minimum time, normally called debounce time, usually it takes around 20ms.
On-Press event trigger after minimum debounce time
On-Release event
Onrelease event is triggered immediately when input goes from active to inactive state, and only if onpress event has been detected prior to that.
On-Release event trigger
On-Click event
Onclick event is triggered after a combination of multiple events:
Onpress event shall be detected properly, indicating button has been pressed
Onrelease event shall be detected, indicating button has been released
Time between onpress and onrelease events has to be within time window
When conditions are met, onclick event is sent, either immediately after onrelease or after certain timeout after onrelease event.
Sequence for valid click event
A windows-test program demonstration of events is visible below.
Click event test program
Second number for each line is a milliseconds difference between events.
OnClick is reported approximately (windows real-time issue) 400 ms after on-release event.
Tip
Timeout window between last onrelease event and onclick event is configurable
Multi-click events
Multi-click feature is where timeout for onclick event comes into play. Idea behind timeout feature is to allow multiple presses and to only send onclick once for all presses, including the number of detected presses during that time. This let’s the application to react only once with known number of presses. This eliminates the problem where in case of double click trigger, you also receive single-click event, while you do not know yet, if second (or third) event will be triggered after.
Note
Imagine having a button that toggles one light on single click and turns off all lights in a room on double click. With timeout feature and single onclick notification, user will only receive the onclick once and will, based on the consecutive presses number value, perform appropriate action if it was single or multi click.
Simplified diagram for multi-click, ignoring debounce time indicators, is below. cp indicates number of detected consecutive onclick press events, to be reported in the final onclick event
Multi-click event example - with 3 consecutive presses
A windows-test program demonstration of events is visible below.
Multi-click event test program
Multi-click event with onclick event reported only after second press after minimum timeout of 400ms.
Note
Number of consecutive clicks can be upper-limited to the desired value.
When user makes more (or equal) consecutive clicks than maximum, an onclick event is sent immediately after onrelease event for last detected click.
Max number of onclick events, onclick is sent immediately after onrelease
There is no need to wait timeout expiration since upper clicks limit has been reached.
Tip
It is possible to control the behavior of onclick event (when consecutive number reaches maximum set value) timing using LWBTN_CFG_CLICK_MAX_CONSECUTIVE_SEND_IMMEDIATELY configuration.
When enabled, behavior is as illustrated above. When disabled, onclick event it sent in timeout (or in case of new onpress), even if max allowed clicks has been reached.
Illustration below shows what happens during multiple clicks
Max number of consecutive clicks is
3User makes
4consecutive clicks
Multi-click events with too many clicks - consecutive send immediately is enabled - it is sent after 3rd onrelease
Multi-click events with too many clicks - consecutive send immediately is disabled
Image below illustrates when send immediately is enabled. It is visible how first onclick is sent
just after onrelease event (when max consecutive is set to 3).
5 presses detected with 3 set as maximum. First on-click is sent immediately, while second is sent after timeout
When multi-click feature is disabled, onclick event is sent after every valid sequence of onpress and onrelease events.
Tip
If you do not want multi-click feature, set max number of consecutive clicks to 1. This will eliminate timeout feature since
every click event will trigger maximum clicks detected and therefore send the event immediately after onrelease
Multi-click events disabled with cp == 1
Demo log text, with fast pressing of button, and events reported after every onrelease
Multi-click events disabled with cp == 1
Multi-click special case
There is currently a special case in the library when dealing with multiclicks.
Configuration option LWBTN_CFG_TIME_CLICK_MULTI_MAX defines the maximum time between 2 consecutive clicks (consecutive onrelease events).
Timing starts with previous valid click. If next click event starts (that starts with onpress event) earlier than maximum time but ends later than maximum, then
new click is not counted as consecutive click to previous one.
As such, library will throw 2 click events to the user.
First one immediately on second onrelease event (to take care of first onpress and onrelease event group) and second one after defined user timeout.
Note
Colors on picture below indicate events that relate to each other, indicated as green or blue rectangles
Special case for multi click when timing overlaps. Orange vertical lines indicate period for valid consecutive clicks.
Keep alive event
Keep-alive event is sent periodically between onpress and onrelease events. It can be used to detect application is still alive and provides counter how many keep-alive events have been sent up to the point of event.
Feature can be used to make a trigger at specific time if button is in active state (a hold event).
Keep alive events with 2 successful click events
Keep alive events when button is kept pressed
Debounce
Debouncing is a software mechanics to remove unwanted bouncing events introduced by the physical buttons.
Tip
This chapter will not go into details about generic debouncing problem. Have a look at Wikipedia post about Switches.
Library supports 2 separate debounce options:
Debounce on press event: This is almost always a must-have in the application, and helps to detect valid “press” event only once after the input is in stable active state for minimum time in a row.
Press event debounce can only be disabled, if application can ensure stable transition from inactive to active state. This is usually done using capacitor and resistor next to the push button (this may not be the most optimized solution for contact longevity)
Debounce on release event: This is usually not necessary by most of the applications,
but can be used in harsh environments, where unwanted external noise could affect line and put it to inactive state for short period of time (while user holds button down in active state).
Note
Configuration settings LWBTN_CFG_TIME_DEBOUNCE_PRESS and LWBTN_CFG_TIME_DEBOUNCE_RELEASE are used to set the debounce time in milliseconds.
When one of the values is set to 0, debounce feature for respective transition is not actived.
Tip
Debounce time of around 20ms is usually a good tradeoff between application reactivity to user events and debounce time required to stabilize the input.
Debounce examples
Examples are demonstrated using NUCLEO-L011K4 board. 2 GPIO pins are used, one in input config, second as output.
Input pin (Blue): A raw input that acts as an user button. There is no hardware filtering. Pin is active when low and inactive when high.
Output pin (Red): Output pin is software controlled. It goes high on press event and it goes low on release event. Press and release events are reported by the library.
Note
Logic analyzer has been connected directly to the microcontroller pins.
Examples #1
20ms debounce for press event. Press event is triggered only after input is stable in active state for minimum time.
20ms debounce for release event. Release event is triggered only after input is stable in inactive state for minimum time.
20ms debounce for press event - press event was not triggered - input was in stable active state for less than minimum debounce time (red line stays low).
Examples #2
LWBTN_CFG_TIME_DEBOUNCE_RELEASE=0- release debounce is disabled
Press event is detected after initial debounce, while release event is detected immediately on button going to inactive state.
Examples #3
100ms debounce for press event. Input bouncing is clearly visible on the diagram. Press event is triggered only after input is stable in active state for minimum time.
100ms debounce for release event. Release event is triggered after input is in stable inactive state for at least release debounce time.
Input is in pressed state (red is high). Blue is in released state for less that minimum stable debounce time, therefore no release event has been triggered. This is clearly visible with the red line that is staying high for the whole time of the transient period.