Search by Tags

Working with Weston on TorizonCore

 

Article updated at 02 Aug 2021
Subscribe for this article updates

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.

Torizon 5.4.0

Introduction

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.

Prerequisites

To have a better understanding of this article, the following prerequisites are recommended:

Configuration options

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.

How to apply configuration options

There are two options to apply changes:

  • Bind mount a custom configuration file.
  • Rebuild a Weston container with the custom configuration file.

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 rebuild the Weston Docker image using your weston.ini file.

You are encouraged to read the following articles for tips on how to do it:

Customization

In this section, customization that is often used by our customers is presented to you.

Screen rotation

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

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.

touch2pointer

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.

kiosk-shell

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

Multi-display

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 it’s 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 it's 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.

Launching two instances of Weston

On modules with two DRM interfaces (i.MX8X), it's possible to launch two instances of Weston, each on it's 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 

Redirecting the output

If Weston 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.

Disabling specific 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

Mirroring

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.

Next Steps / Additional Resources

Additional configuration options can be found in the weston.ini man page.