How to Set Up STM32MP1 with qt: Part 1

This tutorial is meant to show how to set up the st-example-image-qt with STM32MP157c-DK2. How to set up STM32MP1 with qt: Part 2 explains how to set up cross compilation and deploy qt projects to your embedded device using qtcreator.

The st-example-image-qt image is not officially supported by ST and therefore has some bugs and needed some work arounds to get fully setup. My hope is to create the most comprehensive guide that outlines all the tips, tricks and workarounds to get this image up and running. All links to various references that helped me put this together are listed at the bottom of the article.

NOTE: The most up to date version of this content has been updated on my personal blog: https://barenakedembedded.com/how-to-set-up-stm32mp1-with-qt/

Prerequisites:

I used virtual machine running Ubuntu 18.04 with 5.5GB of RAM allocated, 85GB of storage and 3.5GB of swap memory allocated. You will likely need close to 50GB of free space and will need your RAM/memory allocation to look very similar to mine (~8GB) at a minimum. With these specs, the image build took upwards of 15 hours.

First, the Starter Package will need to be installed on the board. This is to prove that your board boots correctly, populates all the Flash Partitions that you will also use for the Distribution Package and introduces you to the STM32CubeProgrammer tool. If you do not have the Starter Package installed, follow this article: Getting Started with STM32MP157c-DK2.

Second run the following commands in your host computer terminal to install a couple of support packages that Yocto and OpenEmbedded need.

pc $> sudo apt-get udpate
pc $> sudo apt-get install gawk wget git-core diffstat unzip textinfo gcc-multilib build-essential chrpath socat cpio python python3 python3-pip python3-pexpect xz-utils debianutils iputils-ping
pc $> sudo apt-get install libsdll.2-dev xterm
pc $> sudo apt-get install make xsltproc docbook-utils fop dblatex xmlto
pc $> sudo apt-get install python-git
pc $> sudo apt-get install repo
pc $> sudo apt-get install coreutils bsdmainutils sed bc lrzsz corkscrew cvs subversion mercurial nfs-common nfs-kernel-server libarchive-zip-perl dos2unix texti2html diffstat libxml2-utils

Step 1 — Initialize Repo:

If you are following the ST recommended file system organization (which I recommend just to make it easier to follow their tutorials so you know your in the right folders) create the following directory where you would like to install the Distribution package at:

pc $> cd STM32MPU_workspace/STM32MP15-Ecosystem-v1.2.0
pc $> mkdir Distribution-package
pc $> cd Distribution-package
pc $> mkdir openstlinux-4.19-thud-mp1-19-02-20
pc $> cd openstlinux-4.19-thud-mp1-19-02-20

Now initialize the repo in the newly created directory.

pc $> repo init -u https://github.com/STMicroelectronics/oe-manifest.git -b refs/tags/openstlinux-4.19-thud-mp1-19-02-20
pc $> repo sync

You might see a couple warnings when running the sync but it should be fine as long as you have the repo tool installed from the prerequisites section.

Step 2 — Modifying Yocto Files:

There are a couple Yocto files we are going to edit in order to remove some problem packages that we don’t need and to add some qt eglfs configurations to a script so that we don't have to manually set them every time we want to run an application on our target board.

while in the “openstlinux-4.19-thud-mp1–19–02–20” directory, navigate to the following directory.

pc $> cd layers/meta-st/meta-st-stm32mp/conf/machine/include

Open the following file using whatever editor you prefer (such as nano or vim).

pc $> nano st-machine-common-stm32mp.inc

Remove lines 141, 149 and 150

openocd-stm32mp-native \
nativesdk-openocd-stm32mp \
nativesdk-sdcard-raw-tools \

Save the file and exit your editor. Next, from the “openstlinux-4.19-thud-mp1–19–02–20” directory, navigate to the following directory and open the following file.

pc $> cd layers/meta-st/meta-st-openstlinux/recipes-qt/qt5/files
pc $> nano qt-eglfs.sh

Add then following two lines to the file after “export QT_QPA_PLATFORM=eglfs”.

export QT_QPA_EGLFS_ALWAYS_SET_MODE="1"
export QT_QPA_EGLFS_INTEGRATION="eglfs_kms"

Lastly, we need to fix a bug related to the rootfs size for the image. The default weston image only needs 786MB for the rootfs partition but the qt image needs 1.1GB so we need to update this. Navigate to the following directory and open the following file using whatever editor you like.

pc $> cd layers/meta-st/conf/machine/include
pc $> nano st-machine-common-stm32mp.inc

Under the Image section, change the following lines:

# New value proposed for rootfs is 768MB
ROOTFS_PARTITION_SIZE = “768432”

To

ROOTFS_PARTITION_SIZE = “1400000”

Step 3 — Build Image:

Now we are ready to start the image build process. As stated earlier, make sure you have close to 8GB of memory (RAM + swap file or partition), about 50GB of storage and 10–15 hours to spare not using your computer. Make sure your computer is plugged into power and has good fan ventilation.

Navigate back to the “openstlinux-4.19-thud-mp1–19–02–20” directory and run the following command and accept any necessary agreements.

pc $> DISTRO=openstlinux-eglfs MACHINE=stm32mp1 source layers/meta-st/scripts/envsetup.sh

This will set up bitbake and automatically move you into a new sub directory called “build-openstlinuxeglfs-stm32mp1”. Now before building the actual image there are a few things to go over. There are a couple of packages that are large and take a lot of memory, specifically the qtwebkit package. In order to get through the build it may be necessary to use the -k option with bitbake (which continues to build the image, even if a package fails), increase your RAM or swap size if possible and re-run bitbake command multiple times. I recommend starting off using the -k option with bitbake just so you do not have to babysit the build and it will continue to run if a certain package fails. Execute the following command:

