Toradex Quick Start Guide

Qt offers all the necessary tools to design, develop, build, and deploy your application onto the target.

This guide describes how to use the GUIs of Qt tools to develop Linux applications on a Toradex device. It describes the overall process and provides step-by-step instructions for the following tasks:

  • Designing a simple UI using Qt Design Studio.
  • Creating a project in Qt Creator and utilizing the ready-made Boot to Qt image for the Toradex device.
  • Building and debugging the project on the target hardware.

Note: Qt for Device Creation requires a license. If you don't have one, you can request a free trial.


The following figure illustrates the basic concept of the software development process when you're using Qt tools and Boot to Qt Software Stack.

  • Development Host is a development computer running Qt tools on Windows, Linux, or macOS.
  • Qt tools includes development tools such as Qt Creator and Qt Design Studio, and quality assurance (QA) tools such as Squish.
  • QBSP SDK contains a cross-compilation toolchain that is integrated into Qt Creator, and a device image that can be used to boot your device using Boot to Qt Software Stack.
  • Target HW is your development target that runs your embedded Linux application.
  • Upload and debug an application (via Ethernet, Wi-Fi, or USB). Use Qt Creator to upload and debug your application on the target HW.
  • Flash a QBSP image represents ways (such as SD card) to install Linux on the target hardware.

Applicable Toradex Target Devices

The instructions in this guide apply to the following Toradex target devices:

  • Toradex Apalis iMX6
  • Toradex Apalis iMX8
  • Toradex Colibri iMX6 ULL

Note: For more details on the supported target devices and development hosts, see Supported Target Devices and Development Hosts.

To successfully set up the Boot to Qt Software Stack, you must closely follow the instructions in this section and perform all the described tasks.

In case of problems, see Troubleshooting.

Note: After you have installed the Boot to Qt software stack and want to connect to the target device with SSH or a serial cable, you can access the device by using the user root and an empty password.

Before you install the Boot to Qt Software Stack, you should note the requirements related to the development hosts:

Installing Qt

Follow the procedures in this guide to get all the required resources, including Qt Creator and Qt Design Studio.

  1. Sign in to Qt Customer Portal to download Qt online installer.
  2. The installer is available for the following hosts:
    • Linux on ARM
    • Linux x86
    • macOS
    • Windows

    Download the installer package that matches your host.

  3. Open the installer.
  4. Continue to Installation Folder and select Custom installation.
  5. Select Next.
  6. In Select Components, select the latest official release of Qt. The required developer and designer tools (such as Qt Creator and Qt Design Studio) are preselected in the installer.
  7. Select Next.
  8. Continue to Ready to Install and select Install.

Note: If you have Qt already installed, use Qt Maintenance Tool to install the missing tools.

Installing Boot to Qt Software Stack Using Qt Maintenance Tool

In the example procedure below, Boot to Qt Software Stack is installed for the Toradex Apalis iMX6.

  1. Open Qt Maintenance Tool.
  2. Continue to Select Components and open the top-level Boot to Qt Software Stack dropdown menu.
  3. Select Toradex Apalis iMX6.
  4. Continue to Ready to Install and select Update.

Installing Boot to Qt on the Target Device

Before you can test your Qt applications on the target device, you must flash the target device with an image containing the Boot to Qt Software Stack. After you have successfully flashed your device, \B2QDL appears on the screen when you power on the device.

To flash the image, you can use either Toradex Easy Installer or Flashing Wizard from Qt Creator.

With Toradex Easy Installer, the image is first written to an SD card or a USB flashdrive and then to the device's internal eMMC flash memory.

With Flashing Wizard you can flash an SD card that is then used to boot the device, or you can use a USB connection to flash the image directly to the device's internal eMMC flash memory. Flashing Wizard does not update the device's boot loader (U-Boot) and if you have trouble booting the device, you may need to use Easy Installer to get the boot loader updated.

Flashing with Toradex Easy Installer

When Toradex Easy Installer is connected to the internet, it automatically provides a Boot to Qt image in its image list. However, this image is not necessarily compatible with your Boot to Qt installation. When you flash with Toradex Easy Installer, you must use the *.tezi.tar package that is included into the Boot to Qt installation.

Flash the Boot to Qt image with Toradex Easy Installer as follows:

  1. If your target device does not have the pre-installed Toradex Easy Installer, follow instructions in Load Toradex Easy Installer to load Toradex Easy Installer.
  2. Your Boot to Qt installation has the *.tezi.tar package under <Qt installation directory>/<Qt version>/Boot2Qt/<target>/images. Extract the package to an SD card or a USB flash drive.
  3. Flash the image from the SD card or the USB flash drive with Toradex Easy Installer. See Install Images with Toradex Easy Installer.

