139 lines
4.6 KiB
ReStructuredText
139 lines
4.6 KiB
ReStructuredText
.. _input:
|
|
|
|
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 :c:struct:`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 :c:struct:`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 :c:func:`input_report`
|
|
or any related function; for example buttons or other on-off input entities
|
|
would use :c:func:`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 :c:struct:`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
|
|
:c:macro:`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 :kconfig:option:`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 :c:func:`input_to_hid_code` and
|
|
:c:func:`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 :ref:`kscan_api` API by enabling both
|
|
:kconfig:option:`CONFIG_INPUT` and :kconfig:option:`CONFIG_KSCAN`, defining a
|
|
:dtcompatible:`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:
|
|
|
|
.. code-block:: devicetree
|
|
|
|
chosen {
|
|
zephyr,keyboard-scan = &kscan_input;
|
|
};
|
|
|
|
ft5336@38 {
|
|
...
|
|
kscan_input: kscan-input {
|
|
compatible = "zephyr,kscan-input";
|
|
};
|
|
};
|
|
|
|
General Purpose Drivers
|
|
***********************
|
|
|
|
- :dtcompatible:`adc-keys`: for buttons connected to a resistor ladder.
|
|
- :dtcompatible:`analog-axis`: for absolute position devices connected to an
|
|
ADC input (thumbsticks, sliders...).
|
|
- :dtcompatible:`gpio-kbd-matrix`: for GPIO-connected keyboard matrices.
|
|
- :dtcompatible:`gpio-keys`: for switches directly connected to a GPIO,
|
|
implements button debouncing.
|
|
- :dtcompatible:`gpio-qdec`: for GPIO-connected quadrature encoders.
|
|
- :dtcompatible:`input-keymap`: maps row/col/touch events from a keyboard
|
|
matrix to key events.
|
|
- :dtcompatible:`zephyr,input-longpress`: listens for key events, emits events
|
|
for short and long press.
|
|
- :dtcompatible:`zephyr,input-double-tap`: listens for key events, emits events
|
|
for input double taps
|
|
- :dtcompatible:`zephyr,lvgl-button-input`
|
|
:dtcompatible:`zephyr,lvgl-encoder-input`
|
|
:dtcompatible:`zephyr,lvgl-keypad-input`
|
|
:dtcompatible:`zephyr,lvgl-pointer-input`: listens for input events and
|
|
translates those to various types of LVGL input devices.
|
|
|
|
Detailed Driver Documentation
|
|
*****************************
|
|
|
|
.. toctree::
|
|
:maxdepth: 1
|
|
|
|
gpio-kbd.rst
|
|
|
|
|
|
API Reference
|
|
*************
|
|
|
|
.. doxygengroup:: input_interface
|
|
|
|
Input Event Definitions
|
|
***********************
|
|
|
|
.. doxygengroup:: input_events
|
|
|
|
Analog Axis API Reference
|
|
*************************
|
|
|
|
.. doxygengroup:: input_analog_axis
|
|
|
|
Touchscreen API Reference
|
|
*************************
|
|
|
|
.. doxygengroup:: touch_events
|