From postmarketOS
Jump to: navigation, search

This is an application developed by the postmarketOS community to unlock the LUKS volume in the beginning of the boot process. It implements a password box and on-screen keyboard directly on the linux framebuffer, but also supports (though largely untested at the moment) any of the other backends supported by SDL2.

It is written in C++14 and uses libcryptsetup directly to unlock the partitions. The osk-sdl package is part of pmOS's aports.

Reporting Issues

Issues with osk-sdl should be reported on the project github issues page.

The osk-sdl-dev room on Matrix can also be used to ask questions: #osk-sdl-dev:disroot.org

Porting to New Devices

It's necessary to configure and/or create a few files when porting osk-sdl to a new device. Some of the files mentioned below are not necessary on all devices. Any files created out of necessity in the below steps should be included in your device package. See the nokia-rx51 device package for an example of how some of these files have been included/installed.

It's highly recommended that you run osk-sdl from within pmOS, which means installing pmOS with the --no-fde parameter. Running osk-sdl from within pmOS during the porting process will allow you to run any additional tools required for generating some of the configuration files below, as well as collect additional diagnostic info if you run into any issues.

Running osk-sdl within pmOS

The osk-sdl package is in pmOS's aports directory. To prepare pmOS for running osk-sdl for porting:

$ git clone https://github.com/postmarketOS/pmbootstrap.git
$ ./pmbootstrap init
<select device options>
<select 'none' for UI so that osk-sdl can be run from within pmos without conflicting with weston>
$ ./pmbootstrap install --no-fde --add osk-sdl

Using --no-fde will allow pmOS to boot straight into rootfs without requiring unlocking of the partition. This seems counter-intuitive for porting a keyboard made for initramfs, but this will allow you to manually run osk-sdl with various environment options set and/or osk.conf options for debug.

To run osk-sdl from pmOS (not in initramfs):

$ sudo su
# export DFBARGS="system=fbdev,no-cursor,linux-input-grab"
# export TSLIB_TSDEVICE=/dev/input/eventX
# osk-sdl -d a -n a -c /etc/osk.conf -v

Do not use the -t option when porting osk-sdl on a device, this mode of running osk-sdl will not be helpful for this purpose!

Set touchscreen device

A rudimentary method for finding this device is to cat /dev/input/eventX each event file in that directory and touch the screen. If you cat the touchscreen device, cat will output a bunch of gibberish on the screen when you touch it.

