RaspberryPi2EGLFS: Difference between revisions

From Qt Wiki
Jump to navigation Jump to search
mNo edit summary
No edit summary
 
(43 intermediate revisions by 25 users not shown)
Line 1: Line 1:
<h2>A modern guide for cross-compiling Qt 5.6 for HW accelerated OpenGL with eglfs on Raspbian Jessie.</h2>
[[Category:Raspberry Pi]]
<h2>A modern guide for cross-compiling Qt for HW accelerated OpenGL with eglfs on Raspbian and setting up Qt Creator</h2>


<b>Note that this is not intended for running desktop-style, windowed Qt apps under X11, but rather for the real embedded/device creation use case where the Qt app runs fullscreen on top of dispmanx/EGL using the Broadcom drivers.</b>
====== <b>Initial notes</b> ======
* This is not intended for running desktop-style, windowed Qt apps under X11, but rather for the real embedded/device creation use case where the Qt app runs fullscreen on top of dispmanx/EGL using the Broadcom drivers.
* For detailed, generic information about eglfs and Qt on Embedded Linux check the [http://doc-snapshots.qt.io/qt5-5.6/embedded-linux.html Qt documentation].


For detailed, generic information about eglfs and Qt on Embedded Linux check the [http://doc-snapshots.qt.io/qt5-5.6/embedded-linux.html Qt documentation].
====== Tested Configurations ======
* Qt 5.6 with Raspbian Wheezy / Jessie
* Qt 5.9.1 with Raspbian Stretch on Raspberry 3 model B
* Qt 5.10 with Raspbian Stretch on Raspberry 1 model B
* Qt 5.10.1 with Raspbian Stretch on Raspberry 3 model B
* Qt 5.10.1 with Raspbian Stretch on Raspberry Zero W
* Qt 5.12.3 with Raspbian Stretch on Raspberry 3 model B
* Qt.5.13.1 with Raspbian Stretch on Raspberry3 model B


<h3>Step by step</h3>
If you are interested in trying QtWebEngine with WebGL support on RasberryPi3 with the open source Vc4 driver see [[RaspberryPiWithWebEngine|here]].


1. Get the latest image from https://downloads.raspberrypi.org/raspbian_latest
======Step by step======
 
# Get old raspbian images from [http://downloads.raspberrypi.org/raspbian/images/ here] or latest raspbian image from [https://www.raspberrypi.org/downloads/raspbian/ here].
2. Unzip and write it to a memory card. Replace ... with the SD card device (check dmesg).
# Follow an [https://www.raspberrypi.org/documentation/installation/installing-images/README.md official installation guide]to boot it up or:  Unzip and write it to a memory card. Replace ... with the SD card device (check with lsblk or dmesg eg. mmcblk0)<syntaxhighlight>
 
sudo dd if=2015-09-24-raspbian-jessie.img of=... bs=4M</syntaxhighlight>
<code lang="bash">
# '''[on RPi]''' ''(optional)'' Run raspi-config, change it to boot to the console instead of X, change the GPU memory to 256 MB.<syntaxhighlight>
sudo dd if=2015-09-24-raspbian-jessie.img of=... bs=4M
</code>
 
3. Boot it up, run raspi-config, change it to boot to the console instead of X, change the GPU memory to 256 MB, install a bunch of development files (for simplicity we use build-dep, not everything is really needed, but it is easier this way), and prepare our target directory:
 
<code lang="bash">
sudo raspi-config
sudo raspi-config
</code>
</syntaxhighlight>
 
# '''[on RPi]''' For <u>Raspbian Stretch</u> you need also to update your RPi (see [https://bugreports.qt.io/browse/QTBUG-62216 here]):<syntaxhighlight>
<code lang="bash">sudo nano /etc/apt/sources.list</code> and uncomment the deb-src line.
sudo rpi-update
 
reboot
<code lang="bash">
</syntaxhighlight>
# '''[on RPi]''' Install a bunch of development files (for simplicity we use build-dep, not everything is really needed, but it is easier this way).
## Edit sources list in ''/etc/apt/sources.list'' with use of your favorite editor (nano / vi) and uncomment the '''deb-src''' line:<syntaxhighlight>
sudo nano /etc/apt/sources.list
</syntaxhighlight>
## Update your system and install required libraries:<syntaxhighlight>
sudo apt-get update
sudo apt-get update
sudo apt-get build-dep qt4-x11
sudo apt-get build-dep qt4-x11
sudo apt-get build-dep libqt5gui5
sudo apt-get build-dep libqt5gui5
sudo apt-get install libudev-dev libinput-dev libts-dev
sudo apt-get install libudev-dev libinput-dev libts-dev libxcb-xinerama0-dev libxcb-xinerama0
 
</syntaxhighlight>
# '''[on RPi]''' Prepare our target directory<syntaxhighlight>
sudo mkdir /usr/local/qt5pi
sudo mkdir /usr/local/qt5pi
sudo chown pi:pi /usr/local/qt5pi
sudo chown pi:pi /usr/local/qt5pi
</code>
</syntaxhighlight>
 
# '''[on host PC]''' Create our working directory and get a toolchain:<syntaxhighlight>
4. Back on the host PC, create our working directory and get a toolchain:
 
<code lang="bash">
mkdir ~/raspi
mkdir ~/raspi
cd ~/raspi
cd ~/raspi
git clone https://github.com/raspberrypi/tools
git clone https://github.com/raspberrypi/tools
</code>
</syntaxhighlight>
 
# '''[on host PC]''' Create a sysroot. Using rsync we can properly keep things synchronized in the future as well. Replace ''raspberrypi.local'' with the address of the Pi.<syntaxhighlight>
5. Create a sysroot. Using rsync we can properly keep things synchronized in the future as well. Replace IP with the address of the Pi.
 
<code lang="bash">
mkdir sysroot sysroot/usr sysroot/opt
mkdir sysroot sysroot/usr sysroot/opt
rsync -avz pi@IP:/lib sysroot
rsync -avz pi@raspberrypi.local:/lib sysroot
rsync -avz pi@IP:/usr/include sysroot/usr
rsync -avz pi@raspberrypi.local:/usr/include sysroot/usr
rsync -avz pi@IP:/usr/lib sysroot/usr
rsync -avz pi@raspberrypi.local:/usr/lib sysroot/usr
rsync -avz pi@IP:/opt/vc sysroot/opt
rsync -avz pi@raspberrypi.local:/opt/vc sysroot/opt
</code>
</syntaxhighlight>
 
# '''[on host PC]''' Adjust symlinks to be relative. Use provided script, because the old ''fixQualifiedLibraryPaths'' is not working properly:<syntaxhighlight>
6. Adjust symlinks to be relative. Instead of the old fixQualifiedLibraryPaths get a script that works:
wget https://raw.githubusercontent.com/Kukkimonsuta/rpi-buildqt/master/scripts/utils/sysroot-relativelinks.py
 
<code lang="bash">
wget https://raw.githubusercontent.com/riscv/riscv-poky/master/scripts/sysroot-relativelinks.py
chmod +x sysroot-relativelinks.py
chmod +x sysroot-relativelinks.py
./sysroot-relativelinks.py sysroot
./sysroot-relativelinks.py sysroot
</code>
</syntaxhighlight>
 
# '''[on host PC]''' Get qtbase and configure Qt. The target directory is ''/usr/local/qt5pi'' on the Pi, the host tools like qmake will go to ''~/raspi/qt5'', while make install will target ''~/raspi/qt5pi'' (this is what we will sync to the device). Don't forget to adjust paths if you changed that. For some reason the ''~/'' in the paths may not work, if this the case just use full paths.  You need to change '''<qt-version>''' with a proper Qt version (for example 5.6, or 5.9.1; note that version 5.9.1 is a tag not a branch, so you may want to create a local branch with it).  You need to change '''<rpi-version>''' with a proper Raspberry Pi version. Use: ''linux-rasp-pi-g++'' for RPi, ''linux-rasp-pi2-g++'' for RPi2 and ''linux-rasp-pi3-g++'' for RPi3.  If your system is 64 bit you may also edit device option to: <code>-device-option CROSS_COMPILE=~/raspi/tools/arm-bcm2708/gcc-linaro-arm-linux-gnueabihf-raspbian-x64/bin/arm-linux-gnueabihf-</code>  For higher Qt version (like 5.9.1) you may also need to add <code>-no-use-gold-linker</code> option.  You probably also want to add ''-jn'' option to make command, where ''n'' is a number of cores you like to use for the complication.<syntaxhighlight>
7. Get qtbase (note that Qt 5.6 is not yet released and is work in progress) and configure Qt. The target directory is /usr/local/qt5pi on the Pi, the host tools like qmake will go to ~/raspi/qt5, while make install will target ~/raspi/qt5pi (this is what we will sync to the device). If using the old Pi instead of the Pi 2, change -device to linux-rasp-pi-g++.
git clone git://code.qt.io/qt/qtbase.git -b <qt-version>
cd qtbase
./configure -release -opengl es2 -device <rpi-version> -device-option CROSS_COMPILE=~/raspi/tools/arm-bcm2708/gcc-linaro-arm-linux-gnueabihf-raspbian/bin/arm-linux-gnueabihf- -sysroot ~/raspi/sysroot -opensource -confirm-license -make libs -prefix /usr/local/qt5pi -extprefix ~/raspi/qt5pi -hostprefix ~/raspi/qt5 -v


<code lang="bash">
git clone git://code.qt.io/qt/qtbase.git -b 5.6
cd qtbase
./configure -release -opengl es2 -device linux-rasp-pi2-g++ -device-option CROSS_COMPILE=~/raspi/tools/arm-bcm2708/gcc-linaro-arm-linux-gnueabihf-raspbian/bin/arm-linux-gnueabihf- -sysroot ~/raspi/sysroot -opensource -confirm-license -make libs -prefix /usr/local/qt5pi -extprefix ~/raspi/qt5pi -hostprefix ~/raspi/qt5 -v
make
make
make install
make install
</code>
</syntaxhighlight>If you failed, you can clear everything with:<syntaxhighlight>
 
git clean -dfx
8. Deploy to the device. We simply sync everything from ~/raspi/qt5pi to the prefix we configured above.
</syntaxhighlight>
 
# '''[on host PC]''' Deploy Qt to the device. We simply sync everything from ''~/raspi/qt5pi'' to the prefix we configured above.<syntaxhighlight>
<code lang="bash">
cd ..
rsync -avz qt5pi pi@IP:/usr/local
rsync -avz qt5pi pi@raspberrypi.local:/usr/local
</code>
</syntaxhighlight>
 
# '''[on host PC]''' Build an example up to test if everything went well. After proper build, copy an executable to the device.<syntaxhighlight>
9. Build an example:
 
<code lang="bash">
cd qtbase/examples/opengl/qopenglwidget
cd qtbase/examples/opengl/qopenglwidget
~/raspi/qt5/bin/qmake
~/raspi/qt5/bin/qmake
make
make
scp qopenglwidget pi@IP:/home/pi
</code>
10. On the device, let the linker find the Qt libs:


<code lang="bash">
scp qopenglwidget pi@raspberrypi.local:/home/pi
</syntaxhighlight>
# '''[on RPi]''' Update the device to let the linker find the Qt libs:<syntaxhighlight>
echo /usr/local/qt5pi/lib | sudo tee /etc/ld.so.conf.d/qt5pi.conf
echo /usr/local/qt5pi/lib | sudo tee /etc/ld.so.conf.d/qt5pi.conf
sudo ldconfig
sudo ldconfig
</code>
</syntaxhighlight>If you're facing issues with running the example, try to use ''00-qt5pi.conf'' instead of ''qt5pi.conf'', to introduce proper order.
 
# '''[on RPi]''' Fix the EGL/GLES libraries.  The device may have the Mesa version of libEGL and libGLESv2 in ''/usr/lib/arm-linux-gnueabihf'', resulting Qt apps picking these instead of the real thing from ''/opt/vc/lib''. This may be fine for X11 desktop apps not caring about OpenGL performance but is totally useless for windowing system-less, fullscreen embedded apps. You may want to save the originals somewhere, just in case. Make sure you're in "/home/pi" aka "~" when you run these commands:<syntaxhighlight>
11. Still on the device, fix the EGL/GLES library nonsense:
sudo mv /usr/lib/arm-linux-gnueabihf/libEGL.so.1.0.0 /usr/lib/arm-linux-gnueabihf/libEGL.so.1.0.0_backup
 
sudo mv /usr/lib/arm-linux-gnueabihf/libGLESv2.so.2.0.0 /usr/lib/arm-linux-gnueabihf/libGLESv2.so.2.0.0_backup
The device may have the Mesa version of libEGL and libGLESv2 in /usr/lib/arm-linux-gnueabihf, resulting Qt apps picking these instead of the real thing from /opt/vc/lib.
This may be fine for X11 desktop apps not caring about OpenGL performance but is totally useless for windowing system-less, fullscreen embedded apps.
 
<code lang="bash">
sudo rm /usr/lib/arm-linux-gnueabihf/libEGL.so.1.0.0 /usr/lib/arm-linux-gnueabihf/libGLESv2.so.2.0.0
sudo ln -s /opt/vc/lib/libEGL.so /usr/lib/arm-linux-gnueabihf/libEGL.so.1.0.0
sudo ln -s /opt/vc/lib/libEGL.so /usr/lib/arm-linux-gnueabihf/libEGL.so.1.0.0
sudo ln -s /opt/vc/lib/libGLESv2.so /usr/lib/arm-linux-gnueabihf/libGLESv2.so.2.0.0
sudo ln -s /opt/vc/lib/libGLESv2.so /usr/lib/arm-linux-gnueabihf/libGLESv2.so.2.0.0
</code>
sudo ln -s /opt/vc/lib/libbrcmEGL.so /opt/vc/lib/libEGL.so
sudo ln -s /opt/vc/lib/libbrcmGLESv2.so /opt/vc/lib/libGLESv2.so
</syntaxhighlight>Please make sure to also add missing symbolic links:<syntaxhighlight>
sudo ln -s /opt/vc/lib/libEGL.so /opt/vc/lib/libEGL.so.1
sudo ln -s /opt/vc/lib/libGLESv2.so /opt/vc/lib/libGLESv2.so.2
</syntaxhighlight>
# '''[on RPi]''' Run example, that we've built before. At this point it should just work at fullscreen with 60 FPS and mouse, keyboard, and possibly touch support.
# '''[on host PC]''' Build other Qt modules as desired, the steps are always the same (you need to adjust '''<qt-module>''' and '''<qt-version>'''):<syntaxhighlight>
git clone git://code.qt.io/qt/<qt-module>.git -b <qt-version>
cd <qt-module>


You may want to save the originals somewhere, just in case.
~/raspi/qt5/bin/qmake
 
12. Run qopenglwidget we deployed to /home/pi. At this point it should just work at fullscreen with 60 FPS and mouse, keyboard, and possibly touch support.
 
13. Build other Qt modules as desired, the steps are the same always:
 
<code lang="bash">
~/raspi/qt5/bin/qmake -r
make
make
make install
make install
</code>
</syntaxhighlight>Then deploy new files by running:<syntaxhighlight>rsync -avz qt5pi pi@raspberrypi.local:/usr/local</syntaxhighlight>
then deploy the new files by running <code lang="bash">rsync -avz qt5pi pi@IP:/usr/local</code> in ~/raspi
 
<h3>Additional notes</h3>
<h3>Additional notes</h3>


Line 121: Line 110:
As a quick fix, try adding disable_overscan=1 to /boot/config.txt and after a reboot check with /opt/vc/bin/tvservice what modes are available. For example, to switch to 1024x768:
As a quick fix, try adding disable_overscan=1 to /boot/config.txt and after a reboot check with /opt/vc/bin/tvservice what modes are available. For example, to switch to 1024x768:


<code>
<syntaxhighlight>
$ /opt/vc/bin/tvservice -m DMT
$ /opt/vc/bin/tvservice -m DMT
Group DMT has 4 modes:
Group DMT has 4 modes:
Line 128: Line 117:
           mode 16: 1024x768 @ 60Hz 4:3, clock:65MHz progressive  
           mode 16: 1024x768 @ 60Hz 4:3, clock:65MHz progressive  
           mode 35: 1280x1024 @ 60Hz 5:4, clock:108MHz progressive  
           mode 35: 1280x1024 @ 60Hz 5:4, clock:108MHz progressive  
$ /opt/vc/bin/tvservice -e "DMT 16 HDMI"
$ /opt/vc/bin/tvservice -e "DMT 16 HDMI"
$ fbset -xres 1024 -yres 768
$ fbset -xres 1024 -yres 768
</code>
</syntaxhighlight>


<h4>Troubleshooting</h4>
<h4>Troubleshooting</h4>
Line 136: Line 126:
Enabling the logging categories under qt.qpa is a good idea in general. This will show some debug prints both from eglfs and the input handlers.
Enabling the logging categories under qt.qpa is a good idea in general. This will show some debug prints both from eglfs and the input handlers.


<code lang="bash">
<syntaxhighlight>
export QT_LOGGING_RULES=qt.qpa.*=true
export QT_LOGGING_RULES=qt.qpa.*=true
./qopenglwidget
./qopenglwidget
</code>
</syntaxhighlight>


A typical output would like like this:
A typical output would like like this:


<code>
<syntaxhighlight>
qt.qpa.egldeviceintegration: EGL device integration plugin keys: ("eglfs_brcm", "eglfs_kms")
qt.qpa.egldeviceintegration: EGL device integration plugin keys: ("eglfs_brcm", "eglfs_kms")
qt.qpa.egldeviceintegration: EGL device integration plugin keys (sorted): ("eglfs_brcm", "eglfs_kms")
qt.qpa.egldeviceintegration: EGL device integration plugin keys (sorted): ("eglfs_brcm", "eglfs_kms")
Line 155: Line 145:
qt.qpa.input: libinput: input device 'Raspberry Pi Sense HAT Joystick', /dev/input/event3 is a keyboard
qt.qpa.input: libinput: input device 'Raspberry Pi Sense HAT Joystick', /dev/input/event3 is a keyboard
qt.qpa.input: Using xkbcommon for key mapping
qt.qpa.input: Using xkbcommon for key mapping
</code>
</syntaxhighlight>


Verify that eglfs_brcm is in use and that input devices are correctly found.
Verify that eglfs_brcm is in use and that input devices are correctly found.
Line 163: Line 153:
It is also wise to carefully check the output of configure (saved as config.summary) before proceeding to build qtbase. Check that the following are marked as 'yes':
It is also wise to carefully check the output of configure (saved as config.summary) before proceeding to build qtbase. Check that the following are marked as 'yes':


<code>
<syntaxhighlight>
Support enabled for:
Support enabled for:
   ...
   ...
Line 184: Line 174:
   udev ................... yes
   udev ................... yes
   xkbcommon-evdev......... yes
   xkbcommon-evdev......... yes
</code>
</syntaxhighlight>
 
'''Missing EGLFS Fix'''
 
On recent versions of Qt (e.g. 5.10.1), the qmake.conf file for linux-rasp-pi3-g++ doesn't work, however, linux-rasp-pi-g++ does. Create a new qmake.conf based on linux-rasp-pi-g++ with the build flags from the Pi 3 spec copied over.
 
Another fix is the replacement of the broken lines:
 
<syntaxhighlight>VC_LIBRARY_PATH = $$[QT_SYSROOT]/opt/vc/lib
VC_INCLUDE_PATH = $$[QT_SYSROOT]/opt/vc/include
VC_LINK_LINE = -L$${VC_LIBRARY_PATH}
QMAKE_LIBDIR_OPENGL_ES2 = $${VC_LIBRARY_PATH}</syntaxhighlight>


<h4>Regarding keyboard input</h4>
<h4>Regarding keyboard input</h4>


By default Qt attempts to disable the keyboard and hide the cursor on application startup. This is very handy since this way keystrokes will not go to the console (which is enabled by default in a normal Raspbian image) "underneath".
By default Qt attempts to disable the keyboard and hide the cursor on application startup. This is very handy since this way keystrokes will not go to the console (which is enabled by default in a normal Raspbian image) "underneath".
However, at the moment this will all silently fail when starting an application remotely via ssh. This is the explanation for the (harmless) 9;15] and similar prints and the keyboard input unexpectedly going to the console as well. As a workaround, start apps directly on the console. Alternatively, get rid of the first TTY by doing sudo systemctl disable getty@tty1.service and reboot. (tty2 and others remain usable)
However, at the moment this will all silently fail when starting an application remotely via ssh. This is the explanation for the (harmless) 9;15] and similar prints and the keyboard input unexpectedly going to the console as well. As a workaround, start apps directly on the console. Alternatively, you could experiment with getting rid of the first TTY by doing sudo systemctl disable getty@tty1.service and reboot. (tty2 and others remain usable)
 
