Skip to main content
Version: Torizon OS 7.x.y

Setting up Displays with Torizon

Introduction​

During the development cycle of a product with a GUI, you usually go through 3 phases when it comes to displays:

Evaluation: often, you will do a basic evaluation using a regular monitor over VGA/DVI-D/HDMI - or similar interfaces, if available. We provide an out-of-the-box experience, where you plug in the monitor and power-on the hardware.

Proof of Concept/Prototype: even with the advantages of cross-development tools and IDEs enabling a good experience for developing GUIs in a development computer, it is often common to make tests on the real end device. We sell touch screen displays that either deliver an out-of-the-box experience or a relatively easy configuration.

Development and Production: often, you want or need a custom display in your final product. The reasons are various: price, robustness, brightness, size, interface, EMI compliance, among others. Supporting a custom display is not an easy task for a beginner, mainly if you use a display with insufficient documentation and Linux support. We document how to enable a custom display, but you must expect that some effort is associated with the process.

Toradex tests and recommends using the following displays with its Computer on Modules (CoM) during early phases of development:

It is often necessary to modify the Linux Device Tree to integrate a display to the board and configure its pin and timing settings. Device Tree Overlays provide a way to alter the overall device tree without the need for re-compiling the complete Device Tree.

For the display listed previously, Toradex provides an easy way to set-up and get it running with ready-to-use device tree overlays. It also means that you can tweak the existing overlays to support other displays as well. This article lists the available Device Tree Overlays provided by Toradex and how to enable it on Torizon OS.

This article complies with the Typographic Conventions for Torizon Documentation.

Using a Monitor​

All computer on modules have a default display interface enabled by default. Unless explicitly stated otherwise, the following interfaces are enabled by default:

  • Colibri Family: RGB interface, commonly connected to VGA, DVI-A, or the Unified Display Interface on our carrier boards.
    • You can use a VGA monitor, with possibly a DVI-A to VGA connector depending on the carrier board you are using.
    • With the default fixed VGA resolution, the Portainer application may seem "too big" for the display. Read Display Output, Resolution and Timings (Linux) for more information on changing the display resolution.
  • Apalis Family: HDMI interface, commonly connected to a DVI-D or the standard HDMI connector on our carrier boards.
    • You can use an HDMI or DVI monitor, depending on the carrier board you are using.
  • Verdin Family: MIPI DSI interface, commonly exposed on a board-to-board connector that can receive multiple display adapters, as our Verdin DSI to HDMI Adapter which is enabled by default, the Verdin DSI to LVDS Adapter which would require additional configuration, or the Verdin DSI Display Adapter which would require additional configuration.
    • You can use an HDMI monitor, through the Verdin DSI to HDMI adapter.

Learn more by checking the pre-enabled Device Tree Overlays

Configure Toradex Displays​

You must apply some device tree overlays to make a specific display work. We already provide all overlays for the displays from our webshop, you just have to:

After you enable the display, check the section at the end of this article on how to test the display and touch.

Find the Correspondent Device Tree Overlays​

See below the list of available Display Device Tree Overlays provided by Toradex:

Displays​

info

Default resolution with these overlays: 1920x1080

Native Interface:

ModuleStarting from versionOverlay
Verdin iMX8M Plus6.1.0verdin-imx8mp_hdmi_overlay.dtbo
Apalis iMX8 QuadMax6.1.0apalis-imx8_hdmi_overlay.dtbo
Apalis iMX8 QuadPlus6.1.0apalis-imx8_hdmi_overlay.dtbo
Apalis iMX66.0.0apalis-imx6_hdmi_overlay.dtbo
Colibri iMX66.0.0colibri-imx6_hdmi_overlay.dtbo

Using Verdin DSI to HDMI adapter:

ModuleStarting from versionOverlay
Verdin iMX8M Plus6.1.0verdin-imx8mp_dsi-to-hdmi_overlay.dtbo
Verdin iMX8M Mini6.1.0verdin-imx8mm_dsi-to-hdmi_overlay.dtbo
Verdin AM626.4.0verdin-am62_dsi-to-hdmi_overlay.dtbo

