With the release of Qt 5.0, Qt no longer contains its own window system implementation: QWS is no longer a supported platform. For single-process use cases, the Qt Platform Abstraction is a superior solution. Multiple graphical processes will be supported through Wayland.

There are multiple platform plugins that are potentially usable on Embedded Linux systems: EGLFS, LinuxFB, KMS, DirectFB, Wayland. The availability of these depend on the configuration of Qt. The default platform plugin is also device specific. For instance, on many boards eglfs will be chosen as the default one. If the default is not suitable, the QT_QPA_PLATFORM environment variable parameter can be used to request another plugin. Alternatively, for quick tests, the -platform command-line can be used with the same syntax.

Configuring for a Specific Device

Building Qt for a given device requires a toolchain and a sysroot. Additionally, some devices require vendor specific adaptation code for EGL and OpenGL ES 2.0 support. This is not relevant for non-accelerated platforms, for example the ones using the LinuxFB plugin, however neither OpenGL nor Qt Quick 2 will be functional in such a setup.

The directory qtbase/mkspecs/devices contains configuration and graphics adaptation code for a number of devices. For example, linux-rasp-pi-g++ contains build settings for the Raspberry Pi and an implementation of the eglfs hooks (vendor-specific adaptation code). This means that the eglfs platform plugin will be automatically built with the correct, Raspberry Pi-specific adaptation code. The device is selected through the configure tool's -device parameter. The name that follows after this argument must, at least partially, match one of the subdirectories under devices.

Below is an example configuration for the Raspberry Pi. For most Embedded Linux boards the configure command will look very similar. The most important parameters are -device and -sysroot.

./configure -release -opengl es2 -device linux-rasp-pi-g++ -device-option CROSS_COMPILE=$TOOLCHAIN/arm-bcm2708/gcc-linaro-arm-linux-gnueabihf-raspbian/bin/arm-linux-gnueabihf- -sysroot $ROOTFS -prefix /usr/local/qt5

See Qt Configure Options for more information.

Platform Plugins for Embedded Linux Devices

EGLFS

EGL is an interface between OpenGL and the native windowing system. Qt can use EGL for context and surface management, however the API contains no platform specifics: The creation of a native window (which will not necessarily be an actual window on the screen) must still be done by platform-specific means. Hence the need for the board and vendor-specific adaptation code (the so-called eglfs hooks).

EGLFS is a platform plugin for running Qt5 applications on top of EGL and OpenGL ES 2.0 without an actual windowing system (like X11 or Wayland). In addition to Qt Quick 2 and native OpenGL applications it supports software-rendered windows (for example QWidget) too. In the latter case the widgets' contents are rendered using the CPU into images which are then uploaded into textures and composited by the plugin.

This is the recommended plugin for modern Embedded Linux devices that include a GPU.

EGLFS forces the first top-level window (be it either a QWidget or a QQuickView) to become fullscreen. This window is also chosen to be the root widget window into which all other top-level widgets (for example dialogs, popup menus or combobox dropdowns) are composited. This is necessary because with EGLFS there is always exactly one native window and EGL window surface, and these belong to the widget or window that is created first. This approach works well when there is a main window that exists for the entire lifetime of the application and all other widgets are either non top-levels or are created afterwards, once the main window is shown.

There are further restrictions for OpenGL-based windows. As of Qt 5.3, eglfs supports a single, fullscreen GL window (for example, an OpenGL-based QWindow, a QQuickView or a QGLWidget). Opening additional OpenGL windows or mixing such windows with QWidget-based content is not supported and will terminate the application with an error message.

If necessary, eglfs can be configured via environment variables:

