Mechanical switches often don't have a clean single transition between pressed and unpressed states.
In an ideal world, when you press a switch, you would expect the digital pin to see something like this: (X axis showing time
voltage +----------------------
^ |
| |
| ------------------+
----> time
However in the real world you will actually see contact bounce, which will look like multiple 1->0 and 0->1 transitions, until the value finally settles.
+-+ +--+ +-------------
| | | | |
| | | | |
+-----------------+ +-+ +-+
The time it takes for the switch to settle might vary with switch type, age, and even pressing technique.
If the device chooses not to mitigate contact bounce, then often actions that happen when the switch is pressed are repeated multiple times.
There are many ways to handle contact bounce ("Debouncing"). Some include employing additional hardware, for example an RC filter, while there are various ways to do debouncing in software too, often called debounce algorithms. This page discusses software debouncing methods available in QMK.
While technically not considered contact bounce/contact chatter, some switch technologies are susceptible to noise, meaning, while the key is not changing state, sometimes short random 0->1 or 1->0 transitions might be read by the digital circuit, for example:
+-+
| |
| |
+-----------------+ +--------------------
Many debounce methods (but not all) will also make the device resistant to noise. If you are working with a technology that is susceptible to noise, you must choose a debounce method that will also mitigate noise for you.
Unit of time: Timestamp (milliseconds) vs Cycles (scans)
config.h
macro.Symmetric vs Asymmetric
sym_*
asym_*
followed by details of the type of algorithm in use, in order, for key-down and then key-upEager vs Defer
sym_eager_*
asym_eager_*_*
: key-down is using eager algorithmasym_*_eager_*
: key-up is using eager algorithmsym_defer_*
asym_defer_*_*
: key-down is using defer algorithmasym_*_defer_*
: key-up is using defer algorithmGlobal vs Per-Key vs Per-Row
*_g
*_pk
*_pr
QMK supports multiple algorithms through its debounce API.
Default debounce time is 5 milliseconds and it can be changed with the following line in config.h
:
#define DEBOUNCE 10
?> Setting DEBOUNCE
to 0
will disable this feature.
Keyboards may select one of the core debounce methods by adding the following line into rules.mk
:
DEBOUNCE_TYPE = <name of algorithm>
Name of algorithm is one of:
Algorithm | Description |
---|---|
sym_defer_g |
Debouncing per keyboard. On any state change, a global timer is set. When DEBOUNCE milliseconds of no changes has occurred, all input changes are pushed. This is the highest performance algorithm with lowest memory usage and is noise-resistant. |
sym_defer_pr |
Debouncing per row. On any state change, a per-row timer is set. When DEBOUNCE milliseconds of no changes have occurred on that row, the entire row is pushed. This can improve responsiveness over sym_defer_g while being less susceptible to noise than per-key algorithm. |
sym_defer_pk |
Debouncing per key. On any state change, a per-key timer is set. When DEBOUNCE milliseconds of no changes have occurred on that key, the key status change is pushed. |
sym_eager_pr |
Debouncing per row. On any state change, response is immediate, followed by DEBOUNCE milliseconds of no further input for that row. |
sym_eager_pk |
Debouncing per key. On any state change, response is immediate, followed by DEBOUNCE milliseconds of no further input for that key. |
asym_eager_defer_pk |
Debouncing per key. On a key-down state change, response is immediate, followed by DEBOUNCE milliseconds of no further input for that key. On a key-up state change, a per-key timer is set. When DEBOUNCE milliseconds of no changes have occurred on that key, the key-up status change is pushed. |
?> sym_defer_g
is the default if DEBOUNCE_TYPE
is undefined.
?> sym_eager_pr
is suitable for use in keyboards where refreshing NUM_KEYS
8-bit counters is computationally expensive or has low scan rate while fingers usually hit one row at a time. This could be appropriate for the ErgoDox models where the matrix is rotated 90°. Hence its "rows" are really columns and each finger only hits a single "row" at a time with normal usage.
You have the option to implement you own debouncing algorithm with the following steps:
DEBOUNCE_TYPE = custom
in rules.mk
.SRC += debounce.c
in rules.mk
debounce.c
. See quantum/debounce
for examples.