The latest development version of this page may be more current than this released 3.4.0 version.

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

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";
    };
};

API Reference¶

group input_interface

Input Interface.

Defines

INPUT_LISTENER_CB_DEFINE(_dev, _callback)¶

Register a callback structure for input events.

The _dev field can be used to only invoke callback for events generated by a specific device. Setting dev to NULL causes callback to be invoked for every event.

Parameters:

_dev – device pointer or NULL.
_callback – The callback function.

Functions

int input_report(const struct device *dev, uint8_t type, uint16_t code, int32_t value, bool sync, k_timeout_t timeout)¶

Report a new input event.

This causes all the listeners for the specified device to be triggered, either synchronously or through the input thread if utilized.

Parameters:

dev – Device generating the event or NULL.
type – Event type (see INPUT_EV_CODES).
code – Event code (see INPUT_KEY_CODES, INPUT_BTN_CODES, INPUT_ABS_CODES, INPUT_REL_CODES, INPUT_MSC_CODES).
value – Event value.
sync – Set the synchronization bit for the event.
timeout – Timeout for reporting the event, ignored if CONFIG_INPUT_MODE_SYNCHRONOUS is used.

Return values:

0 – if the message has been processed.
negative – if CONFIG_INPUT_MODE_THREAD is enabled and the message failed to be enqueued.

static inline int input_report_key(const struct device *dev, uint16_t code, int32_t value, bool sync, k_timeout_t timeout)¶

Report a new INPUT_EV_KEY input event, note that value is converted to either 0 or 1.

Input Event Definitions¶

group input_events

Input event types.

INPUT_EV_KEY¶

INPUT_EV_REL¶

INPUT_EV_ABS¶

INPUT_EV_MSC¶

INPUT_EV_VENDOR_START¶

INPUT_EV_VENDOR_STOP¶

Input event KEY codes.

INPUT_KEY_0¶

INPUT_KEY_1¶

INPUT_KEY_2¶

INPUT_KEY_3¶

INPUT_KEY_4¶

INPUT_KEY_5¶

INPUT_KEY_6¶

INPUT_KEY_7¶

INPUT_KEY_8¶

INPUT_KEY_9¶

INPUT_KEY_A¶

INPUT_KEY_B¶

INPUT_KEY_C¶

INPUT_KEY_D¶

INPUT_KEY_E¶

INPUT_KEY_F¶

INPUT_KEY_G¶

INPUT_KEY_H¶

INPUT_KEY_I¶

INPUT_KEY_J¶

INPUT_KEY_K¶

INPUT_KEY_L¶

INPUT_KEY_M¶

INPUT_KEY_N¶

INPUT_KEY_O¶

INPUT_KEY_P¶

INPUT_KEY_Q¶

INPUT_KEY_R¶

INPUT_KEY_S¶

INPUT_KEY_T¶

INPUT_KEY_U¶

INPUT_KEY_V¶

INPUT_KEY_VOLUMEDOWN¶

INPUT_KEY_VOLUMEUP¶

INPUT_KEY_W¶

INPUT_KEY_X¶

INPUT_KEY_Y¶

INPUT_KEY_Z¶

Input event BTN codes.

INPUT_BTN_DPAD_DOWN¶

INPUT_BTN_DPAD_LEFT¶

INPUT_BTN_DPAD_RIGHT¶

INPUT_BTN_DPAD_UP¶

INPUT_BTN_EAST¶

INPUT_BTN_LEFT¶

INPUT_BTN_MIDDLE¶

INPUT_BTN_MODE¶

INPUT_BTN_NORTH¶

INPUT_BTN_RIGHT¶

INPUT_BTN_SELECT¶

INPUT_BTN_SOUTH¶

INPUT_BTN_START¶

INPUT_BTN_THUMBL¶

INPUT_BTN_THUMBR¶

INPUT_BTN_TL¶

INPUT_BTN_TL2¶

INPUT_BTN_TOUCH¶

INPUT_BTN_TR¶

INPUT_BTN_TR2¶

INPUT_BTN_WEST¶

Input event ABS codes.

INPUT_ABS_RX¶

INPUT_ABS_RY¶

INPUT_ABS_RZ¶

INPUT_ABS_X¶

INPUT_ABS_Y¶

INPUT_ABS_Z¶

Input event REL codes.

INPUT_REL_RX¶

INPUT_REL_RY¶

INPUT_REL_RZ¶

INPUT_REL_X¶

INPUT_REL_Y¶

INPUT_REL_Z¶

Input event MSC codes.

INPUT_MSC_SCAN¶