Tm2-touchkey

The tm2-touchkey are the Android touch buttons of some Samsung devices. Here are some information how they can be used.

Input

Key mapping

The current state of key mapping can be checked as follows:

• Kernel key names by command evtest (package evtest)
• xkb key names by xev (package xev)
• Wayland key names by wev (package wev)

The default kernel key mapping in the tm2-touchkey driver is KEY_PHONE and KEY_BACK.

In the device trees of e.g. samsung-a3 & -a5, samsung-klte and samsung-serranove, the kernel keys are set to KEY_APPSELECT and KEY_BACK. This is the correct mapping to meet the manufacturers intension. When running Android with this kernel (native or sandboxed), the left touch key KEY_APPSELECT brings up the "recent apps" screen on a short click and splits the screen on a long click. The long click action is configurable in the Android settings.

KEY_APPSELECT has a kernel keycode of 580 (0x244). In xkb library this is keycode 588. Keycodes above 255 are not processed in X11 because X11 uses 8 bit keycodes. Therefore, KEY_APPSELECT is not available in X11 UIs. Wayland uses 32 bit keycodes and does not have this limitation. However, the key isn't processed properly in Phosh, some parts of software don't handle it correctly. Also in Plasma Mobile the key can't be used for shortcut assignment.

In postmarketOS, the left touchkey is mapped to KEY_MENU and the right one to KEY_BACK by udev rule /lib/udev/rules.d/20-tm2-touchkey-input.rules. The udev rule gets installed by package postmarketos-base and applies to all devices using the tm2-touchkey driver that run on mainline kernel 5.16 or higher. The kernel version limitation is because of the key mapping via udev needing two patches on the tm2-touchkey driver that where implemented in upstream kernel v5.16-rc1. For qcom-msm8916 devices, these patches have been backported to v5.15-msm8916 kernel.

KEY_MENU is kernel keycode 139 and xkb keycode 147, therefore available in the UIs. The key has no preset functionality (tested in Phosh, Plasma Mobile, Xfce4, MATE) but is available for assignment in the UIs settings.

A drawback is the behaviour in Waydroid "show-full-ui". The left touch key behaves differently as intended by the manufacturer. A short click calls the menu of the app. A long click calls the "recent apps" screen. The option to change the long click behaviour in the Android settings has no effect. (Additional note: Long click in Phosh seems to have a window focusing problem, it only works if the Waydroid window is not focused, e.g. when hitting the top black bar before. In Plasma Mobile, long click in Waydroid works flawless.)

Overriding the key mapping

The udev rule /lib/udev/rules.d/20-tm2-touchkey-input.rules can be copied to /etc/udev/rules.d/20-tm2-touchkey-input.rules and modified there. It will override the default key mapping. The syntax is like the kernel key names without "KEY_" and with lower case. Note that keys beyond kernel keycode 247 (KEY_RFKILL) don't work in X11 and only partially in Phosh and Plasma Mobile due to the limitation described further above (KEY_RFKILL is keycode 255 in xkb library).

Assigning commands to keys

Most user interfaces offer an option to assign commands to keys.

• In Phosh this is in Settings -> Keyboard -> Keyboard Shortcuts.
• On Plasma Mobile, the according settings windows need to be called by commands kcmshell5 kcm_keys and kcmshell5 khotkeys. The fist one is for Application Shortcuts and the second brings up Custom Shortcuts.
• In Xfce4 some are in Settings -> Keyboard -> Application Shortcuts and some more in Settings -> Window Manager -> Keyboard.

LEDs

The tm2-touchkey LEDs are disabled by default. Permissions are set to allow unpriviliged users (need to be in group input) to turn on/off the LEDs by e.g. echo 1 > /sys/class/leds/tm2-touchkey/brightness. The configuration is implemented in udev file /lib/udev/rules.d/20-tm2-touchkey-leds.rules. To change this configuration, another udev file can be placed to /etc/udev/rules.d.

More information on LEDs handling can be found at: LEDs.