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
58Kscan Compatibility
59*******************
60
61Input devices generating X/Y/Touch events can be used in existing applications
62based on the :ref:`kscan_api` API by enabling both
63:kconfig:option:`CONFIG_INPUT` and :kconfig:option:`CONFIG_KSCAN`, defining a
64:dtcompatible:`zephyr,kscan-input` node as a child node of the corresponding
65input device and pointing the ``zephyr,keyboard-scan`` chosen node to the
66compatibility device node, for example:
67
68.. code-block:: devicetree
69
70    chosen {
71        zephyr,keyboard-scan = &kscan_input;
72    };
73
74    ft5336@38 {
75        ...
76        kscan_input: kscan-input {
77            compatible = "zephyr,kscan-input";
78        };
79    };
80
81API Reference
82*************
83
84.. doxygengroup:: input_interface
85
86Input Event Definitions
87***********************
88
89.. doxygengroup:: input_events
90