This is a text-only version of the following page on https://raymii.org: --- Title : Yocto boot2qt for the Seeed reTerminal (Qt 6) Author : Remy van Elst Date : 18-03-2022 Last update : 04-04-2022 URL : https://raymii.org/s/tutorials/Yocto_boot2qt_for_the_Seeed_reTerminal_qt6.html Format : Markdown/HTML --- In this guide we'll build a linux distribution for Seeed reTerminal, using the Yocto project and the `boot2qt` stack provided by Qt. This `boot2qt` image can be written to the internal eMMC and when booted up, the Seeed reTerminal runs a software stack that integrates nicely with Qt Creator (the Qt IDE), for example, one click deployment to the device. You can run your own Qt application on the reTerminal, full screen, it will boot right into it. This guide covers Qt 6.2. The guide also covers changing the default startup app to your own app, Qt Creator integration and rotating your Qt app, both Widgets and QML, the latter via Wayland and Weston. The main difference between the guide that [Seeed provides][1] and this guide is that this guide uses Qt's own boot2qt Yocto stack and runs Qt 6. The Seeed guide covers their own image and Qt 5. This guide also shows you how to make your own Qt app the default and helps you with rotation. Running your own Yocto distribution over the default Debian image provided by Seeed has the advantage that it's reproducible and you are fully in control. Using the `boot2qt` Yocto stack makes the Yocto setup process way easier and faster. By using your own image, no other application run on the device, so all resources are available for your app. (No desktop environment or other software, unless you built it in the image.) This also assures you that in the future, lets say as an example, 5 years later, you can still build your image and software, since your Yocto build server has all the sources locally. Full disclosure: I was contacted by Seeed, they sent me this reTerminal in exchange for a few articles, this one being the first. No monetary payment is involved and Seeed has not reviewed this article before publishing. For official support, please visit the [Seeed wiki][2]. Seeed actually sent me 2 reTerminal units. The first one had a stuck boot-mode switch. It wouldn't move, and later broke off. The boot mode switch is required to flash an image, which is quite essential for this Yocto guide. I contacted them and a replacement unit was sent quickly. So, be careful with your boot mode switch. I now use a pair of tweezers to switch it, just to be extra cautious. Article changelog: - 04-04-2022: Fixed paths in shell commands - 04-04-2022: Fixed syntax in some recipe files including missing slashes - 04-04-2022: Added note regarding the `seeed-linux-dtoverlays` on commit `7c846e23de9346d318fbdc8ac92dcc72b90fb6ce` - Thanks to Ryan Bryngelson for the above issues and fixes! ### What is the reTerminal ![reTerminal][3] > The reTerminal The reTerminal is marketed as a future-ready Human-Machine Interface (HMI). The reTerminal is powered by a Raspberry Pi Compute Module 4 (cm4) which is a Quad-Core ARM Cortex-A72 CPU running at 1.5GHz and a 5-inch IPS capacitive multi-touch screen with a resolution of 1280x720. 4GB of RAM and 32 GB of eMMC storage are built in (non-expandable). It has wireless connectivity with dual-band 2.4GHz/5GHz Wi-Fi and Bluetooth 5.0 BLE. The reTerminal has a high-speed expansion interface and exposes many I/O ports and connectors. The device has security features such as a cryptographic co-processor with secure hardware-based key storage. It also has built-in modules such as an accelerometer, light sensor and a Real-Time Clock. reTerminal has a Gigabit Ethernet Port for faster network connections and also has dual USB 2.0 Type-A ports. The 40-pin Raspberry Pi compatible GPIO header allows most or all of your hat's and existing projects to work with the reTerminal. **You can [buy the reTerminal here, current price is USD 195][9].** That includes a Compute Module 4. ![reterminal hardware][4] > External hardware overview of the reTerminal. Notice the many mounting holes and nuts ![reterminal carrier board][5] > Carrier board including the Compute Module 4 You could bluntly say that the reTerminal is a carrier board for the Compute Module 4 with a multi-touch screen and a convenient case. In my opinion, it's much more than that. It does lack a built-in battery at the time of writing this article. You power it via a USB-C cable or by supplying 5V and ground to the correct GPIO pins. Behind a little cover pad is a high-speed interface, on the picture above it's labeled `Industrial High Speed Interface`. In the [FAQ][6] they write the following: > The High-Speed Interface for Expansion Modules consists of 1 PCIe 1-lane Host Gen 2 (supporting speeds up to 5Gbps), 1 USB 2.0, 1 PoE and 26 GPIOs. The 26 GPIO pins can be further used as 2 I2C, 2 SPI and 1 UART. We plan to build expansion modules in the future for reTerminal and we have reserved this interface to connect these modules to the reTerminal. We will release a wide range of modules such as a Mic Array & Speaker Module, Camera Module, Industrial I/O, LoraWAN Module, 5G/4G Module, PoE Module and an Ethernet Switch. There are 2xM4 mechanical screw holes on the side of the reTerminal to help keep the expansion modules in place. So, hardware wise, the reTerminal is solid and future proof. If you buy one, it comes pre-loaded with a Compute Module and Raspbian including drivers plus a demo application, so you can get started right away. No messy supply chain issues here, only a bit of waiting on shipping a package from China. ### What is Yocto There is a lot of ground to cover, if you are not familiar with the Yocto project, here is a quick, _simplified_, overview of all the terms. **Seeed have their own [FAQ on Yocto for the reTerminal here][1]**. That FAQ covers the basics and has tips and tricks for using Yocto. I recommend you read that guide as well, since it explains different parts. My guide is tailored to (boot 2) Qt on the reTerminal. Yocto is an open-source project which provides a build framework and metadata to help to create a custom image for your target board. Yocto uses so-called (meta) layers and recipes. Recipes are `.bb` (for bitbake) files that contain build instructions and layers are a collection of specific recipes, classes and configuration files. You could have a layer named `meta-raspberry` (all layers, by convention, start with `meta-`) that has recipes applicable only for the Raspberry Pi. Yocto helps you to build a linux distro, their reference distro is named `poky`. The primary build tool is a python command line tool named `bitbake`. It parses all the recipes and then, one by one, gathers the source code and compiles all the software, then packages that up into an image for your board. Yocto is aimed at embedded linux devices, at work we use it to create our own Linux distribution (not `boot2qt`) to run on the coffee machines. Many different boards are supported, most vendors provide a so called board support package (bsp). Often this contains a kernel and drivers for your board. There is a board support package for the Raspberry Pi, which we will use. `boot2qt` is an set of layers for Yocto which builds a simple linux system that starts up without a desktop, right into a Qt application. It also builds a cross-compile SDK for your desktop, which you can use in Qt Creator to cross-compile your application for the target device. Often the device you develop for does not have the same CPU architecture as your desktop workstation. To top this all up, it also integrates into Qt Creator, allowing you to one-click deploy and run your application, via the network, on your device. `boot2qt` also provides a set of scripts to make the `yocto` setup very easy, so the process you see in this guide is not the same as a default `yocto` setup. It's specifically for `boot2qt` and for the reTerminal. So to summarize, `boot2qt` provides a layer on top of yocto that adds integration between your embedded linux device and the Qt suite of tools, saving a boatload of time doing manual busywork. ### Development host Yocto setup The machine that is going to build your `boot2qt` image (the host that runs `bitbake`) needs a few packages before we can get started building. You need at least 50 GB's of free space, but my host has 300 GB. Cross-compiling all the packages takes a huge amount of time, so the more cores and RAM you have, the better. My test build machine has 4 cores and 8 GB of RAM, the entire image build took more than 2 days. At work we have a few beefy servers, there the build takes about 2 hours. Yocto does support incremental builds, so if you change one recipe, only that part has to be rebuilt, not all the other parts. My build machine runs Debian 11, but Ubuntu 20.04 is also known to work. Install the required packages first: apt-get install gawk wget git diffstat unzip texinfo gcc build-essential chrpath socat cpio python3 python3-pip python3-pexpect xz-utils debianutils iputils-ping python3-git python3-jinja2 libegl1-mesa libsdl1.2-dev pylint3 xterm python3-subunit mesa-common-dev python git-lfs g++-multilib gcc-multilib libxkbcommon-dev libxkbcommon-x11-dev libwayland-cursor++0 libwayland-cursor0 These are a bit more packages than the Qt site recommends, I had build issues when building the `qbsp` layer, which is where most of the extra packages come from. #### Google Repo Next you need `repo`, a git management tool [by Google][7]. It hides most of the complexity of submodules and different repo's by putting all of that extra information in a manifest file. You can install it using apt: apt install repo If it's not in the repository, check the [instructions][7], installation process is just a simple copy of one executable. #### Initial boot2qt setup Create a folder where all of yocto will reside: mkdir b2qt cd b2qt Use the `repo` tool to clone all the git repositories of the Yocto project and `boot2qt` at once. First initialize for the correct Qt version: # for Qt 6.2: repo init -u git://code.qt.io/yocto/boot2qt-manifest -m v6.2.3.xml Then sync the repositories: repo sync You must tell which board you want to build for, then source a script: export MACHINE=raspberrypi4-64 && source ./setup-environment.sh **This step must be repeated on every login**. Notice that we specify `raspberrypi-64`. This is because the reTerminal uses a Raspberry Pi Compute Module 4. The `meta-raspberry` layer uses that name for both the regular Pi 4 and the Compute module. The Yocto layer from Seeed has a specific board for the reTerminal since 3 days (at the time of writing), but boot2qt has no support for that, so in this guide we'll port the specific requirements over to our build image. Output: ### Shell environment set up for builds. ### You can now run 'bitbake ' Common targets are: b2qt-embedded-qt6-image meta-toolchain-b2qt-embedded-qt6-sdk QBSP target is: meta-b2qt-embedded-qbsp For creating toolchain or QBSP for Windows, set environment variable before running bitbake: SDKMACHINE=x86_64-mingw32 For more information about Boot to Qt, see https://doc.qt.io/QtForDeviceCreation/ You should now be in a folder named `build-raspberrypi4-64`. Using the `repo` tool and sourcing this script has made a nifty folder structure for yocto: * `build-raspberrypi4-64`: build directory for the board, you are in this folder after sourcing the `setup-environment.sh` file. * `sources`: has all the `bitbake` layers and recipes * `download`: folder where all the source code is downloaded (git repo's, tar.gz archives) In the `build-*` directory there is a `conf` folder, that has two important files. `bblayers.conf` and `local.conf`. The first defines the layers that your build uses and the second has specific configuration options for this specific build. We'll start by adding the reTerminal layer, the config file is covered later. #### Adding the Seeed reTerminal layer We need the reTerminal layer for the device tree and a few drivers. cd ../sources git clone -b main https://github.com/Seeed-Studio/meta-seeed-reterminal.git I've tested this guide with commit `7c846e23de9346d318fbdc8ac92dcc72b90fb6ce` and with commit `57d1b68d73e625fe6a4cb14372a0cb7c42bae9c5`. If the `seeed-linux-dtoverlays` package gives a linker error like below: | aarch64-poky-linux-ld: internal error in set_address, at ../../gold/output.h:322 Then, remove the `ld-is-gold` option that the `boot2qt` `distro.conf` file enabled, as we do in our local config later on: DISTRO_FEATURES_remove = "ld-is-gold" I've made an upstream [bug report][12] for it. If you use commit `7c846e23de9346d318fbdc8ac92dcc72b90fb6ce`, the error will not appear. You must add the Yocto version that `boot2qt` uses to the layer configuration. Edit the following file: vi meta-seeed-reterminal/conf/layer.conf Add `hardknott` to the `LAYERSERIES_COMPAT` line: LAYERSERIES_COMPAT_meta-reterminal = "honister hardknott" Save and close. Change to our build folder: cd ../build-raspberrypi4-64 Add the layer to our config: bitbake-layers add-layer ../sources/meta-seeed-reterminal #### Making our own layer for b2qt image overrides To override a few parts of the default `b2qt-embedded-qt6-image`, we must make our own layer. This layer will include more customization later on, but for the initial build, we'll only override parts of the image. Why do we not just overwrite the contents of the original file? By using a `.bbappend` file, we can keep our changes separated, so we know later on what our specific changes are. It also makes it easier to apply upstream changes. Start by making a few folders for your layer, in the `b2qt` folder: mkdir -p sources/meta-raymii/conf/ mkdir -p sources/meta-raymii/recipes-qt/images/ Edit the following file: sources/meta-raymii/conf/layer.conf Place the below contents: BBPATH .= ":${LAYERDIR}" BBFILES += "${LAYERDIR}/recipes*/*/*.bb \ ${LAYERDIR}/recipes*/*/*.bbappend \ " BBFILE_COLLECTIONS += "raymii" BBFILE_PATTERN_raymii := "^${LAYERDIR}/" BBFILE_PRIORITY_raymii = "1" LAYERSERIES_COMPAT_raymii = "thud zeus dunfell gatesgarth hardknott" Add our layer to the Yocto build for the reTerminal: cd build-raspberrypi4-64 bitbake-layers add-layer ../sources/meta-raymii Now on to the changes to the default `boot2qt` image. The following file is a `.bbappend` file, which, if it has the same name, path and version, will, as you might expect, append stuff to the original. In this case, we will extend the default `b2qt-embedded-qt6-image` image to include our `myapp` recipe in the installation. Edit this file: vi sources/meta-raymii/recipes-qt/images/b2qt-embedded-qt6-image.bbappend Add the following: SUMMARY = "reTerminal changes for Qt image" SPLASH = "psplash-raspberrypi" IMAGE_FEATURES_append = " \ splash \ " IMAGE_INSTALL_append = " \ kernel-modules \ evtest \ iperf3 \ i2c-tools \ util-linux \ " The changes, as you can see, are related to the reTerminal image. Later on we'll add our application here, but for now this is just the essentials to make a bootable image. #### Tweaking our `local.conf` for the reTerminal We need to add a few variables to the local config file (`conf/local.conf`). All of these have to do with the reTerminal hardware, except for one, the removal of `webengine`. If your Qt app uses webengine, leave it in, otherwise, remove it. Not including it saves you a bunch of time compiling and the image is smaller. The reTerminal related features are pulled from the official layer, but tweaked for `boot2qt`. You can see the [backport here][8], quite a recent addition to the reTerminal Yocto layer, 3 days ago when writing this article. The difference between `local.conf` and the `b2qt-embedded-qt6-image.bbappend` is that `local.conf` is for this device only. In my case I also have a `raspberrypi4` machine build folder for [the compute module 4][13]. You could also create your own `distro.conf` or define a new device with machine specific overrides, but for this article, `local.conf` is simple enough. Edit the following file: # in the folder: build-raspberrypi4-64 vi conf/local.conf Add the following: RPI_KERNEL_DEVICETREE_OVERLAYS_append = " overlays/reTerminal.dtbo overlays/i2c3.dtbo overlays/vc4-kms-v3d-pi4.dtbo" ENABLE_UART = "1" ENABLE_I2C = "1" KERNEL_MODULE_AUTOLOAD_rpi += "i2c-dev" MACHINE_EXTRA_RRECOMMENDS += "\ seeed-linux-dtoverlays \ " VC4DTBO ?= "vc4-kms-v3d" PACKAGECONFIG_append_pn-qtbase = " eglfs " DISTRO_FEATURES_remove = "webengine ld-is-gold" PREFERRED_VERSION_linux-raspberrypi ?= "5.10.%" You're all set up for the initial build of `boot2qt`. I recommend you start a `screen` or `tmux` session as the build will take a long time. My initial build on the hardware described earlier took more than 2 days. If you use commit `7c846e23de9346d318fbdc8ac92dcc72b90fb6ce`, you do not need to add the `MACHINE_EXTRA_RRECOMMENDS += "seeed-linux-dtoverlays"`. The device tree overlays [are a patch][31] in that commit, later on they became a git submodule. ### Bitbaking the image With `boot2qt` and the reTerminal hardware layer setup, we can do our initial build. Make sure you have `source`-ed the script and are in the correct folder: cd ~/b2qt export MACHINE=raspberrypi4-64 && source ./setup-environment.sh Start the image build: bitbake b2qt-embedded-qt6-image The output will vary. First it lists all your layers and config, at the bottom it shows the current task. Example output: WARNING: Host distribution "debian-11" has not been validated with this version of the build system; you may possibly experience unexpected failures. It is recommended that you use a tested distribution. Loading cache: 100% |################################################################################################| Time: 0:00:00 Loaded 4374 entries from dependency cache. Parsing recipes: 100% |##############################################################################################| Time: 0:00:00 Parsing of 2813 .bb files complete (2809 cached, 4 parsed). 4377 targets, 611 skipped, 0 masked, 0 errors. NOTE: Resolving any missing task queue dependencies Build Configuration: BB_VERSION = "1.50.0" BUILD_SYS = "x86_64-linux" NATIVELSBSTRING = "universal" TARGET_SYS = "aarch64-poky-linux" MACHINE = "raspberrypi4-64" DISTRO = "b2qt" DISTRO_VERSION = "3.3.4" TUNE_FEATURES = "aarch64 armv8a crc crypto cortexa72" TARGET_FPU = "" SDKMACHINE = "x86_64" meta meta-poky = "HEAD:c40ac16d79026169639f47be76a3f7b9d8b5178e" meta-raspberrypi = "HEAD:b4ec97e4eb8e36efd1f7e2f8ae020a9e55cfc239" meta-oe meta-python meta-networking meta-initramfs meta-multimedia = "HEAD:f72a73b42fa740130b388ba8555cdbefdee8d37d" meta-python2 = "HEAD:810d6d842f103eb59f18b06426106462b15de7e2" meta-boot2qt meta-boot2qt-distro = "HEAD:e59a2e20697e0afc2a0b068835cd90e102dec589" meta-mingw = "HEAD:422b96cb2b6116442be1f40dfb5bd77447d1219e" meta-qt6 = "HEAD:eb3719266fc03b96d5056980b135b371f31811f4" meta-seeed-reterminal = "main:57d1b68d73e625fe6a4cb14372a0cb7c42bae9c5" meta-raymii = "master:84123f093be34a9a4d73de545132cffc3e210c19" Initialising tasks: 100% |###########################################################################################| Time: 0:00:10 Sstate summary: Wanted 1706 Local 49 Network 0 Missed 1657 Current 1441 (2% match, 47% complete) Removing 375 stale sstate objects for arch raspberrypi4_64: 100% |#################################################| Time: 0:00:02 Removing 6 stale sstate objects for arch allarch: 100% |###########################################################| Time: 0:00:00 Removing 956 stale sstate objects for arch cortexa72: 100% |#######################################################| Time: 0:00:02 NOTE: Executing Tasks Currently 8 running tasks (2488 of 9043) 27% |###################### | 0: libunistring-0.9.10-r0 do_configure - 27s (pid 1946515) 1: libpciaccess-0.16-r0 do_configure - 22s (pid 1949317) 2: icu-68.2-r0 do_compile - 15s (pid 1959678) 3: libpam-1.5.1-r0 do_compile - 15s (pid 1959794) 4: tslib-1.22-r0 do_configure - 13s (pid 1961800) 5: nettle-3.7.3-r0 do_configure - 10s (pid 1963210) 6: libpcre2-10.36-r0 do_configure - 8s (pid 1963889) 7: libogg-1.3.4-r0 do_configure - 5s (pid 1964770) Now is a great time to go do something else and return in a few days. If you have a beefy machine, the build will be faster, but it will still take a while. Once the build is done, the image is located in the folder: build-raspberrypi4-64/tmp/deploy/images/raspberrypi4-64/ The image is a `bmap` file. `bmap` is a special format which should be faster to flash and verifies data during flash, initially created by Intel for their Tizen project. If you run Ubuntu, you must install the `bmap-tools` package. #### Flashing the image Because the reTerminal has a Compute Module 4 with eMMC, the SD card slot won't work. You must flash the image to the eMMC, using a tool provided by the Raspberry Pi. This tool is named `rpiboot`, which you must build yourself. Start by installing a dependency: sudo apt install git libusb-1.0-0-dev Next, clone the repo git clone --depth=1 https://github.com/raspberrypi/usbboot cd usbboot Start the build process: make The above steps are one time only. You now have the `rpiboot` tool in this folder. Every time you flash an image, you must repeat the below process. [Flip the boot mode switch][10]. Be very careful, my first unit had a stuck boot mode switch. I use a pair of tweezers to carefully flip the tiny switch. ![boot mode switch][11] While you're playing around with the reTerminal and constantly flashing images, I recommend to leave the device open, not screw back the cooling or the plastic cover. This way the boot switch is easily accessible. My device did get a bit hot, but not extremely. Plug in the USB C cable and run the `rpiboot` utility as root: $ sudo ./rpiboot RPIBOOT: build-date Feb 22 2022 version 20220208~181027 042cd145 Waiting for BCM2835/6/7/2711... Loading embedded: bootcode4.bin Sending bootcode.bin Successful read 4 bytes Waiting for BCM2835/6/7/2711... Loading embedded: bootcode4.bin Second stage boot server Loading embedded: start4.elf File read: start4.elf Second stage boot server done Unmount the folders, otherwise the image flashing will fail: sudo umount /dev/sda1; sudo umount /dev/sda2 Flash the image, using `bmaptool`: cd TO_THE_YOCTO_IMAGE_FOLDER # cd b2qt/build-raspberrypi4-64/tmp/deploy/images/raspberrypi4-64/ sudo bmaptool copy b2qt-embedded-qt6-image-raspberrypi4-64-20220316191856.rootfs.wic.bz2 --bmap b2qt-embedded-qt6-image-raspberrypi4-64-20220316191856.rootfs.wic.bmap /dev/sda Output: bmaptool: info: block map format version 2.0 bmaptool: info: 698368 blocks of size 4096 (2.7 GiB), mapped 367758 blocks (1.4 GiB or 52.7%) bmaptool: info: copying image 'rootfs.wic.bz2' to block device '/dev/sda' using bmap file 'rootfs.wic.bmap' bmaptool: info: 100% copied bmaptool: info: synchronizing '/dev/sda' bmaptool: info: copying time: 5m 6.5s, copying speed 4.7 MiB/sec Flashing takes a while, for me with the default image it takes about 5 minutes. The image filename varies, the date and time is in there. Switch the boot mode switch back (be careful), remove the USB C power cable and plug it back in. ### First boot and a quick recap ![first boot][14] > First bootup of your own `boot2qt` image! Sit back, relax and enjoy your own home-grown image booting. Well done! Play around with the example app, you can click "Learn More" and scroll around a bit. You might notice the application is rotated. Actually the screen's default orientation is portrait, but the terminal is landscape. The [FAQ][15] addresses this for [Ubuntu][16] and Debian, we will fix this later on when we deploy our own Qt app. The fix depends on what kind of Qt app you want to run and if you have access to the source code of said app. You can also plugin a network cable and `ssh` in to the machine, the IP address will be displayed on screen. To recap what you already have achieved: - Installed Yocto - Installed the `boot2qt` stack - Customized Yocto by creating your own layer - Added the reTerminal hardware layer - Built your own image - Flashed it onto the reTerminal. If you make changes to Yocto, subsequent builds will be faster since it only has to re-do stuff that changed. The steps you always have to do on the Yocto side are: - `cd b2qt/` - `export MACHINE=raspberrypi4-64 && source ./setup-environment.sh` - (do your changes) - `bitbake b2qt-embedded-qt6-image` On the reTerminal side for flashing: - Flip the `boot mode switch` and plugin a USB C cable - `./rpiboot` to be able to flash the image - `bmaptool copy b2qt-embedded-qt6-image-raspberrypi4-64-2022*.rootfs.wic.bz2 --bmap b2qt-embedded-qt6-image-raspberrypi4-64-2022*.rootfs.wic.bmap /dev/sda` - Flip back the boot mode switch - Remove the power cable and plug it back in Now that you have your device set up, it's time to make use of all the handy features `boot2qt` offers us, most important, the integration with the Qt IDE, Qt Creator. It allows for rapid development and testing, right from inside the IDE you can deploy to the device and test your changes. That workflow is really nice and quick, including debugging, breakpoints, etc. ### Qt SDK and Qt Creator integration In [my other article][13] on Yocto on the regular Pi Compute Module 4, I've written out all the steps required to build the Qt SDK and integrate it with Qt Creator. Because the process is quite long, I've decided not to duplicate it here but rather refer you to my other guide, which is full of screenshots and explains the whole process. Please check out [that article][13] for the full guide. The only thing that changes is the first command to `source` the setup file, we're exporting the `MACHINE` variable for the 64 bit version, like so: export MACHINE=raspberrypi4-64 && source ./setup-environment.sh Next, you build the SDK, which takes a while: bitbake meta-toolchain-b2qt-embedded-qt6-sdk When you've completed all the [steps in my other guide][13], you should have a new Qt kit configured in Qt Creator and a new device to deploy to. ### Making your own app the default Now that you've got the image working and you have your Qt integration set up, you should be able to run and deploy your app to the reTerminal via Qt Creator. If, and only if that's the case, continue on with the guide. We're going to replace the default `b2qt` `startupscreen` app with our own compiled program. In my case it's a [drag and drop demo app][17]. It's modified a little bit to also show the current IP address, which is useful when debugging on the device. This demo app is cool because it allows me to check the touch screen as well. Later on in the guide, in case of a Qt Widgets app, the rotation of the screen and the touch-screen rotation must match, otherwise the app will be rotated, but not the touch. Very weird stuff happens then. Start by making a new recipe for your app. We'll name it `myapp` for this example: mkdir -p sources/meta-raymii/recipes-myapp/myapp/files/ In the folder `files/` we've just created, place the compiled binary for your app, name it `myapp` for this guides example. Make sure the architecture matches the Pi 64 bit build: $ file myapp myapp: ELF 64-bit LSB pie executable, ARM aarch64, version 1 (GNU/Linux), dynamically linked, interpreter /lib/ld-linux-aarch64.so.1, for GNU/Linux 3.14.0, BuildID[sha1]=f2d876e1fe62e2eec1d5c0ead27a99c74a1f77ca, with debug_info, not stripped Next, create the actual recipe file with filename `myapp_1.0.bb` (not in the `files` folder, but one folder above). The underscore and version number are important, if you raise that number, a new package will be built by Yocto. Paste in the following contents: DESCRIPTION = "My Custom Qt App" AUTHOR = "author@example.org" LICENSE = "CLOSED" PR = "r0" SRC_URI =+ "file://myapp \ " DEPENDS += "qtbase qtdeclarative qtdeclarative-native" do_install() { install -d ${D}/${bindir} install -m 0755 ${WORKDIR}/myapp ${D}/${bindir}/myapp lnr ${D}/${bindir}/myapp ${D}/${bindir}/b2qt } FILES_${PN} = "${bindir}/myapp \ ${bindir}/b2qt \ " The line starting with `lnr` replaces the build in `b2qt` startupscreen app (which is a symlink) to your own application. `boot2qt` ships with a simple launcher that, on boot, launches whatever is the current symlink at `/usr/bin/b2qt` and it has a few more utilities (like start/stop or replacing the symlink) Add the new `myapp` recipe to our custom image `.bbappend` file: vi sources/meta-raymii/recipes-qt/images/b2qt-embedded-qt6-image.bbappend Edit the `IMAGE_INSTALL_append` section and add `myapp` right above the `kernel-modules` line: myapp \ The entire section looks like this now: IMAGE_INSTALL_append = " \ myapp \ kernel-modules \ evtest \ iperf3 \ i2c-tools \ util-linux \ " After the changes, build a new image: bitbake b2qt-embedded-qt6-image Flash that using `bmaptool` as described above. Because we're appending to the default `b2qt` image, and because we're symlinking our own binary where the `b2qt` launcher expects it, the next time you boot up after building and flashing an image, your own app should start. Here's a picture of my custom app after startup, still incorrectly rotated: ![reterminal myapp][18] If you want to upload a new version of your app, replace the `myapp` binary in the `files` folder and increment the `PR = "r0"` line to `r1`. Then bitbake a new image and flash it. Rinse and repeat for every release. If you just want to test out a new version, you can also `bitbake myapp`, then you'll just build the app without a new image. There will be a new `IPK` package in the `tmp/deploy/ipk` folder: $ file tmp/deploy/ipk/cortexa72/myapp_1.0-r2_cortexa72.ipk tmp/deploy/ipk/cortexa72/myapp_1.0-r2_cortexa72.ipk: Debian binary package (format 2.0), with control.tar.gz, data compression xz `scp` this file over to the device and install it using the package manager `opkg`: opkg install myapp_1.0-r2_cortexa72.ipk Then either reboot or restart the `startupscreen` service to load the new app. However, if you just want to test new builds of your app, use the built in Qt creator integration you set up earlier. Works way faster and right from Qt Creator, including remote debugging. ### Rotating your app in b2qt The next sections will cover the rotation aspect. It differs for Qt Widgets and Qt QML apps, and, in my opinion, is a big mess. The [FAQ][15] covers rotation and I've found a Japanese Seeed blog [covering rotation][19], but that is all for the `X11` display server. `boot2qt` uses `eglfs` to directly run your app. EGLFS is a platform plugin for running Qt applications on top of EGL and OpenGL ES 2.0, without an actual windowing system like `X11` or `Wayland`. Using `eglfs`, you can set an environment variable to rotate your application, but that will only work if you have a Qt Widgets app. For a QML app, you must either add a `transform: Rotation {}` to your program or run a display server like `weston` on `wayland` and let that handle rotation. We'll cover all the options in the next sections, starting with Qt Widgets. #### Qt Widgets rotation The simplest option is for a Qt Widget application, you can define 2 environment variables, one for rotation and one for touchscreen rotation, that's all: QT_QPA_EGLFS_ROTATION=-90 QT_QPA_GENERIC_PLUGINS=evdevtouch:/dev/input/event0:rotate=270 Why does one use `-90` and one use `270`? Because when I tried to use `270` instead of `-90`, on startup the app gave an error: `Invalid rotation 270 specified in QT_QPA_EGLFS_ROTATION`. I did try `QT_QPA_EVDEV_TOUCHSCREEN_PARAMETERS`, but that failed to work for touchscreen rotation. Now, how do we apply this to Yocto? There is a default qt environment file in `/etc/default/qt`, which we need to override in our Yocto build. Start by making a folder where our override `.bbappend` will reside: mkdir -p sources/meta-raymii/recipes-qt/boot2qt-addons/default-qt-envs/ Copy over the default environment file from the `boot2qt` layer to that folder: cp sources/meta-boot2qt/meta-boot2qt/recipes-qt/boot2qt-addons/default-qt-envs/defaults sources/meta-raymii/recipes-qt/boot2qt-addons/default-qt-envs/ Edit the `defaults` file: vim sources/meta-raymii/recipes-qt/boot2qt-addons/default-qt-envs/defaults Append the two lines below the existing ones: QT_QPA_EGLFS_ROTATION=-90 QT_QPA_GENERIC_PLUGINS=evdevtouch:/dev/input/event0:rotate=270 In my case, the user programmable keys don't show up, so the touchscreen is `/dev/input/event0`. It might be `event1`, but you can check using the `evtest` command: root@b2qt-raspberrypi4-64:~# evtest No device specified, trying to scan all of /dev/input/event* Available devices: /dev/input/event0: seeed-tp /dev/input/event1: vc4 /dev/input/event2: vc4 Select the device event number [0-2]: `seeed-tp` is the touchscreen (tp stands for touch-panel). Create a `.bbappend` file, which will override the default recipe: vim sources/meta-raymii/recipes-qt/boot2qt-addons/default-qt-envs.bbappend Add the following: FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" This line adds the folder in our own layer to the package, so it will look for the files in that folder as well as the original folder. Your new folder is checked first. [The Yocto manual explains this variable][20] and why using `:=` is important. You can check that your `.bbappend` is used using the following command: bitbake-layers show-appends default-qt-envs Output: === Matched appended recipes === default-qt-envs.bb: /home/remy/b2qt/sources/meta-raymii/recipes-qt/boot2qt-addons/default-qt-envs.bbappend /home/remy/b2qt/sources/meta-boot2qt/meta-boot2qt-distro/dynamic-layers/raspberrypi/recipes-qt/boot2qt-addons/default-qt-envs.bbappend `bitbake` the image and flash it, now your Qt Widgets app should be rotated correctly. Here is a picture of the incorrectly rotated example Qt widgets controls demo app: ![widgets][21] And here is the app with the environment variables set, rotated as you'd expect: ![widgets rotated][22] #### Qt QML rotation For a QML application, rotation is a bit harder. You either need to make changes to the source code, or use `wayland` and `weston`, a display manager and server which handle the rotation. The latter solution is only if you cannot change the source code of your application. If you can change your `QML` source code, add [a `Rotation` transformation][23]: transform: Rotation { angle: 270 origin.x: parent.width / 2 origin.y: parent.width / 2 } In this case I assume the rotation is on your root element. Not the `Window`, but the `Loader` or `StackLayout`, or `Rectangle` in the window, whatever is your root element. No changes to the environment are required, just upload a new version of your application as described above. ##### Weston and Wayland If you cannot change your source code, you must install a display manager. We're using Wayland and Weston, not `X11`. The Qt documentation has an [article explaining why not X11][24]. Here is a quote summarizing the important bits: > X11 is quite large and complex, and it lacks customizability. In fact, it is difficult to run a client fluidly with X11, and reach 60 fps without tearing. Wayland, in contrast, is easier to implement, has better performance, and contains all the necessary parts to run efficiently on modern graphics hardware. For embedded, multi-process systems on Linux, Wayland is the standard. Qt also has a Wayland Compositor, but we're not going to use that. We're going to run our `myapp` program as a client application in `Weston`. Weston is the reference compositor, sort of like the window manager in X11. Why Weston? It ships with the `boot2qt` Yocto stack and can run one program fullscreen without decorations and panels (using the `kiosk` plugin). We're currently at Weston version 9. In [version 10 there will be support for autostarting programs][25], but for now we must do that ourselves using a `systemd` service. As we've done a few times in this guide, we'll make a `.bbappend` file to override the default recipes with our changes. Start by creating a folder structure: mkdir -p sources/meta-raymii/recipes-graphics/wayland/weston-init/ In that folder, create a file named `weston.ini` and put the following in: # configuration file for Weston [core] shell=kiosk-shell.so require-input=false [output] name=DSI-1 mode=720x1280@60 transform=rotate-270 [screen-share] command=/usr/bin/weston --backend=rdp-backend.so --shell=fullscreen-shell.so --no-clients-resize [shell] panel-position=none The default shipped config starts a desktop, but we're changing that. The `kiosk-shell.so` plugin runs one app fullscreen without any window decorations. The `output` section, including the `transform=rotate-270` is the magic section you need to rotate your QML application. Create a `.bbappend` recipe: FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" SRC_URI += " file://weston.ini " do_install_append() { # Remove upstream weston.ini to avoid conflict with weston-ini-conf package rm -f ${D}${sysconfdir}/xdg/weston/weston.ini install -D -p -m0644 ${WORKDIR}/weston.ini ${D}${sysconfdir}/xdg/weston/weston.ini } SYSTEMD_AUTO_ENABLE_${PN} = "enable" This looks like what we did earlier to override the default Qt environment. `FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"` adds the current folder in our own layer, where we just placed the config file. I had some vague issues where the default `weston.ini` file was not replaced, which is why there is such an explicit `do_install_append` section. Normally that is not required, but in my case, the file would not be replaced unless I did it this way. `SYSTEMD_AUTO_ENABLE_${PN} = "enable"` enables the `weston` systemd service. Now, to make sure `weston` starts and not `b2qt` or the `startupscreen`, we must make a few more `.bbappend` recipes to disable those systemd services. There can only be one display service running, if `b2qt` runs, then `weston` will fail to start. Same as earlier, create the following file: sources/meta-raymii/recipes-qt/boot2qt-addons/boot2qt-startupscreen_%.bbappend Put in the below line: SYSTEMD_AUTO_ENABLE_${PN} = "disable" This disables the `startupscreen` service. Repeat the above for the `b2qt` service, which, confusingly, is in the `default-qt-envs` recipe file: sources/meta-raymii/recipes-qt/boot2qt-addons/default-qt-envs.bbappend The same line goes in to disable the systemd service: SYSTEMD_AUTO_ENABLE_${PN} = "disable" The next part involves our custom image `.bbappend` file, where we need to add `weston` to the distro features, to make sure `systemd` boots up to the `graphical` target and not the `multiuser` target: sources/meta-raymii/recipes-qt/images/b2qt-embedded-qt6-image.bbappend Append `weston \` to the `IMAGE_FEATURES_append` section: IMAGE_FEATURES_append = " \ splash \ weston \ " Include the `weston-init` package in the `IMAGE_INSTALL_append` section: IMAGE_INSTALL_append = " \ myapp \ kernel-modules \ evtest \ iperf3 \ i2c-tools \ util-linux \ weston-init \ " The last part involves updating our `myapp` recipe to include a `systemd` service, which will start up our application after `weston` is started. Create a new file: vim sources/meta-raymii/recipes-myapp/myapp/files/myapp.service Place the following contents: [Unit] Description=MyApp on Weston After=weston.service [Service] User=weston Restart=always Type=simple Environment=QT_QPA_PLATFORM=wayland ExecStartPre=/bin/sh -c 'echo XDG_RUNTIME_DIR="$(loginctl show-user --property=RuntimePath --value \"$USER\")" > /tmp/qtenv' EnvironmentFile=-/tmp/qtenv ExecStopPost=/bin/rm /tmp/qtenv ExecStart=/usr/bin/myapp WorkingDirectory=/home/weston [Install] WantedBy=multi-user.target If you run a Qt app on Wayland, it required the `XDG_RUNTIME_DIR` environment variable. We could hardcode this to `/run/user/1000`, which would work for this specific setup, but we can also use the `loginctl` command to query the actual path, which works for all future devices and setups. `systemd` has no option to evaluate a shell command as an `Environment` option, so we use a hack to do that. First, it executes the `ExecStartPre` command, which start a subshell to execute the command and writes the output to a file in `/tmp`. Then we specify the line `EnvironmentFile`, but, **important**, start it with a dash (`-`). This ensures the correct order, first the command, then the file. Not documented well, I found a stackoverflow post explaining it, but I cannot find that anymore to quote as source. Once the app stops, the environment file is removed. Change our `myapp_1.0.bb` recipe to include this systemd recipe: DESCRIPTION = "My Custom Qt App" AUTHOR = "author@example.org" LICENSE = "CLOSED" PR = "r1" SRC_URI =+ "file://myapp \ file://myapp.service \ " inherit systemd DEPENDS += "qtbase qtdeclarative qtdeclarative-native" do_install() { install -d ${D}/${bindir} install -m 0755 ${WORKDIR}/myapp ${D}/${bindir}/myapp lnr ${D}/${bindir}/myapp ${D}/${bindir}/b2qt install -m 0755 -d ${D}${systemd_unitdir}/system install -m 0644 ${WORKDIR}/myapp.service ${D}${systemd_unitdir}/system/ } FILES_${PN} = "${bindir}/myapp \ ${bindir}/b2qt \ " SYSTEMD_SERVICE:${PN} = "myapp.service" By specifying `SYSTEMD_SERVICE`, it will be enabled by default on boot. Build a new image and after all that effort, a correctly rotated QML application should be the result: ![qml rotated][26] In my personal opinion this rotation for QML is an area the Qt Company could improve, rather, make just as easy as Qt Widgets. You can run any Qt app this way manually, compile and copy it via Qt Creator, or if you can't compile it, just copy it. Set the correct environment variables and run it. For example, the Qt built in Bear Whack example (fun game, under `quick/touchinteraction`): XDG_RUNTIME_DIR=/run/user/1000 QT_QPA_PLATFORM=wayland /usr/share/examples/quick/touchinteraction/touchinteraction Here's a picture of [Bear Whack][29]: ![bear whack][28] And here's a picture of the [SameGame demo][30] running. Particles and effects are very smooth on the reTerminal: ![samegame][27] [1]: http://web.archive.org/web/20220315202600/https://wiki.seeedstudio.com/reTerminal-Yocto/ [2]: https://wiki.seeedstudio.com/reTerminal/ [3]: /s/inc/img/reterminal_1.png [4]: /s/inc/img/reterminal_2.png [5]: /s/inc/img/reterminal_3.jpg [6]: https://wiki.seeedstudio.com/reTerminal-hardware-interfaces-usage/#high-speed-interface-for-expansion-modules [7]: https://web.archive.org/web/20220219191821/https://gerrit.googlesource.com/git-repo/ [8]: https://github.com/Seeed-Studio/meta-seeed-cm4/commit/885d6a332a25832dd954beb8cb5337c24bf9d77f [9]: https://www.seeedstudio.com/ReTerminal-with-CM4-p-4904.html [10]: https://wiki.seeedstudio.com/reTerminal/#flash-raspberry-pi-os-64-bit-ubuntu-os-or-other-os-to-emmc [11]: /s/inc/img/reterminal_6.png [12]: https://github.com/Seeed-Studio/seeed-linux-dtoverlays/issues/37 [13]: /s/tutorials/Yocto_boot2qt_for_the_Raspberry_Pi_4_both_Qt_6_and_Qt_5.html [14]: /s/inc/img/reterminal_7.jpg [15]: https://wiki.seeedstudio.com/reTerminal-FAQ/#q11-the-screen-orientation-is-incorrect-after-installing-raspberry-pi-os-bullseye [16]: /s/inc/img/reterminal_8.png [17]: /s/tutorials/Qml_Drag_and_Drop_example_including_reordering_the_Cpp_Model.html [18]: /s/inc/img/reterminal_9.jpg [19]: https://lab.seeed.co.jp/entry/2022/01/20/120000 [20]: https://docs.yoctoproject.org/3.3/singleindex.html#term-FILESEXTRAPATHS [21]: /s/inc/img/reterminal_10.jpg [22]: /s/inc/img/reterminal_11.jpg [23]: https://web.archive.org/web/20220318200959/https://doc.qt.io/qt-6/qml-qtquick-rotation.html [24]: https://web.archive.org/web/20220318194533/https://doc.qt.io/qt-6/wayland-and-qt.html [25]: https://gitlab.freedesktop.org/wayland/weston/-/merge_requests/652 [26]: /s/inc/img/reterminal_12.jpg [27]: /s/inc/img/reterminal_13.jpg [28]: /s/inc/img/reterminal_14.jpg [29]: https://web.archive.org/web/20220318213600/https://doc.qt.io/qt-6/qtquick-touchinteraction-example.html [30]: https://web.archive.org/web/20220318213644/https://doc.qt.io/qt-6/qtquick-tutorials-samegame-samegame4-example.html [31]: https://github.com/Seeed-Studio/meta-seeed-cm4/blob/7c846e23de9346d318fbdc8ac92dcc72b90fb6ce/recipes-kernel/linux/files/0003-add-reTerminal-dtoverlay-for-yocto.patch --- License: All the text on this website is free as in freedom unless stated otherwise. This means you can use it in any way you want, you can copy it, change it the way you like and republish it, as long as you release the (modified) content under the same license to give others the same freedoms you've got and place my name and a link to this site with the article as source. This site uses Google Analytics for statistics and Google Adwords for advertisements. You are tracked and Google knows everything about you. Use an adblocker like ublock-origin if you don't want it. All the code on this website is licensed under the GNU GPL v3 license unless already licensed under a license which does not allows this form of licensing or if another license is stated on that page / in that software: This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program. If not, see . Just to be clear, the information on this website is for meant for educational purposes and you use it at your own risk. I do not take responsibility if you screw something up. Use common sense, do not 'rm -rf /' as root for example. If you have any questions then do not hesitate to contact me. See https://raymii.org/s/static/About.html for details.