Documentation / Troubleshooting / How to read touchscreen input reports

How to read touchscreen input reports

Introduction and orientation

First check whether Linux can see the touch device. Then compare reported contacts in two situations: when nobody touches the screen, and when someone on site deliberately touches a known point. This shows whether the controller reports contacts that do not match reality; it does not automatically identify the cause or a repair.

Checks and troubleshooting

The remote console and Linux tools can help reveal what is happening with touch input — from the office or during an on-site visit. Diagnostics help test assumptions before a firmware update, recalibration or replacement of the touch layer, potentially avoiding unnecessary work. They do not replace hardware inspection.

Start with monitoring, then ask a specific question

First check the latest report’s timestamp and connected USB devices in device monitoring. A recognised controller does not mean it reports correct touches. That is what the following check helps you verify.

1. Identify the symptoms

  • No response: check whether the touch device is detected and connected.
  • Response in the wrong place: check touch orientation and mapping in device settings.
  • Irregular or unsolicited responses: compare reported contacts with nobody touching the screen and during a deliberate touch.
  • Delay: distinguish delayed input from a slow application response; a state snapshot alone does not measure latency.
Separate touch input from the application’s response

If a remote mouse works but physical touch does not, this alone does not confirm a faulty touch panel. Compare the input reported by Linux with the application’s response. Under Wayland, changing XInput settings may not affect the input used by the player; setting the same matrix again is not a repair.

2. Check what the touch device reports

Expand the command below and run it in the remote console. It takes a single snapshot and changes nothing. First make sure nobody is touching the screen and save the output. Then repeat it with someone touching a known point on site. The command does not record what happens between those two readings.

Show the command for a one-time check
python3 - <<'PY'
#!/usr/bin/env python3
"""Read-only Linux evdev snapshot. No reset, grab, calibration or writes.

Requires Python 3, Linux generic ioctl layout (e.g. x86/ARM) and permission
to read /dev/input/event*. Type-B contacts are queried from kernel state.
Raw axes precede compositor rotation/calibration. Run again to compare.
"""
import array
import fcntl
import glob
import os

def query(fd, number, size, initial=None):
    data = bytearray(size) if initial is None else bytearray(initial)
    fcntl.ioctl(fd, (2 << 30) | (size << 16) | (ord('E') << 8) | number, data, True)
    return data

def absinfo(fd, code):
    a = array.array('i')
    a.frombytes(query(fd, 0x40 + code, 24))
    return a

def slots(fd, code, count):
    a = array.array('i', [code] + [0] * count)
    data = query(fd, 0x0a, len(a) * a.itemsize, a.tobytes())
    result = array.array('i'); result.frombytes(data)
    return result[1:]

def position(value, limits):
    lo, hi = limits[1], limits[2]
    return 'n/a' if hi <= lo else '{:.1f}%'.format(100 * (value - lo) / (hi - lo))

