Debian Codegraph @

doc/user/button-debouncing.rst

raw
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.