ref: 6db125ae1480eb0d59d795d298b2f1835dcd5ffe fbp/README.md -rw-r--r-- 7.4 KiB
6db125aeMiles Alan Disambiguate between finger down/drag/up for touch processing 5 months ago


fbp is the graphical framebuffer-based phone UI widget component of framebufferphone project, designed to be used alongside your TTY. In terms of its design, it can be thought of as somewhat of a hybrid between dmenu & fbkeyboard. fbp exposes a on-screen touch keyboard interface, (scriptable) autocomplete / strings menu, rebinds the volumes keys to be usable for item selection, enables VT switching, and provides the user with a lock-mode. It uses low-level Linux APIs like uinput, the framebuffer drawing API, VT iotctls, and similar. fbp is written in Zig. It aims to be "just enough" of a UI to make using the terminal on mobile / on-the-go productive. Ofcourse it targets powerusers but it aims be simple enough for any lay(linux)person to understand and use practically.



fbp's UI is a moded interface with two primary modes: normal mode and lock mode. In addition, normal mode has two submodes: strings submode and keyboard submode.

Normal mode is the default mode fbp starts in. It is made up of two submodes: the strings submode and the keyboard submode. In the strings submode the grid is populated with runtime changable 'strings' that are customized by writing to the FIFO. Selecting an item types the entire string. Depending on whether the NL preference is set (indicated by visual NL in statusbar) a newline will optionally be suffixed after typing the item. Multiple pages may be selected between when present by selecting <- or -> . And finally, in the strings submode holding the powerbutton as explained in the keybindings section will restore the "base set of strings" which is essentially every executable in $PATH. As such by default strings mode operates as a "script launcher". Executables in the $PATH prefixed with u_ or f_ appear first. Thus userscripts appear first, followed by any f_scripts installed on the system. Meanwhile, in keyboard submode, the grid is populated by a standard QWERTY layout keyboard. Selecting an item types the key. Two layers may be switched between by selecting L1 / L2.

Lock mode is the secondary primary mode of fbp which provides a number of auxilary functionalities. The text Lock will appear in this mode in the area where the grid normally is. See below for the keybindings available in lock mode.


Normal Mode keybindings:

Normal Mode Volume Raise Volume Lower Powerkey
1 Tap Previous Grid item Next Grid Item Select (type) item
2 Taps Toggle keyboard/strings submode
3 Taps Switch to lock mode
4 Taps Send ^L (e.g. clear screen) and blink blue led
Hold Previous Grid scroll Next Grid scroll Send ^C (e.g. SIGINT), and blink red led

Lock Mode keybindings:

Lock Mode Volume Raise Volume Lower Powerkey
1 Tap Switch to next VT Switch to Previous VT
2 Taps Brightness up Brightness down
3 Taps Switch to normal mode
Hold Activate deep sleep (CRUST) Switch between screen on/off submode Switch to normal mode

#FIFO Interface

If you want to create custom menu-driven scripts or customize the behavior of fbp, fbp's FIFO interface can be used. Upon boot, fbp installs a FIFO file to /tmp/fbp.fifo. The strings that appear on the grid in fbp's UI in the strings submode, can be customized by simply sending newline-delinated (\n) strings to this FIFO. E.g. to append three items (one, two, and three), issue:

echo  -e "\b\f" > /tmp/fbp.fifo
echo "one\ntwo\nthree" > /tmp/fbp.fifo

In addition to appending items, by sending the items as newline-deliniated (\n) strings, the following control-characters are recognized by fbp's FIFO interface:

Escape code Action
\a Switch to the keyboard submode
\b Switch to ths strings submode
\e Disable newlines in strings submode (E.g. strings will be typed without a trailing \n)
\f Clear the list of strings
\r Enable newlines in strings submode (E.g. strings will be typed followed by trailing \n)
\t Restore the base set of strings (by default all executables in $PATH)
\v Send a resize signal to fbp (useful if screwing around with fbset or term fonts)

A simple example script using fbp's FIFO:

#!/usr/bin/env sh
# Queries the user for a site to curl, loading fbp with some preloaded
# defaults and switches to the strings menu, upon completion switches
# back to the keyboard submode

# Switch to strings submode, clear the list, and enable each entry
# to send a newline after typing
echo -e "\b\f\r" > /tmp/fbp.fifo
echo "google.com" > /tmp/fbp.fifo
echo "yahoo.com" > /tmp/fbp.fifo
echo "msn.com" > /tmp/fbp.fifo

read -p Site: SITE
curl $SITE

# Switch back to keyboard submode
echo -e "\a" > /tmp/fbp.fifo

For more practical examples of using fbp's FIFO please see the f_scripts repository.