TTYescape

TTYescape is a collection of config files and a shell script that allow users to switch to a TTY with a key combination. This is useful when trying to recover from a frozen system without having a way to connect to the device over SSH.
To switch to a TTY with TTYescape enabled, hold down and press three times.
== Installation ==
# apk add ttyescape
# rc-update add hkdm
# rc-service hkdm start 
== On-screen keyboard ==
Besides just dropping the user into a TTY, TYYescape also enables an on-screen keyboard, allowing for typing in the TTY without a physical keyboard connected.
Originally TTYEscape used fbkeyboard; this has been replaced by buffyboard. Built originally for unl0kr, buffyboard also works as a standalone keyboard. It uses the same layout as Phosh, making it easier to use.
== Configuration ==
TTYescape is configured by editing the file /etc/conf.d/ttyescape.conf, currently it's possible to modify the font used in the TTY, adjust the number of times you have to press to switch to a TTY, and change the path to the tempfile used to count button presses.
=== Rotating the screen ===
Run # echo 1 > /sys/class/graphics/fbcon/rotate_all to rotate the screen 90 degrees counter clockwise and # echo 3 > /sys/class/graphics/fbcon/rotate_all to rotate the screen 90 degrees clockwise
== Implementation ==
TTYEscape itself is a simple script, it makes use of HKDM, a tiny hotkey daemon which watches input devices with poll(), matches events to see if a certain command should be run and does so.
On pressing the togglevt.sh script is run with the argument "start", this creates the tempfile /tmp/ttyescape.tmp with the contents "1", releasing deletes the file. Pressing will run the script with the argument "inc", causing the number in the tempfile to be incremented. If the number is equal to the value PRESSCOUNT set in the config file (default: 3), the main body of the script is run, causing the user to switch TTYs, setting the font and launching buffyboard.
No services need to be restarted when editing the ttyescape config, it is only read by the togglevt script which is only executed on button presses.
TTYescape previously made use of triggerhappy, a relatively simple daemon capable of listening directly to input events and performing specific actions on certain keypresses (or combinations thereof).
== Security considerations ==
In order for this to work, both hkdm and the togglevt script must be run as root. It is important to ensure that their configuration files are only writable by root, otherwise it may be trivial for a user to gain root access via this tool.
== Potential improvements ==
There is a usecase not covered yet by TTYescape - that being when you display manager dies and your device / kernel goes with it. In this case you'd need to be able to boot directly to a TTY rather than switch to one, this could be implemented by starting a service before the main display manager, checking for specific key events and somehow preventing the display manager from starting, instead jumping to a TTY.
== See also ==
* - Merge request to add TTYescape to pmaports
* fbkeyboard - fbkeyboard source and docs
* triggerhappy - triggerhappy source and docs
* buffyboard - buffyboard source and docs
* HKDM - HKDM source and docs
* - Merge request to replace triggerhappy and fbkeyboard with hkdm and buffyboard
Category:Technical Reference