feature_debounce_type.md (8129B)
1 # Contact bounce / contact chatter 2 3 Mechanical switches often don't have a clean single transition between pressed and unpressed states. 4 5 In an ideal world, when you press a switch, you would expect the digital pin to see something like this: 6 (X axis showing time 7 ``` 8 voltage +---------------------- 9 ^ | 10 | | 11 | ------------------+ 12 ----> time 13 ``` 14 15 However in the real world you will actually see contact bounce, which will look like multiple 1->0 and 0->1 transitions, 16 until the value finally settles. 17 ``` 18 +-+ +--+ +------------- 19 | | | | | 20 | | | | | 21 +-----------------+ +-+ +-+ 22 ``` 23 The time it takes for the switch to settle might vary with switch type, age, and even pressing technique. 24 25 If the device chooses not to mitigate contact bounce, then often actions that happen when the switch is pressed are repeated 26 multiple times. 27 28 There are many ways to handle contact bounce ("Debouncing"). Some include employing additional hardware, for example an RC filter, 29 while there are various ways to do debouncing in software too, often called debounce algorithms. This page discusses software 30 debouncing methods available in QMK. 31 32 While technically not considered contact bounce/contact chatter, some switch technologies are susceptible to noise, meaning, 33 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: 34 ``` 35 +-+ 36 | | 37 | | 38 +-----------------+ +-------------------- 39 ``` 40 41 Many debounce methods (but not all) will also make the device resistant to noise. If you are working with a technology that is 42 susceptible to noise, you must choose a debounce method that will also mitigate noise for you. 43 44 ## Types of debounce algorithms 45 46 1) Unit of time: Timestamp (milliseconds) vs Cycles (scans) 47 * Debounce algorithms often have a 'debounce time' parameter, that specifies the maximum settling time of the switch contacts. 48 This time might be measured in various units: 49 * Cycles-based debouncing waits n cycles (scans), decreasing count by one each matrix_scan 50 * Timestamp-based debouncing stores the millisecond timestamp a change occurred, and does subtraction to figure out time elapsed. 51 * Timestamp-based debouncing is usually superior, especially in the case of noise-resistant devices because settling times of physical 52 switches is specified in units of time, and should not depend on the matrix scan-rate of the keyboard. 53 * Cycles-based debouncing is sometimes considered inferior, because the settling time that it is able to compensate for depends on the 54 performance of the matrix scanning code. If you use cycles-based debouncing, and you significantly improve the performance of your scanning 55 code, you might end up with less effective debouncing. A situation in which cycles-based debouncing might be preferable is when 56 noise is present, and the scanning algorithm is slow, or variable speed. Even if your debounce algorithm is fundamentally noise-resistant, 57 if the scanning is slow, and you are using a timestamp-based algorithm, you might end up making a debouncing decision based on only two 58 sampled values, which will limit the noise-resistance of the algorithm. 59 * Currently all built-in debounce algorithms support timestamp-based debouncing only. In the future we might 60 implement cycles-based debouncing, and it will be selectable via a `config.h` macro. 61 62 2) Symmetric vs Asymmetric 63 * Symmetric - apply the same debouncing algorithm, to both key-up and key-down events. 64 * Recommended naming convention: `sym_*` 65 * Asymmetric - apply different debouncing algorithms to key-down and key-up events. E.g. Eager key-down, Defer key-up. 66 * Recommended naming convention: `asym_*` followed by details of the type of algorithm in use, in order, for key-down and then key-up 67 68 3) Eager vs Defer 69 * Eager - any key change is reported immediately. All further inputs for DEBOUNCE ms are ignored. 70 * Eager algorithms are not noise-resistant. 71 * Recommended naming conventions: 72 * `sym_eager_*` 73 * `asym_eager_*_*`: key-down is using eager algorithm 74 * `asym_*_eager_*`: key-up is using eager algorithm 75 * Defer - wait for no changes for DEBOUNCE ms before reporting change. 76 * Defer algorithms are noise-resistant 77 * Recommended naming conventions: 78 * `sym_defer_*` 79 * `asym_defer_*_*`: key-down is using defer algorithm 80 * `asym_*_defer_*`: key-up is using defer algorithm 81 82 4) Global vs Per-Key vs Per-Row 83 * Global - one timer for all keys. Any key change state affects global timer 84 * Recommended naming convention: `*_g` 85 * Per-key - one timer per key 86 * Recommended naming convention: `*_pk` 87 * Per-row - one timer per row 88 * Recommended naming convention: `*_pr` 89 * Per-key and per-row algorithms consume more resources (in terms of performance, 90 and ram usage), but fast typists might prefer them over global. 91 92 ## Supported Debounce Algorithms 93 94 QMK supports multiple algorithms through its debounce API. 95 96 ### Debounce Time 97 98 Default debounce time is 5 milliseconds and it can be changed with the following line in `config.h`: 99 ``` 100 #define DEBOUNCE 10 101 ``` 102 ::: tip 103 Setting `DEBOUNCE` to `0` will disable this feature. 104 ::: 105 106 ### Debounce Method 107 108 Keyboards may select one of the core debounce methods by adding the following line into `rules.mk`: 109 ``` 110 DEBOUNCE_TYPE = <name of algorithm> 111 ``` 112 Name of algorithm is one of: 113 114 | Algorithm | Description | 115 | --------------------- | ----------- | 116 | `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. | 117 | `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. | 118 | `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. | 119 | `sym_eager_pr` | Debouncing per row. On any state change, response is immediate, followed by `DEBOUNCE` milliseconds of no further input for that row. | 120 | `sym_eager_pk` | Debouncing per key. On any state change, response is immediate, followed by `DEBOUNCE` milliseconds of no further input for that key. | 121 | `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. | 122 123 ::: tip 124 `sym_defer_g` is the default if `DEBOUNCE_TYPE` is undefined. 125 ::: 126 127 ::: tip 128 `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. 129 ::: 130 131 ### Implementing your own debouncing code 132 133 You have the option to implement you own debouncing algorithm with the following steps: 134 135 * Set `DEBOUNCE_TYPE = custom` in `rules.mk`. 136 * Add `SRC += debounce.c` in `rules.mk` 137 * Implement your own `debounce.c`. See `quantum/debounce` for examples. 138 * Debouncing occurs after every raw matrix scan. 139 * Use num_rows instead of MATRIX_ROWS to support split keyboards correctly. 140 * If your custom algorithm is applicable to other keyboards, please consider making a pull request.