Touch configuration file

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 a 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.

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.

ballistic_coefficients

A set of 16 integers that specify coefficients to
use ballistic coefficients to minimize the noise normally seen
on successive touch events that follow a low-speed ballistic trajectory.
The lower the speed of the ballistic movement (e.g., a stationary finger),
the more gain reduction is applied to the speed of the
movement. By doing so, the result is a solid touch with no
noise. This is specified as 16 integers delimited by a comma.
For example, 1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16.

device_name

A String value that specified the name of the device.

driver

The name of the touch driver to use. This is board specific.
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 type of connection used for the display. These are the
String values you can use for this parameter:

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,296) that specifies the
sampling rate (in microseconds) of the touch controller.
You won't get two touch samples within a time less than that
configured here. The effectiveness of this configuration is
driver-dependent.

scaling

A String value that specified 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 the 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 could use to 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:

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.

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 is 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.
The mtouch service has verbose output
if the -v option is set.

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' does receive touch data then the touchscreen is
configured correctly in screen and the issue may be calibration.

. Check the parameters in the touch configuration file (mtouch.conf).
It's important to note that the width and height
doesn'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.

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 screen or have chosen to
run calib-touch, this must be run every time
screen and mtouch
starts. If a calibration file exists, then it simply loads the
calibration matrix and applies the settings to
Screen Graphics Subsystem(Screen)
Touch service.

Note: It's important to remember that Screen
doesn't apply the matrix settings otherwise on its own.