Implementing calibration for a KMDF HID Minidriver on an I2C touch device involves handling raw coordinate data and applying a transformation matrix before reporting it to the Windows HID class driver. This is critical for devices like those from Silead , where incorrect driver configuration often leads to inverted or misaligned touch input. Core Calibration Best Practices Implement a Transformation Matrix : Instead of hardcoding offsets, use a 3x3 calibration matrix (common in resistive and some capacitive setups) to map raw device coordinates to screen coordinates . Coordinate Normalization : Ensure raw data is first normalized to the HID logical range defined in your HID Report Descriptor (typically 0–4095 or 0–32767). Registry-Based Storage : Store calibration constants (offsets and scale factors) in the Windows Registry under HKEY_LOCAL_MACHINE\HARDWARE\DEVICEMAP\TOUCH as CalibrationData . This allows the driver to load custom values without a recompile. Expose a Secondary HID Collection : For out-of-band communication like sending new calibration data from a user-mode application, expose a secondary Top-Level Collection (TLC) in your HID descriptor. Typical Calibration Workflow Set to Raw Mode : Temporarily set the driver to provide raw, non-translated data. Point Collection : Use a user-mode tool to display targets at known screen coordinates (e.g., and ) and record the raw device response. Calculate Coefficients : Compute the gradient and crossing points to handle scaling, inversions, or rotations. Persistent Storage : Save these values to the device's EEPROM or the host's registry for the driver to apply on every report. Common Issues & Solutions SileadTouch.sys - GitHub Breadcrumbs * gsl-firmware. * /firmware. * /chuwi. * /hi8. * /KMDF HID Minidriver for Touch I2C Device. GitHub Touch screen is horizontally inverted - Microsoft Q&A
Implementing a KMDF HID Minidriver for I2C touch devices requires navigating a unique "driver pair" architecture. Because the HID class driver ( hidclass.sys ) must own the driver dispatch table, a standard KMDF driver cannot act as the function driver directly. Instead, you must use a lower filter driver model where a minimal WDM driver handles the HID registration and forwards requests to your KMDF filter. Microsoft Learn Architecture & Calibration Best Practices For touch device calibration, accuracy depends on how the driver handles coordinate mapping and data persistence. Calibration Persistence : Store calibration data (matrices or offsets) in the device's hardware registry key or the driver's Parameters\Wdf subkey. This ensures that calibration settings survive reboots and driver updates. Coordinate Mapping : Ensure your driver maps raw I2C controller values to the expected Windows HID units. Some touch drivers require sending coordinates in specific increments, such as 4ths of a pixel. HID Descriptor Accuracy HID Minidriver Sample to test your report descriptor. A common pitfall in touch calibration is an incorrectly defined LOGICAL_MAXIMUM for the X and Y axes, which causes scaling errors. Power Management Stability : I2C controllers often have aggressive power management. For stable calibration and touch response, it is a best practice to disable "Allow the computer to turn off this device to save power" in the Intel Serial IO I2C Host Controller properties. Toradex Community Implementation Workflow Driver Initialization WdfFdoInitSetFilter EvtDriverDeviceAdd callback to define your driver as a lower filter. I/O Queue Handling : Create queues to process IOCTLs passed from MsHidKmdf.sys . You must handle specific WDF HID Minidriver IOCTLs to report device capabilities. User-Space Interaction : For end-user calibration tools, leverage the built-in Windows Tablet PC Settings tool to generate the calibration matrix. Hardware Verification : Before software debugging, use I2C tools to confirm the device is detected at the expected address (e.g., ) on the bus. Toradex Community Troubleshooting Common Issues
Mastering Precision: The Ultimate Guide to KMDF HID Minidriver Development for Touch I2C Device Calibration Introduction In the rapidly evolving landscape of embedded systems and human-machine interfaces, the demand for precision touch input has never been higher. From industrial control panels to medical-grade diagnostic displays and automotive infotainment systems, the accuracy of a touchscreen is paramount. At the heart of this accuracy lies a critical software component: the Windows driver . Specifically, for I2C-connected touch devices, the most robust architecture is a KMDF (Kernel-Mode Driver Framework) HID Minidriver . However, even the most well-written driver is only as good as its calibration routine. This article explores the best practices for developing a KMDF HID Minidriver for Touch I2C Device Calibration. We will dive into the architecture, the calibration mathematics, registry persistence, and the integration of vendor-specific HID reports.
Part 1: Why KMDF and HID? The Architecture Breakdown Before discussing calibration, you must understand why KMDF + HID over I2C is the gold standard. The I2C Bus Challenge I2C (Inter-Integrated Circuit) is a low-speed, two-wire bus. Unlike USB, it lacks plug-and-play enumeration and standardized power management. Windows handles this through the HID I2C Driver Stack ( HIDI2C.sys ). However, for custom touch controllers (e.g., from Goodix, ELAN, or Cypress), a vendor minidriver is required. KMDF vs. Legacy WDM kmdf hid minidriver for touch i2c device calibration best
Legacy WDM (Windows Driver Model): Complex, error-prone, requires manual handling of PnP and power. KMDF: Object-oriented, simplifies PnP, power management, and I/O queues. For calibration, KMDF provides deterministic handling of IOCTL requests without the risk of IRQL deadlocks.
The Minidriver Role Your KMDF HID minidriver sits between the OS’s HID class driver and the I2C controller driver. It translates HID Reports (descriptors, input, output, feature) into I2C transactions. Calibration data is typically passed via HID Feature Reports (Report ID-specific). Best Practice: Always subclass your device as HID_DEVICE_SYSTEM_TOUCH (Usage Page 0x0D, Usage 0x04). This ensures Windows uses the built-in touch smoothing and gesture engine.
Part 2: The Calibration Conundrum – Why Defaults Fail Most low-cost I2C touch controllers have three sources of error: Implementing calibration for a KMDF HID Minidriver on
Mechanical Misalignment: The touch sensor overlay is physically offset from the LCD by a few mils. Non-linear ADC Response: The analog-to-digital converter on the controller may have gain/offset errors across the X/Y plane. Temperature Drift: Over time, the I2C device’s internal reference voltage drifts, altering touch coordinates.
A static factory calibration is insufficient. Device calibration must be dynamic, persistent, and user-triggerable . The Calibration Matrix (Affine Transformation) Your KMDF driver should not simply forward raw touch points. It must apply a linear transformation: [ X_{calibrated} = A \cdot X_{raw} + B \cdot Y_{raw} + C ] [ Y_{calibrated} = D \cdot X_{raw} + E \cdot Y_{raw} + F ] Where A, B, D, E are scaling/rotation factors, and C, F are offsets. The best drivers compute these on-the-fly using a 3-point or 4-point least-squares algorithm.
Part 3: Implementing Calibration in the KMDF HID Minidriver Here is the step-by-step implementation of a calibration subroutine within a KMDF HID minidriver for an I2C touch device. 3.1. Device Initialization and HID Descriptor Parsing On EvtDevicePrepareHardware , your driver must: Coordinate Normalization : Ensure raw data is first
Open a WDFI2CTarget to communicate with the touch IC. Read the device’s HID Descriptor (via I2C register 0x0001 ). Identify the Feature Report ID used for calibration registers. Most touch controllers reserve Report ID 0x03 for calibration control.
// Pseudo-logic: Request HID descriptor over I2C WDFI2C_TARGET_REQUEST_PARAMETERS_INIT(&reqParams); // Read 4 bytes: wHIDDescLength, bcdVersion, wReportDescLength // Extract the Report ID for calibration from the Report Descriptor later.
