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.

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

Related code samples

USB HID and CDC ACM: Expose multiple USB HID and CDC ACM instances.
USB HID mouse: Implement a basic HID mouse device.

group input_interface

Input Interface.

Defines

INPUT_CALLBACK_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

Related code samples

Input dump: Print all input events.

group input_events

Input event types.

INPUT_EV_KEY: Key event.

INPUT_EV_REL: Relative coordinate event.

INPUT_EV_ABS: Absolute coordinate event.

INPUT_EV_MSC: Miscellaneous event.

INPUT_EV_VENDOR_START: Vendor specific event start.

INPUT_EV_VENDOR_STOP: Vendor specific event stop.

Input event KEY codes.

INPUT_KEY_0: 0 Key

INPUT_KEY_1: 1 Key

INPUT_KEY_2: 2 Key

INPUT_KEY_3: 3 Key

INPUT_KEY_4: 4 Key

INPUT_KEY_5: 5 Key

INPUT_KEY_6: 6 Key

INPUT_KEY_7: 7 Key

INPUT_KEY_8: 8 Key

INPUT_KEY_9: 9 Key

INPUT_KEY_A: A Key.

INPUT_KEY_APOSTROPHE: Apostrophe Key.

INPUT_KEY_B: B Key.

INPUT_KEY_BACK: Back Key.

INPUT_KEY_BACKSLASH: Backslash Key.

INPUT_KEY_BACKSPACE: Backspace Key.

INPUT_KEY_BLUETOOTH: Bluetooth Key.

INPUT_KEY_BRIGHTNESSDOWN: Brightness Up Key.

INPUT_KEY_BRIGHTNESSUP: Brightneess Down Key.

INPUT_KEY_C: C Key.

INPUT_KEY_CAPSLOCK: Caps Lock Key.

INPUT_KEY_COFFEE: Screen Saver Key.

INPUT_KEY_COMMA: Comma Key.

INPUT_KEY_COMPOSE: Compose Key.

INPUT_KEY_CONNECT: Connect Key.

INPUT_KEY_D: D Key.

INPUT_KEY_DELETE: Delete Key.

INPUT_KEY_DOT: Dot Key.

INPUT_KEY_DOWN: Down Key.

INPUT_KEY_E: E Key.

INPUT_KEY_END: End Key.

INPUT_KEY_ENTER: Enter Key.

INPUT_KEY_EQUAL: Equal Key.

INPUT_KEY_ESC: Escape Key.

INPUT_KEY_F: F Key.

INPUT_KEY_F1: F1 Key.

INPUT_KEY_F10: F10 Key.

INPUT_KEY_F11: F11 Key.

INPUT_KEY_F12: F12 Key.

INPUT_KEY_F13: F13 Key.

INPUT_KEY_F14: F14 Key.

INPUT_KEY_F15: F15 Key.

INPUT_KEY_F16: F16 Key.

INPUT_KEY_F17: F17 Key.

INPUT_KEY_F18: F18 Key.

INPUT_KEY_F19: F19 Key.

INPUT_KEY_F2: F2 Key.

INPUT_KEY_F20: F20 Key.

INPUT_KEY_F21: F21 Key.

INPUT_KEY_F22: F22 Key.

INPUT_KEY_F23: F23 Key.

INPUT_KEY_F24: F24 Key.

INPUT_KEY_F3: F3 Key.

INPUT_KEY_F4: F4 Key.

INPUT_KEY_F5: F5 Key.

INPUT_KEY_F6: F6 Key.

INPUT_KEY_F7: F7 Key.

INPUT_KEY_F8: F8 Key.

INPUT_KEY_F9: F9 Key.

INPUT_KEY_FASTFORWARD: Fast Forward Key.

INPUT_KEY_FORWARD: Forward Key.

INPUT_KEY_G: G Key.

INPUT_KEY_GRAVE: Grave (backtick) Key.

INPUT_KEY_H: H Key.

INPUT_KEY_HOME: Home Key.

