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

Touch Screen Calibration (Torizon)

Introduction

This article will show how you can calibrate a resistive touch screen under Weston on Torizon by using weston-touch-calibrator. Weston is started in a special mode where it exposes the calibration API. Therefore, a separate container is used. See the man page of weston.ini for more information.

The process consists of two steps:

  1. Evaluation and Prototyping: apply the correct calibration using the weston-touch-calibrator container.
  2. Development and Production: capture the changes using the TorizonCore Builder Tool into your custom Torizon OS image.

This article complies with the Typographic Conventions for Torizon Documentation

Prerequisites

Evaluation and Prototyping: Calibration

As a first step, all running containers need to be stopped. You can achieve that by running the following command:

# docker stop $(docker ps -q)

Then you need to start the weston-touch-calibrator container:

# docker run -ti --rm --privileged -v /dev:/dev -v /run/udev/:/run/udev/ -v /etc/udev/rules.d:/etc/udev/rules.d torizon/weston-touch-calibrator:$CT_TAG_WESTON_TOUCH_CALIBRATOR

You should see a calibration screen on the display. When you touch all crosses the display should fall back to the Weston desktop. You can try to start a terminal since the calibration matrix should already be applied. After that, you can stop the container by pressing Ctrl+C and reboot the module. Afterward, Weston should automatically apply the new calibration matrix.

If you experience an error message somewhat like this, it might be because you're using a different connector:

# weston-touch-calibrator error: "DPI-1" was not found

The default connector for the display calibration is DPI-1, and you'll need to pass the new one through the HEAD environment variable. Lets say you are using a LVDS-1 connector, you should add this argument to the docker run command -e HEAD=LVDS-1, like this:

# docker run -ti --rm -e HEAD=LVDS-1 --privileged -v /dev:/dev -v /run/udev/:/run/udev/ -v /etc/udev/rules.d:/etc/udev/rules.d torizon/weston-touch-calibrator:$CT_TAG_WESTON_TOUCH_CALIBRATOR

To identify which connector you are using, you could install the package libdrm-tests in one of our Debian Containers for Torizon, such as torizon/weston:

(Optional) pull the torizon/weston container image:

# docker pull torizon/weston:$CT_TAG_WESTON

Start the weston compositor:

# docker run -it --rm --entrypoint /bin/bash -v /dev:/dev --device-cgroup-rule='c 226:* rmw' torizon/weston:$CT_TAG_WESTON

And inside the docker install the libdrm-tests package:

## apt update && apt install libdrm-tests

Then you can follow this guide to collect the connector information.

Development and Production

You must use the TorizonCore Builder Tool, the recommended method for Torizon OS customization, for capturing the changes into your own Torizon OS custom image.

Here is a summary of what you need to do:

  • Use the isolate command to capture the changes.
  • Optionally, capture other various customization with dt and splash commands.
  • Use the union command to commit the changes into a OSTree branch.
  • Use the deploy command to deploy to a board or Torizon OS image.
  • Use the push command to push your custom Torizon OS image to Torizon Cloud.

Advanced: Background

This section is useful for debugging if something goes wrong. It is not required for plain usage of weston-touch-calibrator.

Weston reads the calibration matrix of a touchscreen from the udev environment of the input device. You can check the environment by running the following command:

# udevadm info /dev/input/event1
P: /devices/platform/5a800000.i2c/i2c-16/16-002c/input/input1/event1
N: input/event1
L: 0
S: input/by-path/platform-5a800000.i2c-event
S: input/touchscreen0
E: DEVPATH=/devices/platform/5a800000.i2c/i2c-16/16-002c/input/input1/event1
E: DEVNAME=/dev/input/event1
E: MAJOR=13
E: MINOR=65
E: SUBSYSTEM=input
E: USEC_INITIALIZED=8598804
E: ID_INPUT=1
E: ID_INPUT_TOUCHSCREEN=1
E: ID_PATH=platform-5a800000.i2c
E: ID_PATH_TAG=platform-5a800000_i2c
E: LIBINPUT_CALIBRATION_MATRIX=1.039948 0.011494 -0.031650 0.009743 -1.089353 1.047852
E: DEVLINKS=/dev/input/by-path/platform-5a800000.i2c-event /dev/input/touchscreen0

Weston applies LIBINPUT_CALIBRATION_MATRIX to all input values of the touchscreen. The output after the transformation is the pixel position of where the touchscreen was pressed. The weston-touch-calibrator container creates a udev rule and stores it under /etc/udev/rules.d/touchscreen.rules. The rule corresponds to the last line in the following file:

# cat /etc/udev/rules.d/touchscreen.rules
# There are a number of modifiers that are allowed to be used in some
# of the different fields. They provide the following subsitutions:
#
# %n the "kernel number" of the device.
# For example, 'sda3' has a "kernel number" of '3'
# %e the smallest number for that name which does not matches an existing node
# %k the kernel name for the device
# %M the kernel major number for the device
# %m the kernel minor number for the device
# %b the bus id for the device
# %c the string returned by the PROGRAM
# %s{filename} the content of a sysfs attribute
# %% the '%' char itself
#

# Create a symlink to any touchscreen input device
SUBSYSTEM=="input", KERNEL=="event[0-9]*", ATTRS{modalias}=="input:*-e0*,3,*a0,1,*18,*", SYMLINK+="input/touchscreen0"
SUBSYSTEM=="input", KERNEL=="event[0-9]*", ATTRS{modalias}=="ads7846", SYMLINK+="input/touchscreen0"
SUBSYSTEM=="input", KERNEL=="event[0-9]*", ENV{ID_INPUT_TOUCHSCREEN}=="1", ENV{LIBINPUT_CALIBRATION_MATRIX}="1.039948 0.011494 -0.031650 0.009743 -1.089353 1.047852"

Because /etc/udev/rules.d is mapped to the host system, the change made by the container will automatically apply to the host system as well.

Dockerfile

The Dockerfile is available in the Toradex Github repository: torizon-containers.



Send Feedback!