Skip to content

HID Report and Touch Event Reporting

Jump to bottom
Barryblueice edited this page Dec 31, 2025 · 1 revision

First is finger(s) moving.

I defined 5 fingers in usb descriptor, the definition of a single finger is as follows:

0x85, REPORTID_TOUCHPAD,            //   REPORT_ID (Touch pad)
0x09, 0x22,                         //   USAGE (Finger)
0xa1, 0x02,                         //   COLLECTION (Logical)
0x15, 0x00,                         //       LOGICAL_MINIMUM (0)
0x25, 0x01,                         //       LOGICAL_MAXIMUM (1)
0x09, 0x47,                         //       USAGE (Confidence)
0x09, 0x42,                         //       USAGE (Tip switch)
0x95, 0x02,                         //       REPORT_COUNT (2)
0x75, 0x01,                         //       REPORT_SIZE (1)
0x81, 0x02,                         //       INPUT (Data,Var,Abs)
0x95, 0x01,                         //       REPORT_COUNT (1)
0x75, 0x02,                         //       REPORT_SIZE (2)
0x25, 0x02,                         //       LOGICAL_MAXIMUM (2)
0x09, 0x51,                         //       USAGE (Contact Identifier)
0x81, 0x02,                         //       INPUT (Data,Var,Abs)
0x75, 0x01,                         //       REPORT_SIZE (1)
0x95, 0x04,                         //       REPORT_COUNT (4)
0x81, 0x03,                         //       INPUT (Cnst,Var,Abs)
0x05, 0x01,                         //       USAGE_PAGE (Generic Desktop)
0x15, 0x00,                         //       LOGICAL_MINIMUM (0)
0x26, 0xff, 0x0f,                   //       LOGICAL_MAXIMUM (4095)
0x75, 0x10,                         //       REPORT_SIZE (16)
0x55, 0x0e,                         //       UNIT_EXPONENT (-2)
0x65, 0x13,                         //       UNIT(Inch,EngLinear)
0x09, 0x30,                         //       USAGE (X)
0x35, 0x00,                         //       PHYSICAL_MINIMUM (0)
0x46, 0x90, 0x01,                   //       PHYSICAL_MAXIMUM (400)
0x95, 0x02,                         //       REPORT_COUNT (2)
0x81, 0x02,                         //       INPUT (Data,Var,Abs)
0x46, 0x13, 0x01,                   //       PHYSICAL_MAXIMUM (275)
0x09, 0x31,                         //       USAGE (Y)
0x81, 0x02,                         //       INPUT (Data,Var,Abs)
0x05, 0x0d,                         //       USAGE_PAGE (Digitizers)
0x15, 0x00,                         //       LOGICAL_MINIMUM (0)
0x25, 0x64,                         //       LOGICAL_MAXIMUM (100)
0x95, 0x02,                         //       REPORT_COUNT (2)
0x09, 0x48,                         //       USAGE (Width)
0x09, 0x49,                         //       USAGE (Height)
0x81, 0x02,                         //       INPUT (Data,Var,Abs)
0xc0,                               //    END_COLLECTION

Then ESP32 will report PTP HID data per frame through the following report format:

typedef struct __attribute__((packed)) {
    finger_t fingers[5];   // Each finger(s) state
    uint16_t scan_time;    // Timestamp
    uint8_t contact_count; // Current number of active fingers
    uint8_t buttons;       // Physical button state
} ptp_report_t;

typedef struct __attribute__((packed)) {
    uint8_t tip_conf_id;  // Tip switch, Confidence, Contact ID
    uint16_t x;           // X coordinate
    uint16_t y;           // Y coordinate
} finger_t;

By Microsoft verification tool DigiInfo sniffering report, we can know that gestures are formed by frames:

image

About physical button on touchpad, because there is only one button on touchpad, so if we pressed, the report raw data shows as follow:

0E 00 04 03 60 02 93 08 E6 38 01 81 1C 63 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00

if not pressed:

0E 00 04 03 60 02 93 08 E6 38 01 80 1C 63 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00

According to the message, it can be known that the 11th byte has changed (0x80→0x81)

So in the end, I sent the touchpad button press event to the computer based on the 11th byte, and at the same time sent the XY coordinates, allowing the system to determine whether the current press was the left clicked or the right clicked.

Clone this wiki locally