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 an AWS (Amazon Web Services) instance in the cloud. 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 using a Qt Board Support Package (QBSP) for the AWS Graviton instance.
• Building and debugging the project on the target hardware.

Overview

The figure below illustrates the simplified development process using Qt tools and QBSP for the AWS Graviton target instance.

• Development host is a development computer running Qt tools on Windows, Linux, or Mac.
• 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.
• Upload and debug an application using Qt Creator.
• Launch AWS instance to run Boot to Qt image on cloud.
• Remote connection to application via VNC provides a remote connection to target instance.
• AWS instance is an EC2 instance that runs your embedded Linux application.
• QBSP image is an AWS Graviton device image that can be used to boot your device using the Boot to Qt Software Stack.

Boot to Qt on AWS

For use on Amazon Elastic Compute Cloud (EC2), a Boot to Qt image has been created targeting the Graviton ARM processor core used by AWS. This image is packaged as an Amazon Machine Image (AMI) file that is available for deployment from the AWS Marketplace.

This virtual Qt target device can be used in the same manner as a physical hardware device; the full development tools suite from Qt can be used for design, development and testing of applications on the AWS cloud.

The tools suite includes Qt Design Studio, Qt Creator, Squish GUI Tester, and Axivion Suite. Further, the Qt tools can be run on either a physical development desktop or on a virtual workstation at AWS WorkSpaces.

Using the Boot to Qt EC2 instance

You need a commercial Qt for Device Creation license to install the Qt development tools. The Qt tools can be installed on a physical on-premises workstation, or on a virtual workbench hosted on AWS WorkSpaces. The installation process is the same for both, and fully described on this page.

Applicable AWS Target Instances

Instructions in this guide apply to the following AWS Graviton target instances:

• t4g.nano
• t4g.micro
• t4g.small
• t4g.medium
• t4g.large
• t4g.2xlarge
• g5g.large
• g5g.2xlarge
• g5g.4xlarge

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 Qt 6.7.3. 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 an AWS Graviton instance, 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 AWS EC2 ARM64.
5. Continue to Ready to Install and select Install.

Overview of Instantiating Boot to Qt AMI

You have three options to choose from: Instantiate Boot to Qt AMI from AWS Marketplace, upload the AMI installed from QBSP, or build and upload a custom AMI. You need to configure AWS according to your chosen installation method.

For more information on building and uploading a custom AMI, see section Building and Uploading Custom AMI.

Launching Boot to Qt AMI from AWS Marketplace

To launch a Boot to Qt instance from AWS Marketplace, follow these steps:

1. Open the Amazon EC2 console.
2. On the EC2 console dashboard, in the Launch instance box, select Launch instance.
3. Under Name and tags, for Name, enter a name for your instance.
4. Under Application and OS Images (Amazon Machine Image), do the following:
   • Search Boot to Qt in the search field and then select it in AWS Marketplace AMIs results. This is the operating system (OS) for your instance.
5. Under Instance type, from the Instance type list, you can select the hardware configuration for your instance. Choose either t4g or g5g; the default choice is g5g.large. G5g offers GPU support and higher performance. T4g offers software rendering but doesn't support hardware acceleration.
6. Under Key pair (login), for Key pair name, choose the key pair that you created when getting set up.

   Warning: Do not choose Proceed without a key pair (Not recommended). If you launch your instance without a key pair, you can't connect to it.

7. In Network settings, choose Edit. For Security group name, you'll see that the wizard created and selected a security group for you. You can use this security group, or alternatively you can select the security group that you created when getting set up using the following steps:
   • Choose Select existing security group.
   • From Common security groups, choose your security group from the list of existing security groups.
8. Keep the default selections for the other configuration settings for your instance.
9. Review a summary of your instance configuration in the Summary panel, and when you're ready, choose Launch instance.
10. A confirmation page lets you know that your instance is launching. Choose View all instances to close the confirmation page and return to the console.
11. On the Instances screen, you can view the status of the launch. It takes a short time for an instance to launch. When you launch an instance, its initial state is pending. After the instance starts, its state changes to running and it receives a public DNS name.

    Note: If the Public IPv4 DNS column is hidden, choose the settings icon in the top-right corner, toggle on Public IPv4 DNS, and choose Confirm.

12. It can take a few minutes for the instance to be ready for you to connect to it. Check that your instance has passed its status checks; you can view this information in the Status check column.

Uploading Boot to Qt AMI from QBSP

Before uploading you might also need to configure your AWS account. Please see AWS documentation for details. However, here are some tips.

1. Open your account's security credentials.
2. Select Create access key.
3. Check the box that acknowledges root access is not best practice.
4. Select Create access key.
5. Copy or download the generated Access Key and the Secret Access Key.
6. Configure AWS cmd line tools. From a cmd line, run

   aws configure

7. When prompted, supply the Access Key and Secret Access Key obtained above.
8. When prompted for region, supply the desired region.
9. When prompted for default output format, leave it blank.
10. Create an aws-bucket for AMI upload.
11. Start by opening the AWS S3 Console.
12. In the left-hand panel select Buckets and then Create Bucket.
13. Provide a unique name for the bucket and select the desired region.
14. Scroll down and select Create Bucket.

