Input events from non-mouse or keyboard USB peripherals in Linux are sent to character device files located within the
/dev/input/ directory. These devices, such as barcode scanners or specialized buttons, appear as distinct event nodes (e.g.,
eventX) rather than generic input classes. The kernel's HID subsystem automatically detects these devices and assigns them unique identifiers, allowing user-space applications to read raw data directly from these specific paths without needing complex configuration.
Understanding the Input Subsystem Architecture
Linux manages input hardware through a layered architecture known as the Linux Input Subsystem. When you plug in a USB peripheral, the kernel’s USB core driver communicates with the device descriptor to identify its capabilities. For standard mice and keyboards, the system maps inputs to virtual console interfaces for immediate usability. However, for non-standard devices like medical scanners, industrial controllers, or custom button arrays, the behavior differs significantly.
The kernel does not treat these devices as simple pointing devices. Instead, it creates specific event nodes that represent the raw input stream. This separation ensures that standard mouse movements do not interfere with scanner triggers or specialized control signals. Understanding this distinction is crucial for developers who need to capture these events programmatically. The hierarchy involves the physical USB connection, the HID parser, and finally the event interface exposed to userspace.
The Role of /dev/input/
All input events, regardless of type, funnel into the
/dev/input/ directory. You can inspect this directory using the
ls -l /dev/input/ command. The output will list several types of entries:
- by-path: Symlinks based on the physical location or bus ID of the device.
- eventX: Character devices representing the event queue for specific hardware.
- mice: A legacy aggregate device for all pointing devices (largely obsolete for new development).
- jsN: Joystick devices, often used for game pads but sometimes applicable to other analog inputs.
For your specific use case involving a scanner, you will primarily interact with the
eventX files. Each
event file corresponds to a specific input device node created by the kernel. Unlike
/dev/input/mice, which aggregates relative motion data,
event files provide absolute key codes and switch states, which is exactly what a scanner button press generates.
Identifying Your Specific Device
To determine which event file belongs to your scanner, you must first identify the device’s unique identifier. The most reliable method is using the dmesg command immediately after connecting the device. Look for lines containing "HID" or "usb". Alternatively, the udevadm tool provides detailed information about the device properties.
Run the following command to monitor udev events in real-time:
udevadm monitor --environment --udev
Connect your scanner. The terminal will output a stream of data including environment variables such as ID_INPUT, ID_MODEL_ID, and DEVNAME. The DEVNAME variable points directly to the device node, typically something like /dev/input/event12. Note this number, as it may change between reboots unless you create a persistent rule.
Another useful tool is evtest, which allows you to listen to raw events from any input device. Install it via your package manager (e.g., apt install evtest). Then run:
evtest /dev/input/eventX
Replace X with the number identified earlier. Press the scanner button. If configured correctly, you will see a line outputting a key code (e.g., EV_KEY BTN_0) and a value of 1 (pressed) or 0 (released). This confirms that the kernel is successfully receiving and translating the physical signal into a digital event.
Managing Permissions and Access
By default, access to /dev/input/eventX is restricted to the root user or members of the input group. Standard user applications cannot read these events directly due to security policies. To allow a specific application to read scanner data, you have two primary options: adding the user to the input group or creating a udev rule.
Adding a user to the group is straightforward but grants broad access to all input devices, which may be undesirable in multi-user environments. A more secure approach is creating a udev rule. Create a file in /etc/udev/rules.d/, for example, 99-scanner.rules. The rule should match the vendor and product IDs of your scanner and set the permissions accordingly.
SUBSYSTEM=="input", ATTRS{idVendor}=="xxxx", ATTRS{idProduct}=="yyyy", MODE="0660", GROUP="scannerusers"
After saving the rule, reload udev with udevadm control --reload-rules and trigger the event with udevadm trigger. Ensure your application runs under a user who is a member of the scannerusers group. This method ensures that only authorized processes can intercept the input stream.
Programming Against Input Events
Once the device node is identified and permissions are set, applications can open the /dev/input/eventX file using standard POSIX I/O calls. The data structure returned is struct input_event, defined in linux/input.h. This structure contains the time stamp, type, code, and value of the event.
Most high-level libraries abstract this complexity. For example, Python’s pyevdev library provides a clean interface to parse these structures. In C or C++, you would typically use open(), read(), and handle potential errors related to device removal. It is important to note that some scanners emulate keyboard input (HID Keyboard Class). In such cases, the events appear as standard key presses (e.g., ASCII characters followed by Enter) rather than raw HID reports. If your scanner behaves this way, you may need to configure it via manufacturer-specific software to switch to "raw mode" or "HID++ mode" if available, ensuring it sends discrete button events rather than typed text.
Frequently Asked Questions
Why does my scanner send keystrokes instead of raw events?
Many consumer-grade scanners default to HID Keyboard emulation to ensure compatibility with basic text fields. To receive raw events, check the device documentation for a configuration utility that allows switching to "Raw Mode" or "Device Mode." Some devices require a specific setup string to be sent before they will operate in this mode.
How can I make the /dev/input/eventX path persistent?
The event numbers (X) change dynamically based on boot order and other connected devices. Use udev rules matching the ID_SERIAL_SHORT or ID_VENDOR_ID to create a symlink in /dev/ with a fixed name, such as /dev/scanner_input. This symlink remains stable across reboots and unplugging events.
Can I use evtest to debug why my application isn't seeing events?
Yes, evtest is the primary diagnostic tool for this issue. If evtest shows no activity when pressing the button, the kernel driver is not binding correctly. Check dmesg for error messages related to the USB device or missing firmware files.
Is tslib still relevant for modern Linux input handling?
No, tslib is largely obsolete for general input management. It was designed for touchscreen calibration on embedded systems running older kernels. Modern Linux uses the unified input subsystem for all touch and pointer devices, making tslib unnecessary for standard USB peripherals like scanners.
What is the difference between /dev/input/mice and /dev/input/eventX?
/dev/input/mice is a legacy aggregate device that combines relative motion data from all pointing devices into a single stream. /dev/input/eventX represents individual devices and provides structured data including key codes, absolute coordinates, and switch states. Always prefer event nodes for precise control over specific hardware.