pc $> bitbake -k st-example-image-qt

NOTE: If you for some reason have to manually stop the build, press “control+c” and let the current process finish running (which could take ten minutes or more). This will save your build state and you won’t have to re-run the whole thing. Do not keep pressing “control+c” or you will corrupt the build and have to start from scratch.

What to do if the build failed:

It is okay to have warnings when the build completes but we do not want any errors. Don’t worry if the build gives errors and is incomplete at this stage. The next time you re-run the bitbake command, it will only have to build the packages that failed which should free up some memory. First try running the same bitbake -k command again. If that does not work, try running the qtwebkit package by itself with the following command:

pc $> bitbake qtwebkit

If this does not work, try adding more swap memory to your swap file or swap partition (which I had to do and needed about 3.5GB of swap memory + 5.5GB of allocated RAM). See References section for links on how to increase swap file or partition size. Lastly, if that does not work (it should if you make your swap file large enough) then you can try following additional steps outlined in this article, Yocto+QT5/B2QT build fails. Also note that if you run out of storage when running this commands multiple times then you can free up some space by navigating to the following directory and deleting the tmp-glibc directory before re-running.

pc $> cd ~/STM32MPU_workspace/STM32MP15-Ecosystem-v1.2.0/Distobution-package/openstlinux-4.19-thud-mp1-19-02-20/build-openstlinuxeglfs-stm32mp1
pc $> rm -rfv tmp-glibc

Step 4 — Flashing the Image:

One the build completes with no errors, the STM32CubeProgrammer tool is used to flash the image to the board. The STM32CubeProgrammer should have been installed when setting up the Starter Package.

First, verify that the image was created by navigating to the following directory:

pc $> cd STM32MPU_workspace/STM32MP15-Ecosystem-v1.2.0/Distribution-package/openstlinux-4.19-thud-mp1-19-02-20/build-openstlinuxeglfs-stm32mp1/tmp-glibc/deploy/images/stm32m1/flashlayout_st-example-image-st/flashlayout_st-example-image-qt

Verify that the following file exists in this directory:

FlashLayout_sdcard_stm32mp157c-dk2-trusted.tsv

If this file exists then your image was built and we are ready to upload it to the board. If the ST recommended file system organization was used to set up the Starter Package then the STM32CubeProgrammer should be installed in the following location:

~/STM32MPU_workspace/STM32MPU-Tools/STM32CubeProgrammer-x.y.z/bin/STM32_Programmer_CLI

Before we flash the image, the two dip switches on the back of the board need to be switched to the “off” position to enable flashing.

Plug the board’s “USB” port into the computer and power the board on. Navigate back to the image folder and use the following command in order to flash the image to the board. This will take about five minutes to complete and you might have to run the command twice as the board tries to reboot and loses connection the first time.

pc $> cd STM32MPU_workspace/STM32MP15-Ecosystem-v1.2.0/Distribution-package/openstlinux-4.19-thud-mp1-19-02-20/build-openstlinuxeglfs-stm32mp1/tmp-glibc/deploy/images/stm32m1
pc $> sudo ~/STM32MPU_workspace/STM32MPU-Tools/STM32CubeProgrammer-x.y.z/bin/STM32_Programmer_CLI -c port=usb1 -w flashlayout_st-example-image-qt/FlashLayout_sdcard_stm32mp157c-dk2-trusted.tsv

NOTE: If the flash fails and you get a “Request would exceed designated area!” message on the board’s DSI display, then make sure you completed the last section of Step 2.

NOTE: You can add the CubeProgrammer to your PATH and not have to reference the whole path each time you run the command but I could not get it to work for some reason so just used the full path instead of wasting more time troublshooting.

Power off your board and move the dip switches on the back to the “on” position. Plug your board back into power and you should see the STM32 boot screen appear after a few seconds. A few seconds later you should see the STM32 splash screen appear. I had issues trying to ssh into the board via ethernet directly from the board to my computer but if I plugged the board into my router then used ssh it worked fine. See the References section for details on how to ssh into the board.

Step 5 — Finished!:

The st-example-image-qt should be fully installed on your board! To run a qt example, ssh into your board and execute the following commands to turn off the backsplash image, navigate to the examples directory and run an example on the board.

root@stm32mp1 $> psplash-drm-quit
root@stm32mp1 $> cd /usr/share/examples/opengl/hellowindow
root@stm32mp1 $> ./hellowindow

Check out “How to set up STM32MP1 with qt: Part 2” to setup the qt tool chain, qtcreator and enable cross compilation in order to deploy qt projects directly to your board from your Linux host computer.

References:

Main tutorials that were followed:

• Flashing the built image on the STM32MP157x-DKx Discovery kit
• https://wiki.st.com/stm32mpu/index.php/STM32MP1_Distribution_Package
• https://www.emsyslabs.com/how-to-compile-linux-using-yocto-for-stm32mp1/

Helpful ST Help Forums:

• https://community.st.com/s/topic/0TO0X000000y2iTWAQ/qt
• https://community.st.com/s/question/0D50X0000B7Ykl5SQC/getting-failure-while-compiling-qtwebkit-for-yocto
• https://community.st.com/s/question/0D50X0000AiyOgrSQE/stexampleimageqt-qt-examples-extremely-slow

How to increase the size of a swap file:

• https://askubuntu.com/questions/1075505/how-do-i-increase-swapfile-in-ubuntu-18-04

How to increase the size of a swap partition:

• https://askubuntu.com/questions/178712/how-to-increase-swap-space

Troublshooting bitbake failures due to qtwebkit:

• https://medium.com/hi-z-labs/yocto-qt5-b2qt-build-fails-on-qtlocation-or-qtwebengine-with-cryptic-gcc-error-1051a7effe3a