Skip to content

PTP_DEBUG_GUIDE.md

Latest commit

 

History

History
134 lines (104 loc) · 4.07 KB

PTP_DEBUG_GUIDE.md

File metadata and controls

134 lines (104 loc) · 4.07 KB
Raw

Windows Precision Trackpad Debug Guide

Quick Debug Steps

1. Check Console Output (QMK)

With CONSOLE_ENABLE = yes in your rules.mk, you should see debug output:

PTP: fingers=1, range: x=1-897, y=1-895, current: f0(450,300) f1(0,0)
PTP Report: count=1, scan=12345, btn=000
  C0: id=0, conf=1, tip=1, x=450, y=300

Use hid_listen or QMK Toolbox to view console output.

2. Check HID Descriptor (Windows)

Option A: Device Manager

  1. Open Device Manager
  2. Find "HID-compliant touch pad" under "Human Interface Devices"
  3. Right-click → Properties → Details
  4. Select "Hardware Ids" - should show:
    • HID\VID_3297&PID_1977&MI_03 (or similar)
    • HID\VID_3297&UP:000D_U:0005 (Usage Page 0x0D, Usage 0x05 = Digitizer/Touchpad)

Option B: USB Device Tree Viewer

  1. Download from: https://www.uwe-sieber.de/usbtreeview_e.html
  2. Find your Voyager device
  3. Look for interface with:
    • Usage Page: 0x0D (Digitizers)
    • Usage: 0x05 (Touch Pad)
  4. Check the HID Report Descriptor

Option C: Python Script

pip install hidapi
python debug_hid_descriptor.py

3. Capture HID Packets (Wireshark)

  1. Install Wireshark with USBPcap: https://www.wireshark.org/
  2. Start capture on USB bus
  3. Filter by: usb.idVendor == 0x3297
  4. Look for URB_INTERRUPT packets to endpoint 0x85 (trackpad IN endpoint)

4. Compare with Working Trackpad

Run this on a working Windows Precision Trackpad:

python debug_hid_descriptor.py

Look for differences in:

  • Contact count behavior
  • Coordinate ranges
  • Scan time increments
  • Button states

Expected PTP Report Structure

Byte 0:    Report ID (0x01)
Byte 1:    Contact 0 flags (confidence, tip, contact_id, reserved)
Byte 2-3:  Contact 0 X (little-endian, 0-900)
Byte 4-5:  Contact 0 Y (little-endian, 0-900)
Byte 6:    Contact 1 flags
Byte 7-8:  Contact 1 X
Byte 9-10: Contact 1 Y
Byte 11-12: Scan time (little-endian, in 100μs units)
Byte 13:   Contact count (0-2)
Byte 14:   Button states (button1, button2, button3, padding)

Common Issues

Gestures Not Working

Symptom: Cursor moves but no scrolling, pinch, rotate

Possible Causes:

  1. Contact ID not consistent - Windows tracks fingers by contact_id
  2. Missing "finger lifted" report - Need to send contact_count=0 when no touch
  3. Scan time not incrementing - Windows uses this for velocity calculations
  4. Confidence bit always 0 - Windows may ignore uncertain contacts
  5. Physical dimensions wrong - Affects gesture recognition

Debug:

// Add to navigator_trackpad_task()
printf("C0: id=%d -> ", prev_contact_id[0]);
printf("%d, ", ptp.contacts[0].contact_id);

Taps Not Working

Symptom: No click on single tap

Possible Causes:

  1. Feature report issues - Windows queries device capabilities
  2. Clickpad bit not set - Check REPORT_ID_TRACKPAD_MAX_COUNT response
  3. No button click simulation - PTP may need button1 set on tap

Debug: Check feature report responses in usb_report_handling.c:

  • REPORT_ID_TRACKPAD_MAX_COUNT: Should return 2 contacts, clickpad mode
  • REPORT_ID_TRACKPAD_PTPHQA: Should return certification blob

Cursor Movement Slow/Fast

Symptom: Cursor doesn't match finger speed

Check:

  1. Logical Maximum in descriptor (should be 900 for our sensor)
  2. Physical Maximum in descriptor (should be 157 = 1.57" = 40mm)
  3. Coordinate mapping in code (currently direct, no scaling)

Verification Checklist

  • Console shows finger touch/release correctly
  • Console shows contact_count changing (0 → 1 → 2 → 1 → 0)
  • Console shows contact_id staying consistent per finger
  • Scan time is incrementing
  • Coordinates in expected range (1-897 x 1-895)
  • Device Manager shows Usage Page 0x0D, Usage 0x05
  • Feature reports respond correctly
  • Two fingers show different contact_ids (0 and 1)

Next Steps

If console output looks correct but gestures don't work:

  1. Capture USB packets with Wireshark
  2. Compare with working Microsoft Precision Trackpad
  3. Check Windows Event Viewer for HID errors
  4. Try on different Windows version (10 vs 11)