Jump to content

Input devices

From postmarketOS Wiki
Note To keep this document user-focused, please keep development-related information (such as driver code troubleshooting) in Input_devices/Development.

Introduction

Typically used human interface devices (HID) include:

  • touchscreens
  • keyboards
  • buttons
    • touch keys
  • mouses
  • gaming devices - gamepads, joysticks, steering wheels

This article's purpose is to provide basic information about troubleshooting and advanced interaction with HID devices.

Touch keys

Touchkeys are buttons with minimal or no physical actuation or haptic feedback. They're triggered by a touch on a specific area of the device, usually with a corresponding icon (see examples below). They are usually detected by the same hardware as the touchscreen itself.

Types of touch keys
Button name App selection Menu Back
Key code KEY_APPSELECT KEY_MENU KEY_BACK
Android's button example
Limitations Not available in X11 - -

Generic debugging steps

Getting input device information using udevadm

Make sure that buttons are recognized as eventX inside /dev/input directory

To make sure that the input buttons are recognized, run the following command:

$ udevadm info -a /dev/input/event0

The command will print udev properties which can be used to assign udev rules, for example tagging specified device as touchscreen.

Note that HID input device doesn't trigger udev event, so the following command can't be used to detect key-presses from HID input device.

# udevadm monitor

Using evtest to show input events

evtest can be used to detect events sent by input devices. To use it, install evtest package.

# apk add evtest

You can run evtest to pick a device from the list, or you can add the device name as an argument. For example:

# evtest /dev/input/event0 
(...)
Testing ... (interrupt to exit)
Event: time 1262306351.564957, type 1 (EV_KEY), code 330 (BTN_TOUCH), value 1
Event: time 1262306351.564957, type 3 (EV_ABS), code 57 (ABS_MT_TRACKING_ID), value 0
Event: time 1262306351.564957, type 3 (EV_ABS), code 48 (ABS_MT_TOUCH_MAJOR), value 8
Event: time 1262306351.564957, type 3 (EV_ABS), code 53 (ABS_MT_POSITION_X), value 101
Event: time 1262306351.564957, type 3 (EV_ABS), code 54 (ABS_MT_POSITION_Y), value 163
Event: time 1262306351.564957, ++++++++++++++ SYN_MT_REPORT ++++++++++++
Event: time 1262306351.564957, -------------- SYN_REPORT ------------
Event: time 1262306351.590508, type 3 (EV_ABS), code 57 (ABS_MT_TRACKING_ID), value 0
Event: time 1262306351.590508, type 3 (EV_ABS), code 48 (ABS_MT_TOUCH_MAJOR), value 8
Event: time 1262306351.590508, type 3 (EV_ABS), code 53 (ABS_MT_POSITION_X), value 103
Event: time 1262306351.590508, type 3 (EV_ABS), code 54 (ABS_MT_POSITION_Y), value 155
Event: time 1262306351.590508, ++++++++++++++ SYN_MT_REPORT ++++++++++++
Event: time 1262306351.590508, -------------- SYN_REPORT ------------

Some of those codes are explained in kernel documentation, see ie. multi-touch protocol

Test with libinput debug-events

You can check if libinput understands the events your HID driver emits with libinput debug-events.

For example it's possible that libinput doesn't get any events or that it doesn't get TOUCH_DOWN/TOUCH_UP events. You can see the raw events libinput receives with libinput record.

Following is example output from libinput debug-events when the screen is briefly touched in a case where the touchscreen is working correctly:

$ libinput debug-events
 event10  TOUCH_DOWN       +0.000s	0 (0) 53.40/23.11 (385.00/296.00mm)
 event10  TOUCH_FRAME      +0.000s	
 event10  TOUCH_MOTION     +0.010s	0 (0) 52.84/24.04 (381.00/308.00mm)
 event10  TOUCH_FRAME      +0.010s	
 event10  TOUCH_MOTION     +0.020s	0 (0) 52.70/24.36 (380.00/312.00mm)
 event10  TOUCH_FRAME      +0.020s	
 event10  TOUCH_MOTION     +0.039s	0 (0) 52.70/24.51 (380.00/314.00mm)
 event10  TOUCH_FRAME      +0.039s	
 event10  TOUCH_UP         +0.065s	
 event10  TOUCH_FRAME      +0.065s

Using xev/wev to get key names

You can get key names with following tools:

  • Kernel names with evtest (package evtest)
  • xkb names with xev (package xev)
  • Wayland names with wev (package wev)

Reacting to events

Using triggerhappy to handle HID input events

{{note|Triggerhappy has been replaced with HKDM}. Help is welcome, to replace this section with up-to-date information.}

Installation

Triggerhappy can be used to handle HID input device. After postmarketOS is installed, add it with:

$ apk add triggerhappy

If you did not install it yet, you can also request it to be added to the installation in pmbootstrap init or by using the --add parameter for the install action:

$ pmbootstrap install --add=triggerhappy

Usage

Run thd on the device to find what is sent:

$ sudo thd --dump /dev/input/event*

With thd --dump running, touch the touchscreen and press the available buttons. There will be information related to the input device printed on the ssh session.

EV_ABS	ABS_MT_TRACKING_ID	16	/dev/input/event0
# ABS_MT_TRACKING_ID	16	command
EV_ABS	ABS_MT_TRACKING_ID	0	/dev/input/event0
# ABS_MT_TRACKING_ID	0	command
EV_ABS	ABS_MT_POSITION_X	312	/dev/input/event0
# ABS_MT_POSITION_X	312	command
EV_ABS	ABS_MT_POSITION_Y	1013	/dev/input/event0
# ABS_MT_POSITION_Y	1013	command
EV_ABS	ABS_MT_TOUCH_MAJOR	123	/dev/input/event0
# ABS_MT_TOUCH_MAJOR	123	command
EV_ABS	ABS_MT_WIDTH_MAJOR	144	/dev/input/event0
# ABS_MT_WIDTH_MAJOR	144	command
EV_KEY  KEY_POWER       1       /dev/input/event1
# KEY_POWER     1       command
EV_KEY  KEY_POWER       0       /dev/input/event1
# KEY_POWER     0       command
EV_KEY  KEY_VOLUMEDOWN  1       /dev/input/event1
# KEY_VOLUMEDOWN        1       command
EV_KEY  KEY_VOLUMEDOWN  0       /dev/input/event1
# KEY_VOLUMEDOWN        0       command
EV_KEY  KEY_VOLUMEUP    1       /dev/input/event2
# KEY_VOLUMEUP  1       command
EV_KEY  KEY_VOLUMEUP    0       /dev/input/event2
# KEY_VOLUMEUP  0       command

The information can be used to create a triggerhappy configuration, for example assigning a command when the home touch button is pressed.

Example /etc/triggerhappy/triggers.d/buttons.conf:

KEY_POWER 1 poweroff
KEY_VOLUMEDOWN+KEY_POWER 1 reboot
#ABS_MT_POSITION_Y@ 1344 @home
#ABS_MT_POSITION_X@home 360 logger "Home button is pressed"
#ABS_MT_POSITION_Y@home 1344 @

The triggerhappy service needs to be enabled to listen HID button keypresses:

# rc-update add triggerhappy default

Using busybox acpid

Some device buttons can trigger acpi events. Busybox acpid can be used to handle these events, for example nokia n900.

For this to work, an acpi.map is needed. Look at device-nokia-n900 for more information.

See also