Calibrating touch

Updated: April 19, 2023

You can calibrate your screen using a few different methods.

Setting the mode parameter in your scaling configuration file determines the type of configuration. Depending on your touch display, you need to set the mode parameter to either direct or scaled. Your scaling configuration file is the scaling.conf file located at /etc/system/config, see Scaling configuration file for more information.

Below are the different methods to calibrate your touch display:
  1. manual: Use the calib as a mode in the scaling configuration file. For more information, see calib option.
  2. direct mapping: This method is used for resistive touch displays. For more information, see Direct mapping.”
  3. scaled: This method is used for capacitive touch displays. For more information, see Scaled calibration.”

Direct mapping

This calibration method is useful for resistive touch displays or displays that can scale values on the hardware (e.g., Atmel controller).

To use this method, do the following:
  1. Set the mode parameter to direct in the scaling configuration file.
  2. After the touch driver and Screen service successfully run, start the calib-touch utility. After Screen completes running, a calibration file is created and loaded into Screen's translation matrix. For more information about the calib-touch utility, see calib-touch section in this guide.

Scaled calibration

This calibration method works with capacitive touch displays. Once they are mounted, the values are static and don't skew over time.

Scaling mode maps the touch area to the display resolution. To use this method, you need to find the display resolution and the matrix size of your touch display.

Display resolution

First, set the scaling mode to scale and include your display's resolution. The resolution is obtained from the graphics.conf and needs to be set in the scaling configuration file. For example, your graphics.conf may look like this:

begin display 1
  cursor=on
  video-mode = 800 x 480 @ 60          
  formats = rgb565 rgba8888 rgb888 yuy2
end display       
     

In this example, the resolution is 800x480. Update the scaling mode in the scaling.conf file and set it to scale:

800x480:mode=scale                 
     
Touch display matrix size

Next, set the width and height properties to the maximum X and Y values of your touch area. Place these values in your touch.conf file located at /etc/system/config. Your configuration may look like this:

begin mtouch
  driver = hid
  options = width=4095,height=4095,your_other_options
end mtouch
            
CAUTION:

The width and height options do not refer to your display resolution. They refer to the maximum X and Y values from your touch area. How to find these values is described below.

How to find the touch display matrix size

USB/HID based touch controllers:

Use the output from hidview -R to search for the Usage(X/Y) and the associated Logical Max(value). On some systems, the Logical Max(value) is referred to as the Physical Max(value). In the following output example, both the X and Y values are 4095:

...                
Logical Max(4095)
Report Size(16)
Report Count(1)
PUSH
Unit Exponent(14)
Unit(51)
Usage(X)
...
Logical Max(4095)
Usage(Y)
...
       

Other Controllers:

Please refer to your controller documentation.

Finding the maximum values directly from the touch display

Finding the maximum values using the touch display is imprecise. If you are unable to find the maximum X and Y using the above instructions, do the following:

  1. Set the scaling mode in scaling.conf to direct:
    800x480:mode=direct                     
           
  2. Start your touch display driver:
    mtouch &                      
          
  3. Run the screeninfo utility:
    screeninfo -w -input /dev/screen/input                        
         
  4. Touch the four corners of your screen and note the output from screeninfo. One of the values should be a reasonable approximation to your maximum X,Y values. Since this method is imprecise, you can round up. For example, if you obtained a value of 4034 for X, the maximum X is most likely 4095.
  5. Set the width and height properties to the maximum X and Y values in the touch.conf file:
     begin mtouch
      driver = hid
      options = width=4095,height=4095,your_other_options
    end mtouch                    
       
  6. Change the scaling mode in scaling.conf back to scale:
    800x480:mode=scale                     
       

It's important to mention that this method doesn't correct misaligned touch displays, but if the origin isn't in the upper-left corner of the display, you can use the invert_x and invert_y options to reverse the directions of the coordinates. For more information, see Settings for various HID displays in the mtouch section of this guide.