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 Raspberry Pi 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 Raspberry Pi device.
• Building and debugging the project on the target device.

Overview

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 Device 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 device.
• Flash a QBSP image represents ways (such as SD card) to install Linux on the target device.

Applicable Raspberry Pi Target Devices

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

• Raspberry Pi 4
• Raspberry Pi 5

Installing Qt

To get all the required resources, including Qt Creator and Qt Design Studio, follow these steps:

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 Qt 6.10.0. 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.

Installing Boot to Qt Software Stack Using Qt Maintenance Tool

To install Boot to Qt Software Stack for Raspberry Pi, do the following:

1. Open Qt Maintenance Tool.
2. Continue to Select Components and open the top-level Boot to Qt Software Stack dropdown menu.
3. Open the correct Qt release -specific Boot to Qt Software Stack dropdown menu.
4. Select Raspberry Pi armv8 (64-bit). This component covers both Raspberry Pi 4 and 5 target devices.
5. Continue to Ready to Update 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, Boot to Qt Demo Launcher appears on the screen when you power on the device.

Flashing Boot to Qt Image to a microSD Card

The Boot to Qt image contains the Boot to Qt Software Stack for the Raspberry Pi device. Flash the image to a microSD card as follows:

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

After you have flashed the image to a microSD card, insert the card into your target device and turn it on.

The Raspberry Pi device starts with Boot to Qt Demo Launcher application by default. If you want to check the IP address of the device, open Get Started with Boot to Qt via Boot to Qt Demo Launcher. The IP address is shown if the device is connected to an Ethernet or Wi-Fi network, or to the host computer via USB OTG.

Configuring the Target Device Display

By default, the Raspberry Pi image is configured to use HDMI display and the resolution is chosen automatically depending on the connected monitor. To modify the display settings, edit the file config.txt on the boot partition of the SD card.

To change the HDMI settings, 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.

To use the Raspberry Pi 7" Touch Display, add the following line in file config.txt:

dtoverlay=vc4-kms-dsi-7inch

Then change the correct device in file /etc/kms.conf:

{
    "hwcursor": false,
    "device": "/dev/dri/card1"
}

Finally, save the files and reboot the device. For more information on Raspberry Pi configuration, see the Raspberry Pi documentation on config.txt.

Connecting the Target Device

Create a connection between the target device and Qt Creator to run, debug, and analyze applications on it. The sections below describe how to set up a device using either USB, Ethernet, or Wi-Fi connectivity.

Connecting the Target 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.

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

Connecting the Target Device via Ethernet or Wi-Fi

Connect your target device 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 be used in 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 Raspberry Pi device).
   3. Select Finish.
5. On the Devices tab, select OK.

Creating an Application UI in Qt Design Studio

Create a cross-platform UI with Qt Design Studio, also for embedded Linux applications, with the following steps:

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.
6. Select File > Export Project > Enable CMake Generator. With the resulting CMakeLists.txt file, you can open your project via Qt Creator.

Now you can modify your UI as you wish. Once it's 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

To configure and build an application in Qt Creator, follow these steps:

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 Raspberry Pi kit.
   • Select Configure Project.

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

Running an Application on the Target Device

After setting up your device, you can upload and start your application on the Raspberry Pi device as follows:

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.

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.

Customizing Boot to Qt for a Raspberry Pi device

Boot to Qt for embedded Linux is built using the tools and resources from the Yocto Project. For more information on how to set up a building environment for building Boot to Qt, see Setting Up Environment for Building Boot to Qt.

The following steps provide an example on how to build Boot to Qt for a Raspberry Pi device:

1. Initialize the build environment from the manifest repository.

   cd <BuildDir>
   repo init -u https://code.qt.io/yocto/boot2qt-manifest -m v6.10.0.xml
   repo sync

   Note: In the example above 6.10.0.xml refers to a specific Boot to Qt version, but you can use any version that is compatible with your target device.

2. Configure the build environment for Linux.

   export MACHINE=raspberrypi-armv8 && source ./setup-environment.sh

   Note: The MACHINE value raspberrypi-armv8 works for both Raspberry Pi 4 and 5 target devices.

3. Start building a QBSP for Boot to Qt.

   bitbake meta-b2qt-embedded-qbsp

   After the build has been completed, you can find the QBSP file at boot2qt/build-raspberrypi-armv8/tmp/deploy/qbsp/meta-b2qt-embedded-qbsp-x86_64-raspberrypi-armv8-6.10.0.qbsp.

For more information on how to create a custom Boot to Qt image, see How to Create Boot to Qt Image.

Troubleshooting

If you have any issues with your Raspberry Pi device, such as how to debug via the serial port connection, turn to Raspberry Pi forum for more information.

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