'''Environment variables'''
 
If you get an error such as "''This application failed to start because it could not find or load the Qt platform plugin "eglfs" in "".''", when attempting to run a Qt app on the RPi, you may need to set some environment variables.
 
<syntaxhighlight>
export QT_QPA_PLATFORM=eglfs
export QT_QPA_PLATFORM_PLUGIN_PATH=/usr/local/qt5pi/plugins/platforms
export LD_LIBRARY_PATH=/usr/local/qt5pi/lib
</syntaxhighlight>
 
<h3>Qt Creator</h3>
 
Once Qt is on the device, Qt Creator can be set up to build, deploy, run and debug Qt apps directly on the device with one click.
 
<syntaxhighlight>
Go to Options -> Devices
  Add
    Generic Linux Device
    Enter IP address, user & password
    Finish
</syntaxhighlight>
 
<syntaxhighlight>
Go to Options -> Compilers
  Add
    GCC
    Compiler path: ~/raspi/tools/arm-bcm2708/gcc-linaro-arm-linux-gnueabihf-raspbian/bin/arm-linux-gnueabihf-g++
</syntaxhighlight>
 
<syntaxhighlight>
Go to Options -> Debuggers
  Add
    ~/raspi/tools/arm-bcm2708/gcc-linaro-arm-linux-gnueabihf-raspbian-x64/bin/arm-linux-gnueabihf-gdb
