The latest development version of this page may be more current than this released 3.5.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_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.