Using Colibri DSI to HDMI adapter:

ModuleStarting from versionOverlay
Colibri iMX8X6.2.0colibri-imx8x_dsihdmi_overlay.dtbo

Enable and Deploy Device Tree Overlays​

For instructions about how to enable the overlays, see the Device Tree Overlays on Torizon article.

Configure Other Displays with Torizon​

We recommend using the device tree overlay to support a specific display to specify the exact display resolution and timings. We recommend looking at the Device Trees on Toradex System on Modules article for sample implementations and modify them according to your display resolution and timings. For more information on usage for overlays, check the instructions in the previous section.

Remember to check your display's datasheet. Every manufacturer provides display timings in a slightly different way.

The Horizontal period must be the sum of hbackporch + hactive + hfront_porch + hsync-len and the _Vertical period must be the sum of vback_porch + vactive + vfront_porch + vsync-len. Hsync-len and vsync-len parameters are not allowed to be zero sometimes.

Check our examples for a starting point. Copy the most appropriate in the test.DTS you have created in a previous step:

LVDS display example: Capacitive Touch Display 10.1" LVDS Overlay

DSI display example: Capacitive Touch Display 10.1" DSI Overlay

Parallel RGB display example: Capacitive Touch Display 7" Parallel Overlay

Other examples: Toradex Device Tree Overlays on GitHub

To deploy your customized Device Tree Overlay, check the instructions in the previous section. After you enable the display, check the section at the end of this article on how to test the display and touch.

Touch Screen Calibration​

To calibrate your touch screen, please read the article Touch Screen Calibration (Torizon).

Testing Display and Touch​

After enabling the Device Tree Overlays, deploying it, and rebooting the board, you can check if the Linux system can find your display. To do that on the command-line, use:

# find /sys/devices -name "edid"

The first step to launch weston-terminal is to launch and execute the Weston Wayland Compositor container (which is a Debian Bookworm release based) to see a GUI with touch support. To pull the weston container and start it on the module, choose your hardware from the tabs below and follow the instructions given:

# docker container run -d --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 253:* rmw" \
    --device-cgroup-rule="c 13:* rmw" --device-cgroup-rule="c 226:* rmw" \
    --device-cgroup-rule="c 10:223 rmw" --device-cgroup-rule="c 199:0 rmw" \
    torizon/weston-imx8:4 \
    --developer
info

To learn more about the device_cgroup_rules section of the docker-compose file above, please refer to the Hardware Access through Control Group Rules (cgroup) section of the Torizon Best Practices Guide

After sending the command above, Weston should start on your display and you are ready to start your Wayland applications. Then, to launch the weston-terminal, follow the instructions below:

In order to launch a container named wayland-app and start the weston-terminal, run this command:

danger

Please, note that by executing the following line you are accepting the terms and conditions of the NXP's End-User License Agreement (EULA)

# docker run -e ACCEPT_FSL_EULA=1 -d --rm --name=wayland-app  \
    -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-imx8:4 weston-terminal

After sending the command, Weston should start on the configured displays.

Weston with Wayland Terminal opened (Click on the upper left corner icon to open the terminal)

Display Output, Resolution and Timings​

Torizon OS uses the Linux Direct Rendering Manager (DRM) with Kernel Mode Setting (KMS). Learn more on the DRM/KMS section from our article Display Output, Resolution and Timings (Linux). To follow some of the instructions that use the modetest program, you can install the package libdrm-tests in one of our Debian Containers for Torizon, such as torizon/weston:

## apt update && apt install libdrm-tests

Common Display Configuration With Weston​

Customers are often interested in configurations such as rotating the display by 90 degrees or using multiple displays concurrently.

Many of these configurations can be done with Weston. Read the article Working with Weston on Torizon OS to learn more.



Send Feedback!