def main():
    found = denied = 0
    for path in sorted(glob.glob('/dev/input/event*')):
        try:
            fd = os.open(path, os.O_RDONLY | os.O_NONBLOCK)
        except PermissionError:
            denied += 1; continue
        except OSError as error:
            print(path, error); continue
        try:
            bits = query(fd, 0x20 + 3, 64)
            has = lambda code: bool(bits[code // 8] & (1 << (code % 8)))
            keys = query(fd, 0x20 + 1, 96)
            touch_supported = bool(keys[330 // 8] & (1 << (330 % 8)))
            multi = has(47) and has(57) and has(53) and has(54)
            if not multi and not (touch_supported and has(0) and has(1)):
                continue
            found += 1
            name = query(fd, 0x06, 256).split(b'\0', 1)[0].decode(errors='replace')
            print('\nDevice:', path, name)
            print('Snapshot only; coordinates are raw sensor axes, not screen pixels.')
            if multi:
                count = absinfo(fd, 47)[2] + 1
                if not 1 <= count <= 256:
                    print('Unsupported slot count:', count); continue
                tracking = slots(fd, 57, count)
                xs, ys = slots(fd, 53, count), slots(fd, 54, count)
                xr, yr = absinfo(fd, 53), absinfo(fd, 54)
                active = [i for i, value in enumerate(tracking) if value >= 0]
                print('Active contacts:', len(active))
                for i in active:
                    print('Slot', i, 'ID', tracking[i], 'X=', xs[i], position(xs[i], xr),
                          'Y=', ys[i], position(ys[i], yr))
            else:
                print('No type-B contact count; single-touch state only.')
                x, y = absinfo(fd, 0), absinfo(fd, 1)
                print('X=', x[0], position(x[0], x), 'Y=', y[0], position(y[0], y))
            if touch_supported:
                state = query(fd, 0x18, 96)
                print('BTN_TOUCH:', bool(state[330 // 8] & (1 << (330 % 8))))
        except OSError as error:
            print(path, 'Cannot read this device:', error)
        finally:
            os.close(fd)
    if not found:
        print('No supported candidate read. This does not prove hardware failure.')
    if denied:
        print('Permission denied for', denied, 'input device(s). Contact authorised support.')

if __name__ == '__main__':
    main()

PY

You can run the same check with the downloadable diagnostic script.

Technical note for administrators

The script requires Linux, Python 3 and permission to read /dev/input/event*. It installs nothing, changes no calibration, disconnects no driver and does not block input to other applications. The list may include other pointing inputs; identify the correct controller by name. The contact count may be unavailable for an unsupported input type. If permission is denied, ask your provider for help rather than broadly changing access permissions.

If the console returns only SEND OK

An acknowledgement of sending is not command output or proof of completion. If the console stops returning results, particularly after the rendering application has been stopped, do not interpret silence as an empty diagnostic finding. Arrange independent verification through an authorised maintenance connection or on site. See also the remote console usage guidance.

3. Interpret contacts and coordinates

What to look forWhat it means
DeviceThe input device’s name and identifier in Linux. Find your touch controller by name.
Active contactsThe number of currently reported contacts for a supported multitouch controller. Expect zero when nobody is touching it.
Slot / IDIdentifies a contact; it is not a numbered location on the screen.
X / YThe position reported by the sensor. Percentages are not automatically pixels or distances from the left and top.
BTN_TOUCHTrue means a touch is reported and False means it is not, when the device provides this information.

Illustrative output, not a measurement from your device:

Device: /dev/input/eventN Example touch controller
Active contacts: 1
Slot 0 ID 12 X= 600 50.0% Y= 1100 100.0%
BTN_TOUCH: True

How to proceed from the result

  • Contacts remain reported when nobody touches the screen: compare their positions with known touches and inspect the corresponding area, edge or enclosure. This is a clue for inspection, not confirmation of dirt or a fault.
  • Contacts match actual touches but the application does not respond: check orientation and mapping in the touch orientation settings. A correct input snapshot alone does not prove a correct application response.
  • The device is not listed or reading fails: save the output and send it to your provider. Permissions, unsupported input or connectivity may be involved; the listing alone does not prove a fault.
Technical note for administrators

X and Y are raw sensor axes; percentages describe position within the range reported by the driver. They are not automatically screen pixels or distances from the left and top. Rotation, calibration and mapping may alter the relationship. Compare known touches to locate a physical point. Values are not read atomically: repeat the command if contacts move.

A contact that remains reported without anyone touching can direct inspection to a particular location. It helps test assumptions before updating firmware or replacing parts without evidence. It does not establish dirt, mechanical pressure, controller state or a fault as the cause. Zero contacts at one moment do not exclude intermittent problems; an undetected input or read error does not prove hardware failure.

Example: contacts reported when nobody is touching the screen

During one service check, the controller repeatedly reported four active contacts near the lower edge and BTN_TOUCH: True when nobody was touching the screen. After a software reset, the contacts returned with new IDs. This confirms the reported contacts, not their cause. New IDs or a changed event filename do not prove that the problem has been resolved. Compare a fresh reading and inspect the corresponding area of the enclosure before changing more settings.

4. Inspect the surface and enclosure

Inspect the surface and edges for dirt, moisture, attached objects or pressure from the enclosure. Follow the manufacturer’s cleaning instructions. For doors carrying a touch film, establish whether the problem started after servicing or a change in position.

5. Restore the initial state appropriately

Record the state before and after any intervention. The /dev/input/eventN identifier may change after a restart or reconnection. Identify the controller again by name rather than blindly reusing an earlier input number. Resetting a software driver may leave the controller powered and does not guarantee a complete hardware reset.

Some designs may automatically adapt the touch controller when powered on. Moving a door or film afterwards may be associated with false contacts on those devices. This is not universal: confirm the procedure with the hardware supplier.

Finish servicing first, close the doors and leave the enclosure in its normal operating position. If the manufacturer recommends complete power disconnection, it must include the touch controller, which may be powered by USB. Restarting the player may not interrupt that power. An authorised person must follow the designated procedure; do not move the enclosure after powering it back on.

Remote USB recovery depends on the wiring and may disconnect other devices. This guide therefore provides neither a universal reset command nor an instruction to update firmware.

Related topics and next steps

6. Check the result and share the findings

Compare the untouched state again with several touches at known locations. Send support the controller name, output, symptoms, screen orientation and last service intervention. State whether complete power disconnection helped and whether moving a door affects the problem. Arrange a hardware inspection if it persists.

Didn't find what you were looking for?
Contact your software provider.