Skip to main content
Version: Torizon OS 7.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:



Send Feedback!