INPUT_KEY_I: I Key.

INPUT_KEY_INSERT: Insert Key.

INPUT_KEY_J: J Key.

INPUT_KEY_K: K Key.

INPUT_KEY_KP0: Keypad 0 Key.

INPUT_KEY_KP1: Keypad 1 Key.

INPUT_KEY_KP2: Keypad 2 Key.

INPUT_KEY_KP3: Keypad 3 Key.

INPUT_KEY_KP4: Keypad 4 Key.

INPUT_KEY_KP5: Keypad 5 Key.

INPUT_KEY_KP6: Keypad 6 Key.

INPUT_KEY_KP7: Keypad 7 Key.

INPUT_KEY_KP8: Keypad 8 Key.

INPUT_KEY_KP9: Keypad 9 Key.

INPUT_KEY_KPASTERISK: Keypad Asterisk Key.

INPUT_KEY_KPCOMMA: Keypad Comma Key.

INPUT_KEY_KPDOT: Keypad Dot Key.

INPUT_KEY_KPEQUAL: Keypad Equal Key.

INPUT_KEY_KPMINUS: Keypad Minus Key.

INPUT_KEY_KPPLUS: Keypad Plus Key.

INPUT_KEY_KPPLUSMINUS: Keypad Plus Key.

INPUT_KEY_L: L Key.

INPUT_KEY_LEFT: Left Key.

INPUT_KEY_LEFTALT: Left Alt Key.

INPUT_KEY_LEFTBRACE: Left Brace Key.

INPUT_KEY_LEFTCTRL: Left Ctrl Key.

INPUT_KEY_LEFTMETA: Left Meta Key.

INPUT_KEY_LEFTSHIFT: Left Shift Key.

INPUT_KEY_M: M Key.

INPUT_KEY_MENU: Menu Key.

INPUT_KEY_MINUS: Minus Key.

INPUT_KEY_MUTE: Mute Key.

INPUT_KEY_N: N Key.

INPUT_KEY_NUMLOCK: Num Lock Key.

INPUT_KEY_O: O Key.

INPUT_KEY_P: P Key.

INPUT_KEY_PAGEDOWN: Page Down Key.

INPUT_KEY_PAGEUP: Page UpKey.

INPUT_KEY_PAUSE: Pause Key.

INPUT_KEY_PLAY: Play Key.

INPUT_KEY_POWER: Power Key.

INPUT_KEY_PRINT: Print Key.

INPUT_KEY_Q: Q Key.

INPUT_KEY_R: R Key.

INPUT_KEY_RIGHT: Right Key.

INPUT_KEY_RIGHTBRACE: Right Brace Key.

INPUT_KEY_RIGHTMETA: Right Meta Key.

INPUT_KEY_RIGHTSHIFT: Right Shift Key.

INPUT_KEY_S: S Key.

INPUT_KEY_SCALE: Scale Key.

INPUT_KEY_SCROLLLOCK: Scroll Lock Key.

INPUT_KEY_SEMICOLON: Semicolon Key.

INPUT_KEY_SLASH: Slash Key.

INPUT_KEY_SLEEP: System Sleep Key.

INPUT_KEY_SPACE: Space Key.

INPUT_KEY_T: T Key.

INPUT_KEY_TAB: Tab Key.

INPUT_KEY_U: U Key.

INPUT_KEY_UP: Up Key.

INPUT_KEY_UWB: Ultra-Wideband Key.

INPUT_KEY_V: V Key.

INPUT_KEY_VOLUMEDOWN: Volume Down Key.

INPUT_KEY_VOLUMEUP: Volume Up Key.

INPUT_KEY_W: W Key.

INPUT_KEY_WAKEUP: System Wake Up Key.

INPUT_KEY_WLAN: Wireless LAN Key.

INPUT_KEY_X: X Key.

INPUT_KEY_Y: Y Key.

INPUT_KEY_Z: Z Key.

Input event BTN codes.

INPUT_BTN_0: 0 button