• QT_QPA_EGLFS_FB - Overrides the framebuffer device. The default is /dev/fb0. On most embedded platforms this is not very relevant because the framebuffer is used only for querying settings like the display dimensions. On certain devices however this parameter provides the ability to specify which display to use in multiple display setups, similarly to the fb parameter in LinuxFB.
• QT_QPA_EGLFS_WIDTH and QT_QPA_EGLFS_HEIGHT - Contain the screen width and height in pixels. While eglfs will try to determine the dimensions from the framebuffer device /dev/fb0, this will not always work and manually specifying the sizes may become necessary.
• QT_QPA_EGLFS_PHYSICAL_WIDTH and QT_QPA_EGLFS_PHYSICAL_HEIGHT - Physical screen width and height in millimeters. On platforms where the framebuffer device /dev/fb0 is not available or the query is not successful, the values are calculated based on a default DPI of 100. This variable can be used to override any such defaults.
• QT_QPA_EGLFS_DEPTH - Overrides the color depth for the screen. On platforms where the framebuffer device /dev/fb0 is not available or the query is not successful, the default of 32 is used. This variable can be used to override any such defaults. Note that this affects only the color depth value reported by QScreen. It has no connection to EGL configurations and the color depth used for OpenGL rendering.
• QT_QPA_EGLFS_SWAPINTERVAL - By default a swap interval of 1 will be requested. This enables synchronizing to the displays vertical refresh. The value can be overridden with this environment variable. For instance, passing 0 will disable blocking on swap, resulting in running as fast as possible without any synchronization.
• QT_QPA_EGLFS_FORCEVSYNC - When set, eglfs requests FBIO_WAITFORVSYNC on the framebuffer device.
• QT_QPA_EGLFS_FORCE888 - When set, the red, green and blue color channel sizes are ignored whenever creating a new context, window or offscreen surface. Instead, the plugin will request a configuration with 8 bits per channel. This can be helpful on devices where configurations with less than 32 or 24 bits per pixel are chosen by default but are known not to be suitable, for example, due to banding effects. Instead of changing all the applications, this variable provides an easier shortcut to force 24/32 bpp configurations for a given device.
• QT_QPA_EGLFS_DEBUG - When set, some debugging information is printed on the debug output. For example, the input QSurfaceFormat and the properties of the chosen EGL configuration are printed whenever creating a new context. Together with Qt Quick's QSG_INFO variable, this can provide useful information for troubleshooting issues related to the EGL configuration.

LinuxFB

This plugin writes directly to the framebuffer. Only software-rendered content is supported. Note that on some setups the display performance is expected to be limited.

The linuxfb plugin allows specifying additional settings by passing them in the QT_QPA_PLATFORM environment variable or -platform command-line option. For example, QT_QPA_PLATFORM=linuxfb:fb=/dev/fb1 specifies that the framebuffer device /dev/fb1 should be used instead of the default fb0. Multiple settings can be specfified by separating them with a colon.

• fb=/dev/fbN - Specifies the framebuffer devices. On multiple display setups this will typically allow running the application on different displays. For the time being there is no way to use multiple framebuffers from one Qt application.
• size=<width>x<height> - Specifies the screen size in pixels. The plugin will try to query the display dimensions, both physical and logical, from the framebuffer device. This may not always lead to proper results however, and therefore it may become necessary to explicitly specify the values.
• mmSize=<width>x<height> - Physical width and height in millimeters.
• offset=<width>x<height> - Offset in pixels specifying the top-left corner of the screen. The default position is at (0, 0).
• nographicsmodeswitch - Do not switch the virtual terminal to graphics mode (KD_GRAPHICS). In addition to switching to graphics mode, the blinking cursor and screen blanking are normally disabled too. When this parameter is set, these are also skipped.
• tty=/dev/ttyN - Overrides the virtual console. Only used when nographicsmodeswitch is not set.

KMS

An experimental platform plugin using kernel modesetting and drm (Direct Rendering Manager).

Input

When no windowing system is present, the mouse, keyboard and touch input are read directly via evdev or using helper libraries like tslib. Note that this requires that devices nodes /dev/input/event* are readable by the user. eglfs has all the evdev input handling code built-in, while linuxfb relies on the traditional and somewhat limited -plugin command-line parameters.

Input on linuxfb

To enable keyboard, mouse, touch or tablet support with linuxfb, pass QT_QPA_GENERIC_PLUGINS=evdevkeyboard,evdevmouse,evdevtouch,... in the environment or, alternatively, -plugin evdevkeyboard, -plugin evdevmouse, -plugin evdevtouch, or -plugin evdevtablet on the command-line. Most of these can take a device node parameter, for example QT_QPA_GENERIC_PLUGINS=evdevmouse:/dev/event1, in case the Qt's automatic device discovery (based either on libudev or a walkthrough of /dev/input/event*) is not functional or misbehaving.

Input on eglfs

For eglfs, parameters like the device node name can be set in the environment variables QT_QPA_EVDEV_MOUSE_PARAMETERS, QT_QPA_EVDEV_KEYBOARD_PARAMETERS and QT_QPA_EVDEV_TOUCHSCREEN_PARAMETERS. Additionally, the built-in input handlers can be disabled by setting QT_QPA_EGLFS_DISABLE_INPUT to 1. On some touch screens the coordinates will need to be rotated. This can be enabled by setting QT_QPA_EVDEV_TOUCHSCREEN_PARAMETERS to rotate=180.

Mouse

