Troubleshooting
Getting a Touchscreen Working Under a Linux HMI Runtime
Short answer
A loaded kernel module proves only that the kernel accepted the touchscreen driver. Touch reaches the visualization only when the driver exports events the image's input layer actually reads — typically an event device under /dev/input consumed by the Nano-X or evdev layer — so verify each link before editing configuration. If the driver exports no event interface, no configuration change fixes it.
On this page
Touch integration on a Linux HMI panel fails one link at a time: somewhere between the kernel and the application, the events stop. A kernel module that loads proves only that the kernel accepted the driver — it says nothing about whether a press on the glass ever reaches the visualization. On a Linux-based IPC running a CODESYS target visualization, touch works only when four links all pass: the driver itself, the event interface it exports under /dev/input, the input layer of the visualization toolkit, and the application's pointer mapping. Walk them in that order: the first link that fails tells you whether a configuration edit can help or whether the real choice is different hardware or a rebuilt image.
The four links touch has to cross #
- Kernel driver. The vendor's module loads and binds to the touch controller.
- Event interface. The kernel input layer describes the device to userspace through a map of types and codes, and an input device appears as an event device under /dev/input, written /dev/input/event*.
- Toolkit input layer. The window system behind the visualization reads those events. Nano-X is a layered design whose lowest level holds the drivers for screen output and for mouse and keyboard input, and touch devices are served at that same driver level. Runtimes and libraries with evdev support read touchscreen, mouse and keyboard input straight from the /dev/input event devices, with no separate user-space input library.
- Pointer mapping. The visualization receives pointer events and maps them onto its screens and controls.
The chain is a series connection: one broken link blocks all touch, and a fix applied above the broken link changes nothing. That is the entire method here, and it is the same discipline as isolating each layer in a controls fault.
What the module load proves, and the next test #
The load confirms link 1 and nothing else. The next test settles link 2: with the image running, press the panel and watch the event devices for activity, using whatever input-event inspection tool this image provides. Record the interface name and its permissions, because the toolkit layer has to be allowed to open it. Also pin down what the target is documented to support: the touchscreens this platform's target supports are reported to run on a TSHARC-based driver, which means the image's input layer was built for that interface. Treat that as reported, not verified, until the image's own documentation confirms it.
The event device under /dev/input #
A touch device on the input layer reports position events and a contact state, expressed through the same types and codes as every other input device. If pressing the panel produces events on an event device, the kernel side is proven and the fault, if any, lives above it.
Creating a file under /dev is not the integration step. A driver that registers with the kernel input layer gets its event node created for it by the system. A hand-made node is legitimate only when the driver's documentation specifies the exact device type and identifiers it expects; a node with no driver behind it is inert, and opening it returns no events whatever the HMI configuration says. The event stream is what you are wiring, not the file name.
What the Nano-X input layer will accept #
The integrator's description of this platform — Nano-X linked to the CODESYS runtime at compile time, with the IPC model and image not identified — carries a hard consequence: input support is decided at build time, because input sits in the driver level of Nano-X's layered design. A configuration file helps only when the installed build actually reads that file and offers the interface your driver exports. If the build compiled in the supported controller's interface and nothing else, events from another controller never become pointer events, and no line in a config file adds an input driver that was never compiled in.
Working the path on a 17-inch panel whose module already loads #
Inputs:
- Platform: a Linux-based Wago IPC running a CODESYS target visualization, with Nano-X linked at compile time — reported by the integrator; model and image unidentified.
- Driver state: the touchscreen vendor's kernel module loads — reported.
- Panel requirement: 17 in or larger — the project's stated minimum screen size.
- Path structure: 4 links in series — driver, event interface, toolkit input, pointer mapping.
Rule: touch passes only when all 4 links pass. Each link is pass or fail, the first failing link is the fault, and anything above it is untouched by fixes.
Arithmetic: links proven so far = 1, the module load. Links outstanding = 4 − 1 = 3, tested in path order: event interface first, toolkit input second, pointer mapping third.
The link-2 test: press the glass and watch for events on the event devices. Events appearing passes the link; silence fails it.
Result: with only the module load confirmed, 3 unverified links stand between the loaded driver and a working touch screen, and the next test resolves the first of them.
Decision:
- Events appear: move to link 3. Establish from the image's documentation which input interface the installed Nano-X build reads. If it can select your driver's interface, point it there, then verify pointer mapping. If it cannot, configuration is finished as an option — the choice is a panel with a supported controller or a rebuilt image.
- No events: the driver registers nothing the kernel input layer exposes. Stop editing; no /dev node and no config line changes that. Fit a touchscreen whose controller is on the image's supported list, or have the image rebuilt with a driver for yours.
The decision for each outcome #
- All four links pass but presses land offset: that is a mapping fault, not a driver fault. Fix it in the coordinate mapping or calibration the visualization provides. Before the station returns to service, verify press-to-action on every control with the machine in a safe state, because a coordinate offset can put an operator's press on the adjacent button.
- Link 2 passes and link 3 fails: the image's input layer cannot consume the interface your driver exports. The real options are an image rebuilt with the driver, an adapter compiled into the image, or a panel with a supported controller. A config edit is not one of them.
- Link 2 fails: hardware or image decision — a supported panel, or a rebuild, as above.
- If the answer is a new panel rather than a rebuild, put the candidate through the same steps as verifying an obsolete HMI replacement before ordering. The touch-controller interface is the same kind of boundary that decides which HMI software works with which HMI panel hardware: it is settled from documentation before anything is ordered. When the computer stays and only the touch surface is chosen new, compare candidates among industrial touchscreen monitors, confirming each touch controller's driver interface against the image's supported list first.
- Moving the visualization to a runtime with its own input stack — a Java-based HMI is the usual suggestion — sidesteps the compiled Nano-X layer entirely, but it is a re-platforming project: screens, PLC communications and operator procedures come with it. Treat it as a platform decision, not a touchscreen fix.
The same method applies to isolating each layer in a controls fault: drive one layer's input, observe that layer's output, and only then move up.
Questions asked
Does loading the touchscreen's kernel module finish the integration?
No. The load is the kernel accepting the driver. Three checks remain: the panel must register as an input device with events under /dev/input, the visualization's input layer must read that interface, and the pointer mapping must be correct. Any one of them can fail while the module stays loaded.
When is creating a device node under /dev the right move?
Almost never with a kernel-registered driver: the system creates the event device for it. A manual node is legitimate only when the driver's documentation names the exact device type and identifiers it expects. A node you invent connects to nothing, and opening it returns no events regardless of the HMI settings.
What is evdev, and why does it matter here?
evdev reads touchscreen, mouse and keyboard events straight from the /dev/input event devices, with no separate user-space input library. A runtime with evdev support can consume any kernel-registered touch driver. A visualization compiled without it cannot, no matter how correct the driver is, which is why the build, not the config file, decides.
Would moving the HMI to a different runtime fix the touch problem?
It can sidestep the mismatch, because a new runtime brings its own input stack and stops depending on the compiled Nano-X layer. But it is a re-platforming: screens, PLC communications and operator procedures get rebuilt. Treat it as a platform decision with its own scope, not a touchscreen setting.
What must be true before a replacement touchscreen is ordered?
Its touch controller needs a Linux driver whose exported interface matches what the installed image's input layer reads, which is the documentation check you would run on any panel replacement. Screen size is not compatibility: a 17-inch panel with an unsupported controller fails exactly like the first one.