buffybox/buffyboard

Buffyboard

Touch-enabled framebuffer keyboard (not only) for vampire slayers.

[[TOC]]

About

Buffyboard is a touch-enabled on-screen keyboard running on the Linux framebuffer. It's primarily intended for vampire hunting¹ but you can also use it as a general purpose keyboard.

Buffyboard uses LVGL for input processing and rendering. Key events are forwarded directly to the kernel via a uinput device. Since the latter emulates a hardware keyboard, the terminal keymap must match with buffyboard's layout or else on-screen keys might not produce the correct result.

Status

We are en route to v1 which aims at providing a useable, visually pleasant application including fbkeyboard's most essential features. For details about the current status, see the v1 milestone. You may also browse the full list of open issues to get an idea of what's planned beyond v1.

Here are a few highlights of what already works:

• On-screen keyboard control via mouse, trackpad or touchscreen
• Multi-layer keyboard layout including lowercase letters, uppercase letters, numbers and selected symbols (based on top three layers of squeekboard's US terminal layout)
• Key chords with one or more modifiers terminated by a single non-modifier (e.g. CTRL-c)
• Highlighting of active modifiers
• Automatic resizing (and later reset) of active VT to prevent overlap with keyboard
• Theming support

Screenshots of the currently available themes may be found in the screenshots folder.

Usage

You can get an overview of available command line options by running it with the -h or --help argument.

$ buffyboard --help
Usage: buffyboard [OPTION]

Mandatory arguments to long options are mandatory for short options too.
  -C, --config-override     Path to a config override file. Can be supplied
                            multiple times. Config files are merged in the
                            following order:
                            * /etc/buffyboard.conf
                            * /etc/buffyboard.conf.d/* (alphabetically)
                            * Override files (in supplied order)
  -g, --geometry=NxM[@X,Y]  Force a display size of N horizontal times M
                            vertical pixels, offset horizontally by X
                            pixels and vertically by Y pixels
  -d  --dpi=N               Override the display's DPI value
  -r, --rotate=[0-3]        Rotate the UI to the given orientation. The
                            values match the ones provided by the kernel in
                            /sys/class/graphics/fbcon/rotate.
                            * 0 - normal orientation (0 degree)
                            * 1 - clockwise orientation (90 degrees)
                            * 2 - upside down orientation (180 degrees)
                            * 3 - counterclockwise orientation (270 degrees)
  -h, --help                Print this message and exit
  -v, --verbose             Enable more detailed logging output on STDERR
  -V, --version             Print the buffyboard version and exit

For an example configuration file, see buffyboard.conf.

Development

Dependencies

• inih
• lvgl (git submodule / linked statically)
• squeek2lvgl (git submodule / linked statically)
• libinput
• libudev
• evdev kernel module
• uinput kernel module

Building & running

Some of buffyboard's dependencies are included as git submodules in this repository. You can clone the repository and initialise the submodules with

$ git clone https://gitlab.com/cherrypicker/buffyboard.git
$ cd buffyboard
$ git submodule init
$ git submodule update

When pulling changes from the remote later, either use git pull --recurse-submodules or manually run git submodule update as needed after pulling.

Once you have the sources, you can build the app and run it in a VT. Unless your user account has special privileges, sudo will be needed to access input device files.

$ meson _build
$ meson compile -C _build
$ sudo chvt 2
$ sudo ./_build/buffyboard

With meson <0.55 use ninja instead of meson compile.

Keyboard layouts

Buffyboard uses squeekboard layouts converted to C via squeek2lvgl. To regenerate the layouts, ensure that you have pipenv installed (e.g. via pip install --user pipenv) and then run

$ ./regenerate-layouts.sh

Generating screenshots

To generate screenshots in a variety of common sizes, install fbcat, build buffyboard and then run

$ sudo ./regenerate-screenshots _build/buffyboard

where _build/buffyboard is the location of the buffyboard binary.

Acknowledgements

The lv_port_linux_frame_buffer project served as a starting point for the codebase.

The mouse cursor image was taken from lv_sim_emscripten.

Buffyboard was inspired by fbkeyboard.

Footnotes

---

1. If you still don't know what vampires have to do with all of this, the train of thought is: Linux framebuffer 👉 buffyboard 👉 ... wait for it ... 👉 Buffy the Vampire Slayer. There you have it. I never claimed I was funny. 😅 ↩︎