Select the version of your OS from the tabs below. If you don't know the version you are using, run the command cat /etc/os-release or cat /etc/issue on the board.
Remember that you can always refer to the Torizon Documentation, there you can find a lot of relevant articles that might help you in the application development.
Linux systems with a graphical output need a graphics stack. There are two famous ones: X, also known as X11 or X.Org, and Wayland which aims at replacing X.
Wayland is a protocol and it requires a compositor implementation. The reference implementation, widely used, is the Weston compositor.
From our software releases 5.x onward, Toradex only supports Wayland/Weston. For Torizon, Toradex provides a Weston container, which is configured from its command line parameters, and a configuration file named weston.ini.
This article explains how to customize the default configuration. It does not replace the Wayland documentation.
This article complies to the Typographic Conventions for the Toradex Documentation.
To have a better understanding of this article, the following prerequisites are recommended:
Weston uses a configuration file named weston.ini for its setup.
The Toradex container has a Weston startup script. While executing docker run, you can pass a --developer switch that allows either of the following files to be passed to Weston:
/etc/xdg/weston/weston.ini: used by default, if the --developer switch is not present./etc/xdg/weston-dev/weston.ini: used when you start the Weston container with the --developer switch.An example of how to use the switch is available in the article Debian Containers for Torizon.
Before proceeding, create your own weston.ini, where you will store your custom configuration.
Attention: The weston.ini file is sensitive to trailing whitespaces after configuration names and options. If a configuration is not applied correctly, check if there are whitespaces between text and line breaks.
There are two options to apply changes:
For evaluation and prototyping you can bind mount the weston.ini file. This will overwrite the existing configuration weston.ini file. To do it, add a volume flag to the docker run command:
-v <path_to_directory_containing_weston.ini_file>:/etc/xdg/weston/
For development and production build your own Weston Docker image overriding the weston.ini file. Here is an example:
DockerfileARG IMAGE_ARCH=linux/arm # For arm64v8 use: # ARG IMAGE_ARCH=linux/arm64 ARG BASE_NAME=weston # For arm64v8 with Vivante use: # ARG BASE_NAME=weston-vivante # Check out https://developer.toradex.com/torizon/working-with-torizon/provided-containers/torizoncore-containers-tags-and-versioning ARG IMAGE_TAG=2 ARG DOCKER_REGISTRY=torizon FROM --platform=$IMAGE_ARCH $DOCKER_REGISTRY/$BASE_NAME:$IMAGE_TAG AS base COPY weston.ini /etc/xdg/weston/
Alternatively, rebuild our weston image replacing the weston.ini configuration file.
You are encouraged to read the following articles for tips on how to do it:
In this section, customization that is often used by our customers is presented to you.
Note that if you start with the pre-defined weston.ini file, many of the settings listed here will be present but commented out. Please make sure to uncomment all matching lines to ensure the functionality you requested is available.
The screen can be rotated or flipped by adding the following to the weston.ini file:
[output]
name=HDMI-A-1
transform=rotate-90
The name value can be found by executing weston-info from inside the running Weston container.
Additional transform values can be found in the weston.ini man page.
Switching between virtual terminals can be enabled by changing these lines in weston.ini file:
[keyboard]
vt-switching=true
Press Ctrl+Alt+F1 till F6 key combinations to switch between virtual terminals. To come back to the graphical session, press Ctrl+Alt+F7.
With Wayland, it is possible to transfer touch events from the Wayland server to the client application. However, some applications are not aware of these events (e.g. QtWidgets). Therefore, they will not react to touch events and it is not possible to click buttons, etc.
touch2pointer is an application created by Toradex that operates directly on top of the touchscreen's evdev interface and creates a virtual pointer device. This makes it possible to use such applications. However, you will lose some of the capability of touchscreens (like multitouch).
How to use:
Calibrate the touchscreen with Weston touch calibrator if it is a resistive touch. Make sure you set the LIBINPUT_CALIBRATION_MATRIX variable to the calibration matrix.
Create a udev rule that makes Weston/libinput ignore the touch device ENV{LIBINPUT_IGNORE_DEVICE}="1". For example:
SUBSYSTEM=="input", KERNEL=="event0", ENV{ID_INPUT_TOUCHSCREEN}=="1", ENV{LIBINPUT_CALIBRATION_MATRIX}="1.034599 -0.008149 -0.013808 0.026801 -1.130055 1.058165"
SUBSYSTEM=="input", KERNEL=="event0", ENV{LIBINPUT_IGNORE_DEVICE}="1"
Start touch2pointer with touchscreen as an argument.
This can be useful in touch displays that use the mouse as input, as it is desirable to make the cursor transparent.
You can change the mouse cursor by adding a custom X11 cursor named left_ptr in an icon theme folder like for instance /usr/share/icons/hicolor/cursors/ and enabling it in weston.ini:
[shell]
locking=false
cursor-theme=hicolor
cursor-size=32
A transparent cursor can be found on this GitHub repo. This has been tested and confirmed to work in the Weston container.
The kiosk container found in Web Browser / Kiosk Mode with TorizonCore with Chromium uses its own mouse cursor by default. This can be overwritten by putting inside the container the custom left_ptr in /usr/share/icons/Adwaita/cursors/.
With version 9.0 Weston introduced the kiosk-shell.
Weston uses the desktop-shell by default. To use kiosk-shell, add the following to the core section in weston.ini file:
[core]
shell=kiosk-shell.so
This section does not explain how to enable displays or change their resolution. You might need to do it before being able to use a multi-display setup. Please refer to Setting up Displays with Torizon for more details.
Weston container extends its surface to all displays connected to the same DRM interface and display controller. Currently, Weston is unable to manage outputs, connected to multiple DRM interfaces. But it's possible to launch two instances of Weston, each on its own DRM interface. Due to this limitation, some multi-display combinations on i.MX8X modules don’t work.
To check whether displays are on the same DRM interface:
ls /sys/class/drm
Current out-of-box multi-display support:
| Module | Display combination | Splash screen displayed on | Weston screen displayed on | DRM card |
|---|---|---|---|---|
| Apalis iMX6 | Parallel RGB + LVDS + HDMI | all displays | all displays | |
| Apalis iMX8X | Parallel RGB + LVDS + HDMI | Parallel RGB and LVDS | Parallel RGB | card0-DPI-1, card1-HDMI-A-1, card1-LVDS-1 |
| Apalis iMX8X | Parallel RGB + HDMI | all displays | Parallel RGB | card0-DPI-1, card1-HDMI-A-1 |
| Apalis iMX8X | LVDS + HDMI | LVDS | LVDS | card0-HDMI-A-1, card0-LVDS-1 |
| Apalis iMX8X | Parallel RGB + LVDS | all displays | Parallel RGB | card0-DPI-1, card1-LVDS-1 |
| Apalis iMX8 | LVDS + HDMI | splash screen not supported | all displays | |
| Colibri iMX6 | Parallel RGB + HDMI | all displays | all displays | |
| Colibri iMX8X | Parallel RGB + HDMI | all displays | Parallel RGB | card0-DPI-1, card1-HDMI-A-1 |
Wayland client application
When starting another container with your Wayland client application, the window will be drawn on top of the Wayland compositor (Weston). On multi-display setup, the Wayland client application will be by default displayed on the top left output or depending on the position of the mouse cursor.
Unless explicitly stated otherwise.
In the next sections, you will get details on how to run a multi-display setup. To help you get started, use the examples from the Torizon Samples - Multi-display:
On modules with two DRM interfaces (i.MX8X), it's possible to launch two instances of Weston, each on its own DRM interface.
To launch two instances of Weston, each output should be associated with a seat name. Therefore we set ID_SEAT property of the device. There are two ways of doing it, either by running the following for example:
sudo loginctl attach seat1 /sys/class/drm/card1
Or by creating an udev rule for example. This method allows you to Capture Changes in the Configuration of a Board on TorizonCore at a later moment, so you can prepare you custom image with the configuration applied:
# cat /etc/udev/rules.d/72-seat-drm-platform-display-subsystem.rules
TAG=="seat", ENV{ID_FOR_SEAT}=="drm-platform-display-subsystem", ENV{ID_SEAT}="seat1"
After that, a reboot is required to load the udev rule.
Launching instance of Weston on the seat1 (DRM card1):
docker run -e ACCEPT_FSL_EULA=1 -d --rm --name=weston --net=host --cap-add CAP_SYS_TTY_CONFIG \
-v /dev:/dev -v /tmp:/tmp -v /run/udev/:/run/udev/ \
--device-cgroup-rule='c 4:* rmw' --device-cgroup-rule='c 13:* rmw' \
--device-cgroup-rule='c 199:* rmw' --device-cgroup-rule='c 226:* rmw' \
torizon/weston-vivante:$CT_TAG_WESTON_VIVANTE --developer weston-launch \
--tty=/dev/tty7 --user=torizon -- --seat=seat1
Launching instance of Weston on seat0 (DRM card0). Since only one card is OpenGL capable, software rendering (--use-pixman) is used:
docker run -e ACCEPT_FSL_EULA=1 -d --rm --name=weston2 --net=host --cap-add CAP_SYS_TTY_CONFIG \
-v /dev:/dev -v /tmp:/tmp -v /run/udev/:/run/udev/ \
--device-cgroup-rule='c 4:* rmw' --device-cgroup-rule='c 13:* rmw' \
--device-cgroup-rule='c 199:* rmw' --device-cgroup-rule='c 226:* rmw' \
torizon/weston-vivante:$CT_TAG_WESTON_VIVANTE --developer weston-launch \
--tty=/dev/tty8 --user=torizon -- --seat=seat0 --use-pixman
Start weston-terminal on card0:
docker run -e ACCEPT_FSL_EULA=1 -d --rm --name=wayland-app2 --user=torizon -e WAYLAND_DISPLAY=wayland-1 \
-v /dev/dri:/dev/dri -v /dev/galcore:/dev/galcore -v /tmp:/tmp \
--device-cgroup-rule='c 199:* rmw' --device-cgroup-rule='c 226:* rmw' \
torizon/weston-vivante:$CT_TAG_WESTON_VIVANTE weston-terminal
Beware that multiple tty sessions can not be "active" simultaneously. So switching to the virtual terminal of card1 (tty7) is required.
sudo chvt 7
Start weston-simple-egl on card1:
docker run -e ACCEPT_FSL_EULA=1 -d --rm --name=wayland-app --user=torizon \
-v /dev/dri:/dev/dri -v /dev/galcore:/dev/galcore -v /tmp:/tmp \
--device-cgroup-rule='c 199:* rmw' --device-cgroup-rule='c 226:* rmw' \
torizon/weston-vivante:$CT_TAG_WESTON_VIVANTE weston-simple-egl
If a single instance Weston using a single DRM interface is running on multiple displays, having different outputs is possible by using kiosk-shell and app-ids.
To do this, the app id of the Wayland application needs to be found out. The application defines its ID using the set_app_id request. The environment WAYLAND_DEBUG must be used to see what your application is setting.
For example, run the following command inside a container with your application:
WAYLAND_DEBUG=1 <MY_APP_NAME> 2>&1 | grep app
And the output would be something like that:
[1292031.851] -> xdg_toplevel@26.set_app_id("my-app-name")
In that case, my-app-name would be the app-id.
Then add for example to the weston.ini file the following:
[output]
name=DPI-1
app-ids=my-app-name
[output]
name=HDMI-A-1
app-ids=my-app-name-2
That would display each application on it's own output.
Showing the output on a particular display can also be achieved by disabling the specific display in the weston.ini file:
[output]
name=HDMI-A-1
mode=off
To clone the output from one display to another, change the weston.ini file:
[output]
name=HDMI-A-1
same-as=HDMI-A-2
Weston's clone mode is currently limited to sharing the display timings between all displays.
Weston supports setting the resolution in the configuration file. In our Weston configuration files, weston.ini and weston-dev.ini from the weston Docker image for Torizon, we add comments to illustrate how to do it.
For more details, refer to the weston-drm documentation.
Graphical applications in some cases do not run on a board that does not have a display connected. But it can be useful for example to validate graphical apps on CI pipelines, or remote access a board while sharing it with others during a development phase.
By forcing the connector state it is possible to run and access a GUI without a display connected. Depending on your board, force it as a root user with a command similar to:
echo on > /sys/class/drm/card1-HDMI-A-1/status
Weston has a built-in screencast recording which can be started and stopped by pressing the <mod-key> + r combination. To check the modifier-key value, just search for binding-modifier in weston.ini file.
## grep binding-modifier /etc/xdg/weston/weston.ini
binding-modifier=super
Note: If weston.ini does not have the definition of a modifier key, you can define it in the file as binding-modifier=super, for example.
Screencasts are saved to the file capture.wcap in the working directory of Weston. Since the WCAP format is specific to Weston, it's necessary to convert the capture to YUV pixel format (.y4m). The pixel file is saved to the file capture.y4m with the following command:
## wcap-decode --yuv4mpeg2 capture.wcap > capture.y4m
Note: To play the recorded screencast, you need to convert the YUV pixel file (capture.y4m) to a format that a media player understands.
To capture a screenshot you can press <mod-key> + s combination. The captured picture is saved in PNG format and stored in the working directory.
Additional configuration options can be found in the weston.ini man page and in the arch linux wiki.
It may also be useful to consult the following articles:
