.\" Automatically generated by Pandoc 2.2.1
.\"
.TH "MXT-APP" "1" "" "" ""
.hy
.SH NAME
.PP
mxt\-app \- command line utility for maXTouch devices
.SH SYNOPSIS
.PP
mxt\-app [\f[I]command\f[]] [\f[I]options\f[]]\&...
.SH DESCRIPTION
.PP
mxt\-app is a utility for managing Atmel maXTouch touch controllers and
other devices that support Atmel Object Based Protocol.
.PP
If no \f[I]command\f[] is not given, mxt\-app will provide an
interactive menu based interface.
.SH OBJECT PROTOCOL
.PP
The Atmel Object Based Protocol defines how device registers (normally
accessed via I2C) are mapped to different functions within the devices.
This interface organises the register map into separate objects each of
which is given a T number.
\f[I]mxt\-app\f[] can inspect and alter the object configuration, and
view diagnostic data, while the device is running.
.PP
For a description of object protocol, see \f[I]Atmel AT42QT1085 Object
Protocol Guide\f[], available from atmel.com.
.PP
The meaning of the configuration bytes within the objects may be found
in the Protocol Guide documentation released with each device, and is
only provided by Atmel under NDA.
.SH GENERAL COMMANDS
.TP
.B \f[C]\-h\ [\-\-help]\f[]
Display a brief summary of available options and exit.
.RS
.RE
.TP
.B \f[C]\-i\ [\-\-info]\f[]
Print the ID information and object table.
.RS
.RE
.TP
.B \f[C]\-M\ [\-\-messages]\ [*timeout*]\f[]
Prints the messages until \f[I]timeout\f[] seconds have passed.
If no \f[I]timeout\f[] is provided, continue until user presses Ctrl\-C.
Zero timeout reads once.
Provide \f[C]\-F\ [\-\-msg\-filter]\f[] option to filter by a specific
object.
.RS
.RE
.TP
.B \f[C]\-F\ [\-\-msg\-filter]\ *TYPE*\f[]
Filters messages by object \f[I]TYPE\f[].
.RS
.RE
.TP
.B \f[C]\-\-reset\f[]
Reset device.
.RS
.RE
.TP
.B \f[C]\-\-calibrate\f[]
Send calibrate command.
.RS
.RE
.TP
.B \f[C]\-\-backup[*=COMMAND*]\f[]
Backup configuration to NVRAM where the optional argument,
\f[I]COMMAND\f[], is the BACKUPNV command.
.RS
.RE
.TP
.B \f[C]\-g\f[]
Write Golden Reference calibration to NVRAM.
.RS
.RE
.TP
.B \f[C]\-\-self\-cap\-tune\-config\f[]
Tune and calibrate the self capacitance settings and store them to the
device configuration.
.RS
.RE
.TP
.B \f[C]\-\-self\-cap\-tune\-nvram\f[]
Tune and calibrate the self capacitance settings and store them to NVRAM
without updating the Config Checksum.
.RS
.RE
.TP
.B \f[C]\-\-version\f[]
print version of mxt\-app.
.RS
.RE
.TP
.B \f[C]\-\-block\-size\ *BLOCKSIZE*\f[]
Sets the i2c block size.
.RS
.RE
.SH CONFIGURATION FILE COMMANDS
.TP
.B \f[C]\-\-load\ *FILE*\f[]
Upload config from \f[I]FILE\f[], write it to NVRAM, and reset device.
The configuration may be in \f[C]\&.xcfg\f[] or \f[C]OBP_RAW\f[] format.
.RS
.RE
.TP
.B \f[C]\-\-save\ *FILE*\f[]
Save config to \f[I]FILE\f[] in either \f[C]OBP_RAW\f[] or
\f[C]\&.xcfg\f[] format.
.RS
.RE
.TP
.B \f[C]\-\-checksum\ *FILE*\f[]
Read the contents of \f[I]FILE\f[] and recalculate the configuration
checksum.
.RS
.RE
.SH REGISTER READ/WRITE COMMANDS
.TP
.B \f[C]\-R\ [\-\-read]\f[]
Read data from the device.
.RS
.RE
.TP
.B \f[C]\-W\ [\-\-write]\f[]
Write data to the device.
.RS
.RE
.TP
.B \f[C]\-n\ [\-\-count]\ *COUNT*\f[]
read/write \f[I]COUNT\f[] registers
.RS
.RE
.TP
.B \f[C]\-f\ [\-\-format]\f[]
format register output
.RS
.RE
.TP
.B \f[C]\-I\ [\-\-instance]\ *INSTANCE*\f[]
select object \f[I]INSTANCE\f[]
.RS
.RE
.TP
.B \f[C]\-r\ [\-\-register]\ *REGISTER*\f[]
start at \f[I]REGISTER\f[] (offset in object when used with
\f[I]TYPE\f[])
.RS
.RE
.TP
.B \f[C]\-T\ [\-\-type]\ *TYPE*\f[]
select object \f[I]TYPE\f[]
.RS
.RE
.TP
.B \f[C]\-\-zero\f[]
zero all configuration settings
.RS
.RE
.SS EXAMPLES
.SS Read info block:
.IP
.nf
\f[C]
$\ mxt\-app\ \-R\ \-n7\ \-r0
82\ 19\ 11\ AA\ 18\ 0E\ 16
\f[]
.fi
.SS Read T7 Power Config object:
.IP
.nf
\f[C]
$\ mxt\-app\ \-R\ \-T7
32\ FF\ 05\ 43
\f[]
.fi
.SS Zero first two bytes of T7:
.IP
.nf
\f[C]
$\ mxt\-app\ \-W\ \-T7\ 0000
\f[]
.fi
.SS Read T7 Power Config object, formatted output:
.IP
.nf
\f[C]
$\ mxt\-app\ \-R\ \-T7\ \-\-format
GEN_POWERCONFIG_T7