See AWS instructions for uploading image to AWS.

The upload script expects to find build aggregates at fixed path. Download the upload script and also copy Boot to Qt build aggregates to correct path so that create-ec2-ami.sh can find them.

curl -L https://raw.githubusercontent.com/aws4embeddedlinux/meta-aws/master/scripts/ec2-ami/create-ec2-ami.sh --create-dirs --output sources/meta-aws/scripts/ec2-ami/create-ec2-ami.sh && chmod +x "${_}"
mkdir -p build/tmp/deploy/images/aws-ec2-arm64/
cp <Qt-install-path>/<version>/Boot2Qt/aws-ec2-arm64/images/* build/tmp/deploy/images/aws-ec2-arm64/

Now you have sources/ and build/ folders so you can run the script to upload the AMI image. You need to replace <aws-bucket> with your AWS bucket name.

sources/meta-aws/scripts/ec2-ami/create-ec2-ami.sh <aws-bucket> 8 b2qt-embedded-qt6-image aws-ec2-arm64

Update your AWS permissions by following steps 1, 2, 3, and 6 in Required service role.

Launching Boot to Qt AMI as EC2 Instance

After successful upload the script reports AMI ID, which you can find and launch as an EC2 instance at AWS > EC2 > AMIs as follows:

• Select the uploaded AMI and then select Launch instance from AMI.
• Enter Name and Key pair for SSH login, then select Launch instance.
• Wait for the instance to pass Status checks.
• Connect to instance over SSH client as user.

The IP address of the instance changes on every reboot. To keep IP address fixed go to EC2 > Elastic IPs and select Associate Elastic IP address to AMI Instance.

Open EC2 > AMI Catalog and launch Boot to Qt AMI. Then connect to instance over SSH client.

Setting Up a Device

A Boot to Qt device can be connected via network.

After the target device is connected and has a public 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 Host name (IP address of the AWS Graviton device).
   3. Select Specific key.
   4. Select Finish.
5. On the Devices tab:
   • Select OK.

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

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:
   1. Select your AWS EC2 ARM64 kit.
   2. Select Configure Project.

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

Running an Application on an Instance

After setting up your device, you can upload and start your application on the AWS Graviton instance.

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:
   1. Edit the Run Settings if necessary.
   2. Select Run.

sudo mkdir /usr/examples
sudo chown user /usr/examples

You can set up application graphics in two different ways based on EC2 Instance capabilities.

1. Using EC2 Instance with GPU

EGLFS and Wayland are supported on EC2 Instances with NVIDIA GPU. To use EGLFS, set QT_QPA_PLATFORM=eglfs or use the parameter '-platform eglfs' and add VncItem under Qml Window of your application or Wayland compositor, for example as follows:

import QtVncServer

Window {
...
VncItem {
id : vncItem
anchors.fill: parent
}

For more information on QtVncServer, see Qt VNC Server.

To use Wayland, start Wayland compositor with EGLFS as above. Then use '-platform wayland-egl' in Wayland client to connect it to Wayland compositor.

At the moment, you also need to modify main.cpp to add

{QCoreApplication::setAttribute(Qt::AA_ShareOpenGLContexts, true)}

and remove

{QSurfaceFormat::setDefaultFormat(QQuick3D::idealSurfaceFormat())}

if it exists, to use NVIDIA GPU drivers.

2. Using EC2 Instance without GPU

Qt VNC plugin can be used on EC2 Instances without GPU. To use Qt VNC plugin, set QT_QPA_PLATFORM=vnc or use the parameter '-platform vnc' when starting the application.

Connecting User Interface to EC2 Instance via VNC

Open SSH tunnel from your local host to your instance, for example as follows:

ssh -i <ami-key.pem> -L 5900:localhost:5900 user@ec2-<ami-ip-address>.compute-1.amazonaws.com

Root and password login are disabled by default so you need to log in over SSH as "user". Also note that login key as in ssh -i <key>.pem must have access rights set only for user, for example on Linux chmod 400 <key>.pem.

Open VNC viewer and connect to your instance over the SSH tunnel:

Protocol: VNC
Host: localhost:5900

Debugging an Application

To enable debugging on Boot to Qt AMI, open TCP port 10000 in AMIs > Security group > Edit inbound rules.

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

Customizing Boot to Qt for an AWS 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.

This section provides an example on how to build Boot to Qt for an AWS Graviton instance.

For more information on how to add support for a new device, see How to Add Support for New Device.

1. Initialize the build environment from the manifest repository.

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

   Note: In the example above 6.7.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=aws-ec2-arm64 && source ./setup-environment.sh

3. To use NVIDIA GPU in the AWS instance with this Boot2Qt AMI, you first need to download the NVIDIA driver package Then, set NVIDIA_DEVNET_MIRROR variable in your local.conf to point to the download directory. To find the currently supported driver version, refer to this README file in code.qt.io.
4. 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-aws-ec2-arm64/tmp/deploy/qbsp/meta-b2qt-embedded-qbsp-x86_64-aws-ec2-arm64-6.7.qbsp.

Troubleshooting

If you have any issues with your instance, see Amazon documentation.

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