</syntaxhighlight>
 
<syntaxhighlight>
Go to Options -> Qt Versions
  Check if an entry with ~/raspi/qt5/bin/qmake shows up. If not, add it.
</syntaxhighlight>
 
<syntaxhighlight>
Go to Options -> Build & Run
  Kits
    Add
      Generic Linux Device
      Device: the one we just created
      Sysroot: ~/raspi/sysroot
      Compiler: the one we just created
      Debugger: the one we just created
      Qt version: the one we saw under Qt Versions
      Qt mkspec: leave empty
</syntaxhighlight>
 
Done. At this point you should be able to start a new project with the new kit, build and deploy it, etc.
 
Note: While things will usually just work for applications, developing libraries and in particular, Qt modules may be problematic when it comes to deployment. The per-project Run tab under Projects -> Build & Run is your friend. In some cases the target deployment paths will just be wrong. Life is too short for worrying about all the intricate details of Creator and the build system. Therefore, if all else fails, use Add Deploy Step ("Make" and "Custom Process Step" are extremely handy, anything can be made working with a combination of make install, rsync and scp) and change Run configuration to Custom Executable.
 
<h3>Sense HAT</h3>
 
To access the sensors and leds on the [https://www.raspberrypi.org/products/sense-hat Sense HAT], you can use the [http://code.qt.io/cgit/qt-labs/qtsensehat.git/ unofficial Qt Sense HAT module on qt-labs]. Check it out via git and build it like any other Qt module.
 
The joystick shows up as an ordinary evdev device providing key events so it will just work. Regarding the leds and sensors, see [http://code.qt.io/cgit/qt-labs/qtsensehat.git/tree/README.md the README].
 
<h3>Qt Multimedia</h3>
 
Unfortunately the GStreamer-based multimedia stuff is not quite usable at the time of writing - accelerated video works only sometimes (and with glitches), while the camera is just broken.
 
As an alternative to Qt Multimedia, try using OpenMAX directly. For an open implementation refer to this [http://thebugfreeblog.blogspot.it/p/overview-of.html project]. For the [https://www.raspberrypi.org/products/camera-module/ Raspberry Pi Camera Module] take a look at the [https://github.com/raspberrypi/userland/tree/master/host_applications/linux/apps/raspicam raspistill application sources] for an example on how to get the camera preview image into an OpenGL texture.
 
If you wish to experiment with Qt Multimedia, try the following:
 
Before building Qt Multimedia 5.6, make sure the following are installed:
 
<syntaxhighlight>
sudo apt-get install gstreamer1.0-omx libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev
</syntaxhighlight>
 
Do not forget to sync the headers and libs back to the sysroot on the host PC and re-run the sysroot-relativelinks.py script.
 
Once the GStreamer 1.0 dependencies are in place, make sure Qt Multimedia is built with 1.0 support:
 
<syntaxhighlight>
~/raspi/qt5/bin/qmake -r GST_VERSION=1.0
</syntaxhighlight>
 
To verify that the accelerated OpenMAX path is used for H.264 videos, do <em>export GST_DEBUG=omx:4</em> before running a video playback app like the qmlvideofx example.

Latest revision as of 08:43, 23 March 2021

A modern guide for cross-compiling Qt for HW accelerated OpenGL with eglfs on Raspbian and setting up Qt Creator

Initial notes
  • This is not intended for running desktop-style, windowed Qt apps under X11, but rather for the real embedded/device creation use case where the Qt app runs fullscreen on top of dispmanx/EGL using the Broadcom drivers.
  • For detailed, generic information about eglfs and Qt on Embedded Linux check the Qt documentation.
Tested Configurations
  • Qt 5.6 with Raspbian Wheezy / Jessie
  • Qt 5.9.1 with Raspbian Stretch on Raspberry 3 model B
  • Qt 5.10 with Raspbian Stretch on Raspberry 1 model B
  • Qt 5.10.1 with Raspbian Stretch on Raspberry 3 model B
  • Qt 5.10.1 with Raspbian Stretch on Raspberry Zero W
  • Qt 5.12.3 with Raspbian Stretch on Raspberry 3 model B
  • Qt.5.13.1 with Raspbian Stretch on Raspberry3 model B

If you are interested in trying QtWebEngine with WebGL support on RasberryPi3 with the open source Vc4 driver see here.

Step by step
  1. Get old raspbian images from here or latest raspbian image from here.
  2. Follow an official installation guideto boot it up or: Unzip and write it to a memory card. Replace ... with the SD card device (check with lsblk or dmesg eg. mmcblk0)
    sudo dd if=2015-09-24-raspbian-jessie.img of=... bs=4M
    
  3. [on RPi] (optional) Run raspi-config, change it to boot to the console instead of X, change the GPU memory to 256 MB.
    sudo raspi-config
    
  4. [on RPi] For Raspbian Stretch you need also to update your RPi (see here):
    sudo rpi-update
    reboot
    
  5. [on RPi] Install a bunch of development files (for simplicity we use build-dep, not everything is really needed, but it is easier this way).
    1. Edit sources list in /etc/apt/sources.list with use of your favorite editor (nano / vi) and uncomment the deb-src line:
      sudo nano /etc/apt/sources.list
      
    2. Update your system and install required libraries:
      sudo apt-get update
      sudo apt-get build-dep qt4-x11
      sudo apt-get build-dep libqt5gui5
      sudo apt-get install libudev-dev libinput-dev libts-dev libxcb-xinerama0-dev libxcb-xinerama0
      
  6. [on RPi] Prepare our target directory
    sudo mkdir /usr/local/qt5pi
    sudo chown pi:pi /usr/local/qt5pi
    
  7. [on host PC] Create our working directory and get a toolchain:
    mkdir ~/raspi
    cd ~/raspi
    git clone https://github.com/raspberrypi/tools
    
  8. [on host PC] Create a sysroot. Using rsync we can properly keep things synchronized in the future as well. Replace raspberrypi.local with the address of the Pi.
    mkdir sysroot sysroot/usr sysroot/opt
    rsync -avz pi@raspberrypi.local:/lib sysroot
    rsync -avz pi@raspberrypi.local:/usr/include sysroot/usr
    rsync -avz pi@raspberrypi.local:/usr/lib sysroot/usr
    rsync -avz pi@raspberrypi.local:/opt/vc sysroot/opt
    
  9. [on host PC] Adjust symlinks to be relative. Use provided script, because the old fixQualifiedLibraryPaths is not working properly:
    wget https://raw.githubusercontent.com/Kukkimonsuta/rpi-buildqt/master/scripts/utils/sysroot-relativelinks.py
    chmod +x sysroot-relativelinks.py
    ./sysroot-relativelinks.py sysroot
    
  10. [on host PC] Get qtbase and configure Qt. The target directory is /usr/local/qt5pi on the Pi, the host tools like qmake will go to ~/raspi/qt5, while make install will target ~/raspi/qt5pi (this is what we will sync to the device). Don't forget to adjust paths if you changed that. For some reason the ~/ in the paths may not work, if this the case just use full paths. You need to change <qt-version> with a proper Qt version (for example 5.6, or 5.9.1; note that version 5.9.1 is a tag not a branch, so you may want to create a local branch with it). You need to change <rpi-version> with a proper Raspberry Pi version. Use: linux-rasp-pi-g++ for RPi, linux-rasp-pi2-g++ for RPi2 and linux-rasp-pi3-g++ for RPi3. If your system is 64 bit you may also edit device option to:
    -device-option CROSS_COMPILE=~/raspi/tools/arm-bcm2708/gcc-linaro-arm-linux-gnueabihf-raspbian-x64/bin/arm-linux-gnueabihf-
    
    For higher Qt version (like 5.9.1) you may also need to add
    -no-use-gold-linker
    
    option. You probably also want to add -jn option to make command, where n is a number of cores you like to use for the complication.
    git clone git://code.qt.io/qt/qtbase.git -b <qt-version>
    cd qtbase
    ./configure -release -opengl es2 -device <rpi-version> -device-option CROSS_COMPILE=~/raspi/tools/arm-bcm2708/gcc-linaro-arm-linux-gnueabihf-raspbian/bin/arm-linux-gnueabihf- -sysroot ~/raspi/sysroot -opensource -confirm-license -make libs -prefix /usr/local/qt5pi -extprefix ~/raspi/qt5pi -hostprefix ~/raspi/qt5 -v
    
    make
    make install
    
    If you failed, you can clear everything with:
    git clean -dfx
    
  11. [on host PC] Deploy Qt to the device. We simply sync everything from ~/raspi/qt5pi to the prefix we configured above.
    cd ..
    rsync -avz qt5pi pi@raspberrypi.local:/usr/local
    
  12. [on host PC] Build an example up to test if everything went well. After proper build, copy an executable to the device.
    cd qtbase/examples/opengl/qopenglwidget
    ~/raspi/qt5/bin/qmake
    make
    
    scp qopenglwidget pi@raspberrypi.local:/home/pi
    
  13. [on RPi] Update the device to let the linker find the Qt libs:
    echo /usr/local/qt5pi/lib | sudo tee /etc/ld.so.conf.d/qt5pi.conf
    sudo ldconfig
    
    If you're facing issues with running the example, try to use 00-qt5pi.conf instead of qt5pi.conf, to introduce proper order.
  14. [on RPi] Fix the EGL/GLES libraries. The device may have the Mesa version of libEGL and libGLESv2 in /usr/lib/arm-linux-gnueabihf, resulting Qt apps picking these instead of the real thing from /opt/vc/lib. This may be fine for X11 desktop apps not caring about OpenGL performance but is totally useless for windowing system-less, fullscreen embedded apps. You may want to save the originals somewhere, just in case. Make sure you're in "/home/pi" aka "~" when you run these commands:
    sudo mv /usr/lib/arm-linux-gnueabihf/libEGL.so.1.0.0 /usr/lib/arm-linux-gnueabihf/libEGL.so.1.0.0_backup
    sudo mv /usr/lib/arm-linux-gnueabihf/libGLESv2.so.2.0.0 /usr/lib/arm-linux-gnueabihf/libGLESv2.so.2.0.0_backup
    sudo ln -s /opt/vc/lib/libEGL.so /usr/lib/arm-linux-gnueabihf/libEGL.so.1.0.0
    sudo ln -s /opt/vc/lib/libGLESv2.so /usr/lib/arm-linux-gnueabihf/libGLESv2.so.2.0.0
    sudo ln -s /opt/vc/lib/libbrcmEGL.so /opt/vc/lib/libEGL.so
    sudo ln -s /opt/vc/lib/libbrcmGLESv2.so /opt/vc/lib/libGLESv2.so
    
    Please make sure to also add missing symbolic links:
    sudo ln -s /opt/vc/lib/libEGL.so /opt/vc/lib/libEGL.so.1
    sudo ln -s /opt/vc/lib/libGLESv2.so /opt/vc/lib/libGLESv2.so.2
    
  15. [on RPi] Run example, that we've built before. At this point it should just work at fullscreen with 60 FPS and mouse, keyboard, and possibly touch support.
  16. [on host PC] Build other Qt modules as desired, the steps are always the same (you need to adjust <qt-module> and <qt-version>):
    git clone git://code.qt.io/qt/<qt-module>.git -b <qt-version>
    cd <qt-module>
    
    ~/raspi/qt5/bin/qmake
    make
    make install
    
    Then deploy new files by running:
    rsync -avz qt5pi pi@raspberrypi.local:/usr/local
    

Additional notes

Frequently asked question: I only get a low resolution like 640x480 or even 576x416 with black boxes. How to fix this?

As a quick fix, try adding disable_overscan=1 to /boot/config.txt and after a reboot check with /opt/vc/bin/tvservice what modes are available. For example, to switch to 1024x768:

$ /opt/vc/bin/tvservice -m DMT
Group DMT has 4 modes:
           mode 4: 640x480 @ 60Hz 4:3, clock:25MHz progressive 
           mode 9: 800x600 @ 60Hz 4:3, clock:40MHz progressive 
           mode 16: 1024x768 @ 60Hz 4:3, clock:65MHz progressive 
           mode 35: 1280x1024 @ 60Hz 5:4, clock:108MHz progressive 

$ /opt/vc/bin/tvservice -e "DMT 16 HDMI"
$ fbset -xres 1024 -yres 768

Troubleshooting

Enabling the logging categories under qt.qpa is a good idea in general. This will show some debug prints both from eglfs and the input handlers.

export QT_LOGGING_RULES=qt.qpa.*=true
./qopenglwidget

A typical output would like like this:

qt.qpa.egldeviceintegration: EGL device integration plugin keys: ("eglfs_brcm", "eglfs_kms")
qt.qpa.egldeviceintegration: EGL device integration plugin keys (sorted): ("eglfs_brcm", "eglfs_kms")
qt.qpa.egldeviceintegration: Trying to load device EGL integration "eglfs_brcm"
qt.qpa.egldeviceintegration: Using EGL device integration "eglfs_brcm"
Unable to query physical screen size, defaulting to 100 dpi.
To override, set QT_QPA_EGLFS_PHYSICAL_WIDTH and QT_QPA_EGLFS_PHYSICAL_HEIGHT (in millimeters).
qt.qpa.input: libinput: input device 'Logitech Optical USB Mouse', /dev/input/event0 is a pointer caps = relative-motion button
qt.qpa.input: libinput: input device 'Apple Inc. Apple Keyboard', /dev/input/event1 is a keyboard
qt.qpa.input: libinput: input device 'Apple Inc. Apple Keyboard', /dev/input/event2 is a keyboard
qt.qpa.input: libinput: input device 'Raspberry Pi Sense HAT Joystick', /dev/input/event3 is a keyboard
qt.qpa.input: Using xkbcommon for key mapping

Verify that eglfs_brcm is in use and that input devices are correctly found.

When using a touchscreen, setting the correct physical screen size may be essential to get properly scaled, finger friendly user interface elements with Qt Quick Controls. When using ordinary monitors via HDMI, the default 100 dpi may be acceptable.

It is also wise to carefully check the output of configure (saved as config.summary) before proceeding to build qtbase. Check that the following are marked as 'yes':

Support enabled for:
  ...
  Evdev .................. yes
  FontConfig ............. yes
  FreeType ............... yes (system library)
  ...
  libinput................ yes
  ...
  OpenGL / OpenVG: 
    EGL .................. yes
    OpenGL ............... yes (OpenGL ES 2.0+)
  QPA backends: 
    EGLFS ................ yes
      ...
      EGLFS Raspberry Pi . yes
    ...
    LinuxFB .............. yes
    ...
  udev ................... yes
  xkbcommon-evdev......... yes

Missing EGLFS Fix

On recent versions of Qt (e.g. 5.10.1), the qmake.conf file for linux-rasp-pi3-g++ doesn't work, however, linux-rasp-pi-g++ does. Create a new qmake.conf based on linux-rasp-pi-g++ with the build flags from the Pi 3 spec copied over.

Another fix is the replacement of the broken lines:

VC_LIBRARY_PATH = $$[QT_SYSROOT]/opt/vc/lib
VC_INCLUDE_PATH = $$[QT_SYSROOT]/opt/vc/include
VC_LINK_LINE = -L$${VC_LIBRARY_PATH}
QMAKE_LIBDIR_OPENGL_ES2 = $${VC_LIBRARY_PATH}

Regarding keyboard input

By default Qt attempts to disable the keyboard and hide the cursor on application startup. This is very handy since this way keystrokes will not go to the console (which is enabled by default in a normal Raspbian image) "underneath". However, at the moment this will all silently fail when starting an application remotely via ssh. This is the explanation for the (harmless) 9;15] and similar prints and the keyboard input unexpectedly going to the console as well. As a workaround, start apps directly on the console. Alternatively, you could experiment with getting rid of the first TTY by doing sudo systemctl disable getty@tty1.service and reboot. (tty2 and others remain usable)

Environment variables

If you get an error such as "This application failed to start because it could not find or load the Qt platform plugin "eglfs" in "".", when attempting to run a Qt app on the RPi, you may need to set some environment variables.

export QT_QPA_PLATFORM=eglfs
export QT_QPA_PLATFORM_PLUGIN_PATH=/usr/local/qt5pi/plugins/platforms
export LD_LIBRARY_PATH=/usr/local/qt5pi/lib

Qt Creator

Once Qt is on the device, Qt Creator can be set up to build, deploy, run and debug Qt apps directly on the device with one click.

Go to Options -> Devices
  Add
    Generic Linux Device
    Enter IP address, user & password
    Finish
Go to Options -> Compilers
  Add
    GCC
    Compiler path: ~/raspi/tools/arm-bcm2708/gcc-linaro-arm-linux-gnueabihf-raspbian/bin/arm-linux-gnueabihf-g++
Go to Options -> Debuggers
  Add
    ~/raspi/tools/arm-bcm2708/gcc-linaro-arm-linux-gnueabihf-raspbian-x64/bin/arm-linux-gnueabihf-gdb
Go to Options -> Qt Versions
  Check if an entry with ~/raspi/qt5/bin/qmake shows up. If not, add it.
Go to Options -> Build & Run
  Kits
    Add
      Generic Linux Device
      Device: the one we just created
      Sysroot: ~/raspi/sysroot
      Compiler: the one we just created
      Debugger: the one we just created
      Qt version: the one we saw under Qt Versions
      Qt mkspec: leave empty

Done. At this point you should be able to start a new project with the new kit, build and deploy it, etc.

Note: While things will usually just work for applications, developing libraries and in particular, Qt modules may be problematic when it comes to deployment. The per-project Run tab under Projects -> Build & Run is your friend. In some cases the target deployment paths will just be wrong. Life is too short for worrying about all the intricate details of Creator and the build system. Therefore, if all else fails, use Add Deploy Step ("Make" and "Custom Process Step" are extremely handy, anything can be made working with a combination of make install, rsync and scp) and change Run configuration to Custom Executable.

Sense HAT

To access the sensors and leds on the Sense HAT, you can use the unofficial Qt Sense HAT module on qt-labs. Check it out via git and build it like any other Qt module.

The joystick shows up as an ordinary evdev device providing key events so it will just work. Regarding the leds and sensors, see the README.

Qt Multimedia

Unfortunately the GStreamer-based multimedia stuff is not quite usable at the time of writing - accelerated video works only sometimes (and with glitches), while the camera is just broken.

As an alternative to Qt Multimedia, try using OpenMAX directly. For an open implementation refer to this project. For the Raspberry Pi Camera Module take a look at the raspistill application sources for an example on how to get the camera preview image into an OpenGL texture.

If you wish to experiment with Qt Multimedia, try the following:

Before building Qt Multimedia 5.6, make sure the following are installed:

sudo apt-get install gstreamer1.0-omx libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev

Do not forget to sync the headers and libs back to the sysroot on the host PC and re-run the sysroot-relativelinks.py script.

Once the GStreamer 1.0 dependencies are in place, make sure Qt Multimedia is built with 1.0 support:

~/raspi/qt5/bin/qmake -r GST_VERSION=1.0

To verify that the accelerated OpenMAX path is used for H.264 videos, do export GST_DEBUG=omx:4 before running a video playback app like the qmlvideofx example.