INPUT_BTN_1: 1 button

INPUT_BTN_2: 2 button

INPUT_BTN_3: 3 button

INPUT_BTN_4: 4 button

INPUT_BTN_5: 5 button

INPUT_BTN_6: 6 button

INPUT_BTN_7: 7 button

INPUT_BTN_8: 8 button

INPUT_BTN_9: 9 button

INPUT_BTN_A: A button.

INPUT_BTN_B: B button.

INPUT_BTN_C: C button.

INPUT_BTN_DPAD_DOWN: Directional pad Down.

INPUT_BTN_DPAD_LEFT: Directional pad Left.

INPUT_BTN_DPAD_RIGHT: Directional pad Right.

INPUT_BTN_DPAD_UP: Directional pad Up.

INPUT_BTN_EAST: East button.

INPUT_BTN_GEAR_DOWN: Gear Up button.

INPUT_BTN_GEAR_UP: Gear Down button.

INPUT_BTN_LEFT: Left button.

INPUT_BTN_MIDDLE: Middle button.

INPUT_BTN_MODE: Mode button.

INPUT_BTN_NORTH: North button.

INPUT_BTN_RIGHT: Right button.

INPUT_BTN_SELECT: Select button.

INPUT_BTN_SOUTH: South button.

INPUT_BTN_START: Start button.

INPUT_BTN_THUMBL: Left thumbstick button.

INPUT_BTN_THUMBR: Right thumbstick button.

INPUT_BTN_TL: Left trigger (L1)

INPUT_BTN_TL2: Left trigger 2 (L2)

INPUT_BTN_TOUCH: Touchscreen touch.

INPUT_BTN_TR: Right trigger (R1)

INPUT_BTN_TR2: Right trigger 2 (R2)

INPUT_BTN_WEST: West button.

INPUT_BTN_X: X button.

INPUT_BTN_Y: Y button.

INPUT_BTN_Z: Z button.

Input event ABS codes.

INPUT_ABS_BRAKE: Absolute brake position.

INPUT_ABS_GAS: Absolute gas position.

INPUT_ABS_RUDDER: Absolute rudder position.

INPUT_ABS_RX: Absolute rotation around X axis.

INPUT_ABS_RY: Absolute rotation around Y axis.

INPUT_ABS_RZ: Absolute rotation around Z axis.

INPUT_ABS_THROTTLE: Absolute throttle position.

INPUT_ABS_WHEEL: Absolute wheel position.

INPUT_ABS_X: Absolute X coordinate.

INPUT_ABS_Y: Absolute Y coordinate.

INPUT_ABS_Z: Absolute Z coordinate.

Input event REL codes.

INPUT_REL_DIAL: Relative dial coordinate.

INPUT_REL_HWHEEL: Relative horizontal wheel coordinate.

INPUT_REL_MISC: Relative misc coordinate.

INPUT_REL_RX: Relative rotation around X axis.

INPUT_REL_RY: Relative rotation around Y axis.

INPUT_REL_RZ: Relative rotation around Z axis.

INPUT_REL_WHEEL: Relative wheel coordinate.

INPUT_REL_X: Relative X coordinate.

INPUT_REL_Y: Relative Y coordinate.

INPUT_REL_Z: Relative Z coordinate.

Input event MSC codes.

INPUT_MSC_SCAN: Scan code.

Keyboard Matrix API Reference

group input_kbd_matrix

Keyboard Matrix API.

Defines

INPUT_KBD_MATRIX_COLUMN_DRIVE_NONE: Special drive_column argument for not driving any column.

INPUT_KBD_MATRIX_COLUMN_DRIVE_ALL: Special drive_column argument for driving all the columns.

INPUT_KBD_MATRIX_SCAN_OCURRENCES: Number of tracked scan cycles.

INPUT_KBD_MATRIX_DATA_NAME(node_id, name)

INPUT_KBD_MATRIX_DT_DEFINE_ROW_COL(node_id, _row_size, _col_size): Defines the common keyboard matrix support data from devicetree, specify row and col count.