00:\ 0x00\ \ \ \ 0\ 0000\ 0000
01:\ 0x00\ \ \ \ 0\ 0000\ 0000
02:\ 0x05\ \ \ \ 5\ 0000\ 0101
03:\ 0x43\ \ \ 67\ 0100\ 0011
\f[]
.fi
.SH TCP SOCKET COMMANDS
.PP
\f[I]mxt\-app\f[] supports connection over TCP using a ASCII protocol
which allows mxt\-app to act as a bridge so that Atmel proprietary tools
such as \f[I]Object Server\f[] can access the device.
.TP
.B \f[C]\-C\ [\-\-bridge\-client]\ *HOST*\f[]
Connect over TCP to \f[I]HOST\f[]
.RS
.RE
.TP
.B \f[C]\-S\ [\-\-bridge\-server]\f[]
Start TCP socket server
.RS
.RE
.TP
.B \f[C]\-p\ [\-\-port]\ PORT\f[]
TCP port (default 4000)
.RS
.RE
.SH BOOTLOADER COMMANDS
.TP
.B \f[C]\-\-bootloader\-version\f[]
Query and print ID and version of bootloader.
.RS
.RE
.TP
.B \f[C]\-\-flash\ *FIRMWARE*\f[]
Flash \f[I]FIRMWARE\f[] to device.
The firmware file should be in \f[C]\&.enc\f[] format.
.RS
.RE
.TP
.B \f[C]\-\-reset\-bootloader\f[]
Reset device in bootloader mode.
In bootloader mode the device will cease normal operation until a
firmware is sent.
The I2C address or USB PID will change.
The only valid command in this mode is \f[C]\-\-flash\f[].
A hard power cycle will return the device to normal Object Protocol
mode, unless the firmware image is corrupted.
This command is only provided for debugging purposes: in most cases
\f[C]\-\-flash\f[] will manage the change to/from bootloader mode
before/after flash.
.RS
.RE
.TP
.B \f[C]\-\-firmware\-version\ *VERSION*\f[]
The .enc file format does not provide the firmware version in a form
available to mxt\-app.
If it is provided via this switch, mxt\-app can check firmware
\f[I]VERSION\f[] before and after flash.
It will skip the flash process if the firmware version is already
correct.
It will also check for a successful flash on completion.
The version must be provided in the format \f[C]1.0.AA\f[].
# T25 SELF TEST OPTIONS
.RS
.RE
.PP
The Self Test T25 object runs self\-test routines in the device to find
faults in the sense lines and electrodes.
The Self Test T25 object runs a series of test sequences.
.TP
.B \f[C]\-t\ [\-\-test]\f[]
Run all self tests.
.RS
.RE
.TP
.B \f[C]\-t*XX*\ [\-\-test=*XX*]\f[]
Run individual self test specified by the \f[I]CMD\f[] hex value.
.RS
.RE
.TP
.B \f[C]\-t01\f[]
run analog power test.
.RS
.RE
.TP
.B \f[C]\-t11\f[]
run pin fault test.
.RS
.RE
.TP
.B \f[C]\-t12\f[]
run pin fault 2 test.
.RS
.RE
.TP
.B \f[C]\-t13\f[]
run AND gate test.
.RS
.RE
.TP
.B \f[C]\-t17\f[]
run signal limit test.
.RS
.RE
.TP
.B \f[C]\-t20\f[]
run gain test.
.RS
.RE
.TP
.B \f[C]\-t21\f[]
run offset fault test.
.RS
.RE
.SH T37 DIAGNOSTIC DATA OPTIONS
.PP
Capture frames of diagnostic data.
The default mode is to capture touch deltas.
Self capacitance measurements are only available on some devices.
.TP
.B \f[C]\-\-debug\-dump\ *FILE*\f[]
The T37 Diagnostic Data object provides raw access to touch
reference/delta measurements from the touch screen.
Diagnostic data is written to \f[I]FILE\f[] in CSV format.
The format is compatible with the Atmel Hawkeye utility.
.RS
.RE
.TP
.B \f[C]\-\-frames\ *N*\f[]
Capture \f[I]N\f[] frames of data.
.RS
.RE
.TP
.B \f[C]\-\-references\f[]
Capture references data.
.RS
.RE
.TP
.B \f[C]\-\-self\-cap\-signals\f[]
Capture self cap signals.
.RS
.RE
.TP
.B \f[C]\-\-self\-cap\-deltas\f[]
Capture self cap deltas.
.RS
.RE
.TP
.B \f[C]\-\-self\-cap\-refs\f[]
Capture self cap references.
.RS
.RE
.TP
.B \f[C]\-\-active\-stylus\-deltas\f[]
Capture active stylus deltas.
.RS
.RE
.TP
.B \f[C]\-\-active\-stylus\-refs\f[]
Capture active stylus references.
.RS
.RE
.SH T68 SERIAL DATA COMMANDS
.TP
.B \f[C]\-\-t68\-file\ *FILE*\f[]
Upload \f[I]FILE\f[] to the device via the T68 Serial Data object.
.RS
.RE
.TP
.B \f[C]\-\-t68\-datatype\ *DATATYPE*\f[]
Set \f[I]DATATYPE\f[] of the file.
This will be automatically detected from the file itself in most cases.
.RS
.RE
.SH BROKEN LINE DETECTION
.PP
The broken line test scans the diagnostic data to identify touch sensor
defects.
.TP
.B \f[C]\-\-broken\-line\f[]
Run the broken line detection algorithm on the device
.RS
.RE
.TP
.B \f[C]\-\-dualx\f[]
Indicate if sensor X lines are double connected
.RS
.RE
.TP
.B \f[C]\-\-x\-center\-threshold\ N\f[]
Set threshold for X lines in center of sensor to N percent
.RS
.RE
.TP
.B \f[C]\-\-x\-border\-threshold\ N\f[]
Set threshold for X lines at edge of sensor to N percent
.RS
.RE
.TP
.B \f[C]\-\-y\-center\-threshold\ N\f[]
Set threshold for Y lines in center of sensor to N percent
.RS
.RE
.TP
.B \f[C]\-\-y\-border\-threshold\ N\f[]
Set threshold for Y lines at edge of sensor to N percent
.RS
.RE
.TP
.B \f[C]\-\-pattern\ *PATTERN*\f[]
set sensor \f[I]PATTERN\f[] material to ITO or Xsense
.RS
.RE
.SH SENSOR VARIANT ALGORITHM
.PP
The sensor variant algorithm calculates all nodes of a channel to find
the trend line of the reference.
A comparison is done between the real and expected sensor reference.
.TP
.B \f[C]\-\-sensor\-variant\f[]
Perform the Sensor Variant algorithm
.RS
.RE
.TP
.B \f[C]\-\-dualx\f[]
Indicate if sensor X lines are double connected
.RS
.RE
.TP
.B \f[C]\-\-fail\-if\-any\f[]
Fail the Sensor Variant test on any defects
.RS
.RE
.TP
.B \f[C]\-\-max\-defects\ N\f[]
Maximum No.\ of continuous defects
.RS
.RE
.TP
.B \f[C]\-\-upper\-limit\ N\f[]
Upper limit for regression, in percentage %
.RS
.RE
.TP
.B \f[C]\-\-lower\-limit\ N\f[]
Lower limit for regression, in percentage %
.RS
.RE
.TP
.B \f[C]\-\-matrix\-size\ N\f[]
The allowed matrix size
.RS
.RE
.SH FINDING AND SPECIFYING DEVICE
.PP
By default mxt\-app will scan available devices and connect to the first
device it finds.
.TP
.B \f[C]\-q\ [\-\-query]\f[]
Scan for devices and output a list.
.RS
.RE
.TP
.B \f[C]\-d\ [\-\-device]\ *DEVICESTRING*\f[]
Connect to a particular device specified by \f[I]DEVICESTRING\f[] which
is given in the same format as output by \f[C]\-\-query\f[].
.RS
.RE
.PP
There are three connection methods supported for hardware access:
.SS sysfs
.PP
This is used in conjunction with the Linux kernel driver.
It accesses sysfs attributes under the directory
.IP
.nf
\f[C]
/sys/bus/i2c/drivers/dddddddd/b\-00xx/
\f[]
.fi
.PP
Where
.TP
.B d
driver name \- \f[C]atmel_mxt_ts\f[], \f[C]Atmel\ MXTXXXX\f[], etc
.RS
.RE
.TP
.B b
i2c adapter
.RS
.RE
.TP
.B xx
i2c address
.RS
.RE
.PP
A specific USB device can be specified by giving a device option
\f[C]\-d\ sysfs:PATH\f[] as given by \f[C]\-q/\-\-query\f[] option
.PP
The sysfs attributes used under this directory are
.TP
.B \f[C]mem_access\f[]
Access to raw I2C address space.
.RS
.RE
.TP
.B \f[C]debug_enable\f[]
Output messages from the device to dmesg log as hexadecimal.
.RS
.RE
.TP
.B \f[C]debug_v2_enable\f[], \f[C]debug_msg\f[], \f[C]debug_notify\f[]
Optional improved binary interface to retrieve messages
.RS
.RE
.PP
They are provided when using the Atmel kernel driver from github, and
may be supported by other devices.
.SS USB
.PP
Many maXTouch devices support a USB mode which reports touches via USB
HID.
In addition, evaluation boards may use a \[lq]bridge chip\[rq] which
interfaces I2C to the same protocol.
.PP
USB mode will be built by autotools when libusb is available.
.PP
A specific USB device can be specified by giving a device option
\f[C]\-d\ usb:001\-003\f[] which corresponds to the bus and device
numbers given by the \f[C]\-q/\-\-query\f[] option and lsusb.
.SS I2C debug interface
.PP
Devices can be accessed directly via the \f[I]i2c\-dev\f[] I2C debug
interface by giving adapter and address on command line.
.PP
The i2c\-dev interface is documented in the Linux kernel source, in
Documentation/i2c/dev\-interface
.PP
The I2C debug interface support must be enabled using the
\f[C]CONFIG_I2C_CHARDEV\f[] kernel configuration option.
It is enabled on a system if files \f[C]/dev/i2c\-*\f[] are present.
.PP
To use i2c\-dev, provide a device string such as
\f[C]\-d\ i2c\-dev:1\-004a\f[].
.PP
Messages from the maXTouch devices are read by polling.
If a kernel driver is also present on the system, reading messages on
interrupt, then no messages will be received by the tool.
A workaround is to set T18.COMMAND (byte 1) to 2 \[lq]Force the CHG line
high (inactive)\[rq] so the kernel driver does not receive an interrupt.
.PP
There is no scanning support.
This is because reading from every possible maXTouch address on every
I2C bus might adversely affect some unrelated hardware that does not
understand Object Protocol.
You must manually identify the correct adapter and address by reference
to the protocol guide or to the platform setup.
.PP
It is possible to use the \f[C]\-\-flash\f[] command with a device
already in bootloader mode, by specifying the bootloader address.
.SS HIDRAW
.PP
The hidraw backend supports maXTouch devices which connect using USB or
HID over I2C.
.PP
The hidraw interface is documented in the Linux kernel source, in
Documentation/hid/hidraw.txt
.PP
The device must have /dev/hidraw raw HID device support enabled using
the CONFIG_HIDRAW kernel configuration option.
.PP
To use hidraw, provide a device string such as
\f[C]\-d\ hidraw:/dev/hidraw0\f[].
.PP
There is no scanning support.
.PP
Bootloading is not supported in this mode.
.SH DEBUG OPTIONS
.TP
.B \f[C]\-v\ [\-\-verbose]\ *LEVEL*\f[]
set debug level.
\f[I]LEVEL\f[] is one of 0 (Silent), 1 (Warnings and Errors), 2 (Info \-
default), 3 (Debug), 4 (Verbose).
Debug and Verbose are only available if built in.
.RS
.RE
.SH EXIT VALUES
.TP
.B 0
Success
.RS
.RE
.TP
.B 1
Internal error/assert
.RS
.RE
.TP
.B 2
Input/output error
.RS
.RE
.TP
.B 3
Memory allocation failure
.RS
.RE
.TP
.B 4
Timeout
.RS
.RE
.TP
.B 5
Could not find a device or device went away
.RS
.RE
.TP
.B 6
Permission denied
.RS
.RE
.TP
.B 7
Operation not allowed for this device type
.RS
.RE
.TP
.B 8
Interrupt function call
.RS
.RE
.TP
.B 9
Object not available on device
.RS
.RE
.TP
.B 10
Received unexpected invalid message from message processor
.RS
.RE
.TP
.B 11
Self test invalid test command
.RS
.RE
.TP
.B 12
Self test AVdd Analog power is not present
.RS
.RE
.TP
.B 13
Self test Pin fault
.RS
.RE
.TP
.B 14
Self test AND Gate Fault
.RS
.RE
.TP
.B 15
Self test Signal limit fault
.RS
.RE
.TP
.B 16
Self test Gain error
.RS
.RE
.TP
.B 17
Information block checksum error
.RS
.RE
.TP
.B 18
Bootloader already unlocked
.RS
.RE
.TP
.B 19
Bootloader CRC failure (transmission failure)
.RS
.RE
.TP
.B 20
File format error
.RS
.RE
.TP
.B 21
Device firmware already required version
.RS
.RE
.TP
.B 22
Could not identify bootloader address
.RS
.RE
.TP
.B 23
Version on device did not match version given after bootloading
operation
.RS
.RE
.TP
.B 24
Device did not reset
.RS
.RE
.TP
.B 25
Device in unexpected state
.RS
.RE
.TP
.B 26
Incorrect command line parameters or menu input given
.RS
.RE
.TP
.B 27
Bridge TCP protocol parse error
.RS
.RE
.TP
.B 28
Bridge connection error
.RS
.RE
.TP
.B 29
Serial data download failed
.RS
.RE
.TP
.B 30
No such file or directory
.RS
.RE
.TP
.B 31
Error processing self cap command
.RS
.RE
.SH COMPILING FROM SOURCE
.PP
To download the source code using git:
.IP
.nf
\f[C]
git\ clone\ https://github.com/atmel\-maxtouch/mxt\-app.git
\f[]
.fi
.PP
There are two build harnesses, for Android and autotools:
.SS Android
.PP
To download libusbdroid submodule:
.IP
.nf
\f[C]
git\ submodule\ init
git\ submodule\ update
\f[]
.fi
.PP
To compile using Android NDK:
.IP
.nf
\f[C]
ndk\-build
\f[]
.fi
.PP
To enable debug:
.IP
.nf
\f[C]
ndk\-build\ NDK_DEBUG=1
\f[]
.fi
.PP
To enable PIE support (for Android L):
.IP
.nf
\f[C]
ndk\-build\ APP_PLATFORM=android\-16
\f[]
.fi
.PP
Binaries will be placed in libs/
.PP
The Android NDK is available from
https://developer.android.com/tools/sdk/ndk/
.SS Running on Android
.IP
.nf
\f[C]
adb\ push\ libs/armeabi/mxt\-app\ /data/local/tmp/
adb\ shell\ /data/local/tmp/mxt\-app\ [command]
\f[]
.fi
.PP
If executable permissions have not been set, run:
.IP
.nf
\f[C]
adb\ shell\ chmod\ 777\ /data/local/tmp/mxt\-app
\f[]
.fi
.SS autotools
.PP
To compile using autotools:
.IP
.nf
\f[C]
\&./autogen.sh\ &&\ make
\f[]
.fi
.PP
To cross\-compile:
.IP
.nf
\f[C]
\&./autogen.sh\ \-\-host=arm\-linux\-gnueabi\ &&\ make

