1.. _input:
2
3Input
4#####
5
6The input subsystem provides an API for dispatching input events from input
7devices to the application.
8
9Input Events
10************
11
12The subsystem is built around the :c:struct:`input_event` structure. An input
13event represents a change in an individual event entity, for example the state
14of a single button, or a movement in a single axis.
15
16The :c:struct:`input_event` structure describes the specific event, and
17includes a synchronization bit to indicate that the device reached a stable
18state, for example when the events corresponding to multiple axes of a
19multi-axis device have been reported.
20
21Input Devices
22*************
23
24An input device can report input events directly using :c:func:`input_report`
25or any related function; for example buttons or other on-off input entities
26would use :c:func:`input_report_key`.
27
28Complex devices may use a combination of multiple events, and set the ``sync``
29bit once the output is stable.
30
31The ``input_report*`` functions take a :c:struct:`device` pointer, which is
32used to indicate which device reported the event and can be used by subscribers
33to only receive events from a specific device. If there's no actual device
34associated with the event, it can be set to ``NULL``, in which case only
35subscribers with no device filter will receive the event.
36
37Application API
38***************
39
40An application can register a callback using the
41:c:macro:`INPUT_CALLBACK_DEFINE` macro. If a device node is specified, the
42callback is only invoked for events from the specific device, otherwise the
43callback will receive all the events in the system. This is the only type of
44filtering supported, any more complex filtering logic has to be implemented in
45the callback itself.
46
47The subsystem can operate synchronously or by using an event queue, depending
48on the :kconfig:option:`CONFIG_INPUT_MODE` option. If the input thread is used,
49all the events are added to a queue and executed in a common ``input`` thread.
50If the thread is not used, the callback are invoked directly in the input
51driver context.
52
53The synchronous mode can be used in a simple application to keep a minimal
54footprint, or in a complex application with an existing event model, where the
55callback is just a wrapper to pipe back the event in a more complex application
56specific event system.
57
58HID code mapping
59****************
60
61A common use case for input devices is to use them to generate HID reports. For
62this purpose, the :c:func:`input_to_hid_code` and
63:c:func:`input_to_hid_modifier` functions can be used to map input codes to HID
64codes and modifiers.
65
66Kscan Compatibility
67*******************
68
69Input devices generating X/Y/Touch events can be used in existing applications
70based on the :ref:`kscan_api` API by enabling both
71:kconfig:option:`CONFIG_INPUT` and :kconfig:option:`CONFIG_KSCAN`, defining a
72:dtcompatible:`zephyr,kscan-input` node as a child node of the corresponding
73input device and pointing the ``zephyr,keyboard-scan`` chosen node to the
74compatibility device node, for example:
75
76.. code-block:: devicetree
77
78    chosen {
79        zephyr,keyboard-scan = &kscan_input;
80    };
81
82    ft5336@38 {
83        ...
84        kscan_input: kscan-input {
85            compatible = "zephyr,kscan-input";
86        };
87    };
88
89General Purpose Drivers
90***********************
91
92- :dtcompatible:`adc-keys`: for buttons connected to a resistor ladder.
93- :dtcompatible:`analog-axis`: for absolute position devices connected to an
94  ADC input (thumbsticks, sliders...).
95- :dtcompatible:`gpio-kbd-matrix`: for GPIO-connected keyboard matrices.
96- :dtcompatible:`gpio-keys`: for switches directly connected to a GPIO,
97  implements button debouncing.
98- :dtcompatible:`gpio-qdec`: for GPIO-connected quadrature encoders.
99- :dtcompatible:`input-keymap`: maps row/col/touch events from a keyboard
100  matrix to key events.
101- :dtcompatible:`zephyr,input-longpress`: listens for key events, emits events
102  for short and long press.
103- :dtcompatible:`zephyr,input-double-tap`: listens for key events, emits events
104  for input double taps
105- :dtcompatible:`zephyr,lvgl-button-input`
106  :dtcompatible:`zephyr,lvgl-encoder-input`
107  :dtcompatible:`zephyr,lvgl-keypad-input`
108  :dtcompatible:`zephyr,lvgl-pointer-input`: listens for input events and
109  translates those to various types of LVGL input devices.
110
111Detailed Driver Documentation
112*****************************
113
114.. toctree::
115   :maxdepth: 1
116
117   gpio-kbd.rst
118
119
120API Reference
121*************
122
123.. doxygengroup:: input_interface
124
125Input Event Definitions
126***********************
127
128.. doxygengroup:: input_events
129
130Analog Axis API Reference
131*************************
132
133.. doxygengroup:: input_analog_axis
134
135Touchscreen API Reference
136*************************
137
138.. doxygengroup:: touch_events
139