The mouse cursor will show up whenever QT_QPA_EGLFS_HIDECURSOR (for eglfs) or QT_QPA_FB_HIDECURSOR (for linuxfb) is not set and Qt's libudev-based device discovery reports that at least one mouse is available. When libudev support is not present, the mouse cursor will always show up unless explicitly disabled via the environment variable.

Hot plugging is supported, but only if Qt was configured with libudev support (that is, if the libudev development headers are present in the sysroot at configure time). This allows connecting or disconnecting an input device while the application is running. On eglfs the mouse cursor will disappear and reappear appropriately.

Keyboard

The evdev keyboard handler supports the following extra parameters:

• /dev/input/... - Specifies the name of the input device. When not given, Qt will look for a suitable device either via libudev or by walking through the available nodes.
• grab - Enables grabbing the input device.
• keymap - Specifies the name of a custom keyboard map file.
• enable-compose - Enables compositing.
• repeat-delay - Sets a custom key repeat delay.
• repeat-rate - Sets a custom key repeat rate.

On Embedded Linux systems that do not have their terminal sessions disabled, the behavior when pressing a key can be confusing due to having the input event processed both by the Qt application and the tty. To overcome this, the following options are available:

• EGLFS, LinuxFB and KMS attempt to disable the terminal keyboard on application startup by setting the tty's keyboard mode to K_OFF. This prevents keystrokes from going to the terminal. If the standard behavior needs to be restored for some reason, set the environment variable QT_QPA_ENABLE_TERMINAL_KEYBOARD to 1. Note that this will not work when the application is launched from a remote console (for example, via ssh) and the terminal keyboard input will remain enabled.
• An alternative approach is to use the evdev keyboard handler's grab parameter by passing grab=1 in QT_QPA_EVDEV_KEYBOARD_PARAMETERS. This results in trying to get a grab on the input device which, if successful, means that no other components in the system receive events from it as long as the Qt application is running. This approach is more suitable for applications started remotely as it does not need access to the tty device.
• Finally, for many specialized Embedded Linux images it will not make sense to have the standard terminal sessions enabled in the first place. Refer to your build environment's documentation on how to disable them. For example, when generating images using the Yocto Project, unsetting SYSVINIT_ENABLED_GETTYS will result in having no getty process running, and thus no input, on any of the virtual terminals.

Note: Special system key combinations, such as console switching (Ctrl+Alt+Fx) or zap (Ctrl+Alt+Backspace) are not currently supported and will get ignored.

To generate a custom keymap, the kmap2qmap utility can be used. This can be found in the qttools module. The source files have to be in standard Linux kmap format that is e.g. understood by the kernel's loadkeys command. This means one can use the following sources to generate qmap files:

• The Linux Console Tools (LCT) project.
• Xorg X11 keymaps can be converted to the kmap format with the ckbcomp utility.
• As kmap files are plain text files, they can also be hand crafted.

kmap2qmap is a command line program, that needs at least 2 files as parameters. The last one will be the generated .qmap file, while all the others will be parsed as input .kmap files. For example:

kmap2qmap i386/qwertz/de-latin1-nodeadkeys.kmap include/compose.latin1.inc de-latin1-nodeadkeys.qmap

Note: kmap2qmap does not support all the (pseudo) symbols that the Linux kernel supports. When converting a standard keymap, a number of warnings will be shown regarding Show_Registers, Hex_A, and so on; these messages can safely be ignored.

Touch

For some resistive, single-touch touch screens it may be necessary to fall back to using tslib instead of relying on the Linux multitouch protocol and the event devices. For modern touch screens this should not be necessary. tslib support can be enabled by passing -plugin tslib instead of evdevtouch. To change the device, set the environment variable TSLIB_TSDEVICE or pass the device name on the command-line.

Platform Plugins for Windowing Systems on Embedded Linux Devices

XCB

This is the X11 plugin used on regular desktop Linux platforms. In some embedded environments, that provide X and the necessary development files for xcb, this plugin will function just like it does on a regular PC desktop.

Note: On some devices there is no EGL and OpenGL support available under X because the EGL implementation is not compatible with Xlib. In this case the XCB plugin will be built without EGL support, meaning that Qt Quick 2 or other OpenGL-based applications will not work with this platform plugin. It can still be used however to run software-rendered applications (based on QWidget for example).

As a general rule, the usage of XCB on embedded devices is not advisable. Plugins like eglfs are likely to provide better performance, and hardware acceleration.

Wayland

Wayland is a light-weight windowing system; or more precisely, it is a protocol for clients to talk to a display server.

The Qt Wayland module provides a wayland platform plugin that allows Qt application to connect to a Wayland compositor.