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 defining a zephyr,kscan-input node as a childnode of the corresponding input device.

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

See also

input_report() for more details.

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

Report a new INPUT_EV_REL input event.

See also

input_report() for more details.

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

Report a new INPUT_EV_ABS input event.

See also

input_report() for more details.

bool input_queue_empty(void)

Returns true if the input queue is empty.

This can be used to batch input event processing until the whole queue has been emptied. Always returns true if CONFIG_INPUT_MODE_SYNCHRONOUS is enabled.

struct input_event
#include <input.h>

Input event structure.

This structure represents a single input event, for example a key or button press for a single button, or an absolute or relative coordinate for a single axis.

Public Members

const struct device *dev

Device generating the event or NULL.

uint8_t sync

Sync flag.

uint8_t type

Event type (see INPUT_EV_CODES).

uint16_t code

Event code (see INPUT_KEY_CODES, INPUT_BTN_CODES, INPUT_ABS_CODES, INPUT_REL_CODES, INPUT_MSC_CODES).

int32_t value

Event value.

struct input_listener
#include <input.h>

Input listener callback structure.

Public Members

const struct device *dev

device pointer or NULL.

void (*callback)(struct input_event *evt)

The callback function.

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