INPUT_KBD_MATRIX_DT_DEFINE(node_id): Defines the common keyboard matrix support data from devicetree.

INPUT_KBD_MATRIX_DT_INST_DEFINE_ROW_COL(inst, row_size, col_size)

Defines the common keyboard matrix support data from devicetree instance, specify row and col count.

Parameters:

inst – Instance.
row_size – The matrix row count.
col_size – The matrix column count.

INPUT_KBD_MATRIX_DT_INST_DEFINE(inst)

Defines the common keyboard matrix support data from devicetree instance.

Parameters:

inst – Instance.

INPUT_KBD_MATRIX_DT_COMMON_CONFIG_INIT_ROW_COL(node_id, _api, _row_size, _col_size)

Initialize common keyboard matrix config from devicetree, specify row and col count.

Parameters:

node_id – The devicetree node identifier.
_api – Pointer to a input_kbd_matrix_api structure.
_row_size – The matrix row count.
_col_size – The matrix column count.

INPUT_KBD_MATRIX_DT_COMMON_CONFIG_INIT(node_id, api)

Initialize common keyboard matrix config from devicetree.

Parameters:

node_id – The devicetree node identifier.
api – Pointer to a input_kbd_matrix_api structure.

INPUT_KBD_MATRIX_DT_INST_COMMON_CONFIG_INIT_ROW_COL(inst, api, row_size, col_size)

Initialize common keyboard matrix config from devicetree instance, specify row and col count.

Parameters:

inst – Instance.
api – Pointer to a input_kbd_matrix_api structure.
row_size – The matrix row count.
col_size – The matrix column count.

INPUT_KBD_MATRIX_DT_INST_COMMON_CONFIG_INIT(inst, api)

Initialize common keyboard matrix config from devicetree instance.

Parameters:

inst – Instance.
api – Pointer to a input_kbd_matrix_api structure.

INPUT_KBD_STRUCT_CHECK(config, data)

Validate the offset of the common data structures.

Parameters:

config – Name of the config structure.
data – Name of the data structure.

Functions

void input_kbd_matrix_poll_start(const struct device *dev)

Start scanning the keyboard matrix.

Starts the keyboard matrix scanning cycle, this should be called in reaction of a press event, after the device has been put in detect mode.

Parameters:

dev – Keyboard matrix device instance.

int input_kbd_matrix_common_init(const struct device *dev)

Common function to initialize a keyboard matrix device at init time.

This function must be called at the end of the device init function.

Parameters:

dev – Keyboard matrix device instance.

Return values:

0 – If initialized successfully.
-errno – Negative errno in case of failure.

struct input_kbd_matrix_api

#include <input_kbd_matrix.h>

Keyboard matrix internal APIs.

Public Members

void (*drive_column)(const struct device *dev, int col)

Request to drive a specific column.

Request to drive a specific matrix column, or none, or all.

Param dev:: Pointer to the keyboard matrix device.
Param col:: The column to drive, or INPUT_KBD_MATRIX_COLUMN_DRIVE_NONE or INPUT_KBD_MATRIX_COLUMN_DRIVE_ALL.

int (*read_row)(const struct device *dev)

Read the matrix row.

Param dev:: Pointer to the keyboard matrix device.

void (*set_detect_mode)(const struct device *dev, bool enabled)

Request to put the matrix in detection mode.

Request to put the driver in detection mode, this is called after a request to drive all the column and typically involves reenabling interrupts row pin changes.

Param dev:: Pointer to the keyboard matrix device.
Param enable:: Whether detection mode has to be enabled or disabled.

struct input_kbd_matrix_common_config

#include <input_kbd_matrix.h>

Common keyboard matrix config.

This structure must be placed first in the driver’s config structure.

struct input_kbd_matrix_common_data

#include <input_kbd_matrix.h>

Common keyboard matrix data.

This structure must be placed first in the driver’s data structure.