main/ttyescape: new aports: a shell script and triggerhappy configuration to let mobile device users "escape" to a tty

Caleb Connolly requested to merge sdm845-mainline/pmaports:ttyescape into master

One of the largest limitations with a mobile device is the lack of keyboard, for mainstream OSs like Android and iOS, this is a non-issue as the whole OS stack is built to automatically recover in case of a crash / hang, hiding the internal state of affairs from users and making use of careful design to minimise the impact.

When bringing Linux to mobile, we carry not only the benefits of the Linux desktop but also it's limitations. In the event that your desktop manager goes haywire or hangs completely, or your graphics drivers get unhappy, the ability to quickly jump to a tty and start killing bad behaving programs or reset your display manager is one that most of us take for granted. But when hit by similar errors on a mobile device there is no such recourse available, users either have to reboot and hope that the issue doesn't occur again, or pull out a laptop and pull up a shell (assuming ssh is enabled and the rndis interface comes up).


ttyescape proposes to solve this issues by pieceing together several already available tools, notably:

  • triggerhappy, a tool used to perform actions when certain buttons or key combinations are pressed with no dependencies on the display manager in use.
  • fbkeyboard, a framebuffer keyboard for tty's, it renders on top of the current tty and uses the device touchscreen as input.


There are a few issues to resolve before this is ready for use:


Right now, I depend on terminus-fonts and kbd (for setfont), then the font size is set to 28px, this is great for the OnePlus 6 but may not be so suitable on other devices. Perhaps something slightly smaller would be a suitable workaround until we find a device-specific solution?

Key combination

Some discussion has already happened in the postmarketOS matrix channel regarding the exact implementation and key combinations, the naive volume down + power combination set here currently may be confusing for users attempting to take a screenshot (migrating from Android), or could be accidentally triggered.

Other suggestions included reading for a key combination during boot and interrupting the usual boot procedure to enter a tty instead, personally I think that kind of implementation solves a different problem to the one attempting to be fixed here.

Holding both volume buttons is not an option for all devices (doesn't work on the PinePhone for example).

Device specific key combos

A device-specific solution to this problem might be the most sensible solution here, we could for example make the triggerhappy config in this package a template, and allow devices to specify their own solution. This would be ideal for devices which have extra buttons which may otherwise go unused.

However, I see this is a feature that should be enabled by default, the last thing you want to find out when trying to debugging a device out in the field is that your device never had this feature enabled....

A potential solution for this would be to ship the triggerhappy config as ttyescape.conf.example and then create a symlink to ttyescape.conf in the post-install script, this would avoid file overwrites in apk and let device-specific post-install hooks copy and edit the example (replacing the symlink).

I'm fairly set on roughly the implementation I've laid out here, I think it solves an important problem that will be relevant for as long as we have a userspace that isn't 100% stable, personally I can think of several times in the past where this feature would have come in really handy for me. However I'd like to see what people think.

For the sake of quickly gathering opinions I've made a strawpoll of some potential key combinations which can be found here:


I've updated the script, implementing the top method suggested in the strawpoll, the tty is now toggled by holding volume down and pressing the power button a default of 3 times, this can be set to any value by setting PRESSCOUNT in /etc/conf.d/ttyescape.conf.

I've also solved an issue where it was possible for multiple instances of fbkeyboard to be active, this probably shouldn't have happened in use /anyway/ but it should be impossible to happen now, and would be fixed by toggling tty anyway.

The triggerhappy config is now deployed to /etc/triggerhappy/triggers.d/ttyescape.conf.example and then symlinked to /etc/triggerhappy/triggers.d/ttyescape.conf in the post-install script, this means it can be replaced by the user without being cleared on package upgrade. It will also only be removed on deinstall if it hasn't been modified.

This makes it possible for pretty much everything that can be configured to be configured, and we could look into something like postmarketos-tweaks integration fairly easily. It would most likely make sense to convert this into a standalone application, replacing triggerhappy entirely.

I have visions of a kernelmode configurable hotkey driver (which could run arbitrary programs or just fire custom events and avoid propagating certain input combinations to userspace) to enable more advanced handling of this kind of mobile workaround for things we take for granted on the desktop, kernel mode would also mean that even in the case of a complete userspace hangup we're still able to recover some semblence of control. Although that is widely out of scope for this MR, I think it's something worth considering in the future to make better use of extra buttons on devices and solve these issues without having to hack on top of the input subsystem and implement distro-specific solutions.

Simplified the code, thanks @craftyguy!

This package and it's behaviour needs to be documented on the wiki, otherwise this should be ready to merge!

Edited by Caleb Connolly

Merge request reports