1. Article purpose
Purpose of this article is to:
- Introduce the X-LINUX-QT Expansion Package[1],
- Define the hardware & software deliverables to use the X-LINUX-QT packages,
- Describe all steps to integrate the X-LINUX-QT packages and associated expected results,
- Give some use case examples enabled by the X-LINUX-QT package,
- Explain how to create a Qt™ application using the X-LINUX-QT Developer Package
- Describe all steps to use Qt™ Creator with the X-LINUX-QT Developer Package and associated expected results.
2. X-LINUX-QT Expansion Package description
2.1. Overview
X-LINUX-QT is an STM32 MPU OpenSTLinux Expansion Package that targets Qt™ based application and graphical user interface (GUI) development for STM32MP25x lines 
.
It contains Linux® Qt™ frameworks, as well as an ST Application Launcher based on Qt™ Framework and application examples to get started with Qt™ application development.
The Qt™ framework contains a comprehensive set of highly intuitive and modularized C++ library classes and is loaded with APIs to simplify your application development. Qt™ produces highly readable, easily maintainable and reusable code with high runtime performance and small footprint – and it's cross-platform.
This expansion package is a complete ecosystem that allows developers working with OpenSTLinux to create Qt™ based application very easily.
- All-in-one Qt™ solutions for the STM32MP2 series supporting Wayland and Weston.
- Pre-integrated into Linux® distribution based on ST environment
- Include Qt™ frameworks to build UIs and Applications
- Include ST Application Launcher based on Qt™ framework forSTM32 MPU devices (see supported platforms list)
2.2. Main restrictions
This first version of X-LINUX-QT Expansion Package is not yet functional with STM32MP1 series.
2.3. Versioning
Latest version of X-LINUX-QT is 2.0.0. The X-LINUX-QT Expansion Package is based to be used with OpenSTLinux distribution ecosystem release v5.1.0 .
The generic versioning X-LINUX-QT vx.y.z is built as follows:
- x: major version depending on Qt™ major versions. Each new major version is incompatible with previous Qt™ versions. Initial major version 1.0.0 is for Qt 5.x and current version 2.0.0 is for Qt 6.x
- y: minor version depending on the OpenSTLinux distribution major versions. Each new major version is incompatible with previous OpenSTLinux distribution versions. Initial minor version will be for OpenSTLinux Distribution v5.x
- z: patch version is changed when new functionalities, bug fixes and/or modules are added to the X-LINUX-QT Expansion Package in a backward compatible manner.
3. Associated licenses
Associated licenses are available in the wiki article X-LINUX-QT_licenses.
4. Prerequisites
4.1. Hardware prerequisites
- STM32MP257F-EV1 Evaluation board
- STM32MP257F-DK Discovery kit
4.2. Software prerequisites
The X-LINUX-QT Expansion Package runs with OpenSTLinux ecosystem release v5.1.0 .
The X-LINUX-QT Expansion Package can be used in standalone or with the Qt™ Creator[2] tool.
The Qt™ Creator[2] tool can be used to build, debug and run applications demos on target. If you want to use it, you need to make following prerequisites:
- You will need to create a Qt™ account then download and install the Qt™ Creator
- The Qt™ online installer is available from here
5. Hardware setup
5.1. STM32MP257x-EV1 Evaluation board
The STM32MP257x-EV1 - hardware description describes how to set up the STM32MP257F-EV1 Evaluation board : it explains how to assemble the boards, set the right power jumper configuration, connect the display to the board and connect the board to your development environment.
5.2. STM32MP257x-DK Discovery Discovery kit
The STM32MP257x-DKx_-_hardware_description describes how to set up the STM32MP257F-DK Discovery kit : it explains how to connect the display to the board and connect the board to your development environment.
6. Software setup
6.1. How to get software
There are 3 possibilities to install the additional X-LINUX-QT Expansion Package software to port on top of OpenSTLinux.
Select the one corresponding to your needs amongst :
- X-LINUX-QT Starter Package : quickly and easily bring Qt™ framework on STM32 MPU as graphics solution.
- X-LINUX-QT Developer Package: quickly and easily bring and develop with Qt™ framework on STM32 MPU as graphics solution.
- X-LINUX-QT Distribution package: an OpenEmbedded meta-layer must be added on top of the STM32MPU Distribution Package to bring "Qt™ framework" as graphics solution.
6.1.1. How to install the Starter Package
6.1.1.1. Install OpenSTLinux Starter Package
Before developing with the Developer Package, it is essential to start up your board thanks to its Starter Package. All articles relative to Starter Packages are found in Category:Starter Package: find the one that corresponds to your board, and follow the installation instructions (if not yet done), before going further.
Thanks to the Starter Package, all Flash partitions are populated.
6.1.1.2. Install the X-LINUX-QT Starter Package
The packagegroup-x-linux-qt package must be installed on top of the STM32MPU Starter Package to bring the "Qt framework" as graphics solution.
Once the board is booted, make sure it is connected to the internet then execute the following commands in the console to install the X-LINUX-QT packages:
- First of all , you may need to update date and time on your connected board before running the below commands. Date and Time on your connected board can be updated by this command:
date +%y%m%d -s "20250701"
date +%T -s "00:00:00"
- Refresh the apt database to access the Qt™ package repository:
apt-get update
 Information
