mtouch Parent topic: mtouch

Touch configuration file

Updated: April 19, 2023

The mtouch section specifies the configuration to apply touch devices (also called mtouch devices for multitouch devices) supported by the platform.

The touch configuration file (default name is mtouch.conf) file is a free-form ASCII text file parsed by mtouch service. The file can contain extra tabs and blank lines for formatting purposes. Keywords in the file are case-sensitive. Comments can be placed anywhere within the file (except within quotes). Comments begin with the # character and end at the end of the line.

The section must begin with begin mtouch and end with end mtouch only if your system supports touch devices, or if there are applications on your system that require them.

There can be multiple mtouch sections in your configuration file. The number of mtouch sections must match the number of physical displays that your platform supports. You can specify different parameters (such as drivers) in each mtouch section to match the display.

Below is an example of an mtouch section of a /etc/system/config/mtouch.conf on a target. This file is board-specific and therefore part of the Board Support Package (BSP) for the board you want to use.
Note: You can specify a different path and different name for the configuration file if you use the -c option to start the mtouch driver. For more information, see mtouch. 
begin mtouch
  driver = hid
  options = vid=0x0eef,did=0x7200,verbose=6,width=4096,height=4096,max_touchpoints=1
end mtouch

Parameters for the mtouch section

The following are valid parameters that can be configured under the mtouch section: It's common to use display, scaling, driver, and options.

device_name
A string value that specifies the name of the device.
driver
The name of the touch driver to use. The name is specific to each board. The mtouch service uses the following algorithm to determine the touch drivers to load: "libmtouch-" + driver name + ".so" For example, you have driver names such as, egalax, focaltech, hid, or lg-tsc101, which correspond to libmtouch-egalax.so, libmtouch-focaltech.so, libmtouch-hid.so, and libmtouch-lg-tsc101.so.
Note: The libmtouch-hid.so driver is used for displays connected to the board. Typically the displays are connected using HDMI or DVI and a USB cable. For examples of various settings to use for different displays, see “Example of various displays to use.” For information about troubleshooting working with HID devices, see “Troubleshooting HID display issues.”
display
The display identifier (Integer) or the type of connection used for the display (String).

As an Integer, specify the identifier of the display that's associated with this touch device. The display ID is identified in the display subsections of your graphics configuration file (e.g., graphics.conf). You can also retrieve the display ID from the SCREEN_PROPERTY_ID property of a Screen display object by using the Screen API.

As a String, the values that you can use for this parameter are:

  • composite: The display is connected via a composite connection.
  • dvi: The display is connected via a DVI connection.
  • hdmi: The display is connected via an HDMI connection.
  • internal: The display is connected to the board.
  • rgb: The display is connected via RGB signal of the component connection.
  • rgbhv: The display is connected via the RBGHV signal of the component connection.
  • svideo: The display is connected via S-Video video.
  • YPbPr: The display is connected via component video, specifically the YPbPr signal of the component connection.
min_event_interval
An unsigned integer (0 - 4,294,967,295) that specifies the sampling rate (in microseconds) of the touch controller. This specified time represents the minimum time between two touch samples. The effectiveness of this configuration is driver-dependent.
scaling
A string value that specifies the location of the scaling.conf file. You can specify a different name. If this parameter isn't specified, the expected location and filename on your system is: /etc/system/config/scaling.conf
scaling_factor
Overrides the scaling factor from the touch matrix to the mode parameter specified in the scaling.conf file. The value for this parameter can be specified as a decimal value, such as 2.5.
options
The options configuration is driver-dependent. The string that you configure is passed verbatim to the driver itself. For example, it can be used to set the height and width (in pixels) of a rectangular touch surface. In this case, you would set the maximum values X and Y values for the touch controller hardware.

This configuration must be in the form of option_name=value, delimited with a comma (,) for multiple options. For example:

vid=vendorID ,did=productID ,max_touchpoints=number_of_touchpoints ,lvds=interface

Here are some examples:

  • height=4096
  • width=4096
  • vid=0x0eef
  • did=0x7200
  • lvds=720
  • verbose=6
  • max_touchpoints=2

For more information, see the BSP user's guide for your board.

Settings for various HID displays

In general, the entries you can use for options parameter are specific to the touch controller hardware. For HID, these are the common generic options that are available:

did
The USB Device ID or Product ID.
height
The touchscreen's maximum Y-coordinate value.
invert_x
The X-coordinate is inversed. Set to 0 (zero) to turn this off or 1 to set it on. The default is off.
invert_y
The Y-coordinate is inversed. Set to 0 (zero) to turn this off or 1 to set it on. The default is off.
verbose
Set the verbosity level of the logging messages to screen. You can set the number from 0 to 6. A higher number indicates a higher number of logs. The default is 0 (zero) if not specified.
vid
The USB Vendor ID.
width
The touchscreen's maximum X-coordinate value.

To determine the width and height values, you run your driver in the mode:direct first and get the output from the events binary to see the largest X and Y values from the system logs by running the mtouch service in verbose mode. Alternatively, you can get the output from the hidview -R (logical maximum X and Y) or contact your vendor to get them for your HID display. For more information about the hidview, see “hidview” section in the QNX Neutrino Utilities Reference.

Here are some of the settings for the following displays:

Troubleshooting HID issues

Here are some troubleshooting practices if you are having problems working with your HID device: Should the touchscreen not appear to work with HMI ensure the following:
  • Check that the USB controller works. You must start the USB controller when you use a HID touch controller. To check if the USB controller shows up, run the command usb -vvv command. If it doesn't, check that:
    • you have the correct driver started and on your target board
    • the touch controller is powered on. For example, for the Lilliput display, the touch controller won't appear from the USB if there's no power to the display or there's no video to the monitor.
  • The controller shows up when you run the hidview command.

    If not, ensure that io-hid is started with the devh-usb.so module and that no errors occurred.

  • When mtouch is started check slog2info for any errors. You can increase the verbosity of the drivers by passing the verbose option in the configuration file for the driver. Use the -v option to set the verbosity level of the mtouch service.
  • Slay HMI processes and start with screen and mtouch. Then run the binary events to see if it receives touch events from the controller. If the binary events receives touch data, this confirms that the touchscreen is configured correctly in Screen and the issue may be in the calibration.
  • Check the parameters in the touch configuration file (mtouch.conf). It's important to note that the width and height don't specify the display resolution, but the the touch resolution (i.e., MaxX and MaxY values). You can run the hidview -R command to obtain the width and height values. The values are delimited by the HID report Logical Max for the X and Y reports.
  • Check the settings in the scaling configuration file (scaling.conf). There must be a matching configuration for the display resolution and this needs to be set correctly based on whether calibration is used or not.

    mode=scale means, don't use with calibration, the Touch framework calculates the scaling based on the width and height specified in options parameter in the touch configuration file (mtouch.conf) and the resolution of the display.

    The mode, mode=direct, means to use the calib-touch because the framework doesn't perform any scaling and sends the coordinates straight through, unaltered.

  • If you are using a resistive touchscreen or have chosen to run calib-touch, calib-touch must be run every time screen and mtouch starts. If a calibration file exists, then calib-touch simply loads the calibration matrix and applies the settings to Screen Graphics Subsystem (Screen) service.
    Note: It's important to remember that Screen doesn't apply the matrix settings otherwise on its own.
Parent topic: mtouch