Flashing with Qt's Flashing Wizard

Flash the Boot to Qt image to an SD card with Flashing Wizard as follows:

Note: Make sure that the SD card size is at least 4 GB.

  1. Insert a microSD card into your host PC.
  2. Open Qt Creator.
  3. Select Tools > Flash Boot to Qt Device.
  4. Select Next.

Alternatively you can flash the Boot to Qt image directly to the device's internal eMMC flash memory:

  1. Use the RS-232 or USB cable to access the serial terminal on the target device.
  2. Power on your device and press any key to stop the autoboot.
  3. To make eMMC accessible via USB, run the following command in U-Boot:
    ums 0 mmc 0
  4. Connect your device to the development host using USB On-The-Go (OTG).
  5. Use Flashing Wizard to flash the image to the device:
    • Launch Qt Creator.
    • Select Tools > Flash Boot to Qt Device, and follow the instructions in Flashing Wizard.
  6. Press Ctrl+C in the U-Boot console and run the reset command.

Setting Up a Device

A Boot to Qt device can be connected either via USB, Ethernet, or Wi-Fi. The sections below provide instructions on how to set up a device using either USB, Ethernet, or Wi-Fi connectivity.

Setting Up a Device via USB

The target device can be connected to the host via USB On-the-Go (OTG). Once connected via a USB network, the device is automatically added to the Devices in Qt Creator.

The USB access to the target device supports two different USB protocols. The default RNDIS protocol can be used when connecting the target device to either a Linux or Windows host. When you want to connect the target device to a macOS host, you need to change to the CDC-ECM protocol.

Note: You can change the protocol from the Boot to Qt Startup Screen.

For more information on connecting a device via USB, see Setting Up USB Ethernet on Target Device.

Setting Up a Device via Ethernet or Wi-Fi

The target device can be connected to network either via Ethernet or Wi-Fi connectivity. After the target device is connected and has an IP address, you can set it up to Qt Creator with the following steps:

  1. Open Qt Creator.
  2. Select Edit > Preferences.
  3. In the Preferences window:
    1. Select Devices.
    2. Select Add > Boot2Qt Device > Start Wizard.
  4. In the Boot2Qt Network Device Setup window:
    1. Enter the Device name.
    2. Enter the Device address (IP address of the Toradex device).
    3. Select Finish.
  5. On the Devices tab:
    • Select OK.

Note: You can also set up Wi-Fi connection from the Boot to Qt Startup Screen

Note: Qt Creator uploads the application over the IP network, so the Toradex device has to be in the same network as your development host PC.

Creating an Application UI in Qt Design Studio

You can use Qt Design Studio to create a cross-platform UI, also for embedded Linux applications.

  1. Open Qt Design Studio.
  2. Select Create Project.
  3. In Presets, select General.
    • Name your project (also notice the project path to open it with Qt Creator).
    • Adjust display resolution and orientation to suit your display.
  4. Make sure your Target Qt Version matches the version of Qt installed on your machine.
  5. Select Create.

Now you can modify your UI as you wish. Once it is ready, select Save All to make sure that you can open your UI project in Qt Creator.

Configuring and Building an Application in Qt Creator

  1. Open Qt Creator.
  2. Navigate to the project you created with Qt Design Studio.
  3. Select CMakeLists.txt to open the project.
  4. In the Configure Project window:
    • Select your Toradex kit.
    • Select Configure Project.

Finally, select Build > Build Project to build the project you configured.

Running an Application on a Device

After setting up your device, you can upload and start your application on the Toradex Apalis iMX6 device.

  1. Open Qt Creator.
  2. Select File > Open File or Project.
  3. Navigate to the project you configured earlier and select Open.
  4. In the Projects window:
    • Edit the Run Settings if necessary.
    • Select Run.

Note: To make changes to your application, you can update it on the device simply by running it again.

For more information on how to deploy Qt projects to the device, see Tutorial: Deploying Your First Project with Boot to Qt.

Debugging an Application

For more information on using Qt Creator to debug an application, see Debugging.


If you have any issues with your Toradex device, such as how to setup boot switches or connect the debug terminal, turn to Toradex Developer Center for more information.

For more information on troubleshooting Boot to Qt, see Troubleshooting.

Available under certain Qt licenses.
Find out more.