| 1 |
|
| 2 |
.. _button_debouncing: |
| 3 |
|
| 4 |
============================================================================== |
| 5 |
Button debouncing |
| 6 |
============================================================================== |
| 7 |
|
| 8 |
Physical buttons experience wear-and-tear with usage. On some devices this |
| 9 |
can result in an effect called "contact bouncing" or "chatter". This effect |
| 10 |
can cause the button to send multiple events within a short time frame, even |
| 11 |
though the user only pressed or clicked the button once. This effect can be |
| 12 |
counteracted by "debouncing" the buttons, usually by ignoring erroneous |
| 13 |
events. |
| 14 |
|
| 15 |
libinput provides two methods of debouncing buttons, referred to as the |
| 16 |
"bounce" and "spurious" methods: |
| 17 |
|
| 18 |
- In the "bounce" method, libinput monitors hardware bouncing on button |
| 19 |
state changes, i.e. when a user clicks or releases a button. For example, |
| 20 |
if a user presses a button but the hardware generates a |
| 21 |
press-release-press sequence in quick succession, libinput ignores the |
| 22 |
release and second press event. This method is always enabled. |
| 23 |
- in the "spurious" method, libinput detects spurious releases of a button |
| 24 |
while the button is physically held down by the user. These releases are |
| 25 |
immediately followed by a press event. libinput monitors for these events |
| 26 |
and ignores the release and press event. This method is disabled by |
| 27 |
default and enables once libinput detects the first faulty event sequence. |
| 28 |
|
| 29 |
The "bounce" method guarantees that all press events are delivered |
| 30 |
immediately and most release events are delivered immediately. The |
| 31 |
"spurious" method requires that release events are delayed, libinput thus |
| 32 |
does not enable this method unless a faulty event sequence is detected. A |
| 33 |
message is printed to the log when spurious deboucing was detected. |
| 34 |
|
| 35 |
libinput's debouncing is supposed to correct hardware damage or |
| 36 |
substandard hardware. Debouncing also exists as an accessibility feature |
| 37 |
but the requirements are different. In the accessibility feature, multiple |
| 38 |
physical key presses, usually caused by involuntary muscle movement, must be |
| 39 |
filtered to only one key press. This feature must be implemented higher in |
| 40 |
the stack, libinput is limited to hardware debouncing. |
| 41 |
|
| 42 |
Below is an illustration of the button debouncing modes to show the relation |
| 43 |
of the physical button state and the application state. Where applicable, an |
| 44 |
extra line is added to show the timeouts used by libinput that |
| 45 |
affect the button state handling. The waveform's high and low states |
| 46 |
correspond to the buttons 'pressed' and 'released' states, respectively. |
| 47 |
|
| 48 |
.. figure:: button-debouncing-wave-diagram.svg |
| 49 |
:align: center |
| 50 |
|
| 51 |
Diagram illustrating button debouncing |
| 52 |
|
| 53 |
|
| 54 |
Some devices send events in bursts, erroneously triggering the button |
| 55 |
debouncing detection. Please :ref:`file a bug <reporting_bugs>` if that |
| 56 |
occurs for your device. |