Customizing Runtime Environment

Environment and Input

By default, the basic environment variables and startup options of Boot to Qt applications are set in /etc/default/qt or /etc/appcontroller.conf on embedded Linux devices.

You can customize this file if your target device that has other input devices than the ones that the Boot to Qt stack is configured for by default.

When you need to configure input devices, see Input in Embedded Linux Devices for more information.

USB input devices, such as keyboards and mice, are automatically recognized. The mouse pointer is shown automatically if a mouse is connected.

However, hotplugging may not work, which means that the input devices, such as a keyboard and mouse, have to be connected at boot time.

Switching to tslib for Resistive Touchscreens

For touchscreens that do not provide modern multitouch capabilities it may be necessary to use the tslib library instead of relying on direct event device access and the Linux kernel's multitouch protocol. This also allows calibration and is more suitable for resistive touchscreens that are often used in an industrial setting.

To enable tslib, add the following lines to /etc/default/qt on the device:


Note: The tslib plugin provides no multitouch events (QTouchEvent). It only generates mouse events (QMouseEvent).

If necessary, the device can be specified explicitly by setting TSLIB_TSDEVICE:


The touchscreen calibration can be done with ts_calibrate and the calibration file can be used by setting TSLIB_CALIBFILE:


Booting to a Custom Application

By default, the Boot to Qt Startup Screen is configured to run on startup.

To have your application launch on boot:

  • Go to Projects > Run for the Boot to Qt version you want to customize.
  • Under Deployment, click on Add Deploy Step, and select Change default application.
  • Re-deploy your project. In Edit mode, right-click on the project and select Deploy, or click (Run).

Your application will now be launched on the next device reboot.

Alternatively, you can also run the following command on the device:

appcontroller --make-default <path>

Where <path> is the install path of your application binary on the device.

To remove your application from the default startup, run the following command on the device:

appcontroller --remove-default

Configuring Display Resolution

Steps for configuring a custom resolution depend on the device and display.

Boundary Devices i.MX6 Boards

The resolution can be changed by modifying the boot environment:

Start the device with a serial terminal connected, and hit any key to enter the u-boot prompt:

Hit any key to stop autoboot

A list of available preconfigured panels is shown with the command


There are four variables that control the selected panel for different connection types:

fb_hdmiHDMI display
fb_lcdLCD display
fb_lvdsLVDS display
fb_lvds2LVDS2 display

A complete example configuration for all types could look as follows:

setenv fb_hdmi 1280x720M@60
setenv fb_lcd CLAA-WVGA
setenv fb_lvds hannstar7
setenv fb_lvds2 hannstar

If your HDMI screen has a non-default CEA resolution, you should also set

setenv allow_noncea 1

For more information, see the Boundary Devices documentation on https://boundarydevices.com/display-configuration-u-boot/.

Raspberry Pi

By default, the resolution is chosen automatically depending on the connected monitor. To select specific display settings, edit the file config.txt on the boot partition of the SD card.

Scroll down to the "hdmi_mode" section and search the table for the mode you want to set. Uncomment the line at the end of the section and set the value to the one you picked from the table. Save the file and reboot the device.

For more information, see the Raspberry Pi documentation on config.txt.

Configuring the physical screen size for scalable user interfaces

The Boot to Qt Startup Screen and Qt Quick Controls scale automatically to screens of different sizes, from 7" touchscreens to 60" or larger TVs to ensure readability and touch friendliness. For this, Qt has to know the physical dimensions of the screen. By default it tries to query these values from the framebuffer devices. Many kernel drivers do not provide this information, however.

To override and manually set a desired screen size, go the Launcher Settings view and change the values in the Physical screen size in millimeters boxes. Then tap the reboot button or restart your application. The controls will adjust their sizes based on the new settings.

Switching Between Portrait and Landscape Views

Depending on device screen dimensions and application requirements, it might be desirable to change the default view orientation. The following example shows how to rotate your application in QML.

import QtQuick 2.2

Item {
    id: root
    width: 800
    height: 1280
    // Container element for rotating
    Rectangle {
        id: main
        // Swap the width and height of the root item
        width: root.height
        height: root.width
        anchors.centerIn: parent
        // Rotate 90 degrees clockwise around transformOrigin
        rotation: 90
        // The rotated content
        Text {
            text: qsTr("Hello World")
            anchors.centerIn: parent
        MouseArea {
            anchors.fill: parent
            onClicked: {

Resizing the SD Card Root Partition

By default, the Boot to Qt image will have some extra free space reserved for development purposes, but not all of the extra capacity that the SD card might have is available. The Boot to Qt image includes tools that can be used to extend the root partition in the SD card to its full size.

Note: The tools will modify the partition layout which can cause data loss. You should never attempt these steps if you are unsure or your SD card contains important files.

The resizing is done in two steps:

  • Resize the partition table for the root partition, which is usually the second partition:
    parted -s /dev/mmcblk0 resizepart 2 100%
  • Resize the file system on the second partition:
    resize2fs /dev/mmcblk0p2

where /dev/mmcblk0 refers to the device node of the SD card, and /dev/mmcblk0p2 to the second partition on that SD card.

Setting Up USB Ethernet on Target Device

The USB access to the embedded target device supports two different USB protocols. The default protocol (Remote Network Driver Interface Specification, RNDIS) can be used when connecting the target device to either Linux or Windows host. When you want to connect the target device to a macOS host, you will need to change the protocol to CDC-ECM (Communications Device Class - Ethernet Control Module).

After you have installed Boot to Qt to your target device, you can change the protocol by editing a configuration file on the device.

Editing Configuration File on Device

The USB Ethernet protocol support can be configured from the following file on the target device:


Support the RNDIS protocol for Windows and Linux hosts (default):


Support the CDC-ECM protocol for macOS and Linux hosts:


Connect the target to host with a USB cable. After changing the above file restart the target device.

In case of problems, see Troubleshooting.

Available under certain Qt licenses.
Find out more.