Input
The input subsystem provides an API for dispatching input events from input devices to the application.
Input Events
The subsystem is built around the input_event structure. An input
event represents a change in an individual event entity, for example the state
of a single button, or a movement in a single axis.
The input_event structure describes the specific event, and
includes a synchronization bit to indicate that the device reached a stable
state, for example when the events corresponding to multiple axes of a
multi-axis device have been reported.
Input Devices
An input device can report input events directly using input_report()
or any related function; for example buttons or other on-off input entities
would use input_report_key().
Complex devices may use a combination of multiple events, and set the sync
bit once the output is stable.
The input_report* functions take a device pointer, which is
used to indicate which device reported the event and can be used by subscribers
to only receive events from a specific device. If there’s no actual device
associated with the event, it can be set to NULL, in which case only
subscribers with no device filter will receive the event.
Application API
An application can register a callback using the
INPUT_CALLBACK_DEFINE macro. If a device node is specified, the
callback is only invoked for events from the specific device, otherwise the
callback will receive all the events in the system. This is the only type of
filtering supported, any more complex filtering logic has to be implemented in
the callback itself.
The subsystem can operate synchronously or by using an event queue, depending
on the CONFIG_INPUT_MODE option. If the input thread is used,
all the events are added to a queue and executed in a common input thread.
If the thread is not used, the callback are invoked directly in the input
driver context.
The synchronous mode can be used in a simple application to keep a minimal footprint, or in a complex application with an existing event model, where the callback is just a wrapper to pipe back the event in a more complex application specific event system.
HID code mapping
A common use case for input devices is to use them to generate HID reports. For
this purpose, the input_to_hid_code() and
input_to_hid_modifier() functions can be used to map input codes to HID
codes and modifiers.
Kscan Compatibility
Input devices generating X/Y/Touch events can be used in existing applications
based on the Keyboard Scan API by enabling both
CONFIG_INPUT and CONFIG_KSCAN, defining a
zephyr,kscan-input node as a child node of the corresponding
input device and pointing the zephyr,keyboard-scan chosen node to the
compatibility device node, for example:
chosen {
zephyr,keyboard-scan = &kscan_input;
};
ft5336@38 {
...
kscan_input: kscan-input {
compatible = "zephyr,kscan-input";
};
};