|
| If some proxy issue occurs executing the previous command, refer to prerequisites from here |
.
- Install the package with the apt configuration to access the Qt™ packages :
CollapseFor Qt6: cd /var/cache/apt/archives wget unknown version apt-get install unknown version
ExpandFor Qt5:
- Update the apt database to read the Qt™ package repository :
apt-get update
- Install the package group for the X-LINUX-QT package
apt-get install -y packagegroup-x-linux-qt
- Restart the Weston graphical services with the new ST-Launcher
systemctl restart weston-graphical-session.service
| Information
|
| Instead of restarting the Weston graphical service which could take few seconds, user could just close the current GTK demo-launcher and start the new ST-Launcher from the weston bottom toolbar (last icon in the list) |
6.1.1.3. Starter Package expected results
Once the X-LINUX-QT Starter Package is installed and the Weston graphical service is restarted, the new STLauncher is displayed.
- The STLauncher Splash Screen is displayed for few seconds
- The Main Window displays all compatible installed applications
- To display more information about the running hardware and software:
- Click on the Settings button on the top right of the screen
- The SETTINGS screen is displayed
- Click on the INFORMATIONS button
- The INFORMATIONS screen is displayed
6.1.1.4. Run examples from the starter package
6.1.1.4.1. Legacy demonstrations
Demos, which are available via the GTK demo launcher, are still supported by the new QT STLauncher.
For example, you can run the 3D Cube Demo from the new Qt STLauncher:
- Select the demo's icon (Selected icon will be in Yellow)
- Click on the demo's icon again to run the demo
6.1.1.4.2. New Qt examples
- Qt™ OpenGL Cube example
- The Qt™ OpenGL Cube example is now displayed in the new STLauncher.
- In order to run the examples, select its icon first then click on it again to start it
- Select the Qt™ OpenGL Cube example icon (Selected icon will be in Yellow)
- Click on the demo's icon again to run the demo
6.1.1.4.3. New Qt demonstrations
The new Medical and RobotArm3D demonstrations are displayed in the new STLauncher. In order to run the demonstration, select its icon first then click on it again to start it.
- ST Medical
- ST RobotArm3D Demo
6.1.2. How to install Developer Package
6.1.2.1. Install the STM32MPU OpenSTLinux Developer Package
To download and install the STM32MPU OpenSTLinux Developer Package, you need to follow instructions from here
6.1.2.2. Install the X-LINUX-QT Developer Package
- Download and install the X-LINUX-QT Developer Package
- The X-LINUX-QT Developer Package is delivered through two tarball files named :
- en.sdk-x86_64-stm32mp2-openstlinux-6.1-yocto-mickledore-mpu-v24.06.26-x-linux-qt-v1.0.0.tar.gz for x86_64 host architecture
- en.sdk-aarch64-stm32mp2-openstlinux-6.1-yocto-mickledore-mpu-v24.06.26-x-linux-qt-v1.0.0.tar.gz for arm64 host architecture
- Download and install the X-LINUX-QT Developer Package
- The software package is provided AS IS, and by downloading it, you agree to be bound to the terms of the software license agreement (SLA0048). The detailed content licenses can be found here.
X-LINUX-QT Developer Package v2.0.0 release Download - Go on st.com to download
- en.sdk-x86_64-stm32mp2-openstlinux-6.1-yocto-mickledore-mpu-v24.06.26-x-linux-qt-v1.0.0.tar.gz file for x86_64 host architecture
- en.sdk-aarch64-stm32mp2-openstlinux-6.1-yocto-mickledore-mpu-v24.06.26-x-linux-qt-v1.0.0.tar.gz file for arm64 host architecture
Installation CollapseFor x86_64 host architecture
- Uncompress the tarball file to get the Developer Package installation script.
mkdir -p ~/MySDK tar xvf en.sdk-x86_64-stm32mp2-openstlinux-6.1-yocto-mickledore-mpu-v24.06.26-x-linux-qt-v1.0.0.tar.gz -C ~/MySDK- If needed, change the permissions on the SDK installation script so that it is executable.
chmod +x ~/MySDK/stm32mp2-openstlinux-6.1-yocto-mickledore-mpu-v24.06.26-x-linux-qt-v1.0.0/sdk/st-image-qt-openstlinux-weston-stm32mp2-x86_64-toolchain-4.2.4-openstlinux-6.1-yocto-mickledore-mpu-v24.06.26-addon-x-linux-qt-v1.0.0.sh- Run the SDK installation script.
- go to the absolute path to the directory in which you had installed your Developer Package (<Developer Package installation directory>).
- If you follow the proposition to organize the working directory, it means:
cd <working directory absolute path>/Developer-Package/SDK ~/MySDK/stm32mp2-openstlinux-6.1-yocto-mickledore-mpu-v24.06.26-x-linux-qt-v1.0.0/sdk/st-image-qt-openstlinux-weston-stm32mp2-x86_64-toolchain-4.2.4-openstlinux-6.1-yocto-mickledore-mpu-v24.06.26-addon-x-linux-qt-v1.0.0.sh- A successful installation outputs the following log:
=============================================================================================================================================== ST OpenSTLinux - Weston - (A Yocto Project Based Distro) SDK installer version 5.0.3-openstlinux-6.6-yocto-scarthgap-mpu-v24.11.06 - X-LINUX-QT version 2.0.0 SDK-Addon installer =============================================================================================================================================== Extracting X-LINUX-QT-Addon SDK................................................................................................Done. Setting it up... Done. Do you want to configure the Qt Creator for this SDK [y/n]? n Qt Creator configuration will be ignored. X-LINUX-QT-Addon SDK has been successfully set up and is ready to be used.Alternative : If you have installed preliminary the Qt Creator as explained in the "Prerequisites" chapter, you can now configure it. For that, you need to answer y to the next question
Do you want to configure the Qt Creator for this SDK [y/n]? y Please enter the directory where Qt Tools are installed (default: "/usr/lib, /usr/libexec"): /usr/libexec Using /home/USER/Qt/Tools/sdktool/libexec/qtcreator/sdktool Adding "Qt unknown package for STM32MP25 ( 5.0.3-openstlinux-6.6-yocto-scarthgap-mpu-v24.11.06, X-LINUX-QT v2.0.0)" kit for Qt Creator... Done.
X-LINUX-QT-Addon SDK has been successfully set up and is ready to be used.ExpandFor arm64 host architecture
- Go on st.com to download
- Older versions of X-LINUX-QT Developer Package can be found here.
6.1.3. How to install Distribution Package
6.1.3.1. Install the STM32MPU OpenSTLinux Distribution Package
As prerequisite to X-LINUX-QT Distribution Package, you need to get and install the STM32MPU OpenSTLinux Distribution Package v6.0.0.
The way to proceed is given in STM32MPU_Distribution_Package article.
6.1.3.2. Install X-LINUX-QT Distribution Package
To install the X-LINUX-QT Distribution Package follow the below steps
6.1.3.2.1. Clone the meta-st-x-linux-qt git repository
cd <Distribution Package installation directory>
| CollapseFor Qt6: |
|---|
git clone -b v2.0.0 https://github.com/STMicroelectronics/meta-st-x-linux-qt.git layers/meta-st/meta-st-x-linux-qt |
| ExpandFor Qt5: |
|---|
6.1.3.2.2. Clone the meta-qt git repository
| CollapseFor Qt6: |
|---|
git clone -b unknown package unknown package |
| ExpandFor Qt5: |
|---|
6.1.3.2.3. Setup the build environment
| CollapseFor Qt6: | ||
|---|---|---|
cd <Distribution Package installation directory> source layers/meta-st/scripts/envsetup.sh bitbake-layers add-layer ../unknown package ../layers/meta-st/meta-st-x-linux-qt |
| ExpandFor Qt5: |
|---|
6.1.3.3. Re-build the X-LINUX-QT Starter Package
To rebuild the X-LINUX-QT Starter Package, user must install the X-LINUX-QT Distribution Package (as explained in previous chapter), set up the environment and run the adequate bitbake command as below:
bitbake st-image-qt package-index
The output will be the "full image" files for the st-image-qt.
6.1.3.4. Re-build the X-LINUX-QT Developer Package
To rebuild the X-LINUX-QT Developer Package, user must install the X-LINUX-QT Distribution Package (as explained in previous chapter), set up the environment and run the adequate bitbake command as below:
bitbake st-image-qt -c do_populate_sdk
The output will be the full SDK installer for the st-image-qt.
7. How to create QT applications using the X-LINUX-QT Developer Package
7.1. Building QT application using CMake
7.1.1. Update the SDK environment for CMake
| Information
|
| The OE_CMAKE_TOOLCHAIN_FILE variable needs to be set to allow building CMake projects with the installed SDK |
Follow below steps if you need to add the missing OE_CMAKE_TOOLCHAIN_FILE variable to your SDK configuration
- Open terminal and load the environment setup
source /opt/st/stm32mp2/5.0.3-openstlinux-6.6-yocto-scarthgap-mpu-v24.11.06/environment-setup-cortexa35-ostl-linux
- Export the OE_CMAKE_TOOLCHAIN_FILE variable
export OE_CMAKE_TOOLCHAIN_FILE="$OECORE_NATIVE_SYSROOT/usr/lib/cmake/Qt6/qt.toolchain.cmake"
7.1.2. Download the Demo example source code
mkdir -p /opt/st/demos/Qt cd /opt/st/demos/Qt git clone https://github.com/KDABLabs/KDBoatDemo.git -b qt6
7.1.3. Build the Demo example
cd KDBoatDemo
cmake -S . -B config_default
-- Toolchain file defaulted to '/opt/st/stm32mp2/4.2.4-openstlinux-6.1-yocto-mickledore-mpu-v24.06.26_x-linux-qt_v2.0.0/sysroots/x86_64-ostl_sdk-linux/usr/lib/cmake/Qt6/qt.toolchain.cmake'
-- The C compiler identification is GNU 12.3.0
-- The CXX compiler identification is GNU 12.3.0
-- Detecting C compiler ABI info
-- Detecting C compiler ABI info - done
-- Check for working C compiler: /opt/st/stm32mp2/4.2.4-openstlinux-6.1-yocto-mickledore-mpu-v24.06.26_x-linux-qt_v2.0.0/sysroots/x86_64-ostl_sdk-linux/usr/bin/aarch64-ostl-linux/aarch64-ostl-linux-gcc - skipped
-- Detecting C compile features
-- Detecting C compile features - done
-- Detecting CXX compiler ABI info
-- Detecting CXX compiler ABI info - done
-- Check for working CXX compiler: /opt/st/stm32mp2/4.2.4-openstlinux-6.1-yocto-mickledore-mpu-v24.06.26_x-linux-qt_v2.0.0/sysroots/x86_64-ostl_sdk-linux/usr/bin/aarch64-ostl-linux/aarch64-ostl-linux-g++ - skipped
-- Detecting CXX compile features
-- Detecting CXX compile features - done
-- Performing Test CMAKE_HAVE_LIBC_PTHREAD
-- Performing Test CMAKE_HAVE_LIBC_PTHREAD - Success
-- Found Threads: TRUE
-- Performing Test HAVE_STDATOMIC
-- Performing Test HAVE_STDATOMIC - Success
-- Found WrapAtomic: TRUE
-- Performing Test HAVE_EGL
-- Performing Test HAVE_EGL - Success
-- Found EGL: /opt/st/stm32mp2/4.2.4-openstlinux-6.1-yocto-mickledore-mpu-v24.06.26_x-linux-qt_v2.0.0/sysroots/cortexa35-ostl-linux/usr/include (found version "1.5")
-- Performing Test HAVE_GLESv2
-- Performing Test HAVE_GLESv2 - Success
-- Found GLESv2: /opt/st/stm32mp2/4.2.4-openstlinux-6.1-yocto-mickledore-mpu-v24.06.26_x-linux-qt_v2.0.0/sysroots/cortexa35-ostl-linux/usr/include
-- Found XKB: /opt/st/stm32mp2/4.2.4-openstlinux-6.1-yocto-mickledore-mpu-v24.06.26_x-linux-qt_v2.0.0/sysroots/cortexa35-ostl-linux/usr/lib/libxkbcommon.so (found suitable version "1.5.0", minimum required is "0.5.0")
-- Could NOT find WrapVulkanHeaders (missing: Vulkan_INCLUDE_DIR)
-- Could NOT find WrapVulkanHeaders (missing: Vulkan_INCLUDE_DIR)
-- Configuring done
-- Generating done
-- Build files have been written to: /opt/st/demos/Qt/KDBoatDemo/config_default
cmake --build config_default --target all [ 7%] Running qmlimportscanner for KDABBoatDemo [ 7%] Built target KDABBoatDemo_qmlimportscan [ 15%] Automatic MOC for target KDABBoatDemo [ 15%] Built target KDABBoatDemo_autogen [ 23%] Automatic RCC for imagesMaps2.qrc [ 30%] Automatic RCC for data.qrc [ 38%] Automatic RCC for images.qrc [ 46%] Automatic RCC for imagesMaps.qrc [ 53%] Building CXX object CMakeFiles/KDABBoatDemo.dir/KDABBoatDemo_autogen/mocs_compilation.cpp.o [ 61%] Building CXX object CMakeFiles/KDABBoatDemo.dir/main.cpp.o [ 69%] Building CXX object CMakeFiles/KDABBoatDemo.dir/KDABBoatDemo_autogen/EWIEGA46WW/qrc_imagesMaps.cpp.o [ 76%] Building CXX object CMakeFiles/KDABBoatDemo.dir/KDABBoatDemo_autogen/EWIEGA46WW/qrc_imagesMaps2.cpp.o [ 84%] Building CXX object CMakeFiles/KDABBoatDemo.dir/KDABBoatDemo_autogen/EWIEGA46WW/qrc_images.cpp.o [ 92%] Building CXX object CMakeFiles/KDABBoatDemo.dir/KDABBoatDemo_autogen/EWIEGA46WW/qrc_data.cpp.o [100%] Linking CXX executable KDABBoatDemo [100%] Built target KDABBoatDemo
7.1.4. Deploy the Demo example to your running board
- Copy the Example's binary into your connected board
cd /opt/st/demos/Qt
scp config_default/KDABBoatDemo root@192.168.7.1:/home/root/.
7.1.5. Run the Demo example on your board
- Connect to your running board
ssh root@192.168.7.1
- Run the Demo's example (windowed mode)
./KDABBoatDemo
- Check the running Demo example on your board's display
- Run the Demo's example (Full screen mode)
./KDABBoatDemo --fullscreen
- Check the running Demo example on your board's display
7.2. Building QT application using STM32CubeIDE
7.2.1. Update the SDK environment for CMake
| Information
|
| The OE_CMAKE_TOOLCHAIN_FILE variable needs to be set to allow building CMake projects with the installed SDK |
Please follow below steps if you need to add the missing OE_CMAKE_TOOLCHAIN_FILE variable to your SDK configuration
- Open terminal and load the environment setup
source /opt/st/stm32mp2/5.0.3-openstlinux-6.6-yocto-scarthgap-mpu-v24.11.06/environment-setup-cortexa35-ostl-linux
- Add the missing OE_CMAKE_TOOLCHAIN_FILE variable to the qt6 environment file
echo "export OE_CMAKE_TOOLCHAIN_FILE=\"\$OECORE_NATIVE_SYSROOT/usr/lib/cmake/Qt6/qt.toolchain.cmake\"" >> $OECORE_NATIVE_SYSROOT/environment-setup.d/qt6.sh
7.2.2. Install the STM32CubeIDE
- Please follow instructions from here to know how to install and use the STM32CubeIDE.
7.2.3. Select the updated OpenSTLinux SDK by the X-LINUX-QT Developer Package
- Please follow instructions from here to know how to install the STM32MPU OpenSTLinux Developper Package for the STM32CubeIDE.
- Please select the updated STM32MPU OpenSTLinux Developper Package by the X-LINUX-QT Developer Package.
7.2.4. Download the Demo example source code
mkdir -p /opt/st/demos/Qt cd /opt/st/demos/Qt git clone https://github.com/KDABLabs/KDBoatDemo.git -b qt6
7.2.5. Build the Demo example
- Import the Project from STM32CubeIDE
- Start a new STM32 CMake Project
- Select Project with existing CMake sources
- Fill the Project name and source directory
- Project name = KDBoatDemo
- Source directory = /opt/st/demos/Qt/KDBoatDemo
- Configure default toolchain
- Select OpenSTLinux SDK for the Toolchain field
- Select your installed OpenSTLinux SDK (openstlinux-6.1-yocto-mickledore-mpu-v24.06.26) for the Version field
- Build the Project
- Select the project from the list and press the Build button
- Wait until the build is finished and make sure it is done successfully
7.2.6. Deploy the Demo example to your running board
- Copy the Example's binary into your connected board
cd /opt/st/demos/Qt
scp config_default/KDABBoatDemo root@192.168.7.1:/home/root/.
7.2.7. Run the Demo example on your board
- Connect to your running board
ssh root@192.168.7.1
- Run the Demo's example (windowed mode)
./KDABBoatDemo
- Check the running Demo example on your board's display
- Run the Demo's example (Full screen mode)
./KDABBoatDemo --fullscreen
- Check the running Demo example on your board's display
7.3. Building Qt applications using Qt Creator
The Qt™ Creator[2] tool is used to build, debug and run applications demos on target.
7.3.1. Install the Qt Creator
- The Qt™ Creator can be downloaded and installed following this link
- The Qt™ online installer can be dowloaded cliking on this link
- Installing the X-LINUX-QT Developer Package configures also the new STM32MPU Kit for the already installed Qt™ Creator IDE.
7.3.2. Select the new Kit installed by the X-LINUX-QT Developer Package
| Information
|
| Qt6 unknown package must be installed in order to have the list of Examples for that Qt version. |
Once the Qt™ Creator is launched and the Welcome to Qt™ Creator is displayed:
- Go to the Examples from the list on the left ,
- Then select the new Qt6 unknown package from the dropdown list.
The supported examples are then displayed.
7.3.3. Select the project example
- You may search for a specific example in the Search bar in front of the selected Kit
- Select the example you are looking for (just a simple click on it)
- Close the Help window if not needed
7.3.4. Configure the project example
- Make sure the new added Kit by X-LINUX-QT Developer Package is selected
- Press the Configure Project button
- Make sure all configuration steps are successfully done (Green Bars)
7.3.5. Configure the STM32 MPU Kit
- Select the Configure Project button from the vertical bar on the left
- Select the new Kit added by the X-LINUX-QT Developer Package
- Select Run Settings
- On the right panel, scroll down till the Environment section
- Press the Details button
- Add the below environment variables
XDG_RUNTIME_DIR=/run/user/1000
QT_QPA_PLATFORM=wayland
QT_VULKAN_LIB=/usr/lib/libvulkan.so.1
7.3.6. Build and run the project
- Make sure your board is connected to your host machine via the USB DRD TypeC connector.
- Follow instructions from the Hardware setup section and check how to get your board connected to your host machine.
- Once in the Run Setting panel, you shouldn't have the below notice at the bottom of the screen.
- Press the Run button from the vertical bar on the left
- That will build, deploy and run the selected example on the connected board.
- If everything went well, then the example will be running on the connected board.
8. References