USB HID Descriptors: Mouse vs Digitizer
The RP2040 presents two distinct USB device personalities depending on which firmware is flashed.
1. HID Mouse Mode (pico_platformio_touch_mouse)
In mouse mode, the Pico exposes a standard 3-byte or 4-byte relative mouse HID descriptor:
- Usage Page: Generic Desktop (
0x01) - Usage: Mouse (
0x02) - Report Contents:
- Byte 0: Buttons (Bit 0: Left Click / Touch Active)
- Byte 1: X displacement (ΔX, signed 8-bit integer)
- Byte 2: Y displacement (ΔY, signed 8-bit integer)
- Byte 3: Wheel (optional)
When finger dragging occurs, the firmware calculates relative offset deltas:
dX = X_now - X_prev
dY = Y_now - Y_prev
and issues Mouse.move(dx, dy).
2. HID Digitizer Mode (pico_sdk_touch)
In digitizer mode, the device registers as a single-touch integrated touchscreen (Usage Page
Digitizers 0x0D, Usage Touch Screen 0x04). The HID report descriptor declares a logical range
of 0 to 799 on X and 0 to 479 on Y, exactly matching what the firmware sends. Each report is
eight bytes:
| Byte | Field | Value |
|---|---|---|
| 0 | Report ID | 0x01 |
| 1 | Tip Switch (bit 0) and In Range (bit 1) | 0x03 touching, 0x00 released |
| 2–3 | X coordinate, little-endian uint16 | 0 to 799 |
| 4–5 | Y coordinate, little-endian uint16 | 0 to 479 |
| 6 | Tip pressure | 0xFF while touching |
| 7 | Contact count | 1 while touching, 0 on release |
This mode allows modern Linux desktop window managers (Wayland, X11) and embedded GUI stacks (LVGL) to process direct touch inputs at the exact finger coordinates without needing mouse emulation or software calibration overlays.