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.

HID code mapping

A common use case for input devices is to use them to generate HID reports. For this purpose, the input_to_hid_code() and 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 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";
    };
};

Driver Documentation

API Reference

Related code samples

LVGL basic sample

Display a "Hello World" and react to user input using LVGL.

USB HID keyboard

Implement a basic HID keyboard device.

USB HID mouse

Implement a basic HID mouse device.

group input_interface

Input Interface.

Since

3.4

Version

0.1.0

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 callbacks for the specified device to be executed, 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.

int16_t input_to_hid_code(uint16_t input_code)

Convert an input code to HID code.

Takes an input code as input and returns the corresponding HID code as output. The return value is -1 if the code is not found, if found it can safely be casted to a uint8_t type.

Parameters:
Return values:

  • the – HID code corresponding to the input code.

  • -1 – if there’s no HID code for the specified input code.

uint8_t input_to_hid_modifier(uint16_t input_code)

Convert an input code to HID modifier.

Takes an input code as input and returns the corresponding HID modifier as output or 0.

Parameters:
Return values:

  • the – HID modifier corresponding to the input code.

  • 0 – if there’s no HID modifier for the specified input code.

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_callback
#include <input.h>

Input callback structure.

Public Members

const struct device *dev

device pointer or NULL.

void (*callback)(struct input_event *evt)

The callback function.

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_RESERVED

Reserved, do not use.

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_KPENTER

Keypad Enter 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_KPSLASH

Keypad Slash 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_RIGHTALT

Right Alt Key.

INPUT_KEY_RIGHTBRACE

Right Brace Key.

INPUT_KEY_RIGHTCTRL

Right Ctrl 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_SYSRQ

SysReq 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_BACK

Back 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_EXTRA

Extra button.

INPUT_BTN_FORWARD

Forward 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_SIDE

Side button.

INPUT_BTN_SOUTH

South button.

INPUT_BTN_START

Start button.

INPUT_BTN_TASK

Task 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_MT_SLOT

Absolute multitouch slot identifier.

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.

Analog Axis API Reference

group input_analog_axis

Analog axis API.

Typedefs

typedef void (*analog_axis_raw_data_t)(const struct device *dev, int channel, int16_t raw_val)

Analog axis raw data callback.

Param dev:

Analog axis device.

Param channel:

Channel number.

Param raw_val:

Raw value for the channel.

Functions

void analog_axis_set_raw_data_cb(const struct device *dev, analog_axis_raw_data_t cb)

Set a raw data callback.

Set a callback to receive raw data for the specified analog axis device. This is meant to be use in the application to acquire the data to use for calibration. Set cb to NULL to disable the callback.

Parameters:

  • dev – Analog axis device.

  • cb – An analog_axis_raw_data_t callback to use, NULL disable.

int analog_axis_num_axes(const struct device *dev)

Get the number of defined axes.

Return values:

n – The number of defined axes for dev.

int analog_axis_calibration_get(const struct device *dev, int channel, struct analog_axis_calibration *cal)

Get the axis calibration data.

Parameters:

  • dev – Analog axis device.

  • channel – Channel number.

  • cal – Pointer to an analog_axis_calibration structure that is going to get set with the current calibration data.

Return values:

  • 0 – If successful.

  • -EINVAL – If the specified channel is not valid.

int analog_axis_calibration_set(const struct device *dev, int channel, struct analog_axis_calibration *cal)

Set the axis calibration data.

Parameters:

  • dev – Analog axis device.

  • channel – Channel number.

  • cal – Pointer to an analog_axis_calibration structure with the new calibration data

Return values:

  • 0 – If successful.

  • -EINVAL – If the specified channel is not valid.

int analog_axis_calibration_save(const struct device *dev)

Save the calibration data.

Save the calibration data permanently on the specifided device, requires the Settings subsystem to be configured and initialized.

Parameters:

  • dev – Analog axis device.

Return values:

  • 0 – If successful.

  • -errno – In case of any other error.

struct analog_axis_calibration
#include <input_analog_axis.h>

Analog axis calibration data structure.

Holds the calibration data for a single analog axis. Initial values are set from the devicetree and can be changed by the applicatoin in runtime using analog_axis_calibration_set and analog_axis_calibration_get.

Public Members

int16_t in_min

Input value that corresponds to the minimum output value.

int16_t in_max

Input value that corresponds to the maximum output value.

uint16_t in_deadzone

Input value center deadzone.