or,\ 

\&./autogen.sh\ \-\-host=arm\-linux\-gnueabihf\ &&\ make
\f[]
.fi
.PP
To enable debug:
.IP
.nf
\f[C]
\&./autogen.sh\ \-\-enable\-debug
\f[]
.fi
.PP
To enable generation of the man page using pandoc:
.IP
.nf
\f[C]
\&./autogen.sh\ \-\-enable\-man
\f[]
.fi
.PP
To build the doxygen documentation (this requires doxygen and graphviz
to be installed):
.IP
.nf
\f[C]
make\ doc
\f[]
.fi
.SH VERSION NUMBERING
.PP
A version number is generated by \f[C]git\ describe\f[] during the build
process and is reported by \f[C]\-\-version\f[] and to debug logs.
.PP
A typical version might be \f[C]1.15\-29\-g8321\f[] which means, 29
commits after the release tag 1.15, with a git SHA id beginning with
8321.
.PP
If the source is not checked out using git (for example by clicking on
the github \[lq]Download ZIP\[rq] link), then the version from the file
VERSION in the source archive is used.
.PP
The suffix \f[C]\-mod\f[] is appended if there are uncommitted changes
in the source code.
.SH TROUBLESHOOTING
.SS klogctl error
.PP
If you see the warning
.IP
.nf
\f[C]
W:\ klogctl\ error\ 1\ (Operation\ not\ permitted)
\f[]
.fi
.PP
this indicates that mxt\-app has been unable to retrieve messages from
dmesg.
Various features will not work properly.
It may be possible to unrestrict dmesg by doing
.IP
.nf
\f[C]
#\ echo\ 0\ >\ /proc/sys/kernel/dmesg_restrict
\f[]
.fi