Once you have identified the touchscreen event file under /dev/input, set (or add if it doesn't exist) the deviceinfo_dev_touchscreen variable in your deviceinfo file to the /dev/input/eventX event device file representing your touchscreen. For example:


Create fb.modes

Some devices require creating a file to inform DirectFB of the correct mode that the display supports.

To calculate the mode for your device you can run fbset, however beware that the mode it returns isn't always supported. Some things to be aware of:

  • Make sure the last number of the geometry line (the color depth) is not 32 or 24, because this is not supported by directfb. If you need 32 or 24 there, set this value to 16 and set pixelformat in DFBARGS to a supported pixel format with color depth 32 or 24 (see man page of directfbrc for all available pixelformat options).
  • Normally the geometry line should have twice your resolution (both for physical and virtual resolution). Fbset sometimes returns wrong values with which osk-sdl cannot cope (generates segmentation fault when touching the keyboard).

An example for a display with 1080x1920 resolution and 32-bit color depth:

mode "1080x1920-0"
    # D: 0.001 MHz, H: 0.001 kHz, V: 0.000 Hz
    geometry 1080 1920 1080 1920 16
    timings 898000000 75 129 4 8 5 4
    rgba 8/16,8/8,8/0,8/24

If you had to create this file for osk-sdl to display on your device, make sure to include the /etc/fb.modes file in your device package.

DirectFB modes
SDL2 modes

Create touchscreen calibration file

Some devices require touchscreen calibration for osk-sdl to properly handle taps on the screen. To create the calibration file necessary for osk-sdl, run the ts_calibrate utility and tap the small X's on screen as accurately as you can. This will generate a file /etc/pointercal.

After running the calibration, re-run osk-sdl to confirm that touch input is being appropriately handled.

If you had to create this file for osk-sdl to properly handle the touchscreen input on your device, make sure to include the /etc/pointercal file in your device package.

The file format is quite similar to the calibration for libinput. The file consists of 9 values. It starts with two groups of three values, the first is for the x coordinate and the second for the y coordinate. Each group consists of a multiplier for the x and a multiplier for the y coordinate and then an offset. However, as all values need to be integers, the values are scaled by a scaling factor. This is the 7th number in the file and is always 65536. The last two values are the screen width and height. Similar to the calibration matrix for libinput, some of the first two values of every group should be 0. While one might think that the other values should always be around the scaling factor or, for the offsets, 0 or the scaling factor times device width/height (as for libinput), this is not the case. E.g. for the Google_Nexus_7_2012_(asus-grouper) the x/y multipliers are around 0.6 (see pointercal) even though for Weston no such scaling is necessary. This could actually be the width/height ratio (0.625) or something unrelated. If you have more information on this, please add it here so we can get more precise calibration files!

Porting References


Updating osk-sdl without flashing the rootfs

osk-sdl does not get updated when flashing the kernel/initramfs/boot.img to your device. That is, because it is in the initramfs-extra file inside the boot partition of the rootfs. Here's a rough description of the steps you need to take to update it without flashing the entire rootfs (which is the easy way), in case you have flashed a version that doesn't boot up anymore. As usually, just ask in the channel for help if you get stuck.

  • Install the debug-shell initramfs hook and connect via telnet
  • Mount the boot partition of the rootfs image
  • use netcat to upload the new initramfs-extra file via telnet

Unlocking via telnet

If osk-sdl does not work for some reason, but you really need to access your data, you can connect to the initramfs via telnet, then run the following to unlock it:

# source /init_functions.sh
# cryptsetup luksOpen "$(find_root_partition)" root
Enter passphrase for /dev/mapper/mmcblk0p2:
# killall osk-sdl

ERROR: Library not found: libGL.so

This should be resolved in SDL2 2.0.6, however if this issue occurs then most likely the mesa-gl dependency for osk-sdl did not install properly. Please report this issue, see #Reporting Issues.

Make sure you've exported SDL_VIDEO_GL_DRIVER:

$ sudo su
# export SDL_VIDEO_GL_DRIVER="libGL.so.1"

If you have been testing earlier versions of osk-sdl, you may still have a custom SDL2 package with version 9999 in your packages directory. That is not required anymore, all necessary changes to SDL2 have been upstreamed, we can use the version from Alpine now. Delete it with the following steps:

$ sudo rm -v ~/.local/var/pmbootstrap/packages/*/sdl2*
$ pmbootstrap index

DirectFB/FBDev: No supported modes found in /etc/fb.modes and current mode not supported!

You will need to create a fb.modes file for your device. See the above section #Create fb.modes

Building osk-sdl from repo

This is an example APKBUILD you can use to build osk-sdl from a branch instead of a tag. Don't forget to generate a new checksum (pmbootstrap checksum osk-sdl) before trying to build it.

# Change out the hash here with the hash of the git commit you want to build
pkgdesc="Onscreen keyboard for unlocking LUKS devices"
depends="sdl2 sdl2_ttf cryptsetup-libs mesa-gl directfb"
makedepends="linux-headers sdl2-dev sdl2_ttf-dev cryptsetup-dev"


options="!strip !check"

build() {
    cd $srcdir/${pkgname}-${_hash}

package() {
    install -D -m755 "${srcdir}/${pkgname}-${_hash}"/osk-sdl \
    install -D -m755 "${srcdir}/${pkgname}-${_hash}"/osk.conf \