Osk-sdl

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 gitlab issues page.

The osk-sdl-dev room on Matrix can also be used to ask questions, see Matrix_and_IRC.

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  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 without the  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:

Not using  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):

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

Enable hardware acceleration
osk-sdl can use hardware acceleration (instead of slowly drawing to the framebuffer). The necessary setup is automatically done by setting  (see deviceinfo reference) in the device package. The driver that needs to be specified there can be found for example by running:

In this example, "sun4i-drm" should be specified. In some cases also additional GPU firmware needs to be copied to the initramfs which can be done by putting e.g.  into the device package with each file that should be copied on a separate line. See the Fairphone 2 device port for an example where a firmware file is copied.

In addition to setting, you must also add a dependency on    OR   for newer devices.

This feature was added in.

Set touchscreen device
See deviceinfo_dev_touchscreen.

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, 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  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 endmode

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

Source: • 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  utility and tap the small X's on screen as accurately as you can. This will generate a file. Use  utility to check if touchscreen is working correctly after calibration.

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  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

 * fb.modes man page
 * fbset man page
 * directfbrc man page

Testing with QEMU
To build osk-sdl from a local source tree and test it in QEMU, run the following once:

Then for every time you want to test (it's faster the second time):

The  command will set the password to.

Updating osk-sdl without flashing the rootfs
does not get updated when flashing the kernel/initramfs/boot.img to your device. That is, because it is in the  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 usual, 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  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, enable initramfs-extra, then run the following to unlock it:

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.

Make sure you've exported SDL_VIDEO_GL_DRIVER:

If you have been testing earlier versions of, you may still have a custom SDL2 package with version   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:

DirectFB/FBDev: No supported modes found in /etc/fb.modes and current mode not supported!
You will need to create a  file for your device. See the above section

ERROR: Unknown dfb pixelformat
osk-sdl is using SDL2 and DirectFB for rendering to the framebuffer (which is what we need to do for most devices, because they only have framebuffer drivers in the kernel, not the more modern DRI/DRM drivers). The error message means, that the SDL2 mode is not mapped to a DirectFB mode. See for detailed instructions on how to patch SDL2 to add a mapping for your mode.

Building osk-sdl from repo
Quote from osk-sdl issue 90:

Here's the workflow for modifying the code and building it as postmarketOS package:

Then you can copy the new package to the device, either with scp or with this guide: Installing_packages_on_a_running_phone